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

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

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

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

В примерах этого раздела используются следующие словари. Вы можете создать их в 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);

Передача ключей в функции словаря

Аргумент ключа (id_expr) в таких функциях, как dictGet, dictGetOrDefault, dictGetOrNull и dictHas, зависит от ключа словаря:

Для словаря с простым ключом (UInt64) передайте значение ключа напрямую:

SELECT dictGet('simple_key_dictionary', 'attr_name', toUInt64(1));

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

SELECT dictGet('complex_key_dictionary', 'attr_name', ('value_for_field1', 42));

Когда составной ключ состоит из одного атрибута, значение ключа можно передавать напрямую, не оборачивая его в tuple. Оба следующих варианта допустимы и эквивалентны:

SELECT dictGet('complex_key_dictionary', 'attr_name', 'key');
SELECT dictGet('complex_key_dictionary', 'attr_name', tuple('key'));

Это также относится к словарям ip_trie, у которых ключом служит один атрибут. IP-адрес для поиска можно передать напрямую:

SELECT dictGet('ip_trie_dictionary', 'attr_name', toIPv4('202.79.32.10'));

dictGet

Добавленный в: v18.16.0 Возвращает значения из словаря.

Эта функция недетерминирована: она может возвращать разные результаты для одних и тех же аргументов.

Синтаксис

dictGet('dict_name', attr_names, id_expr)

Аргументы

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

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

Query

CREATE TABLE ext_dict_test_source (id UInt32, c1 UInt32, c2 String) ENGINE = Memory;
INSERT INTO ext_dict_test_source VALUES (1, 1, '1'), (2, 2, '2'), (3, 3, '3');
CREATE DICTIONARY ext_dict_test (id UInt32, c1 UInt32, c2 String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'ext_dict_test_source' DB currentDatabase())) LAYOUT(FLAT()) LIFETIME(MIN 0 MAX 0);
SELECT dictGet('ext_dict_test', 'c1', toUInt64(1)) AS val

Response

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

Query

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(TABLE 'dict_mult_source' DB currentDatabase())) LAYOUT(FLAT()) LIFETIME(MIN 0 MAX 0);
SELECT
    dictGet('ext_dict_mult', ('c1','c2'), number + 1) AS val,
    toTypeName(val) AS type
FROM system.numbers
LIMIT 3;

Response

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

dictGetAll

Добавленный в: v23.5.0 Возвращает значения атрибутов всех узлов, совпавших с каждым ключом в словаре дерева регулярных выражений. За исключением того, что эта функция возвращает значения типа Array(T) вместо T, она ведёт себя аналогично dictGet.

Эта функция недетерминирована: она может возвращать разные результаты для одних и тех же аргументов.

Синтаксис

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

Аргументы

dict_name — Имя словаря. String
attr_names — Имя столбца словаря или кортеж имён столбцов. String или Tuple(String)
id_expr — Значение ключа. Выражение, возвращающее значение типа ключа словаря или значение кортежа (в зависимости от конфигурации словаря). Expression или Tuple(T)
limit — Необязательно. Максимальная длина каждого возвращаемого массива значений. При усечении дочерним узлам отдаётся приоритет перед родительскими; в остальных случаях соблюдается заданный порядок элементов в словаре дерева регулярных выражений. Если не указано, длина массива не ограничена. UInt*

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

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

Array(T) Примеры Пример использования

Query

CREATE TABLE regexp_os (id UInt64, parent_id UInt64, regexp String, keys Array(String), values Array(String)) ENGINE = Memory;
INSERT INTO regexp_os VALUES
    (1, 0, 'Linux',      ['os_replacement'], ['Linux']),
    (2, 1, 'Android',    ['os_replacement'], ['Android']),
    (3, 2, 'Android 1',  ['os_replacement'], ['Android']),
    (4, 3, 'Android 12', ['os_replacement'], ['Android']);
CREATE DICTIONARY regexp_tree (regexp String, os_replacement String DEFAULT 'Other') PRIMARY KEY regexp SOURCE(CLICKHOUSE(TABLE 'regexp_os' DB currentDatabase())) LIFETIME(MIN 0 MAX 0) LAYOUT(REGEXP_TREE);
SELECT
    'Mozilla/5.0 (Linux; Android 12; SM-G998B) Mobile Safari/537.36' AS user_agent,

    -- This will match ALL applicable patterns
    dictGetAll('regexp_tree', 'os_replacement', 'Mozilla/5.0 (Linux; Android 12; SM-G998B) Mobile Safari/537.36') AS all_matches,

    -- This returns only the first match
    dictGet('regexp_tree', 'os_replacement', 'Mozilla/5.0 (Linux; Android 12; SM-G998B) Mobile Safari/537.36') AS first_match;

