Для словарей, созданных с помощью DDL-запросов, в параметре dict_name
указывается полное имя словаря вместе с базой данных, например: <database>.<dict_name>
. Если база данных не указана, используется текущая.
Функции для работы с внешними словарями
Информацию о подключении и настройке внешних словарей смотрите в разделе Внешние словари.
dictGet, dictGetOrDefault, dictGetOrNull
Извлекает значение из внешнего словаря.
Аргументы
dict_name
— имя словаря. Строковый литерал.attr_names
— имя столбца словаря. Строковый литерал, или кортеж Tuple таких имен.id_expr
— значение ключа словаря. Expression возвращает пару "ключ-значение" словаря или Tuple, в зависимости от конфигурации словаря.default_value_expr
— значение, возвращаемое в том случае, когда словарь не содержит строки с заданным ключомid_expr
. Выражение, возвращающее значение с типом данных, сконфигурированным для атрибутаattr_names
, или кортеж Tuple таких выражений.
Возвращаемое значение
-
Значение атрибута, соответствующее ключу
id_expr
, если ClickHouse смог привести это значение к заданному типу данных. -
Если ключа, соответствующего
id_expr
в словаре нет, то:dictGet
возвращает содержимое элемента<null_value>
, указанного для атрибута в конфигурации словаря.dictGetOrDefault
возвращает атрибутdefault_value_expr
.dictGetOrNull
возвращаетNULL
в случае, если ключ не найден в словаре.
Если значение атрибута не удалось обработать или оно не соответствует типу данных атрибута, то ClickHouse генерирует исключение.
Пример с единственным атрибутом
Создадим текстовый файл ext-dict-text.csv
со следующим содержимым:
Первый столбец — id
, второй столбец — c1
.
Настройка внешнего словаря:
Выполним запрос:
Пример с несколькими атрибутами
Создадим текстовый файл ext-dict-mult.csv
со следующим содержимым:
Первый столбец — id
, второй столбец — c1
, третий столбец — c2
.
Настройка внешнего словаря:
Выполним запрос:
Пример для словаря с диапазоном ключей
Создадим таблицу:
Создадим внешний словарь:
Выполним запрос:
Результат:
Смотрите также
dictHas
Проверяет, присутствует ли запись с указанным ключом в словаре.
Аргументы
dict_name
— имя словаря. Строковый литерал.id_expr
— значение ключа словаря. Expression возвращает пару "ключ-значение" словаря или Tuple в зависимости от конфигурации словаря.
Возвращаемое значение
- 0, если ключа нет.
- 1, если ключ есть.
Тип: UInt8.
dictGetHierarchy
Создаёт массив, содержащий цепочку предков для заданного ключа в иерархическом словаре.
Синтаксис
Аргументы
dict_name
— имя словаря. Строковый литерал.key
— значение ключа. Выражение, возвращающее значение типа UInt64.
Возвращаемое значение
- Цепочка предков заданного ключа.
dictIsIn
Проверяет предка ключа по всей иерархической цепочке словаря.
dictIsIn ('dict_name', child_id_expr, ancestor_id_expr)
Аргументы
dict_name
— имя словаря. Строковый литерал.child_id_expr
— ключ для проверки. Выражение, возвращающее значение типа UInt64.ancestor_id_expr
— предполагаемый предок ключаchild_id_expr
. Выражение, возвращающее значение типа UInt64.
Возвращаемое значение
- 0, если
child_id_expr
— не дочерний элементancestor_id_expr
. - 1, если
child_id_expr
— дочерний элементancestor_id_expr
или еслиchild_id_expr
и естьancestor_id_expr
.
Тип: UInt8.
dictGetChildren
Возвращает потомков первого уровня в виде массива индексов. Это обратное преобразование для dictGetHierarchy.
Синтаксис
Аргументы
dict_name
— имя словаря. String literal.key
— значение ключа. Выражение, возвращающее значение типа UInt64.
Возвращаемые значения
- Потомки первого уровня для ключа.
Пример
Рассмотрим иерархический словарь:
Потомки первого уровня:
dictGetDescendant
Возвращает всех потомков, как если бы функция dictGetChildren была выполнена level
раз рекурсивно.
Синтаксис
Аргументы
dict_name
— имя словаря. String literal.key
— значение ключа. Выражение, возвращающее значение типа UInt64.level
— уровень иерархии. Еслиlevel = 0
, возвращаются все потомки. UInt8.
Возвращаемые значения
- Потомки для ключа.
Пример
Рассмотрим иерархический словарь:
Все потомки:
Потомки первого уровня:
Прочие функции
ClickHouse поддерживает специализированные функции, которые приводят значения атрибутов словаря к определённому типу данных независимо от конфигурации словаря.
Функции:
dictGetInt8
,dictGetInt16
,dictGetInt32
,dictGetInt64
dictGetUInt8
,dictGetUInt16
,dictGetUInt32
,dictGetUInt64
dictGetFloat32
,dictGetFloat64
dictGetDate
dictGetDateTime
dictGetUUID
dictGetString
Все эти функции можно использовать с модификатором OrDefault
. Например, dictGetDateOrDefault
.
Синтаксис:
Аргументы
dict_name
— имя словаря. Строковый литерал.attr_name
— имя столбца словаря. Строковый литерал.id_expr
— значение ключа словаря. Выражение, возвращающее значение типа UInt64 или Tuple в зависимости от конфигурации словаря.default_value_expr
— значение, возвращаемое в том случае, когда словарь не содержит строки с заданным ключомid_expr
. Выражение, возвращающее значение с типом данных, сконфигурированным для атрибутаattr_name
.
Возвращаемое значение
-
Если ClickHouse успешно обработал атрибут в соответствии с заданным типом данных, то функции возвращают значение атрибута, соответствующее ключу
id_expr
. -
Если запрошенного
id_expr
нет в словаре, то:dictGet[Type]
возвращает содержимое элемента<null_value>
, указанного для атрибута в конфигурации словаря.dictGet[Type]OrDefault
возвращает аргументdefault_value_expr
.
Если значение атрибута не удалось обработать или оно не соответствует типу данных атрибута, то ClickHouse генерирует исключение.