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

Примечание

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

Информацию о подключении и настройке словарей см. в разделе Словари.

dictGet, dictGetOrDefault, dictGetOrNull

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

dictGet('dict_name', attr_names, id_expr)
dictGetOrDefault('dict_name', attr_names, id_expr, default_value_expr)
dictGetOrNull('dict_name', attr_name, id_expr)

Аргументы

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

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

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

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

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

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

1,1
2,2

Первый столбец — id, второй столбец — c1.

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

<clickhouse>
    <dictionary>
        <name>ext-dict-test</name>
        <source>
            <file>
                <path>/path-to/ext-dict-test.csv</path>
                <format>CSV</format>
            </file>
        </source>
        <layout>
            <flat />
        </layout>
        <structure>
            <id>
                <name>id</name>
            </id>
            <attribute>
                <name>c1</name>
                <type>UInt32</type>
                <null_value></null_value>
            </attribute>
        </structure>
        <lifetime>0</lifetime>
    </dictionary>
</clickhouse>

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

SELECT
    dictGetOrDefault('ext-dict-test', 'c1', number + 1, toUInt32(number * 10)) AS val,
    toTypeName(val) AS type
FROM system.numbers
LIMIT 3;

┌─val─┬─type───┐
│   1 │ UInt32 │
│   2 │ UInt32 │
│  20 │ UInt32 │
└─────┴────────┘

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

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

1,1,'1'
2,2,'2'
3,3,'3'

Первый столбец — id, второй — c1, третий — c2.

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

<clickhouse>
    <dictionary>
        <name>ext-dict-mult</name>
        <source>
            <file>
                <path>/path-to/ext-dict-mult.csv</path>
                <format>CSV</format>
            </file>
        </source>
        <layout>
            <flat />
        </layout>
        <structure>
            <id>
                <name>id</name>
            </id>
            <attribute>
                <name>c1</name>
                <type>UInt32</type>
                <null_value></null_value>
            </attribute>
            <attribute>
                <name>c2</name>
                <type>String</type>
                <null_value></null_value>
            </attribute>
        </structure>
        <lifetime>0</lifetime>
    </dictionary>
</clickhouse>

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

SELECT
    dictGet('ext-dict-mult', ('c1','c2'), number + 1) AS val,
    toTypeName(val) AS type
FROM system.numbers
LIMIT 3;

┌─val─────┬─type──────────────────┐
│ (1,'1') │ Tuple(UInt8, String)  │
│ (2,'2') │ Tuple(UInt8, String)  │
│ (3,'3') │ Tuple(UInt8, String)  │
└─────────┴───────────────────────┘

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

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

CREATE TABLE range_key_dictionary_source_table
(
    key UInt64,
    start_date Date,
    end_date Date,
    value String,
    value_nullable Nullable(String)
)
ENGINE = TinyLog();

INSERT INTO range_key_dictionary_source_table VALUES(1, toDate('2019-05-20'), toDate('2019-05-20'), 'First', 'First');
INSERT INTO range_key_dictionary_source_table VALUES(2, toDate('2019-05-20'), toDate('2019-05-20'), 'Second', NULL);
INSERT INTO range_key_dictionary_source_table VALUES(3, toDate('2019-05-20'), toDate('2019-05-20'), 'Third', 'Third');

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

CREATE DICTIONARY range_key_dictionary
(
    key UInt64,
    start_date Date,
    end_date Date,
    value String,
    value_nullable Nullable(String)
)
PRIMARY KEY key
SOURCE(CLICKHOUSE(HOST 'localhost' PORT tcpPort() TABLE 'range_key_dictionary_source_table'))
LIFETIME(MIN 1 MAX 1000)
LAYOUT(RANGE_HASHED())
RANGE(MIN start_date MAX end_date);

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

SELECT
    (number, toDate('2019-05-20')),
    dictHas('range_key_dictionary', number, toDate('2019-05-20')),
    dictGetOrNull('range_key_dictionary', 'value', number, toDate('2019-05-20')),
    dictGetOrNull('range_key_dictionary', 'value_nullable', number, toDate('2019-05-20')),
    dictGetOrNull('range_key_dictionary', ('value', 'value_nullable'), number, toDate('2019-05-20'))
FROM system.numbers LIMIT 5 FORMAT TabSeparated;

Результат:

(0,'2019-05-20')        0       \N      \N      (NULL,NULL)
(1,'2019-05-20')        1       First   First   ('First','First')
(2,'2019-05-20')        1       Second  \N      ('Second',NULL)
(3,'2019-05-20')        1       Third   Third   ('Third','Third')
(4,'2019-05-20')        0       \N      \N      (NULL,NULL)

См. также

Словари

dictHas

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

dictHas('dict_name', id_expr)

Аргументы

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

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

0, если ключ отсутствует. UInt8.
1, если ключ существует. UInt8.

dictGetHierarchy

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

Синтаксис

dictGetHierarchy('dict_name', key)

Аргументы

dict_name — Имя словаря. Строковый литерал.
key — Значение ключа. Выражение, возвращающее значение типа UInt64.

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