Response

┌─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.0 Возвращает дочерние элементы первого уровня в виде массива индексов. Это преобразование, обратное dictGetHierarchy.

Эта функция является недетерминированной: она может возвращать разные результаты для одних и тех же аргументов.

Синтаксис

dictGetChildren(dict_name, key)

Аргументы

dict_name — Имя словаря. String
key — Проверяемый ключ. const String

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

Query

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');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetChildren('hierarchical_dictionary', 2);

Response

┌─dictGetChildren('hierarchical_dictionary', 2)─┐
│ [4,5]                                         │
└───────────────────────────────────────────────┘

dictGetDate

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

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

Query

CREATE TABLE all_types_test (id UInt32, Date_value Date) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '2020-01-01');
CREATE DICTIONARY all_types_dict (id UInt32, Date_value Date) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetDate('all_types_dict', 'Date_value', 1)

Response

┌─dictGetDate('all_types_dict', 'Date_value', 1)─┐
│                                     2020-01-01 │
└────────────────────────────────────────────────┘

dictGetDateOrDefault

Добавленный в: v1.1.0 Преобразует значение атрибута словаря в тип данных 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.

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

Query

CREATE TABLE all_types_test (id UInt32, Date_value Date) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '2024-01-15');
CREATE DICTIONARY all_types_dict (id UInt32, Date_value Date) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetDate('all_types_dict', 'Date_value', 1);

-- for key which does not exist, returns the provided default value
SELECT dictGetDateOrDefault('all_types_dict', 'Date_value', 999, toDate('1970-01-01'));

Response

┌─dictGetDate('all_types_dict', 'Date_value', 1)─┐
│                                     2024-01-15 │
└────────────────────────────────────────────────┘
┌─dictGetDateOrDefault('all_types_dict', 'Date_value', 999, toDate('1970-01-01'))─┐
│                                                                      1970-01-01 │
└─────────────────────────────────────────────────────────────────────────────────┘

dictGetDateTime

Добавленный в: v1.1.0 Преобразует значение атрибута словаря в тип данных 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>, указанное для этого атрибута в конфигурации словаря.

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

Query

CREATE TABLE all_types_test (id UInt32, DateTime_value DateTime) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '2024-01-15 10:30:00');
CREATE DICTIONARY all_types_dict (id UInt32, DateTime_value DateTime) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetDateTime('all_types_dict', 'DateTime_value', 1)

Response

┌─dictGetDateTime('all_types_dict', 'DateTime_value', 1)─┐
│                                    2024-01-15 10:30:00 │
└────────────────────────────────────────────────────────┘

dictGetDateTimeOrDefault

Добавленный в: v1.1.0 Преобразует значение атрибута словаря в тип данных 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)

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

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

Query

CREATE TABLE all_types_test (id UInt32, DateTime_value DateTime) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '2024-01-15 10:30:00');
CREATE DICTIONARY all_types_dict (id UInt32, DateTime_value DateTime) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetDateTime('all_types_dict', 'DateTime_value', 1);

-- for key which does not exist, returns the provided default value
SELECT dictGetDateTimeOrDefault('all_types_dict', 'DateTime_value', 999, toDateTime('1970-01-01 00:00:00'));

Response

┌─dictGetDateTime('all_types_dict', 'DateTime_value', 1)─┐
│                                    2024-01-15 10:30:00 │
└────────────────────────────────────────────────────────┘
┌─dictGetDateTimeOrDefault('all_types_dict', 'DateTime_value', 999, toDateTime('1970-01-01 00:00:00'))─┐
│                                                                                  1970-01-01 00:00:00 │
└──────────────────────────────────────────────────────────────────────────────────────────────────────┘

dictGetDescendants

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

Синтаксис

dictGetDescendants(dict_name, key, level)

Аргументы

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

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

Query

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');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- consider the following hierarchical dictionary:
-- 0 (Root)
-- └── 1 (Level 1 - Node 1)
--     ├── 2 (Level 2 - Node 2)
--     │   ├── 4 (Level 3 - Node 4)
--     │   └── 5 (Level 3 - Node 5)
--     └── 3 (Level 2 - Node 3)
--         └── 6 (Level 3 - Node 6)

