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

Примечание

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

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

dictGet, dictGetOrDefault, dictGetOrNull

Возвращают значения из словаря.

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

Аргументы

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

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

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

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

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

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

1,1
2,2

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Результат:

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

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

Справочники

dictHas

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

dictHas('dict_name', id_expr)

Аргументы

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

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

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

dictGetHierarchy

Создаёт массив со всеми родительскими элементами указанного ключа в иерархическом словаре.

Синтаксис

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

Аргументы

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

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

Родители ключа. Array(UInt64).

dictIsIn

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

dictIsIn('dict_name', child_id_expr, ancestor_id_expr)

Аргументы

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

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

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

dictGetChildren

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

Синтаксис

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

Аргументы

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

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

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

Пример

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

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

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

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

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

dictGetDescendant

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

Синтаксис

dictGetDescendants(dict_name, key, level)

Аргументы

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

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

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

Пример

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

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

Все дочерние элементы:

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

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

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

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

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

dictGetAll

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

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

Синтаксис

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

Аргументы

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

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

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

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

Пример

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

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

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

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

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

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

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

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

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

dictGetKeys

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

Синтаксис

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

Аргументы

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

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

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

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

Пример

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

 ┌─id─┬─level──┐
 │  1 │ низкий  │
 │  2 │ высокий │
 │  3 │ средний │
 │  4 │ высокий │
 └────┴────────┘

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

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

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

Примечание

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

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

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

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

Функции:

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

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

Синтаксис:

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

Аргументы

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

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

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

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

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

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

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

-- Создание таблицы со всеми необходимыми типами данных
CREATE TABLE all_types_test (
    `id` UInt32,

    -- Тип String
    `String_value` String,

    -- Беззнаковые целочисленные типы
    `UInt8_value` UInt8,
    `UInt16_value` UInt16,
    `UInt32_value` UInt32,
    `UInt64_value` UInt64,

    -- Знаковые целочисленные типы
    `Int8_value` Int8,
    `Int16_value` Int16,
    `Int32_value` Int32,
    `Int64_value` Int64,

    -- Типы с плавающей точкой
    `Float32_value` Float32,
    `Float64_value` Float64,

    -- Типы даты и времени
    `Date_value` Date,
    `DateTime_value` DateTime,

    -- Сетевые типы
    `IPv4_value` IPv4,
    `IPv6_value` IPv6,

    -- Тип UUID
    `UUID_value` UUID
) ENGINE = MergeTree()
ORDER BY id;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

-- 0 (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)

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

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

dictGet

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

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

Синтаксис

dictGet('dict_name', attr_names, id_expr)

Аргументы

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

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

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

Примеры

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

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

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

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

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

dictGetAll

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

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

Синтаксис

dictGetAll(dict_name, attr_name, id_expr)

Аргументы

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

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

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

Примечание

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

Примеры

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

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

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

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

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

dictGetChildren

Введено в: v21.4

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

Синтаксис

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

Аргументы

dict_name — Название словаря. String
key — Ключ для проверки. const String

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

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

Примеры

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

SELECT dictGetChildren('hierarchical_dictionary', 2);

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

dictGetDate

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

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

Синтаксис

dictGetDate(имя_словаря, имя_атрибута, id_expr)

Аргументы

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

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

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

Примечание

Примеры

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

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

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

dictGetDateOrDefault

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

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

Синтаксис

dictGetDateOrDefault(имя_словаря, имя_атрибута, выражение_id, выражение_значения_по_умолчанию)

Аргументы

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

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

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

Примечание

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

Примеры

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

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

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

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

dictGetDateTime

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

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

Синтаксис

dictGetDateTime(dict_name, attr_name, id_expr)

Аргументы

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

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

Примечание

Примеры

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

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

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

dictGetDateTimeOrDefault

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

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

Синтаксис

dictGetDateTimeOrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

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

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

Примечание

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

Примеры

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

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

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

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

dictGetDescendants

Введена в версии: v21.4

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

Синтаксис

dictGetDescendants(имя_словаря, ключ, уровень)

Аргументы

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

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

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

Примеры

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

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

SELECT dictGetDescendants('hierarchical_dictionary', 0, 2)

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

dictGetFloat32

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

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

Синтаксис

dictGetFloat32(dict_name, attr_name, id_expr)

Аргументы

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

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

Примечание

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

Примеры

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

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

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

