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

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

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

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

Примеры

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

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

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

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;

┌─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.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, возвращается пустой массив.

Array(T)

Примеры

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

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;

┌─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)

Примеры

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

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);

┌─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>, указанного для атрибута в конфигурации словаря.

Примеры

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

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)

┌─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.

Примеры

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

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'));

┌─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>, указанное для этого атрибута в конфигурации словаря.

Примеры

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

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)

┌─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)

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

Примеры

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

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'));

┌─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)

Примеры

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

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)

┌─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>, указанного для атрибута в конфигурации словаря.

Примеры

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

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)

┌─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, если такого ключа в словаре нет.

Примеры

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

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);

┌─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>, указанного для атрибута в конфигурации словаря.

Примеры

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

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)

┌─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)

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

Примеры

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

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);

┌─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)

Примеры

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

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)

┌─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>, указанного для атрибута в конфигурации словаря.

Примеры

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

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)

┌─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)

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

Примеры

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

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'));

┌─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>, указанное для атрибута в конфигурации словаря.

Примеры

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

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)

┌─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.

Примеры

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

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);

┌─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>, указанное для атрибута в конфигурации словаря.

Примеры

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

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)

┌─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)

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

Примеры

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

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);

┌─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)

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

Примеры

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

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)

┌─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)

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

Примеры

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

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);

┌─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>, заданного для атрибута в конфигурации словаря.

Примеры

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

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)

┌─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.

Примеры

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

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);

┌─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>, заданного для этого атрибута в конфигурации словаря.

Примеры

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

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)

┌─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.

Примеры

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

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);

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

Примеры

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

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;

┌─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.

Примеры

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

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

dictGetOrNull

Добавленный в: v21.4.0

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

Синтаксис

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

Аргументы

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

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

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

Примеры

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

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;

(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

Примеры

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

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)

┌─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)

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

Примеры

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

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)

┌─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)

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

Примеры

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

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');

┌─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>, заданное для атрибута в конфигурации словаря.

Примеры

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

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)

┌─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)

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

Примеры

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

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);

┌─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>, указанного для атрибута в конфигурации словаря.

Примеры

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

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)

┌─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)

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

Примеры

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

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);

┌─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)

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

Примеры

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

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)

┌─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.

Примеры

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

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);

┌─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)

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

Примеры

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

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)

┌─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)

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

Примеры

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

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);

┌─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>, указанного для этого атрибута в конфигурации словаря.

Примеры

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

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)

┌─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.

Примеры

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

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);

┌─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

Примеры

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

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);

┌─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

Примеры

Проверка иерархической зависимости

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);

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