SELECT dictGetDescendants('hierarchical_dictionary', 0, 2)

Response

┌─dictGetDescendants('hierarchical_dictionary', 0, 2)─┐
│ [3,2]                                               │
└─────────────────────────────────────────────────────┘

dictGetFloat32

Добавленный в: v1.1.0 Преобразует значение атрибута словаря в тип данных 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>, указанного для атрибута в конфигурации словаря.

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

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

Query

CREATE TABLE all_types_test (id UInt32, Float32_value Float32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -123.123);
CREATE DICTIONARY all_types_dict (id UInt32, Float32_value Float32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetFloat32('all_types_dict', 'Float32_value', 1)

Response

┌─dictGetFloat32('all_types_dict', 'Float32_value', 1)─┐
│                                             -123.123 │
└──────────────────────────────────────────────────────┘

dictGetFloat32OrDefault

Добавленный в: v1.1.0 Преобразует значение атрибута словаря в тип данных 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, если такого ключа в словаре нет.

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

Query

CREATE TABLE all_types_test (id UInt32, Float32_value Float32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 123.45);
CREATE DICTIONARY all_types_dict (id UInt32, Float32_value Float32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetFloat32('all_types_dict', 'Float32_value', 1);

-- for key which does not exist, returns the provided default value (-1.0)
SELECT dictGetFloat32OrDefault('all_types_dict', 'Float32_value', 999, -1.0);

Response

┌─dictGetFloat32('all_types_dict', 'Float32_value', 1)─┐
│                                               123.45 │
└──────────────────────────────────────────────────────┘
┌─dictGetFloat32OrDefault('all_types_dict', 'Float32_value', 999, -1.)─┐
│                                                                   -1 │
└──────────────────────────────────────────────────────────────────────┘

dictGetFloat64

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

Синтаксис

dictGetFloat64(dict_name, attr_name, id_expr)

Аргументы

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

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

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

Query

CREATE TABLE all_types_test (id UInt32, Float64_value Float64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -123.123);
CREATE DICTIONARY all_types_dict (id UInt32, Float64_value Float64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetFloat64('all_types_dict', 'Float64_value', 1)

Response

┌─dictGetFloat64('all_types_dict', 'Float64_value', 1)─┐
│                                             -123.123 │
└──────────────────────────────────────────────────────┘

dictGetFloat64OrDefault

Добавленный в: v1.1.0 Преобразует значение атрибута словаря в тип данных 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)

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

Query

CREATE TABLE all_types_test (id UInt32, Float64_value Float64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 987654.123456);
CREATE DICTIONARY all_types_dict (id UInt32, Float64_value Float64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetFloat64('all_types_dict', 'Float64_value', 1);

-- for key which does not exist, returns the provided default value (nan)
SELECT dictGetFloat64OrDefault('all_types_dict', 'Float64_value', 999, nan);

Response

┌─dictGetFloat64('all_types_dict', 'Float64_value', 1)─┐
│                                        987654.123456 │
└──────────────────────────────────────────────────────┘
┌─dictGetFloat64OrDefault('all_types_dict', 'Float64_value', 999, nan)─┐
│                                                                  nan │
└──────────────────────────────────────────────────────────────────────┘

dictGetHierarchy

Добавленный в: v1.1.0 Создает массив, содержащий всех предков ключа в иерархическом словаре.

Синтаксис

dictGetHierarchy(dict_name, key)

Аргументы

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

Возвращаемое значение Возвращает родительские узлы для ключа. Array(UInt64) Примеры Получение иерархии для ключа

Query

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');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetHierarchy('hierarchical_dictionary', 5)

Response

┌─dictGetHierarchy('hierarchical_dictionary', 5)─┐
│ [5,2,1]                                        │
└────────────────────────────────────────────────┘

dictGetIPv4

Добавленный в: v1.1.0 Преобразует значение атрибута словаря в тип данных 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>, указанного для атрибута в конфигурации словаря.

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

Query

CREATE TABLE all_types_test (id UInt32, IPv4_value IPv4) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '192.168.0.1');
CREATE DICTIONARY all_types_dict (id UInt32, IPv4_value IPv4) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetIPv4('all_types_dict', 'IPv4_value', 1)

Response

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

dictGetIPv4OrDefault

Добавленный в: v23.1.0 Преобразует значение атрибута словаря в тип данных 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)

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

Query

CREATE TABLE all_types_test (id UInt32, IPv4_value IPv4) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '192.168.0.1');
CREATE DICTIONARY all_types_dict (id UInt32, IPv4_value IPv4) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetIPv4('all_types_dict', 'IPv4_value', 1);