dictGetFloat32OrDefault

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

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

Синтаксис

dictGetFloat32OrDefault(имя_словаря, имя_атрибута, id_выражение, выражение_значения_по_умолчанию)

Аргументы

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

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

Примечание

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

Примеры

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

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

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

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

dictGetFloat64

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

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

Синтаксис

dictGetFloat64(имя_словаря, имя_атрибута, id_expr)

Аргументы

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

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

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

Примечание

Примеры

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

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

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

dictGetFloat64OrDefault

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

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

Синтаксис

dictGetFloat64OrDefault(имя_словаря, имя_атрибута, id_выражение, выражение_значения_по_умолчанию)

Аргументы

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

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

Примечание

Примеры

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

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

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

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

dictGetHierarchy

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

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

Синтаксис

dictGetHierarchy(dict_name, key)

Аргументы

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

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

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

Примеры

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

SELECT dictGetHierarchy('hierarchical_dictionary', 5)

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

dictGetIPv4

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

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

Синтаксис

dictGetIPv4(dict_name, attr_name, id_expr)

Аргументы

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

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

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

Примечание

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

Примеры

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

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

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

dictGetIPv4OrDefault

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

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

Синтаксис

dictGetIPv4OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

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

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

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

Примечание

Примеры

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

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

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

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

dictGetIPv6

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

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

Синтаксис

dictGetIPv6(dict_name, attr_name, id_expr)

Аргументы

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

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

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

Примечание

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

Примеры

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

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

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

dictGetIPv6OrDefault

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

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

Синтаксис

dictGetIPv6OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

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

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

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

Примечание

Примеры

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

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

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

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

dictGetInt16

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

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

Синтаксис

dictGetInt16(dict_name, attr_name, id_expr)

Аргументы

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

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

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

Примечание

Примеры

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

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

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

dictGetInt16OrDefault

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

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

Синтаксис

dictGetInt16OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

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

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

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

Примечание

Примеры

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

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

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

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

dictGetInt32

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

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

Синтаксис

dictGetInt32(dict_name, attr_name, id_expr)

Аргументы

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

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

Примечание

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

Примеры

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

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

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

dictGetInt32OrDefault

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

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

Синтаксис

dictGetInt32OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

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

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

Примечание

Примеры

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

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

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

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

dictGetInt64

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

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

Синтаксис

dictGetInt64(dict_name, attr_name, id_expr)

Аргументы

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

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

Примечание

Примеры

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

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

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

dictGetInt64OrDefault

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

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

Синтаксис

dictGetInt64OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

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

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

Примечание

Примеры

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

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

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

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

dictGetInt8

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

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

Синтаксис

dictGetInt8(dict_name, attr_name, id_expr)

Аргументы

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

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

Примечание

Примеры

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

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

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

dictGetInt8OrDefault

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

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

Синтаксис

dictGetInt8OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

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

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

Примечание

Примеры

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

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

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

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

dictGetKeys

Добавлена в: v25.11

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

Примеры

dictGetOrDefault

Начиная с версии: v18.16

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

Синтаксис

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

Аргументы

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

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

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

Примеры

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

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

dictGetOrNull

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

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

Синтаксис

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

Аргументы

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

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

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

Примеры

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

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

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

dictGetString

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

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

Синтаксис

dictGetString(dict_name, attr_name, id_expr)

Аргументы

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

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

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

Примечание

Примеры

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

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

