Перейти к основному содержимому
Перейти к основному содержимому

Функции для работы со словарями

примечание

Для словарей, созданных с помощью DDL запросов, параметр dict_name должен быть полностью указан, например, <database>.<dict_name>. В противном случае используется текущая база данных.

Для получения информации о подключении и настройке словарей, смотрите Словари.

dictGet, dictGetOrDefault, dictGetOrNull​

Извлекает значения из словаря.

Аргументы

  • dict_name — Название словаря. Строковый литерал.
  • attr_names — Название колонки словаря, Строковый литерал или кортеж имен колонок, Tuple(Строковый литерал.
  • id_expr — Ключевое значение. Выражение возвращающее значение ключа словаря или Tuple-тип значения в зависимости от конфигурации словаря.
  • default_value_expr — Значения, возвращаемые если словарь не содержит строки с ключом id_expr. Выражение или Tuple(Выражение), возвращающее значение (или значения) в типах данных, настроенных для атрибута attr_names.

Возвращаемое значение

  • Если ClickHouse успешно разбирает атрибут в типе данных атрибута, функции возвращают значение атрибута словаря, соответствующее id_expr.

  • Если в словаре нет ключа, соответствующего id_expr, то:

    • dictGet возвращает содержимое элемента <null_value>, указанного для атрибута в конфигурации словаря.
    • dictGetOrDefault возвращает значение, переданное как параметр default_value_expr.
    • dictGetOrNull возвращает NULL, если ключ не был найден в словаре.

ClickHouse выбрасывает исключение, если не может разобрать значение атрибута или если значение не соответствует типу данных атрибута.

Пример для словаря с простым ключом

Создайте текстовый файл ext-dict-test.csv, содержащий следующее:

Первая колонка id, вторая колонка c1.

Настройте словарь:

Выполните запрос:

Пример для словаря со сложным ключом

Создайте текстовый файл ext-dict-mult.csv, содержащий следующее:

Первая колонка id, вторая — c1, третья — c2.

Настройте словарь:

Выполните запрос:

Пример для словаря с диапазоном ключей

Входная таблица:

Создайте словарь:

Выполните запрос:

Результат:

Смотрите также

dictHas​

Проверяет, присутствует ли ключ в словаре.

Аргументы

  • dict_name — Название словаря. Строковый литерал.
  • id_expr — Ключевое значение. Выражение возвращающее значение типа ключа словаря или Tuple-тип значения в зависимости от конфигурации словаря.

Возвращаемое значение

  • 0, если ключа нет. UInt8.
  • 1, если ключ есть. UInt8.

dictGetHierarchy​

Создает массив, содержащий всех предков ключа в иерархическом словаре.

Синтаксис

Аргументы

Возвращаемое значение

dictIsIn​

Проверяет, является ли предком ключа через всю иерархическую цепочку в словаре.

Аргументы

Возвращаемое значение

  • 0, если child_id_expr не является ребенком ancestor_id_expr. UInt8.
  • 1, если child_id_expr является ребенком ancestor_id_expr или если child_id_expr является ancestor_id_expr. UInt8.

dictGetChildren​

Возвращает детей первого уровня в виде массива индексов. Это обратное преобразование для dictGetHierarchy.

Синтаксис

Аргументы

Возвращаемые значения

  • Дети первого уровня для ключа. Array(UInt64).

Пример

Рассмотрим иерархический словарь:

Дети первого уровня:

dictGetDescendant​

Возвращает всех потомков так, как если бы функция dictGetChildren применялась level раз рекурсивно.

Синтаксис

Аргументы

  • dict_name — Название словаря. Строковый литерал.
  • key — Ключевое значение. Выражение возвращающее значение типа UInt64.
  • level — Уровень иерархии. Если level = 0, возвращает всех потомков до конца. UInt8.

Возвращаемые значения

Пример

Рассмотрим иерархический словарь:

Все потомки:

Дети первого уровня:

dictGetAll​

Извлекает значения атрибутов всех узлов, которые соответствуют каждому ключу в словаре-дереве регулярных выражений.

Кроме возвращения значений типа Array(T) вместо T, эта функция ведет себя аналогично dictGet.

Синтаксис

Аргументы

  • dict_name — Название словаря. Строковый литерал.
  • attr_names — Название колонки словаря, Строковой литерал или кортеж имен колонок, Tuple(Строковой литерал).
  • id_expr — Ключевое значение. Выражение возвращающее массив значений типа ключа словаря или Tuple-тип значения в зависимости от конфигурации словаря.
  • limit - Максимальная длина для каждого возвращаемого массива значений. При усечении дочерние узлы имеют приоритет над родительскими узлами, если не указано, длина массива не ограничена.

Возвращаемое значение

  • Если ClickHouse успешно разбирает атрибут в типе данных атрибута, как определено в словаре, возвращает массив значений атрибутов словаря, соответствующих id_expr для каждого атрибута, указанного в attr_names.

  • Если в словаре нет ключа, соответствующего id_expr, то возвращается пустой массив.

ClickHouse выбрасывает исключение, если не может разобрать значение атрибута или если значение не соответствует типу данных атрибута.

Пример

Рассмотрим следующий словарь-дерево регулярных выражений:

Получите все соответствующие значения:

Получите до 2 соответствующих значений:

Другие функции​

ClickHouse поддерживает специализированные функции, которые конвертируют значения атрибутов словаря в конкретный тип данных независимо от конфигурации словаря.

Функции:

  • dictGetInt8, dictGetInt16, dictGetInt32, dictGetInt64
  • dictGetUInt8, dictGetUInt16, dictGetUInt32, dictGetUInt64
  • dictGetFloat32, dictGetFloat64
  • dictGetDate
  • dictGetDateTime
  • dictGetUUID
  • dictGetString
  • dictGetIPv4, dictGetIPv6

Все эти функции имеют модификацию 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 выбрасывает исключение, если не может разобрать значение атрибута или если значение не соответствует типу данных атрибута.