-- for key which does not exist, returns the provided default value
SELECT dictGetIPv4OrDefault('all_types_dict', 'IPv4_value', 999, toIPv4('0.0.0.0'));

Response

┌─dictGetIPv4('all_types_dict', 'IPv4_value', 1)─┐
│ 192.168.0.1                                    │
└────────────────────────────────────────────────┘
┌─dictGetIPv4OrDefault('all_types_dict', 'IPv4_value', 999, toIPv4('0.0.0.0'))─┐
│ 0.0.0.0                                                                      │
└──────────────────────────────────────────────────────────────────────────────┘

dictGetIPv6

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

Синтаксис

dictGetIPv6(dict_name, attr_name, id_expr)

Аргументы

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

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

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

Query

CREATE TABLE all_types_test (id UInt32, IPv6_value IPv6) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '2001:db8:85a3::8a2e:370:7334');
CREATE DICTIONARY all_types_dict (id UInt32, IPv6_value IPv6) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetIPv6('all_types_dict', 'IPv6_value', 1)

Response

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

dictGetIPv6OrDefault

Добавленный в: v23.1.0 Преобразует значение атрибута словаря в тип данных 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)

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

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

Query

CREATE TABLE all_types_test (id UInt32, IPv6_value IPv6) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '2001:db8:85a3::8a2e:370:7334');
CREATE DICTIONARY all_types_dict (id UInt32, IPv6_value IPv6) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetIPv6('all_types_dict', 'IPv6_value', 1);

-- for key which does not exist, returns the provided default value
SELECT dictGetIPv6OrDefault('all_types_dict', 'IPv6_value', 999, '::1'::IPv6);

Response

┌─dictGetIPv6('all_types_dict', 'IPv6_value', 1)─┐
│ 2001:db8:85a3::8a2e:370:7334                   │
└────────────────────────────────────────────────┘
┌─dictGetIPv6OrDefault('all_types_dict', 'IPv6_value', 999, CAST('::1', 'IPv6'))─┐
│ ::1                                                                            │
└────────────────────────────────────────────────────────────────────────────────┘

dictGetInt16

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

Эта функция недетерминирована: она может возвращать разные результаты для одних и тех же аргументов.

Синтаксис

dictGetInt16(dict_name, attr_name, id_expr)

Аргументы

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

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

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

Query

CREATE TABLE all_types_test (id UInt32, Int16_value Int16) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -5000);
CREATE DICTIONARY all_types_dict (id UInt32, Int16_value Int16) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetInt16('all_types_dict', 'Int16_value', 1)

Response

┌─dictGetInt16('all_types_dict', 'Int16_value', 1)─┐
│                                            -5000 │
└──────────────────────────────────────────────────┘

dictGetInt16OrDefault

Добавленный в: v1.1.0 Преобразует значение атрибута словаря в тип данных 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)

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

Query

CREATE TABLE all_types_test (id UInt32, Int16_value Int16) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -5000);
CREATE DICTIONARY all_types_dict (id UInt32, Int16_value Int16) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetInt16('all_types_dict', 'Int16_value', 1);

-- for key which does not exist, returns the provided default value (-1)
SELECT dictGetInt16OrDefault('all_types_dict', 'Int16_value', 999, -1);

Response

┌─dictGetInt16('all_types_dict', 'Int16_value', 1)─┐
│                                            -5000 │
└──────────────────────────────────────────────────┘
┌─dictGetInt16OrDefault('all_types_dict', 'Int16_value', 999, -1)─┐
│                                                              -1 │
└─────────────────────────────────────────────────────────────────┘

dictGetInt32

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

Синтаксис

dictGetInt32(dict_name, attr_name, id_expr)

Аргументы

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

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

Query

CREATE TABLE all_types_test (id UInt32, Int32_value Int32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -1000000);
CREATE DICTIONARY all_types_dict (id UInt32, Int32_value Int32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetInt32('all_types_dict', 'Int32_value', 1)

Response

┌─dictGetInt32('all_types_dict', 'Int32_value', 1)─┐
│                                         -1000000 │
└──────────────────────────────────────────────────┘

dictGetInt32OrDefault

Добавленный в: v1.1.0 Преобразует значение атрибута словаря в тип данных 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)

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