Родительские элементы для ключа. Array(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. UInt8.
1, если child_id_expr является потомком ancestor_id_expr или если child_id_expr равен ancestor_id_expr. UInt8.

dictGetChildren

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

Синтаксис

dictGetChildren(имя_словаря, ключ)

Аргументы

dict_name — имя словаря. Строковый литерал.
key — значение ключа. Выражение, возвращающее значение типа UInt64.

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

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

Пример

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

┌─id─┬─parent_id─┐
│  1 │         0 │
│  2 │         1 │
│  3 │         1 │
│  4 │         2 │
└────┴───────────┘

Дочерние элементы первого уровня:

SELECT dictGetChildren('hierarchy_flat_dictionary', number) FROM system.numbers LIMIT 4;

┌─dictGetChildren('hierarchy_flat_dictionary', number)─┐
│ [1]                                                  │
│ [2,3]                                                │
│ [4]                                                  │
│ []                                                   │
└──────────────────────────────────────────────────────┘

dictGetDescendant

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

Синтаксис

dictGetDescendants(dict_name, key, level)

Аргументы

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

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

Потомки указанного ключа. Array(UInt64).

Пример

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

┌─id─┬─parent_id─┐
│  1 │         0 │
│  2 │         1 │
│  3 │         1 │
│  4 │         2 │
└────┴───────────┘

Все потомки:

SELECT dictGetDescendants('hierarchy_flat_dictionary', number) FROM system.numbers LIMIT 4;

┌─dictGetDescendants('hierarchy_flat_dictionary', number)─┐
│ [1,2,3,4]                                               │
│ [2,3,4]                                                 │
│ [4]                                                     │
│ []                                                      │
└─────────────────────────────────────────────────────────┘

Потомки первого уровня:

SELECT dictGetDescendants('hierarchy_flat_dictionary', number, 1) FROM system.numbers LIMIT 4;

┌─dictGetDescendants('hierarchy_flat_dictionary', number, 1)─┐
│ [1]                                                        │
│ [2,3]                                                      │
│ [4]                                                        │
│ []                                                         │
└────────────────────────────────────────────────────────────┘

dictGetAll

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

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

Синтаксис

dictGetAll('dict_name', attr_names, id_expr[, limit])

Аргументы

dict_name — имя словаря. Строковый литерал.
attr_names — имя столбца словаря — строковый литерал — или кортеж имён столбцов — Tuple(строковый литерал).
id_expr — значение ключа. Выражение, возвращающее массив значений типа ключа словаря или значение типа Tuple в зависимости от конфигурации словаря.
limit — максимальная длина для каждого возвращаемого массива значений. При усечении дочерние узлы имеют приоритет над родительскими, а в остальных случаях соблюдается определённый порядок списка для словаря regexp tree. Если параметр не указан, длина массива не ограничена.

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

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

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

Пример

Рассмотрим следующий словарь regexp tree:

CREATE DICTIONARY regexp_dict
(
    regexp String,
    tag String
)
PRIMARY KEY(regexp)
SOURCE(YAMLRegExpTree(PATH '/var/lib/clickhouse/user_files/regexp_tree.yaml'))
LAYOUT(regexp_tree)
...

# /var/lib/clickhouse/user_files/regexp_tree.yaml \{#varlibclickhouseuser_filesregexp_treeyaml}
- regexp: 'foo'
  tag: 'foo_attr'
- regexp: 'bar'
  tag: 'bar_attr'
- regexp: 'baz'
  tag: 'baz_attr'

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

SELECT dictGetAll('regexp_dict', 'tag', 'foobarbaz');

┌─dictGetAll('regexp_dict', 'tag', 'foobarbaz')─┐
│ ['foo_attr','bar_attr','baz_attr']            │
└───────────────────────────────────────────────┘

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

SELECT dictGetAll('regexp_dict', 'tag', 'foobarbaz', 2);

┌─dictGetAll('regexp_dict', 'tag', 'foobarbaz', 2)─┐
│ ['foo_attr','bar_attr']                          │
└──────────────────────────────────────────────────┘

dictGetKeys

Возвращает ключ(и) словаря, значение указанного атрибута которых равно заданному значению. Является обратной функцией к dictGet по одному атрибуту.

Синтаксис

dictGetKeys('dict_name', 'attr_name', value_expr);

Аргументы

dict_name — имя словаря. Строковый литерал.
attr_name — имя столбца атрибута словаря. Строковый литерал.
value_expr — значение для сравнения с атрибутом. Выражение, которое может быть приведено к типу данных атрибута.

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

Для словарей с простым ключом: массив ключей, для которых значение атрибута равно value_expr. Array(T), где T — тип данных ключа словаря.
Для словарей с составным ключом: массив кортежей ключей, для которых значение атрибута равно value_expr. Array(Tuple(T1, T2, ...)), где каждый Tuple содержит столбцы ключа словаря в заданном порядке.
Если в словаре нет атрибута, соответствующего value_expr, возвращается пустой массив.

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

Пример

Рассмотрим следующий словарь:

 ┌─id─┬─level──┐
 │  1 │ low    │
 │  2 │ high   │
 │  3 │ medium │
 │  4 │ high   │
 └────┴────────┘

Теперь получим все идентификаторы с уровнем high:

SELECT dictGetKeys('levels', 'level', 'high') AS ids;

 ┌─ids───┐
 │ [4,2] │
 └───────┘

Примечание

Используйте параметр max_reverse_dictionary_lookup_cache_size_bytes, чтобы ограничить размер кеша обратного поиска для каждого запроса, используемого dictGetKeys. Кеш хранит сериализованные кортежи ключей для каждого значения атрибута, чтобы избежать повторного сканирования словаря в рамках одного и того же запроса. Кеш не сохраняется между запросами. Когда лимит достигается, записи вытесняются по принципу LRU. Это наиболее эффективно для больших словарей, когда входные данные имеют низкую кардинальность и рабочий набор помещается в кеш. Установите значение 0, чтобы отключить кеширование.

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

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

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

Функции:

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

Все эти функции имеют модификацию OrDefault. Например, dictGetDateOrDefault.

Синтаксис:

dictGet[Type]('dict_name', 'attr_name', id_expr)
dictGet[Type]OrDefault('dict_name', 'attr_name', id_expr, default_value_expr)

Аргументы

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

Примеры словарей

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

Пример словаря для функций dictGet<T> и dictGet<T>OrDefault

-- Создать таблицу со всеми необходимыми типами данных
CREATE TABLE all_types_test (
    `id` UInt32,
    
    -- Тип String
    `String_value` String,
    
    -- Беззнаковые целочисленные типы
    `UInt8_value` UInt8,
    `UInt16_value` UInt16,
    `UInt32_value` UInt32,
    `UInt64_value` UInt64,
    
    -- Знаковые целочисленные типы
    `Int8_value` Int8,
    `Int16_value` Int16,
    `Int32_value` Int32,
    `Int64_value` Int64,
    
    -- Типы с плавающей точкой
    `Float32_value` Float32,
    `Float64_value` Float64,
    
    -- Типы даты/времени
    `Date_value` Date,
    `DateTime_value` DateTime,
    
    -- Сетевые типы
    `IPv4_value` IPv4,
    `IPv6_value` IPv6,
    
    -- Тип UUID
    `UUID_value` UUID
) ENGINE = MergeTree() 
ORDER BY id;

-- Вставить тестовые данные
INSERT INTO all_types_test VALUES
(
    1,                              -- id
    'ClickHouse',                   -- String
    100,                            -- UInt8
    5000,                           -- UInt16
    1000000,                        -- UInt32
    9223372036854775807,            -- UInt64
    -100,                           -- Int8
    -5000,                          -- Int16
    -1000000,                       -- Int32
    -9223372036854775808,           -- Int64
    123.45,                         -- Float32
    987654.123456,                  -- Float64
    '2024-01-15',                   -- Date
    '2024-01-15 10:30:00',          -- DateTime
    '192.168.1.1',                  -- IPv4
    '2001:db8::1',                  -- IPv6
    '550e8400-e29b-41d4-a716-446655440000' -- UUID
)

-- Создать словарь
CREATE DICTIONARY all_types_dict
(
    id UInt32,
    String_value String,
    UInt8_value UInt8,
    UInt16_value UInt16,
    UInt32_value UInt32,
    UInt64_value UInt64,
    Int8_value Int8,
    Int16_value Int16,
    Int32_value Int32,
    Int64_value Int64,
    Float32_value Float32,
    Float64_value Float64,
    Date_value Date,
    DateTime_value DateTime,
    IPv4_value IPv4,
    IPv6_value IPv6,
    UUID_value UUID
)
PRIMARY KEY id
SOURCE(CLICKHOUSE(HOST 'localhost' PORT 9000 USER 'default' TABLE 'all_types_test' DB 'default'))
LAYOUT(HASHED())
LIFETIME(MIN 300 MAX 600);

Пример словаря для dictGetAll

Создайте таблицу для хранения данных словаря regexp tree:

CREATE TABLE regexp_os(
    id UInt64,
    parent_id UInt64,
    regexp String,
    keys Array(String),
    values Array(String)
)
ENGINE = Memory;

Вставьте данные в таблицу:

INSERT INTO regexp_os 
SELECT *
FROM s3(
    'https://datasets-documentation.s3.eu-west-3.amazonaws.com/' ||
    'user_agent_regex/regexp_os.csv'
);

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

CREATE DICTIONARY regexp_tree
(
    regexp String,
    os_replacement String DEFAULT 'Other',
    os_v1_replacement String DEFAULT '0',
    os_v2_replacement String DEFAULT '0',
    os_v3_replacement String DEFAULT '0',
    os_v4_replacement String DEFAULT '0'
)
PRIMARY KEY regexp
SOURCE(CLICKHOUSE(TABLE 'regexp_os'))
LIFETIME(MIN 0 MAX 0)
LAYOUT(REGEXP_TREE);

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

Создайте исходную таблицу:

CREATE TABLE range_key_dictionary_source_table
(
    key UInt64,
    start_date Date,
    end_date Date,
    value String,
    value_nullable Nullable(String)
)
ENGINE = TinyLog();

Вставьте данные в исходную таблицу:

INSERT INTO range_key_dictionary_source_table VALUES(1, toDate('2019-05-20'), toDate('2019-05-20'), 'First', 'First');
INSERT INTO range_key_dictionary_source_table VALUES(2, toDate('2019-05-20'), toDate('2019-05-20'), 'Second', NULL);
INSERT INTO range_key_dictionary_source_table VALUES(3, toDate('2019-05-20'), toDate('2019-05-20'), 'Third', 'Third');

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

CREATE DICTIONARY range_key_dictionary
(
    key UInt64,
    start_date Date,
    end_date Date,
    value String,
    value_nullable Nullable(String)
)
PRIMARY KEY key
SOURCE(CLICKHOUSE(HOST 'localhost' PORT tcpPort() TABLE 'range_key_dictionary_source_table'))
LIFETIME(MIN 1 MAX 1000)
LAYOUT(RANGE_HASHED())
RANGE(MIN start_date MAX end_date);

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

Создайте исходную таблицу:

CREATE TABLE dict_mult_source
(
id UInt32,
c1 UInt32,
c2 String
) ENGINE = Memory;

Вставьте данные в исходную таблицу:

INSERT INTO dict_mult_source VALUES
(1, 1, '1'),
(2, 2, '2'),
(3, 3, '3');

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

CREATE DICTIONARY ext_dict_mult
(
    id UInt32,
    c1 UInt32,
    c2 String
)
PRIMARY KEY id
SOURCE(CLICKHOUSE(HOST 'localhost' PORT 9000 USER 'default' TABLE 'dict_mult_source' DB 'default'))
LAYOUT(FLAT())
LIFETIME(MIN 0 MAX 0);

Пример иерархического словаря

Создайте исходную таблицу:

CREATE TABLE hierarchy_source
(
  id UInt64,
  parent_id UInt64,
  name String
) ENGINE = Memory;

Вставьте данные в исходную таблицу:

INSERT INTO hierarchy_source VALUES
(0, 0, 'Root'),
(1, 0, 'Level 1 - Node 1'),
(2, 1, 'Level 2 - Node 2'),
(3, 1, 'Level 2 - Node 3'),
(4, 2, 'Level 3 - Node 4'),
(5, 2, 'Level 3 - Node 5'),
(6, 3, 'Level 3 - Node 6');

-- 0 (Корень)
-- └── 1 (Уровень 1 - Узел 1)
--     ├── 2 (Уровень 2 - Узел 2)
--     │   ├── 4 (Уровень 3 - Узел 4)
--     │   └── 5 (Уровень 3 - Узел 5)
--     └── 3 (Уровень 2 - Узел 3)
--         └── 6 (Уровень 3 - Узел 6)

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

CREATE DICTIONARY hierarchical_dictionary
(
    id UInt64,
    parent_id UInt64 HIERARCHICAL,
    name String
)
PRIMARY KEY id
SOURCE(CLICKHOUSE(HOST 'localhost' PORT 9000 USER 'default' TABLE 'hierarchy_source' DB 'default'))
LAYOUT(HASHED())
LIFETIME(MIN 300 MAX 600);

dictGet

Появилась в версии: v18.16

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

Синтаксис

dictGet('dict_name', attr_names, id_expr)

Аргументы

dict_name — Имя словаря. String
attr_names — Имя столбца словаря или кортеж имен столбцов. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее UInt64/Tuple(T). UInt64 или Tuple(T)

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

Возвращает значение атрибута словаря, которое соответствует id_expr, если ключ найден. Если ключ не найден, возвращает содержимое элемента <null_value>, указанного для атрибута в конфигурации словаря.

Примеры

Получение одного атрибута

SELECT dictGet('ext_dict_test', 'c1', toUInt64(1)) AS val

Несколько атрибутов

SELECT
    dictGet('ext_dict_mult', ('c1','c2'), number + 1) AS val,
    toTypeName(val) AS type
FROM system.numbers
LIMIT 3;

┌─val─────┬─type───────────┐
│ (1,'1') │ Tuple(        ↴│
│         │↳    c1 UInt32,↴│
│         │↳    c2 String) │
│ (2,'2') │ Tuple(        ↴│
│         │↳    c1 UInt32,↴│
│         │↳    c2 String) │
│ (3,'3') │ Tuple(        ↴│
│         │↳    c1 UInt32,↴│
│         │↳    c2 String) │
└─────────┴────────────────┘

dictGetAll

Появилась в версии: v23.5

Преобразует значение атрибута словаря в тип данных All независимо от конфигурации словаря.

Синтаксис

dictGetAll(dict_name, attr_name, id_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или кортеж (в зависимости от конфигурации словаря). Expression или Tuple(T)

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

Возвращает значение атрибута словаря, которое соответствует id_expr, в противном случае возвращает содержимое элемента <null_value>, указанного для атрибута в конфигурации словаря.

Примечание

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

Примеры

Пример использования

SELECT
    'Mozilla/5.0 (Linux; Android 12; SM-G998B) Mobile Safari/537.36' AS user_agent,

    -- Найдет ВСЕ применимые шаблоны
    dictGetAll('regexp_tree', 'os_replacement', 'Mozilla/5.0 (Linux; Android 12; SM-G998B) Mobile Safari/537.36') AS all_matches,

    -- Вернет только первое совпадение
    dictGet('regexp_tree', 'os_replacement', 'Mozilla/5.0 (Linux; Android 12; SM-G998B) Mobile Safari/537.36') AS first_match;

┌─user_agent─────────────────────────────────────────────────────┬─all_matches─────────────────────────────┬─first_match─┐
│ Mozilla/5.0 (Linux; Android 12; SM-G998B) Mobile Safari/537.36 │ ['Android','Android','Android','Linux'] │ Android     │
└────────────────────────────────────────────────────────────────┴─────────────────────────────────────────┴─────────────┘

dictGetChildren

Появилась в версии: v21.4

Возвращает дочерние элементы первого уровня в виде массива индексов. Является обратным преобразованием к dictGetHierarchy.

Синтаксис

dictGetChildren(dict_name, key)

Аргументы

dict_name — имя словаря. String
key — ключ, который требуется проверить. const String

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

Возвращает потомков первого уровня для ключа. Array(UInt64)

Примеры

Получение потомков первого уровня словаря

SELECT dictGetChildren('hierarchical_dictionary', 2);

┌─dictGetChild⋯ionary', 2)─┐
│ [4,5]                    │
└──────────────────────────┘

dictGetDate

Введена в версии: v1.1

Преобразует значение атрибута словаря к типу данных Date независимо от конфигурации словаря.

Синтаксис

dictGetDate(dict_name, attr_name, id_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или кортеж (в зависимости от конфигурации словаря). Expression или Tuple(T)

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

Возвращает значение атрибута словаря, которое соответствует id_expr, в противном случае возвращает содержимое элемента <null_value>, заданного для атрибута в конфигурации словаря.

Примечание

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

Примеры

Пример использования

SELECT dictGetDate('all_types_dict', 'Date_value', 1)

┌─dictGetDate(⋯_value', 1)─┐
│               2020-01-01 │
└──────────────────────────┘

dictGetDateOrDefault

Добавлено в: v1.1

Преобразует значение атрибута словаря в тип данных Date независимо от настроек словаря или возвращает указанное значение по умолчанию, если ключ не найден.

Синтаксис

dictGetDateOrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или значение-кортеж (в зависимости от конфигурации словаря). Expression или Tuple(T)
default_value_expr — Значение или значения, возвращаемые, если словарь не содержит строки с ключом id_expr. Expression или Tuple(T)

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

Возвращает значение атрибута словаря, соответствующее id_expr, в противном случае — значение, переданное в параметре default_value_expr.

Примечание

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

Примеры

Пример использования

-- для существующего ключа
SELECT dictGetDate('all_types_dict', 'Date_value', 1);

-- для несуществующего ключа возвращается указанное значение по умолчанию
SELECT dictGetDateOrDefault('all_types_dict', 'Date_value', 999, toDate('1970-01-01'));

┌─dictGetDate(⋯_value', 1)─┐
│               2024-01-15 │
└──────────────────────────┘
┌─dictGetDateO⋯70-01-01'))─┐
│               1970-01-01 │
└──────────────────────────┘

dictGetDateTime

Появилась в версии: v1.1

Преобразует значение атрибута словаря в тип данных DateTime независимо от конфигурации словаря.

Синтаксис

dictGetDateTime(dict_name, attr_name, id_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или кортеж (в зависимости от конфигурации словаря). Expression или Tuple(T)

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

Возвращает значение атрибута словаря, которое соответствует id_expr, в противном случае — содержимое элемента <null_value>, указанного для атрибута в конфигурации словаря.

Примечание

Примеры

Пример использования

SELECT dictGetDateTime('all_types_dict', 'DateTime_value', 1)

┌─dictGetDateT⋯_value', 1)─┐
│      2024-01-15 10:30:00 │
└──────────────────────────┘

dictGetDateTimeOrDefault

Добавлена в версии: v1.1

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

Синтаксис

dictGetDateTimeOrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или значение кортежа (в зависимости от конфигурации словаря). Expression или Tuple(T)
default_value_expr — Значение или значения, возвращаемые, если словарь не содержит строки с ключом id_expr. Expression или Tuple(T)

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

Возвращает значение атрибута словаря, которое соответствует id_expr, иначе возвращает значение, переданное в параметре default_value_expr.

Примечание

Примеры

Пример использования

-- для существующего ключа
SELECT dictGetDateTime('all_types_dict', 'DateTime_value', 1);

-- для несуществующего ключа возвращает заданное значение по умолчанию
SELECT dictGetDateTimeOrDefault('all_types_dict', 'DateTime_value', 999, toDateTime('1970-01-01 00:00:00'));

┌─dictGetDateT⋯_value', 1)─┐
│      2024-01-15 10:30:00 │
└──────────────────────────┘
┌─dictGetDateT⋯0:00:00'))──┐
│      1970-01-01 00:00:00 │
└──────────────────────────┘

dictGetDescendants

Добавлено в: v21.4

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

Синтаксис

dictGetDescendants(dict_name, key, level)

Аргументы

dict_name — имя словаря. String
key — ключ, который нужно проверить. const String
level — уровень иерархии. Если level = 0, возвращает всех потомков до конца. UInt8

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

Возвращает потомков для ключа. Array(UInt64)

Примеры

Получение дочерних элементов словаря первого уровня

-- рассмотрим следующий иерархический словарь:
-- 0 (Корень)
-- └── 1 (Уровень 1 - Узел 1)
--     ├── 2 (Уровень 2 - Узел 2)
--     │   ├── 4 (Уровень 3 - Узел 4)
--     │   └── 5 (Уровень 3 - Узел 5)
--     └── 3 (Уровень 2 - Узел 3)
--         └── 6 (Уровень 3 - Узел 6)

SELECT dictGetDescendants('hierarchical_dictionary', 0, 2)

┌─dictGetDesce⋯ary', 0, 2)─┐
│ [3,2]                    │
└──────────────────────────┘

dictGetFloat32

Появилась в версии: v1.1

Преобразует значение атрибута словаря к типу данных Float32 независимо от конфигурации словаря.

Синтаксис

dictGetFloat32(dict_name, attr_name, id_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или значение-кортеж (в зависимости от конфигурации словаря). Expression или Tuple(T)

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

Возвращает значение атрибута словаря, соответствующее id_expr, в противном случае возвращает содержимое элемента <null_value>, указанного для атрибута в конфигурации словаря.

Примечание

Примеры

Пример использования

SELECT dictGetFloat32('all_types_dict', 'Float32_value', 1)

┌─dictGetFloat⋯_value', 1)─┐
│               -123.123   │
└──────────────────────────┘

dictGetFloat32OrDefault

Добавлена в версии: v1.1

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

Синтаксис

dictGetFloat32OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или кортеж (в зависимости от конфигурации словаря). Expression или Tuple(T)
default_value_expr — Значение или значения, возвращаемые, если в словаре нет строки с ключом id_expr. Expression или Tuple(T)

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

Возвращает значение атрибута словаря, соответствующее id_expr, в противном случае возвращает значение, переданное в параметре default_value_expr.

Примечание

Примеры

Пример использования

-- для существующего ключа
SELECT dictGetFloat32('all_types_dict', 'Float32_value', 1);

-- для несуществующего ключа возвращается заданное значение по умолчанию (-1.0)
SELECT dictGetFloat32OrDefault('all_types_dict', 'Float32_value', 999, -1.0);

┌─dictGetFloat⋯_value', 1)─┐
│                   123.45 │
└──────────────────────────┘
┌─dictGetFloat⋯e', 999, -1)─┐
│                       -1  │
└───────────────────────────┘

dictGetFloat64

Впервые представлена в версии v1.1

Преобразует значение атрибута словаря к типу данных Float64 независимо от конфигурации словаря.

Синтаксис

dictGetFloat64(dict_name, attr_name, id_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя атрибута словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или кортеж значений (в зависимости от конфигурации словаря). Expression или Tuple(T)

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

Примечание

Примеры

Пример использования

SELECT dictGetFloat64('all_types_dict', 'Float64_value', 1)

┌─dictGetFloat⋯_value', 1)─┐
│                 -123.123 │
└──────────────────────────┘

dictGetFloat64OrDefault

Впервые представлена в: v1.1

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

Синтаксис

dictGetFloat64OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или значение кортежа (в зависимости от конфигурации словаря). Expression или Tuple(T)
default_value_expr — Значение или значения, которые возвращаются, если словарь не содержит строку с ключом id_expr. Expression или Tuple(T)

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

Примечание

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

Примеры

Пример использования

-- для существующего ключа
SELECT dictGetFloat64('all_types_dict', 'Float64_value', 1);

-- для несуществующего ключа возвращается указанное значение по умолчанию (nan)
SELECT dictGetFloat64OrDefault('all_types_dict', 'Float64_value', 999, nan);

┌─dictGetFloat⋯_value', 1)─┐
│            987654.123456 │
└──────────────────────────┘
┌─dictGetFloat⋯, 999, nan)─┐
│                      nan │
└──────────────────────────┘

dictGetHierarchy

Появилось в версии: v1.1

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

Синтаксис

dictGetHierarchy(dict_name, key)

Аргументы

dict_name — Имя словаря. String
key — Значение ключа. const String

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

Возвращает родителей для ключа. Array(UInt64)

Примеры

Получение иерархии для ключа

SELECT dictGetHierarchy('hierarchical_dictionary', 5)

┌─dictGetHiera⋯ionary', 5)─┐
│ [5,2,1]                  │
└──────────────────────────┘

dictGetIPv4

Впервые появилась в версии v1.1

Преобразует значение атрибута словаря в тип данных IPv4 независимо от конфигурации словаря.

Синтаксис

dictGetIPv4(dict_name, attr_name, id_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или значение кортежа (в зависимости от конфигурации словаря). Expression или Tuple(T)

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

Возвращает значение атрибута словаря, соответствующее id_expr, иначе возвращает содержимое элемента <null_value>, указанного для атрибута в конфигурации словаря.

Примечание

Примеры

Пример использования

SELECT dictGetIPv4('all_types_dict', 'IPv4_value', 1)

┌─dictGetIPv4('all_⋯ 'IPv4_value', 1)─┐
│ 192.168.0.1                         │
└─────────────────────────────────────┘

dictGetIPv4OrDefault

Впервые появилась в: v23.1

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

Синтаксис

dictGetIPv4OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или кортеж (в зависимости от конфигурации словаря). Expression или Tuple(T)
default_value_expr — Значение или значения, возвращаемые, если словарь не содержит строки с ключом id_expr. Expression или Tuple(T)

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

Возвращает значение атрибута словаря, соответствующее id_expr, в противном случае возвращает значение, переданное через параметр default_value_expr.

Примечание

Примеры

Пример использования

-- для существующего ключа
SELECT dictGetIPv4('all_types_dict', 'IPv4_value', 1);

-- для несуществующего ключа возвращает заданное значение по умолчанию
SELECT dictGetIPv4OrDefault('all_types_dict', 'IPv4_value', 999, toIPv4('0.0.0.0'));

┌─dictGetIPv4('all_⋯ 'IPv4_value', 1)─┐
│ 192.168.0.1                         │
└─────────────────────────────────────┘
┌─dictGetIPv4OrDefa⋯0.0.0.0'))─┐
│ 0.0.0.0                      │
└──────────────────────────────┘

dictGetIPv6

Добавлена в версии: v23.1

Преобразует значение атрибута словаря в тип данных IPv6 независимо от конфигурации словаря.

Синтаксис

dictGetIPv6(dict_name, attr_name, id_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или значение кортежа (в зависимости от конфигурации словаря). Expression или Tuple(T)

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

Примечание

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

Примеры

Пример использования

SELECT dictGetIPv6('all_types_dict', 'IPv6_value', 1)

┌─dictGetIPv6('all_⋯ 'IPv6_value', 1)─┐
│ 2001:db8:85a3::8a2e:370:7334        │
└─────────────────────────────────────┘

dictGetIPv6OrDefault

Введена в версии: v23.1

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

Синтаксис

dictGetIPv6OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или значение кортежа (в зависимости от конфигурации словаря). Expression или Tuple(T)
default_value_expr — Значение или значения, возвращаемые, если словарь не содержит строку с ключом id_expr. Expression или Tuple(T)

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

Примечание

Примеры

Пример использования

-- для существующего ключа
SELECT dictGetIPv6('all_types_dict', 'IPv6_value', 1);

-- для несуществующего ключа возвращает переданное значение по умолчанию
SELECT dictGetIPv6OrDefault('all_types_dict', 'IPv6_value', 999, '::1'::IPv6);

┌─dictGetIPv6('all_⋯ 'IPv6_value', 1)─┐
│ 2001:db8:85a3::8a2e:370:7334        │
└─────────────────────────────────────┘
┌─dictGetIPv6OrDefa⋯:1'::IPv6)─┐
│ ::1                          │
└──────────────────────────────┘

dictGetInt16

Добавлено в: v1.1

Преобразует значение атрибута словаря к типу данных Int16 независимо от конфигурации словаря.

Синтаксис

dictGetInt16(dict_name, attr_name, id_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или кортеж (в зависимости от конфигурации словаря). Expression или Tuple(T)

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

Примечание

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

Примеры

Пример использования

SELECT dictGetInt16('all_types_dict', 'Int16_value', 1)

┌─dictGetInt16⋯_value', 1)─┐
│                    -5000 │
└──────────────────────────┘

dictGetInt16OrDefault

Впервые представлена в: v1.1

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

Синтаксис

dictGetInt16OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

dict_name — имя словаря. String
attr_name — имя столбца словаря. String или Tuple(String)
id_expr — значение ключа. Выражение, возвращающее значение типа ключа словаря или кортеж значений (в зависимости от конфигурации словаря). Expression или Tuple(T)
default_value_expr — значение или значения, возвращаемые, если словарь не содержит строки с ключом id_expr. Expression или Tuple(T)

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

Примечание

Примеры

Пример использования

-- для существующего ключа
SELECT dictGetInt16('all_types_dict', 'Int16_value', 1);

-- для несуществующего ключа возвращается указанное значение по умолчанию (-1)
SELECT dictGetInt16OrDefault('all_types_dict', 'Int16_value', 999, -1);

┌─dictGetInt16⋯_value', 1)─┐
│                    -5000 │
└──────────────────────────┘
┌─dictGetInt16⋯', 999, -1)─┐
│                       -1 │
└──────────────────────────┘

dictGetInt32

Добавлена в версии: v1.1

Преобразует значение атрибута словаря к типу данных Int32 независимо от конфигурации словаря.

Синтаксис

dictGetInt32(dict_name, attr_name, id_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или кортеж (в зависимости от конфигурации словаря). Expression или Tuple(T)

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

Возвращает значение атрибута словаря, которое соответствует id_expr, иначе возвращает содержимое элемента <null_value>, указанного для атрибута в конфигурации словаря.

Примечание

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

Примеры

Пример использования

SELECT dictGetInt32('all_types_dict', 'Int32_value', 1)

┌─dictGetInt32⋯_value', 1)─┐
│                -1000000  │
└──────────────────────────┘

dictGetInt32OrDefault

Введён в версии: v1.1

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

Синтаксис

dictGetInt32OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или значение-кортеж (в зависимости от конфигурации словаря). Expression или Tuple(T)
default_value_expr — Значение (значения), возвращаемое, если словарь не содержит строки с ключом id_expr. Expression или Tuple(T)

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

Примечание

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

Примеры

Пример использования

-- для существующего ключа
SELECT dictGetInt32('all_types_dict', 'Int32_value', 1);

-- для несуществующего ключа возвращается заданное значение по умолчанию (-1)
SELECT dictGetInt32OrDefault('all_types_dict', 'Int32_value', 999, -1);

┌─dictGetInt32⋯_value', 1)─┐
│                -1000000  │
└──────────────────────────┘
┌─dictGetInt32⋯', 999, -1)─┐
│                       -1 │
└──────────────────────────┘

dictGetInt64

Добавлена в: v1.1

Преобразует значение атрибута словаря к типу данных Int64 независимо от конфигурации словаря.

Синтаксис

dictGetInt64(dict_name, attr_name, id_expr)

Аргументы

dict_name — имя словаря. String
attr_name — имя столбца словаря. String или Tuple(String)
id_expr — значение ключа. Выражение, возвращающее значение типа ключа словаря или кортеж (в зависимости от конфигурации словаря). Expression или Tuple(T)

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

Возвращает значение атрибута словаря, которое соответствует id_expr, в противном случае возвращает значение элемента <null_value>, заданного для атрибута в конфигурации словаря.

Примечание

Примеры

Пример использования

SELECT dictGetInt64('all_types_dict', 'Int64_value', 1)

┌─dictGetInt64⋯_value', 1)───┐
│       -9223372036854775807 │
└────────────────────────────┘

dictGetInt64OrDefault

Добавлена в версии: v1.1

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

Синтаксис

dictGetInt64OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или кортеж (в зависимости от конфигурации словаря). Expression или Tuple(T)
default_value_expr — Значение или значения, которые возвращаются, если словарь не содержит строки с ключом id_expr. Expression или Tuple(T)

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

Возвращает значение атрибута словаря, которое соответствует id_expr, в противном случае возвращает значение, переданное в параметре default_value_expr.

Примечание

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

Примеры

Пример использования

-- для существующего ключа
SELECT dictGetInt64('all_types_dict', 'Int64_value', 1);

-- для несуществующего ключа возвращается указанное значение по умолчанию (-1)
SELECT dictGetInt64OrDefault('all_types_dict', 'Int64_value', 999, -1);

┌─dictGetInt64⋯_value', 1)─┐
│     -9223372036854775808 │
└──────────────────────────┘
┌─dictGetInt64⋯', 999, -1)─┐
│                       -1 │
└──────────────────────────┘

dictGetInt8

Введена в версии: v1.1

Преобразует значение атрибута словаря в тип данных Int8 независимо от конфигурации словаря.

Синтаксис

dictGetInt8(dict_name, attr_name, id_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или значение-кортеж (в зависимости от конфигурации словаря). Expression или Tuple(T)

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

Примечание

Примеры

Пример использования

SELECT dictGetInt8('all_types_dict', 'Int8_value', 1)

┌─dictGetInt8(⋯_value', 1)─┐
│                     -100 │
└──────────────────────────┘

dictGetInt8OrDefault

Введена в версии v1.1

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

Синтаксис

dictGetInt8OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение ключевого типа словаря или значение кортежа (зависит от конфигурации словаря). Expression или Tuple(T)
default_value_expr — Значение или значения, возвращаемые, если словарь не содержит строки с ключом id_expr. Expression или Tuple(T)

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

Примечание

Примеры

Пример использования

-- для существующего ключа
SELECT dictGetInt8('all_types_dict', 'Int8_value', 1);

-- для несуществующего ключа возвращается указанное значение по умолчанию (-1)
SELECT dictGetInt8OrDefault('all_types_dict', 'Int8_value', 999, -1);

┌─dictGetInt8(⋯_value', 1)─┐
│                     -100 │
└──────────────────────────┘
┌─dictGetInt8O⋯', 999, -1)─┐
│                       -1 │
└──────────────────────────┘

dictGetKeys

Введена в версии v25.12

Возвращает ключ(и) словаря, для которых значение атрибута равно указанному. Это обратная операция к функции dictGet для одного атрибута.

Используйте SETTING max_reverse_dictionary_lookup_cache_size_bytes, чтобы ограничить размер кэша обратного поиска для каждого запроса, используемого в dictGetKeys. Кэш хранит сериализованные кортежи ключей для каждого значения атрибута, чтобы избежать повторного сканирования словаря в рамках одного запроса. Кэш не сохраняется между запросами. При достижении лимита записи вытесняются по алгоритму LRU. Функция наиболее эффективна для больших словарей, когда входные данные имеют низкую кардинальность, а рабочий набор помещается в кэш. Установите 0, чтобы отключить кэширование.

Синтаксис

dictGetKeys('dict_name', 'attr_name', value_expr)

Аргументы

dict_name — имя словаря. String
attr_name — атрибут для сравнения. String
value_expr — значение для сравнения с атрибутом. Expression

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

Для словарей с одним ключом: массив ключей, атрибут которых равен value_expr. Для словарей с составным ключом: массив кортежей ключей, атрибут которых равен value_expr. Если в словаре нет атрибута, соответствующего значению value_expr, возвращается пустой массив. ClickHouse генерирует исключение, если не может разобрать значение атрибута или если значение не может быть преобразовано к типу данных атрибута.

Примеры

Пример использования

SELECT dictGetKeys('task_id_to_priority_dictionary', 'priority_level', 'high') AS ids;

┌─-ids──┐
│ [4,2] │
└───────┘

dictGetOrDefault

Добавлена в версии v18.16

Извлекает значения из словаря, возвращая значение по умолчанию, если ключ не найден.

Синтаксис

dictGetOrDefault('dict_name', attr_names, id_expr, default_value)

Аргументы

dict_name — Имя словаря. String
attr_names — Имя столбца словаря или кортеж имён столбцов. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее UInt64/Tuple(T). UInt64 или Tuple(T)
default_value — Значение по умолчанию, которое возвращается, если ключ не найден. Тип должен соответствовать типу данных атрибута.

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

Возвращает значение атрибута словаря, которое соответствует id_expr, если ключ найден. Если ключ не найден, возвращает переданное значение default_value.

Примеры

Получение значения с заданным значением по умолчанию

SELECT dictGetOrDefault('ext_dict_mult', 'c1', toUInt64(999), 0) AS val

dictGetOrNull

Появилась в версии: v21.4

Извлекает значения из словаря, возвращая NULL, если ключ не найден.

Синтаксис

dictGetOrNull('dict_name', 'attr_name', id_expr)

Аргументы

dict_name — Имя словаря. Строковый литерал. - attr_name — Имя столбца, значение которого нужно получить. Строковый литерал. - id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря.

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

Возвращает значение атрибута словаря, соответствующее id_expr, если ключ найден. Если ключ не найден, возвращает NULL.

Примеры

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

SELECT
    (number, toDate('2019-05-20')),
    dictGetOrNull('range_key_dictionary', 'value', number, toDate('2019-05-20')),
FROM system.numbers LIMIT 5 FORMAT TabSeparated;

(0,'2019-05-20')  \N
(1,'2019-05-20')  Первый
(2,'2019-05-20')  Второй
(3,'2019-05-20')  Третий
(4,'2019-05-20')  \N

dictGetString

Добавлена в версии: v1.1

Преобразует значение атрибута словаря в тип данных String независимо от конфигурации словаря.

Синтаксис

dictGetString(dict_name, attr_name, id_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или кортеж (в зависимости от конфигурации словаря). Expression или Tuple(T)

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

Примечание

Примеры

Пример использования

SELECT dictGetString('all_types_dict', 'String_value', 1)

┌─dictGetString(⋯_value', 1)─┐
│ test string                │
└────────────────────────────┘

dictGetStringOrDefault

Введена в версии: v1.1

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

Синтаксис

dictGetStringOrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или значение типа кортежа (в зависимости от конфигурации словаря). Expression или Tuple(T)
default_value_expr — Значение (или значения), возвращаемое, если в словаре нет строки с ключом id_expr. Expression или Tuple(T)

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

Примечание

Примеры

Пример использования

-- для существующего ключа
SELECT dictGetString('all_types_dict', 'String_value', 1);

-- для несуществующего ключа возвращается указанное значение по умолчанию
SELECT dictGetStringOrDefault('all_types_dict', 'String_value', 999, 'default');

┌─dictGetString(⋯_value', 1)─┐
│ test string                │
└────────────────────────────┘
┌─dictGetStringO⋯ 999, 'default')─┐
│ default                         │
└─────────────────────────────────┘

dictGetUInt16

Впервые появилась в версии v1.1

Преобразует значение атрибута словаря к типу данных UInt16 независимо от конфигурации словаря.

Синтаксис

dictGetUInt16(dict_name, attr_name, id_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или значение кортежа (в зависимости от конфигурации словаря). Expression или Tuple(T)

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

Примечание

Примеры

Пример использования

SELECT dictGetUInt16('all_types_dict', 'UInt16_value', 1)

┌─dictGetUInt1⋯_value', 1)─┐
│                     5000 │
└──────────────────────────┘

dictGetUInt16OrDefault

Впервые появилась в: v1.1

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

Синтаксис

dictGetUInt16OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или значение-кортеж (в зависимости от конфигурации словаря). Expression или Tuple(T)
default_value_expr — Значение или значения, возвращаемые, если словарь не содержит строку с ключом id_expr. Expression или Tuple(T)

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

Возвращает значение атрибута словаря, которое соответствует значению id_expr, в противном случае возвращает значение, переданное в параметре default_value_expr.

Примечание

Примеры

Пример использования

-- для существующего ключа
SELECT dictGetUInt16('all_types_dict', 'UInt16_value', 1);

-- для несуществующего ключа возвращается указанное значение по умолчанию (0)
SELECT dictGetUInt16OrDefault('all_types_dict', 'UInt16_value', 999, 0);

┌─dictGetUInt1⋯_value', 1)─┐
│                     5000 │
└──────────────────────────┘
┌─dictGetUInt1⋯e', 999, 0)─┐
│                        0 │
└──────────────────────────┘

dictGetUInt32

Добавлена в версии: v1.1

Преобразует значение атрибута словаря к типу данных UInt32 независимо от конфигурации словаря.

Синтаксис

dictGetUInt32(dict_name, attr_name, id_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или значение кортежа (в зависимости от конфигурации словаря). Expression или Tuple(T)

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

Примечание

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

Примеры

Пример использования

SELECT dictGetUInt32('all_types_dict', 'UInt32_value', 1)

┌─dictGetUInt3⋯_value', 1)─┐
│                  1000000 │
└──────────────────────────┘

dictGetUInt32OrDefault

Добавлено в версии: v1.1

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

Синтаксис

dictGetUInt32OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или кортеж значений (в зависимости от конфигурации словаря). Expression или Tuple(T)
default_value_expr — Значение (значения), возвращаемое, если в словаре нет строки с ключом id_expr. Expression или Tuple(T)

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

Примечание

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

Примеры

Пример использования

-- для существующего ключа
SELECT dictGetUInt32('all_types_dict', 'UInt32_value', 1);

-- для несуществующего ключа возвращается указанное значение по умолчанию (0)
SELECT dictGetUInt32OrDefault('all_types_dict', 'UInt32_value', 999, 0);

┌─dictGetUInt3⋯_value', 1)─┐
│                  1000000 │
└──────────────────────────┘
┌─dictGetUInt3⋯e', 999, 0)─┐
│                        0 │
└──────────────────────────┘

dictGetUInt64

Впервые представлена в версии v1.1

Преобразует значение атрибута словаря к типу данных UInt64 независимо от конфигурации словаря.

Синтаксис

dictGetUInt64(dict_name, attr_name, id_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или кортеж (в зависимости от конфигурации словаря). Expression или Tuple(T)

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

Примечание

Примеры

Пример использования

SELECT dictGetUInt64('all_types_dict', 'UInt64_value', 1)

┌─dictGetUInt6⋯_value', 1)─┐
│      9223372036854775807 │
└──────────────────────────┘

dictGetUInt64OrDefault

Добавлена в версии v1.1

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

Синтаксис

dictGetUInt64OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или кортеж (в зависимости от конфигурации словаря). Expression или Tuple(T)
default_value_expr — Значение (значения), возвращаемое, если словарь не содержит строку с ключом id_expr. Expression или Tuple(T)

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

Примечание

Примеры

Пример использования

-- для существующего ключа
SELECT dictGetUInt64('all_types_dict', 'UInt64_value', 1);

-- для несуществующего ключа возвращается заданное значение по умолчанию (0)
SELECT dictGetUInt64OrDefault('all_types_dict', 'UInt64_value', 999, 0);

┌─dictGetUInt6⋯_value', 1)─┐
│      9223372036854775807 │
└──────────────────────────┘
┌─dictGetUInt6⋯e', 999, 0)─┐
│                        0 │
└──────────────────────────┘

dictGetUInt8

Добавлена в версии v1.1

Преобразует значение атрибута словаря к типу данных UInt8 независимо от конфигурации словаря.

Синтаксис

dictGetUInt8(dict_name, attr_name, id_expr)

Параметры

dict_name — имя словаря. String
attr_name — имя столбца словаря. String или Tuple(String)
id_expr — значение ключа. Выражение, возвращающее значение типа ключа словаря или кортеж (в зависимости от конфигурации словаря). Expression или Tuple(T)

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

Примечание

Примеры

Пример использования

SELECT dictGetUInt8('all_types_dict', 'UInt8_value', 1)

┌─dictGetUInt8⋯_value', 1)─┐
│                      100 │
└──────────────────────────┘

dictGetUInt8OrDefault

Добавлена в версии v1.1

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

Синтаксис

dictGetUInt8OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, которое возвращает значение типа ключа словаря или кортеж значений (в зависимости от конфигурации словаря). Expression или Tuple(T)
default_value_expr — Значение или кортеж значений, возвращаемые, если словарь не содержит строки с ключом id_expr. Expression или Tuple(T)

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

Примечание

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

Примеры

Пример использования

-- для существующего ключа
SELECT dictGetUInt8('all_types_dict', 'UInt8_value', 1);

-- для несуществующего ключа возвращается указанное значение по умолчанию (0)
SELECT dictGetUInt8OrDefault('all_types_dict', 'UInt8_value', 999, 0);

┌─dictGetUInt8⋯_value', 1)─┐
│                      100 │
└──────────────────────────┘
┌─dictGetUInt8⋯e', 999, 0)─┐
│                        0 │
└──────────────────────────┘

dictGetUUID

Появилось в версии: v1.1

Преобразует значение атрибута словаря в тип данных UUID независимо от конфигурации словаря.

Синтаксис

dictGetUUID(dict_name, attr_name, id_expr)

Аргументы

dict_name — имя словаря. String
attr_name — имя столбца словаря. String или Tuple(String)
id_expr — значение ключа. Выражение, возвращающее значение типа ключа словаря или кортеж (в зависимости от конфигурации словаря). Expression или Tuple(T)

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

Возвращает значение атрибута словаря, которое соответствует id_expr, в противном случае возвращает содержимое элемента <null_value>, указанного для этого атрибута в конфигурации словаря.

Примечание

Примеры

Пример использования

SELECT dictGetUUID('all_types_dict', 'UUID_value', 1)

┌─dictGetUUID(⋯_value', 1)─────────────┐
│ 123e4567-e89b-12d3-a456-426614174000 │
└──────────────────────────────────────┘

dictGetUUIDOrDefault

Появилась в версии: v1.1

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

Синтаксис

dictGetUUIDOrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

dict_name — Имя словаря. String
attr_name — Имя столбца словаря. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение ключевого типа словаря или кортеж значений (в зависимости от конфигурации словаря). Expression или Tuple(T)
default_value_expr — Значение (значения), возвращаемое, если словарь не содержит строки с ключом id_expr. Expression или Tuple(T)

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

Возвращает значение атрибута словаря, которое соответствует id_expr, в противном случае возвращает значение, переданное в параметр default_value_expr.

Примечание

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

Примеры

Пример использования

-- для существующего ключа
SELECT dictGetUUID('all_types_dict', 'UUID_value', 1);

-- для несуществующего ключа возвращает переданное значение по умолчанию
SELECT dictGetUUIDOrDefault('all_types_dict', 'UUID_value', 999, '00000000-0000-0000-0000-000000000000'::UUID);

┌─dictGetUUID('all_t⋯ 'UUID_value', 1)─┐
│ 550e8400-e29b-41d4-a716-446655440000 │
└──────────────────────────────────────┘
┌─dictGetUUIDOrDefa⋯000000000000'::UUID)─┐
│ 00000000-0000-0000-0000-000000000000   │
└────────────────────────────────────────┘

dictHas

Добавлена в версии: v1.1

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

Синтаксис

dictHas('dict_name', id_expr)

Аргументы

dict_name — Имя словаря. String
id_expr — Значение ключа. const String

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

Возвращает 1, если ключ существует, иначе 0. UInt8

Примеры

Проверка существования ключа в словаре

-- рассмотрим следующий иерархический словарь:
-- 0 (Корень)
-- └── 1 (Уровень 1 - Узел 1)
--     ├── 2 (Уровень 2 - Узел 2)
--     │   ├── 4 (Уровень 3 - Узел 4)
--     │   └── 5 (Уровень 3 - Узел 5)
--     └── 3 (Уровень 2 - Узел 3)
--         └── 6 (Уровень 3 - Узел 6)

SELECT dictHas('hierarchical_dictionary', 2);
SELECT dictHas('hierarchical_dictionary', 7);

┌─dictHas('hie⋯ionary', 2)─┐
│                        1 │
└──────────────────────────┘
┌─dictHas('hie⋯ionary', 7)─┐
│                        0 │
└──────────────────────────┘

dictIsIn

Появилась в версии: v1.1

Проверяет наличие предка ключа по всей иерархической цепочке в словаре.

Синтаксис

dictIsIn(dict_name, child_id_expr, ancestor_id_expr)

Аргументы

dict_name — имя словаря. String
child_id_expr — ключ, подлежащий проверке. String
ancestor_id_expr — предполагаемый предок ключа child_id_expr. const String

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

Возвращает 0, если child_id_expr не является потомком ancestor_id_expr, и 1, если child_id_expr является потомком ancestor_id_expr или если child_id_expr равен ancestor_id_expr. UInt8

Примеры

Проверка иерархического отношения

-- корректная иерархия
SELECT dictIsIn('hierarchical_dictionary', 6, 3)

-- некорректная иерархия
SELECT dictIsIn('hierarchical_dictionary', 3, 5)

┌─dictIsIn('hi⋯ary', 6, 3)─┐
│                        1 │
└──────────────────────────┘
┌─dictIsIn('hi⋯ary', 3, 5)─┐
│                        0 │
└──────────────────────────┘

dictGet, dictGetOrDefault, dictGetOrNull​

dictHas​

dictGetHierarchy​

dictIsIn​

dictGetChildren​

dictGetDescendant​

dictGetAll​

dictGetKeys​

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

Примеры словарей​

dictGet​

dictGetAll​

dictGetChildren​

dictGetDate​

dictGetDateOrDefault​

dictGetDateTime​

dictGetDateTimeOrDefault​

dictGetDescendants​

dictGetFloat32​

dictGetFloat32OrDefault​

dictGetFloat64​

dictGetFloat64OrDefault​

dictGetHierarchy​

dictGetIPv4​

dictGetIPv4OrDefault​

dictGetIPv6​

dictGetIPv6OrDefault​

dictGetInt16​

dictGetInt16OrDefault​

dictGetInt32​

dictGetInt32OrDefault​

dictGetInt64​

dictGetInt64OrDefault​

dictGetInt8​

dictGetInt8OrDefault​

dictGetKeys​

dictGetOrDefault​

dictGetOrNull​

dictGetString​

dictGetStringOrDefault​

dictGetUInt16​

dictGetUInt16OrDefault​

dictGetUInt32​

dictGetUInt32OrDefault​

dictGetUInt64​

dictGetUInt64OrDefault​

dictGetUInt8​

dictGetUInt8OrDefault​

dictGetUUID​

dictGetUUIDOrDefault​

dictHas​

dictIsIn​

dictGet, dictGetOrDefault, dictGetOrNull

dictHas

dictGetHierarchy

dictIsIn

dictGetChildren

dictGetDescendant

dictGetAll

dictGetKeys

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

Примеры словарей

dictGet

dictGetAll

dictGetChildren

dictGetDate

dictGetDateOrDefault

dictGetDateTime

dictGetDateTimeOrDefault

dictGetDescendants

dictGetFloat32

dictGetFloat32OrDefault

dictGetFloat64

dictGetFloat64OrDefault

dictGetHierarchy

dictGetIPv4

dictGetIPv4OrDefault

dictGetIPv6

dictGetIPv6OrDefault

dictGetInt16

dictGetInt16OrDefault

dictGetInt32

dictGetInt32OrDefault

dictGetInt64

dictGetInt64OrDefault

dictGetInt8

dictGetInt8OrDefault

dictGetKeys

dictGetOrDefault

dictGetOrNull

dictGetString

dictGetStringOrDefault

dictGetUInt16

dictGetUInt16OrDefault

dictGetUInt32

dictGetUInt32OrDefault

dictGetUInt64

dictGetUInt64OrDefault

dictGetUInt8

dictGetUInt8OrDefault

dictGetUUID

dictGetUUIDOrDefault

dictHas

dictIsIn