┌─dictGetString(⋯_value', 1)─┐
│ тестовая строка            │
└────────────────────────────┘

dictGetStringOrDefault

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

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

Синтаксис

dictGetStringOrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

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

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

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

Примечание

Примеры

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

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

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

┌─dictGetString(⋯_value', 1)─┐
│ тестовая строка            │
└────────────────────────────┘
┌─dictGetStringO⋯ 999, 'default')─┐
│ значение по умолчанию           │
└─────────────────────────────────┘

dictGetUInt16

Введена в: v1.1

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

Синтаксис

dictGetUInt16(dict_name, attr_name, id_expr)

Аргументы

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

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

Примечание

Примеры

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

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

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

dictGetUInt16OrDefault

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

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

Синтаксис

dictGetUInt16OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

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

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

Примечание

Примеры

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

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

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

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

dictGetUInt32

Функция появилась в версии v1.1

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

Синтаксис

dictGetUInt32(dict_name, attr_name, id_expr)

Аргументы

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

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

Примечание

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

Примеры

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

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

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

dictGetUInt32OrDefault

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

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

Синтаксис

dictGetUInt32OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

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

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

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

Примечание

Примеры

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

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

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

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

dictGetUInt64

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

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

Синтаксис

dictGetUInt64(dict_name, attr_name, id_expr)

Аргументы

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

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

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

Примечание

Примеры

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

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

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

dictGetUInt64OrDefault

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

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

Синтаксис

dictGetUInt64OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

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

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

Примечание

Примеры

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

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

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

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

dictGetUInt8

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

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

Синтаксис

dictGetUInt8(dict_name, attr_name, id_expr)

Аргументы

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

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

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

Примечание

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

Примеры

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

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

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

dictGetUInt8OrDefault

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

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

Синтаксис

dictGetUInt8OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

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

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

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

Примечание

Примеры

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

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

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

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

dictGetUUID

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

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

Синтаксис

dictGetUUID(dict_name, attr_name, id_expr)

Аргументы

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

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

Примечание

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

Примеры

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

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

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

dictGetUUIDOrDefault

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

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

Синтаксис

dictGetUUIDOrDefault(dict_name, attr_name, id_expr, default_value_expr)

Аргументы

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

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

Примечание

Примеры

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

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

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

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

dictHas

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

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

Синтаксис

dictHas('dict_name', id_expr)

Аргументы

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

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

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

Примеры

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

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

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

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

dictIsIn

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

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

Синтаксис

dictIsIn(dict_name, child_id_expr, ancestor_id_expr)

Аргументы

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

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

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

Примеры

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

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

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

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

dictGet, dictGetOrDefault, dictGetOrNull​

dictHas​

dictGetHierarchy​

dictIsIn​

dictGetChildren​

dictGetDescendant​

dictGetAll​

dictGetKeys​

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

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

dictGet​

dictGetAll​

dictGetChildren​

dictGetDate​

dictGetDateOrDefault​

dictGetDateTime​

dictGetDateTimeOrDefault​

dictGetDescendants​

dictGetFloat32​

dictGetFloat32OrDefault​

dictGetFloat64​

dictGetFloat64OrDefault​

dictGetHierarchy​

dictGetIPv4​

dictGetIPv4OrDefault​

dictGetIPv6​

dictGetIPv6OrDefault​

dictGetInt16​

dictGetInt16OrDefault​

dictGetInt32​

dictGetInt32OrDefault​

dictGetInt64​

dictGetInt64OrDefault​

dictGetInt8​

dictGetInt8OrDefault​

dictGetKeys​

dictGetOrDefault​

dictGetOrNull​

dictGetString​

dictGetStringOrDefault​

dictGetUInt16​

dictGetUInt16OrDefault​

dictGetUInt32​

dictGetUInt32OrDefault​

dictGetUInt64​

dictGetUInt64OrDefault​

dictGetUInt8​

dictGetUInt8OrDefault​

dictGetUUID​

dictGetUUIDOrDefault​

dictHas​

dictIsIn​

dictGet, dictGetOrDefault, dictGetOrNull

dictHas

dictGetHierarchy

dictIsIn

dictGetChildren

dictGetDescendant

dictGetAll

dictGetKeys

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

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

dictGet

dictGetAll

dictGetChildren

dictGetDate

dictGetDateOrDefault

dictGetDateTime

dictGetDateTimeOrDefault

dictGetDescendants

dictGetFloat32

dictGetFloat32OrDefault

dictGetFloat64

dictGetFloat64OrDefault

dictGetHierarchy

dictGetIPv4

dictGetIPv4OrDefault

dictGetIPv6

dictGetIPv6OrDefault

dictGetInt16

dictGetInt16OrDefault

dictGetInt32

dictGetInt32OrDefault

dictGetInt64

dictGetInt64OrDefault

dictGetInt8

dictGetInt8OrDefault

dictGetKeys

dictGetOrDefault

dictGetOrNull

dictGetString

dictGetStringOrDefault

dictGetUInt16

dictGetUInt16OrDefault

dictGetUInt32

dictGetUInt32OrDefault

dictGetUInt64

dictGetUInt64OrDefault

dictGetUInt8

dictGetUInt8OrDefault

dictGetUUID

dictGetUUIDOrDefault

dictHas

dictIsIn