Query

CREATE TABLE all_types_test (id UInt32, Int32_value Int32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -1000000);
CREATE DICTIONARY all_types_dict (id UInt32, Int32_value Int32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetInt32('all_types_dict', 'Int32_value', 1);

-- for key which does not exist, returns the provided default value (-1)
SELECT dictGetInt32OrDefault('all_types_dict', 'Int32_value', 999, -1);

Response

┌─dictGetInt32('all_types_dict', 'Int32_value', 1)─┐
│                                         -1000000 │
└──────────────────────────────────────────────────┘
┌─dictGetInt32OrDefault('all_types_dict', 'Int32_value', 999, -1)─┐
│                                                              -1 │
└─────────────────────────────────────────────────────────────────┘

dictGetInt64

Добавленный в: v1.1.0 Преобразует значение атрибута словаря к типу данных 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>, заданного для атрибута в конфигурации словаря.

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

Query

CREATE TABLE all_types_test (id UInt32, Int64_value Int64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -9223372036854775807);
CREATE DICTIONARY all_types_dict (id UInt32, Int64_value Int64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetInt64('all_types_dict', 'Int64_value', 1)

Response

┌─dictGetInt64('all_types_dict', 'Int64_value', 1)─┐
│                             -9223372036854775807 │
└──────────────────────────────────────────────────┘

dictGetInt64OrDefault

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

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

Query

CREATE TABLE all_types_test (id UInt32, Int64_value Int64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -9223372036854775808);
CREATE DICTIONARY all_types_dict (id UInt32, Int64_value Int64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetInt64('all_types_dict', 'Int64_value', 1);

-- for key which does not exist, returns the provided default value (-1)
SELECT dictGetInt64OrDefault('all_types_dict', 'Int64_value', 999, -1);

Response

┌─dictGetInt64('all_types_dict', 'Int64_value', 1)─┐
│                             -9223372036854775808 │
└──────────────────────────────────────────────────┘
┌─dictGetInt64OrDefault('all_types_dict', 'Int64_value', 999, -1)─┐
│                                                              -1 │
└─────────────────────────────────────────────────────────────────┘

dictGetInt8

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

Синтаксис

dictGetInt8(dict_name, attr_name, id_expr)

Аргументы

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

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

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

Query

CREATE TABLE all_types_test (id UInt32, Int8_value Int8) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -100);
CREATE DICTIONARY all_types_dict (id UInt32, Int8_value Int8) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetInt8('all_types_dict', 'Int8_value', 1)

Response

┌─dictGetInt8('all_types_dict', 'Int8_value', 1)─┐
│                                           -100 │
└────────────────────────────────────────────────┘

dictGetInt8OrDefault

Добавленный в: v1.1.0 Преобразует значение атрибута словаря в тип данных 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)

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

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

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

Query

CREATE TABLE all_types_test (id UInt32, Int8_value Int8) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -100);
CREATE DICTIONARY all_types_dict (id UInt32, Int8_value Int8) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetInt8('all_types_dict', 'Int8_value', 1);

-- for key which does not exist, returns the provided default value (-1)
SELECT dictGetInt8OrDefault('all_types_dict', 'Int8_value', 999, -1);

Response

┌─dictGetInt8('all_types_dict', 'Int8_value', 1)─┐
│                                           -100 │
└────────────────────────────────────────────────┘
┌─dictGetInt8OrDefault('all_types_dict', 'Int8_value', 999, -1)─┐
│                                                            -1 │
└───────────────────────────────────────────────────────────────┘

dictGetKeys

Добавленный в: v25.12.0 Возвращает ключ или ключи словаря, атрибут которых равен указанному значению. Это обратная функция к dictGet для одного атрибута. Используйте настройку 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 генерирует исключение, если не может разобрать значение атрибута или если это значение нельзя преобразовать к типу данных атрибута. Примеры Пример использования

Query

CREATE TABLE task_priority_source (task_id UInt64, priority_level String) ENGINE = Memory;
INSERT INTO task_priority_source VALUES (1, 'low'), (2, 'high'), (3, 'medium'), (4, 'high');
CREATE DICTIONARY task_id_to_priority_dictionary (task_id UInt64, priority_level String) PRIMARY KEY task_id SOURCE(CLICKHOUSE(TABLE 'task_priority_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 0 MAX 0);
SELECT arraySort(dictGetKeys('task_id_to_priority_dictionary', 'priority_level', 'high')) AS ids;

Response

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

dictGetOrDefault

Добавленный в: v18.16.0 Возвращает значения из словаря; если ключ не найден, используется значение по умолчанию.

Эта функция недетерминирована: она может возвращать разные результаты для одних и тех же аргументов.

Синтаксис

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

Аргументы

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

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

Query

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(TABLE 'dict_mult_source' DB currentDatabase())) LAYOUT(FLAT()) LIFETIME(MIN 0 MAX 0);
SELECT dictGetOrDefault('ext_dict_mult', 'c1', toUInt64(999), 0) AS val

Response

dictGetOrNull

Добавленный в: v21.4.0 Возвращает значения из словаря; если ключ не найден, возвращает NULL.

Синтаксис

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

Аргументы

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

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

Query

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(TABLE 'range_key_dictionary_source_table' DB currentDatabase())) LIFETIME(MIN 1 MAX 1000) LAYOUT(RANGE_HASHED()) RANGE(MIN start_date MAX end_date);
SELECT
    (number, toDate('2019-05-20')),
    dictGetOrNull('range_key_dictionary', 'value', number, toDate('2019-05-20')),
FROM system.numbers LIMIT 5 FORMAT TabSeparated;

Response

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

dictGetRoot

Добавленный в: v26.7.0 Возвращает самого верхнего предка (корень) ключа в иерархическом словаре. Это удобный эквивалент получения последнего элемента массива, возвращаемого dictGetHierarchy, то есть dictGetHierarchy(dict_name, key)[-1]. Если ключ сам является узлом верхнего уровня в иерархии, возвращается этот же ключ. Если ключ отсутствует в словаре, возвращается 0.

Эта функция недетерминирована: она может возвращать разные результаты для одних и тех же аргументов.

Синтаксис

dictGetRoot(dict_name, key)

Аргументы

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

Возвращаемое значение Возвращает корневого предка для ключа. UInt64 Примеры Получение корня для ключа

Query

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');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetRoot('hierarchical_dictionary', 5)

Response

┌─dictGetRoot('hierarchical_dictionary', 5)─┐
│                                         1 │
└───────────────────────────────────────────┘

dictGetString

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

Синтаксис

dictGetString(dict_name, attr_name, id_expr)

Аргументы

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

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

Query

CREATE TABLE all_types_test (id UInt32, String_value String) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 'test string');
CREATE DICTIONARY all_types_dict (id UInt32, String_value String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetString('all_types_dict', 'String_value', 1)

Response

┌─dictGetString('all_types_dict', 'String_value', 1)─┐
│ test string                                        │
└────────────────────────────────────────────────────┘

dictGetStringOrDefault

Добавленный в: v1.1.0 Преобразует значение атрибута словаря в тип данных 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)

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

Query

CREATE TABLE all_types_test (id UInt32, String_value String) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 'test string');
CREATE DICTIONARY all_types_dict (id UInt32, String_value String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetString('all_types_dict', 'String_value', 1);

-- for key which does not exist, returns the provided default value
SELECT dictGetStringOrDefault('all_types_dict', 'String_value', 999, 'default');

Response

┌─dictGetString('all_types_dict', 'String_value', 1)─┐
│ test string                                        │
└────────────────────────────────────────────────────┘
┌─dictGetStringOrDefault('all_types_dict', 'String_value', 999, 'default')─┐
│ default                                                                  │
└──────────────────────────────────────────────────────────────────────────┘

dictGetUInt16

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

Эта функция недетерминирована: она может возвращать разные результаты для одних и тех же аргументов.

Синтаксис

dictGetUInt16(dict_name, attr_name, id_expr)

Аргументы

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

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

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

Query

CREATE TABLE all_types_test (id UInt32, UInt16_value UInt16) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 5000);
CREATE DICTIONARY all_types_dict (id UInt32, UInt16_value UInt16) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetUInt16('all_types_dict', 'UInt16_value', 1)

Response

┌─dictGetUInt16('all_types_dict', 'UInt16_value', 1)─┐
│                                               5000 │
└────────────────────────────────────────────────────┘

dictGetUInt16OrDefault

Добавленный в: v1.1.0 Преобразует значение атрибута словаря в тип данных 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)

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

Query

CREATE TABLE all_types_test (id UInt32, UInt16_value UInt16) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 5000);
CREATE DICTIONARY all_types_dict (id UInt32, UInt16_value UInt16) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetUInt16('all_types_dict', 'UInt16_value', 1);

-- for key which does not exist, returns the provided default value (0)
SELECT dictGetUInt16OrDefault('all_types_dict', 'UInt16_value', 999, 0);

Response

┌─dictGetUInt16('all_types_dict', 'UInt16_value', 1)─┐
│                                               5000 │
└────────────────────────────────────────────────────┘
┌─dictGetUInt16OrDefault('all_types_dict', 'UInt16_value', 999, 0)─┐
│                                                                0 │
└──────────────────────────────────────────────────────────────────┘

dictGetUInt32

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

Эта функция недетерминирована: она может возвращать разные результаты для одних и тех же аргументов.

Синтаксис

dictGetUInt32(dict_name, attr_name, id_expr)

Аргументы

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

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

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

Query

CREATE TABLE all_types_test (id UInt32, UInt32_value UInt32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 1000000);
CREATE DICTIONARY all_types_dict (id UInt32, UInt32_value UInt32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetUInt32('all_types_dict', 'UInt32_value', 1)

Response

┌─dictGetUInt32('all_types_dict', 'UInt32_value', 1)─┐
│                                            1000000 │
└────────────────────────────────────────────────────┘

dictGetUInt32OrDefault

Добавленный в: v1.1.0 Преобразует значение атрибута словаря в тип данных 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)

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

Query

CREATE TABLE all_types_test (id UInt32, UInt32_value UInt32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 1000000);
CREATE DICTIONARY all_types_dict (id UInt32, UInt32_value UInt32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetUInt32('all_types_dict', 'UInt32_value', 1);

-- for key which does not exist, returns the provided default value (0)
SELECT dictGetUInt32OrDefault('all_types_dict', 'UInt32_value', 999, 0);

Response

┌─dictGetUInt32('all_types_dict', 'UInt32_value', 1)─┐
│                                            1000000 │
└────────────────────────────────────────────────────┘
┌─dictGetUInt32OrDefault('all_types_dict', 'UInt32_value', 999, 0)─┐
│                                                                0 │
└──────────────────────────────────────────────────────────────────┘

dictGetUInt64

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

Синтаксис

dictGetUInt64(dict_name, attr_name, id_expr)

Аргументы

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

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

Query

CREATE TABLE all_types_test (id UInt32, UInt64_value UInt64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 9223372036854775807);
CREATE DICTIONARY all_types_dict (id UInt32, UInt64_value UInt64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetUInt64('all_types_dict', 'UInt64_value', 1)

Response

┌─dictGetUInt64('all_types_dict', 'UInt64_value', 1)─┐
│                                9223372036854775807 │
└────────────────────────────────────────────────────┘

dictGetUInt64OrDefault

Добавленный в: v1.1.0 Преобразует значение атрибута словаря в тип данных 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)

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

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

Query

CREATE TABLE all_types_test (id UInt32, UInt64_value UInt64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 9223372036854775807);
CREATE DICTIONARY all_types_dict (id UInt32, UInt64_value UInt64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetUInt64('all_types_dict', 'UInt64_value', 1);

-- for key which does not exist, returns the provideddefault value (0)
SELECT dictGetUInt64OrDefault('all_types_dict', 'UInt64_value', 999, 0);

Response

┌─dictGetUInt64('all_types_dict', 'UInt64_value', 1)─┐
│                                9223372036854775807 │
└────────────────────────────────────────────────────┘
┌─dictGetUInt64OrDefault('all_types_dict', 'UInt64_value', 999, 0)─┐
│                                                                0 │
└──────────────────────────────────────────────────────────────────┘

dictGetUInt8

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

Эта функция недетерминирована: она может возвращать разные результаты для одних и тех же аргументов.

Синтаксис

dictGetUInt8(dict_name, attr_name, id_expr)

Аргументы

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

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

Query

CREATE TABLE all_types_test (id UInt32, UInt8_value UInt8) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 100);
CREATE DICTIONARY all_types_dict (id UInt32, UInt8_value UInt8) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetUInt8('all_types_dict', 'UInt8_value', 1)

Response

┌─dictGetUInt8('all_types_dict', 'UInt8_value', 1)─┐
│                                              100 │
└──────────────────────────────────────────────────┘

dictGetUInt8OrDefault

Добавленный в: v1.1.0 Преобразует значение атрибута словаря в тип данных 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)

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

Query

CREATE TABLE all_types_test (id UInt32, UInt8_value UInt8) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 100);
CREATE DICTIONARY all_types_dict (id UInt32, UInt8_value UInt8) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetUInt8('all_types_dict', 'UInt8_value', 1);

-- for key which does not exist, returns the provided default value (0)
SELECT dictGetUInt8OrDefault('all_types_dict', 'UInt8_value', 999, 0);

Response

┌─dictGetUInt8('all_types_dict', 'UInt8_value', 1)─┐
│                                              100 │
└──────────────────────────────────────────────────┘
┌─dictGetUInt8OrDefault('all_types_dict', 'UInt8_value', 999, 0)─┐
│                                                              0 │
└────────────────────────────────────────────────────────────────┘

dictGetUUID

Добавленный в: v1.1.0 Преобразует значение атрибута словаря в тип данных 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>, указанного для этого атрибута в конфигурации словаря.

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

Query

CREATE TABLE all_types_test (id UInt32, UUID_value UUID) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '123e4567-e89b-12d3-a456-426614174000');
CREATE DICTIONARY all_types_dict (id UInt32, UUID_value UUID) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetUUID('all_types_dict', 'UUID_value', 1)

Response

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

dictGetUUIDOrDefault

Добавленный в: v1.1.0 Преобразует значение атрибута словаря в тип данных 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.

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

Query

CREATE TABLE all_types_test (id UInt32, UUID_value UUID) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '550e8400-e29b-41d4-a716-446655440000');
CREATE DICTIONARY all_types_dict (id UInt32, UUID_value UUID) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetUUID('all_types_dict', 'UUID_value', 1);

-- for key which does not exist, returns the provided default value
SELECT dictGetUUIDOrDefault('all_types_dict', 'UUID_value', 999, '00000000-0000-0000-0000-000000000000'::UUID);

Response

┌─dictGetUUID('all_types_dict', 'UUID_value', 1)─┐
│ 550e8400-e29b-41d4-a716-446655440000           │
└────────────────────────────────────────────────┘
┌─dictGetUUIDOrDefault('all_types_dict', 'UUID_value', 999, CAST('00000000-0000-0000-0000-000000000000', 'UUID'))─┐
│ 00000000-0000-0000-0000-000000000000                                                                            │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

dictHas

Добавленный в: v1.1.0 Проверяет, содержится ли ключ в словаре.

Синтаксис

dictHas('dict_name', id_expr)

Аргументы

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

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

Query

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');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- consider the following hierarchical dictionary:
-- 0 (Root)
-- └── 1 (Level 1 - Node 1)
--     ├── 2 (Level 2 - Node 2)
--     │   ├── 4 (Level 3 - Node 4)
--     │   └── 5 (Level 3 - Node 5)
--     └── 3 (Level 2 - Node 3)
--         └── 6 (Level 3 - Node 6)

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

Response

┌─dictHas('hierarchical_dictionary', 2)─┐
│                                     1 │
└───────────────────────────────────────┘
┌─dictHas('hierarchical_dictionary', 7)─┐
│                                     0 │
└───────────────────────────────────────┘

dictIsIn

Добавленный в: v1.1.0 Проверяет предка ключа по всей иерархической цепочке словаря.

Синтаксис

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 или совпадает с ancestor_id_expr. UInt8 Примеры Проверка иерархической зависимости

Query

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');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- valid hierarchy
SELECT dictIsIn('hierarchical_dictionary', 6, 3);

-- invalid hierarchy
SELECT dictIsIn('hierarchical_dictionary', 3, 5);

Response

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

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

​Передача ключей в функции словаря

​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

​dictGetRoot

​dictGetString

​dictGetStringOrDefault

​dictGetUInt16

​dictGetUInt16OrDefault

​dictGetUInt32

​dictGetUInt32OrDefault

​dictGetUInt64

​dictGetUInt64OrDefault

​dictGetUInt8

​dictGetUInt8OrDefault

​dictGetUUID

​dictGetUUIDOrDefault

​dictHas

​dictIsIn

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

Передача ключей в функции словаря

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

dictGetRoot

dictGetString

dictGetStringOrDefault

dictGetUInt16

dictGetUInt16OrDefault

dictGetUInt32

dictGetUInt32OrDefault

dictGetUInt64

dictGetUInt64OrDefault

dictGetUInt8

dictGetUInt8OrDefault

dictGetUUID

dictGetUUIDOrDefault

dictHas

dictIsIn