Funções para Trabalhar com Dicionários

Para dicionários criados com consultas DDL, o parâmetro dict_name deve ser especificado por completo, como <database>.<dict_name>. Caso contrário, será usado o banco de dados atual.

Para obter informações sobre como conectar e configurar dicionários, consulte Dicionários.

Dicionários de exemplo

Os exemplos desta seção usam os dicionários a seguir. Você pode criá-los no ClickHouse para executar os exemplos das funções descritas abaixo.

Dicionário de exemplo para as funções dictGet<T> e dictGet<T>OrDefault

-- Criar tabela com todos os tipos de dados necessários
CREATE TABLE all_types_test (
    `id` UInt32,
    
    -- Tipo String
    `String_value` String,
    
    -- Tipos inteiros sem sinal
    `UInt8_value` UInt8,
    `UInt16_value` UInt16,
    `UInt32_value` UInt32,
    `UInt64_value` UInt64,
    
    -- Tipos inteiros com sinal
    `Int8_value` Int8,
    `Int16_value` Int16,
    `Int32_value` Int32,
    `Int64_value` Int64,
    
    -- Tipos de ponto flutuante
    `Float32_value` Float32,
    `Float64_value` Float64,
    
    -- Tipos de data/hora
    `Date_value` Date,
    `DateTime_value` DateTime,
    
    -- Tipos de rede
    `IPv4_value` IPv4,
    `IPv6_value` IPv6,
    
    -- Tipo UUID
    `UUID_value` UUID
) ENGINE = MergeTree() 
ORDER BY id;

-- Inserir dados de teste
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
)

-- Criar dicionário
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);

Dicionário de exemplo para dictGetAll

Crie uma tabela para armazenar os dados do dicionário regexp tree:

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

Insira os dados na tabela:

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

Crie o dicionário 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);

Exemplo de dicionário com chave de intervalo

Crie a tabela de entrada:

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

Insira os dados na tabela de entrada:

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

Crie o dicionário:

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

Exemplo de dicionário com chave complexa

Crie a tabela de origem:

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

Insira os dados na tabela de origem:

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

Crie o dicionário:

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

Exemplo de dicionário hierárquico

Crie a tabela de origem:

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

Insira os dados na tabela de origem:

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 (Raiz)
-- └── 1 (Nível 1 - Nó 1)
--     ├── 2 (Nível 2 - Nó 2)
--     │   ├── 4 (Nível 3 - Nó 4)
--     │   └── 5 (Nível 3 - Nó 5)
--     └── 3 (Nível 2 - Nó 3)
--         └── 6 (Nível 3 - Nó 6)

Crie o dicionário:

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

Passando chaves para funções de dicionário

O argumento de chave (id_expr) de funções como dictGet, dictGetOrDefault, dictGetOrNull e dictHas depende da chave do dicionário:

Para um dicionário com uma chave simples (UInt64), passe o valor da chave diretamente:

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

Para um dicionário com uma chave composta (complexa) de mais de um atributo, passe os valores da chave como uma tupla:

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

Quando a chave composta consiste em um único atributo, o valor da chave pode ser passado diretamente, sem precisar envolvê-lo em tuple. Ambos os exemplos a seguir são válidos e equivalentes:

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

Isso também se aplica a dicionários ip_trie, cuja chave é um único atributo. O endereço IP a ser pesquisado pode ser passado diretamente:

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

dictGet

Introduzido em: v18.16.0 Recupera valores de um dicionário.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGet('dict_name', attr_names, id_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_names — Nome da coluna do dicionário ou tupla de nomes de colunas. String ou Tuple(String)
id_expr — Valor da chave. Para um dicionário com chave simples, uma expressão que retorna um valor UInt64. Para um dicionário com chave composta (complexa), uma expressão que retorna uma tupla dos valores da chave. Se a chave composta consistir em um único atributo, seu valor pode ser passado diretamente, sem envolvê-lo em tuple. UInt64 ou Tuple(T)

Valor retornado Retorna o valor do atributo do dicionário correspondente a id_expr, se a chave for encontrada. Se a chave não for encontrada, retorna o conteúdo do elemento <null_value> especificado para o atributo na configuração do dicionário. Exemplos Obter um único atributo

Query

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

Response

Vários atributos

Query

CREATE TABLE dict_mult_source (id UInt32, c1 UInt32, c2 String) ENGINE = Memory;
INSERT INTO dict_mult_source VALUES (1, 1, '1'), (2, 2, '2'), (3, 3, '3');
CREATE DICTIONARY ext_dict_mult (id UInt32, c1 UInt32, c2 String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'dict_mult_source' DB currentDatabase())) LAYOUT(FLAT()) LIFETIME(MIN 0 MAX 0);
SELECT
    dictGet('ext_dict_mult', ('c1','c2'), number + 1) AS val,
    toTypeName(val) AS type
FROM system.numbers
LIMIT 3;

Response

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

dictGetAll

Introduzido em: v23.5.0 Recupera os valores do atributo de todos os nós que corresponderam a cada chave em um dicionário de árvore de expressões regulares. Além de retornar valores do tipo Array(T) em vez de T, esta função se comporta de forma semelhante a dictGet.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

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

Argumentos

dict_name — Nome do dicionário. String
attr_names — Nome da coluna do dicionário ou tupla de nomes de colunas. String ou Tuple(String)
id_expr — Valor da chave. Uma expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)
limit — Opcional. Comprimento máximo de cada array de valores retornado. Ao truncar, os nós filhos têm precedência sobre os nós pais e, caso contrário, a ordem definida da lista para o dicionário regexp tree é respeitada. Se não for especificado, o comprimento do array é ilimitado. UInt*

Valor retornado Retorna um array com os valores dos atributos do dicionário que correspondem a id_expr para cada atributo especificado por attr_names. Se não houver nenhuma chave correspondente a id_expr no dicionário, um array vazio será retornado.

O ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Array(T) Exemplos Exemplo de uso

Query

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

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

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

Response

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

dictGetChildren

Introduzido na versão: v21.4.0 Retorna os filhos de primeiro nível como um Array de índices. É a transformação inversa de dictGetHierarchy.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetChildren(dict_name, key)

Argumentos

dict_name — Nome do dicionário. String
key — Chave a ser verificada. const String

Valor retornado Retorna os filhos de primeiro nível da chave. Array(UInt64) Exemplos Obter os filhos de primeiro nível de um dicionário

Query

CREATE TABLE hierarchy_source (id UInt64, parent_id UInt64, name String) ENGINE = Memory;
INSERT INTO hierarchy_source VALUES (0, 0, 'Root'), (1, 0, 'Level 1 - Node 1'), (2, 1, 'Level 2 - Node 2'), (3, 1, 'Level 2 - Node 3'), (4, 2, 'Level 3 - Node 4'), (5, 2, 'Level 3 - Node 5'), (6, 3, 'Level 3 - Node 6');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetChildren('hierarchical_dictionary', 2);

Response

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

dictGetDate

Introduzido na versão: v1.1.0 Converte o valor de um atributo de dicionário para o tipo de dado Date, independentemente da configuração do dicionário.

Esta função não é determinística: ela pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetDate(dict_name, attr_name, id_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Uma expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)

Valor retornado Retorna o valor do atributo do dicionário correspondente a id_expr; caso contrário, retorna o conteúdo do elemento <null_value> especificado para o atributo na configuração do dicionário.

O ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

Response

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

dictGetDateOrDefault

Introduzido em: v1.1.0 Converte um valor de atributo de dicionário para o tipo de dados Date, independentemente da configuração do dicionário, ou retorna o valor padrão fornecido se a chave não for encontrada.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetDateOrDefault(dict_name, attr_name, id_expr, default_value_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)
default_value_expr — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave id_expr. Expression ou Tuple(T)

Valor retornado Retorna o valor do atributo do dicionário correspondente a id_expr, caso contrário, retorna o valor passado no parâmetro default_value_expr.

ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

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

Response

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

dictGetDateTime

Introduzido na: v1.1.0 Converte o valor de um atributo de dicionário para o tipo de dado DateTime, independentemente da configuração do dicionário.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetDateTime(dict_name, attr_name, id_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Uma expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)

ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

Response

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

dictGetDateTimeOrDefault

Introduzido em: v1.1.0 Converte o valor de um atributo de dicionário para o tipo de dado DateTime, independentemente da configuração do dicionário, ou retorna o valor padrão fornecido se a chave não for encontrada.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetDateTimeOrDefault(dict_name, attr_name, id_expr, default_value_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Expressão que retorna um valor do tipo da chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)
default_value_expr — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave id_expr. Expression ou Tuple(T)

Valor retornado Retorna o valor do atributo do dicionário correspondente a id_expr, caso contrário, retorna o valor informado no parâmetro default_value_expr.

O ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

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

Response

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

dictGetDescendants

Introduzido em: v21.4.0 Retorna todos os descendentes como se a função dictGetChildren fosse aplicada recursivamente level vezes.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetDescendants(dict_name, key, level)

Argumentos

dict_name — Nome do dicionário. String
key — Chave a ser verificada. const String
level — Chave a ser verificada. Nível da hierarquia. Se level = 0, retorna todos os descendentes até o final. UInt8

Valor retornado Retorna os descendentes da chave. Array(UInt64) Exemplos Obter os filhos de primeiro nível de um dicionário

Query

CREATE TABLE hierarchy_source (id UInt64, parent_id UInt64, name String) ENGINE = Memory;
INSERT INTO hierarchy_source VALUES (0, 0, 'Root'), (1, 0, 'Level 1 - Node 1'), (2, 1, 'Level 2 - Node 2'), (3, 1, 'Level 2 - Node 3'), (4, 2, 'Level 3 - Node 4'), (5, 2, 'Level 3 - Node 5'), (6, 3, 'Level 3 - Node 6');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- consider the following hierarchical dictionary:
-- 0 (Root)
-- └── 1 (Level 1 - Node 1)
--     ├── 2 (Level 2 - Node 2)
--     │   ├── 4 (Level 3 - Node 4)
--     │   └── 5 (Level 3 - Node 5)
--     └── 3 (Level 2 - Node 3)
--         └── 6 (Level 3 - Node 6)

SELECT dictGetDescendants('hierarchical_dictionary', 0, 2)

Response

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

dictGetFloat32

Introduzido em: v1.1.0 Converte o valor de um atributo do dicionário para o tipo de dado Float32, independentemente da configuração do dicionário.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetFloat32(dict_name, attr_name, id_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Uma expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)

ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

Response

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

dictGetFloat32OrDefault

Introduzido em: v1.1.0 Converte o valor de um atributo do dicionário para o tipo de dado Float32, independentemente da configuração do dicionário, ou retorna o valor padrão fornecido caso a chave não seja encontrada.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetFloat32OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)
default_value_expr — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave id_expr. Expression ou Tuple(T)

Valor retornado Retorna o valor do atributo do dicionário correspondente a id_expr; caso contrário, retorna o valor passado no parâmetro default_value_expr.

O ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

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

Response

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

dictGetFloat64

Introduzido em: v1.1.0 Converte o valor de um atributo do dicionário para o tipo de dado Float64, independentemente da configuração do dicionário.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetFloat64(dict_name, attr_name, id_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Uma expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)

ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

Response

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

dictGetFloat64OrDefault

Introduzido em: v1.1.0 Converte o valor de um atributo do dicionário para o tipo de dado Float64, independentemente da configuração do dicionário, ou retorna o valor padrão fornecido se a chave não for encontrada.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetFloat64OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)
default_value_expr — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave id_expr. Expression ou Tuple(T)

Valor retornado Retorna o valor do atributo do dicionário correspondente a id_expr, caso contrário, retorna o valor passado no parâmetro default_value_expr.

O ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

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

Response

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

dictGetHierarchy

Introduzido em: v1.1.0 Cria um array contendo todos os ancestrais de uma chave no dicionário hierárquico.

Esta função é não determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetHierarchy(dict_name, key)

Argumentos

dict_name — Nome do dicionário. String
key — Valor da chave. const String

Valor retornado Retorna os ancestrais da chave. Array(UInt64) Exemplos Obter a hierarquia de uma chave

Query

CREATE TABLE hierarchy_source (id UInt64, parent_id UInt64, name String) ENGINE = Memory;
INSERT INTO hierarchy_source VALUES (0, 0, 'Root'), (1, 0, 'Level 1 - Node 1'), (2, 1, 'Level 2 - Node 2'), (3, 1, 'Level 2 - Node 3'), (4, 2, 'Level 3 - Node 4'), (5, 2, 'Level 3 - Node 5'), (6, 3, 'Level 3 - Node 6');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetHierarchy('hierarchical_dictionary', 5)

Response

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

dictGetIPv4

Introduzido em: v1.1.0 Converte o valor de um atributo do dicionário para o tipo de dado IPv4, independentemente da configuração do dicionário.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetIPv4(dict_name, attr_name, id_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Uma expressão que retorna um valor com o tipo da chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)

ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

Response

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

dictGetIPv4OrDefault

Introduzido em: v23.1.0 Converte o valor de um atributo do dicionário para o tipo de dado IPv4, independentemente da configuração do dicionário, ou retorna o valor padrão fornecido caso a chave não seja encontrada.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetIPv4OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)
default_value_expr — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave id_expr. Expression ou Tuple(T)

Valor retornado Retorna o valor do atributo do dicionário correspondente a id_expr; caso contrário, retorna o valor passado no parâmetro default_value_expr.

O ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

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

Response

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

dictGetIPv6

Introduzido em: v23.1.0 Converte o valor de um atributo do dicionário para o tipo de dado IPv6, independentemente da configuração do dicionário.

Esta função não é determinística: ela pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetIPv6(dict_name, attr_name, id_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Uma expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)

O ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

Response

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

dictGetIPv6OrDefault

Introduzido em: v23.1.0 Converte um valor de atributo do dicionário para o tipo de dado IPv6, independentemente da configuração do dicionário, ou retorna o valor padrão fornecido se a chave não for encontrada.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetIPv6OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)
default_value_expr — Valor ou valores retornados se o dicionário não contiver uma linha com a chave id_expr. Expression ou Tuple(T)

Valor retornado Retorna o valor do atributo do dicionário correspondente a id_expr, caso contrário, retorna o valor informado no parâmetro default_value_expr.

O ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

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

Response

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

dictGetInt16

Introduzido em: v1.1.0 Converte o valor de um atributo do dicionário para o tipo de dado Int16, independentemente da configuração do dicionário.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetInt16(dict_name, attr_name, id_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Uma expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)

Valor retornado Retorna o valor do atributo do dicionário correspondente a id_expr, caso contrário, retorna o conteúdo do elemento <null_value> especificado para o atributo na configuração do dicionário.

O ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

Response

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

dictGetInt16OrDefault

Introduzido em: v1.1.0 Converte o valor de um atributo do dicionário para o tipo de dado Int16, independentemente da configuração do dicionário, ou retorna o valor padrão fornecido caso a chave não seja encontrada.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetInt16OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)
default_value_expr — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave id_expr. Expression ou Tuple(T)

Valor retornado Retorna o valor do atributo do dicionário correspondente a id_expr, caso contrário, retorna o valor passado no parâmetro default_value_expr.

ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

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

Response

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

dictGetInt32

Introduzido em: v1.1.0 Converte o valor de um atributo do dicionário para o tipo de dado Int32, independentemente da configuração do dicionário.

Esta função não é determinística: ela pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetInt32(dict_name, attr_name, id_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Uma expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)

ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

Response

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

dictGetInt32OrDefault

Introduzido em: v1.1.0 Converte o valor de um atributo de dicionário para o tipo de dado Int32, independentemente da configuração do dicionário, ou retorna o valor padrão fornecido caso a chave não seja encontrada.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetInt32OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)
default_value_expr — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave id_expr. Expression ou Tuple(T)

Valor retornado Retorna o valor do atributo do dicionário correspondente a id_expr; caso contrário, retorna o valor passado no parâmetro default_value_expr.

O ClickHouse lança uma exceção se não conseguir analisar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

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

Response

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

dictGetInt64

Introduzido em: v1.1.0 Converte o valor de um atributo do dicionário para o tipo de dado Int64, independentemente da configuração do dicionário.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetInt64(dict_name, attr_name, id_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Uma expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)

O ClickHouse lança uma exceção se não conseguir analisar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

Response

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

dictGetInt64OrDefault

Introduzido em: v1.1.0 Converte o valor de um atributo do dicionário para o tipo de dado Int64, independentemente da configuração do dicionário, ou retorna o valor padrão fornecido caso a chave não seja encontrada.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetInt64OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)
default_value_expr — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave id_expr. Expression ou Tuple(T)

Valor retornado Retorna o valor do atributo do dicionário correspondente a id_expr; caso contrário, retorna o valor passado no parâmetro default_value_expr.

O ClickHouse lança uma exceção se não conseguir analisar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

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

Response

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

dictGetInt8

Introduzido em: v1.1.0 Converte o valor de um atributo de dicionário para o tipo de dado Int8, independentemente da configuração do dicionário.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetInt8(dict_name, attr_name, id_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Uma expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)

O ClickHouse lança uma exceção se não conseguir analisar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

Response

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

dictGetInt8OrDefault

Introduzido em: v1.1.0 Converte o valor de um atributo de dicionário para o tipo de dado Int8, independentemente da configuração do dicionário, ou retorna o valor padrão fornecido caso a chave não seja encontrada.

Esta função é não determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetInt8OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)
default_value_expr — Valor(es) retornado(s) se o dicionário não contiver nenhuma linha com a chave id_expr. Expression ou Tuple(T)

Valor retornado Retorna o valor do atributo do dicionário correspondente a id_expr; caso contrário, retorna o valor passado no parâmetro default_value_expr.

O ClickHouse lança uma exceção se não conseguir analisar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

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

Response

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

dictGetKeys

Introduzido em: v25.12.0 Retorna a(s) chave(s) do dicionário cujo atributo é igual ao valor especificado. Esta é a função inversa de dictGet para um único atributo. Use a configuração max_reverse_dictionary_lookup_cache_size_bytes para limitar o tamanho do cache de busca reversa por consulta usado por dictGetKeys. O cache armazena tuplas de chaves serializadas para cada valor de atributo, evitando varrer o dicionário novamente dentro da mesma consulta. O cache não é persistente entre consultas. Quando o limite é atingido, as entradas são removidas com LRU. Isso é mais eficaz com dicionários grandes quando a entrada tem baixa cardinalidade e o conjunto de trabalho cabe no cache. Defina como 0 para desabilitar o cache.

Esta função não é determinística: ela pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

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

Argumentos

dict_name — Nome do dicionário. String
attr_name — Atributo a ser comparado. String
value_expr — Valor a ser comparado com o atributo. Expression

Valor retornado Para dicionários de chave única: um array de chaves cujo atributo é igual a value_expr. Para dicionários com múltiplas chaves: um array de tuplas de chaves cujo atributo é igual a value_expr. Se não houver nenhum atributo correspondente a value_expr no dicionário, será retornado um array vazio. O ClickHouse lança uma exceção se não conseguir analisar o valor do atributo ou se o valor não puder ser convertido para o tipo de dado do atributo. Exemplos Exemplo de uso

Query

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

Response

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

dictGetOrDefault

Introduzido em: v18.16.0 Recupera valores de um dicionário, com um valor padrão caso a chave não seja encontrada.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

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

Argumentos

dict_name — Nome do dicionário. String
attr_names — Nome da coluna do dicionário ou tupla de nomes de colunas. String ou Tuple(String)
id_expr — Valor da chave. Para um dicionário com uma chave simples, uma expressão que retorna um valor UInt64. Para um dicionário com uma chave composta (complexa), uma expressão que retorna uma tupla com os valores da chave. Se a chave composta consistir em um único atributo, seu valor pode ser passado diretamente, sem envolvê-lo em tuple. UInt64 ou Tuple(T)
default_value — Valor padrão retornado se a chave não for encontrada. O tipo deve corresponder ao tipo de dado do atributo.

Valor retornado Retorna o valor do atributo do dicionário correspondente a id_expr se a chave for encontrada. Se a chave não for encontrada, retorna o default_value fornecido. Exemplos Obter valor com valor padrão

Query

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

Response

dictGetOrNull

Introduzido em: v21.4.0 Obtém valores de um Dicionário, retornando NULL se a chave não for encontrada.

Esta função não é determinística: ela pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

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

Argumentos

dict_name — Nome do dicionário. Literal de String. - attr_name — Nome da coluna a ser obtida. Literal de String. - id_expr — Valor da chave. expressão que retorna um valor do tipo de chave do dicionário.

Valor retornado Retorna o valor do atributo do dicionário correspondente a id_expr se a chave for encontrada. Se a chave não for encontrada, retorna NULL. Exemplos Exemplo usando o dicionário com chave de intervalo

Query

CREATE TABLE range_key_dictionary_source_table (key UInt64, start_date Date, end_date Date, value String, value_nullable Nullable(String)) ENGINE = TinyLog();
INSERT INTO range_key_dictionary_source_table VALUES(1, toDate('2019-05-20'), toDate('2019-05-20'), 'First', 'First');
INSERT INTO range_key_dictionary_source_table VALUES(2, toDate('2019-05-20'), toDate('2019-05-20'), 'Second', NULL);
INSERT INTO range_key_dictionary_source_table VALUES(3, toDate('2019-05-20'), toDate('2019-05-20'), 'Third', 'Third');
CREATE DICTIONARY range_key_dictionary (key UInt64, start_date Date, end_date Date, value String, value_nullable Nullable(String)) PRIMARY KEY key SOURCE(CLICKHOUSE(TABLE 'range_key_dictionary_source_table' DB currentDatabase())) LIFETIME(MIN 1 MAX 1000) LAYOUT(RANGE_HASHED()) RANGE(MIN start_date MAX end_date);
SELECT
    (number, toDate('2019-05-20')),
    dictGetOrNull('range_key_dictionary', 'value', number, toDate('2019-05-20')),
FROM system.numbers LIMIT 5 FORMAT TabSeparated;

Response

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

dictGetRoot

Introduzido em: v26.7.0 Retorna o ancestral mais alto (a raiz) de uma chave em um dicionário hierárquico. Este é um equivalente prático a obter o último elemento do array retornado por dictGetHierarchy, ou seja, dictGetHierarchy(dict_name, key)[-1]. Se a chave for ela própria um nó de nível superior da hierarquia, a própria chave será retornada. Se a chave não existir no dicionário, 0 será retornado.

Esta função é não determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetRoot(dict_name, key)

Argumentos

dict_name — Nome do dicionário. String
key — Valor da chave. UInt64

Valor retornado Retorna o ancestral de nível mais alto (a raiz) da chave. UInt64 Exemplos Obter a raiz de uma chave

Query

CREATE TABLE hierarchy_source (id UInt64, parent_id UInt64, name String) ENGINE = Memory;
INSERT INTO hierarchy_source VALUES (0, 0, 'Root'), (1, 0, 'Level 1 - Node 1'), (2, 1, 'Level 2 - Node 2'), (3, 1, 'Level 2 - Node 3'), (4, 2, 'Level 3 - Node 4'), (5, 2, 'Level 3 - Node 5'), (6, 3, 'Level 3 - Node 6');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetRoot('hierarchical_dictionary', 5)

Response

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

dictGetString

Introduzido em: v1.1.0 Converte o valor de um atributo do dicionário para o tipo de dado String, independentemente da configuração do dicionário.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetString(dict_name, attr_name, id_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Uma expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)

O ClickHouse lança uma exceção se não conseguir analisar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

Response

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

dictGetStringOrDefault

Introduzido em: v1.1.0 Converte o valor de um atributo do dicionário para o tipo de dado String, independentemente da configuração do dicionário, ou retorna o valor padrão fornecido se a chave não for encontrada.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetStringOrDefault(dict_name, attr_name, id_expr, default_value_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)
default_value_expr — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave id_expr. Expression ou Tuple(T)

Valor retornado Retorna o valor do atributo do dicionário correspondente a id_expr, caso contrário, retorna o valor informado no parâmetro default_value_expr.

O ClickHouse lança uma exceção se não conseguir analisar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

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

Response

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

dictGetUInt16

Introduzido em: v1.1.0 Converte um valor de atributo do dicionário para o tipo de dado UInt16, independentemente da configuração do dicionário.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetUInt16(dict_name, attr_name, id_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Uma expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)

O ClickHouse lança uma exceção se não conseguir analisar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

Response

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

dictGetUInt16OrDefault

Introduzido em: v1.1.0 Converte um valor de atributo de dicionário para o tipo de dado UInt16, independentemente da configuração do dicionário, ou retorna o valor padrão fornecido caso a chave não seja encontrada.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetUInt16OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)
default_value_expr — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave id_expr. Expression ou Tuple(T)

Valor retornado Retorna o valor do atributo do dicionário correspondente a id_expr; caso contrário, retorna o valor passado no parâmetro default_value_expr.

ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

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

Response

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

dictGetUInt32

Introduzido em: v1.1.0 Converte o valor de um atributo de dicionário para o tipo de dado UInt32, independentemente da configuração do dicionário.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetUInt32(dict_name, attr_name, id_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Uma expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)

ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

Response

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

dictGetUInt32OrDefault

Introduzido em: v1.1.0 Converte o valor de um atributo de dicionário para o tipo de dado UInt32, independentemente da configuração do dicionário, ou retorna o valor padrão fornecido caso a chave não seja encontrada.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetUInt32OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)
default_value_expr — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave id_expr. Expression ou Tuple(T)

Valor retornado Retorna o valor do atributo do dicionário correspondente a id_expr, do contrário, retorna o valor passado no parâmetro default_value_expr.

O ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

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

Response

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

dictGetUInt64

Introduzido em: v1.1.0 Converte o valor de um atributo de dicionário para o tipo de dado UInt64, independentemente da configuração do dicionário.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetUInt64(dict_name, attr_name, id_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Uma expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)

O ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

Response

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

dictGetUInt64OrDefault

Introduzido em: v1.1.0 Converte o valor de um atributo de dicionário para o tipo de dado UInt64, independentemente da configuração do dicionário, ou retorna o valor padrão fornecido se a chave não for encontrada.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetUInt64OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)
default_value_expr — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave id_expr. Expression ou Tuple(T)

Valor retornado Retorna o valor do atributo do dicionário correspondente a id_expr; caso contrário, retorna o valor passado no parâmetro default_value_expr.

O ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

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

Response

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

dictGetUInt8

Introduzido em: v1.1.0 Converte o valor de um atributo de dicionário para o tipo de dado UInt8, independentemente da configuração do dicionário.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetUInt8(dict_name, attr_name, id_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Uma expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)

O ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

Response

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

dictGetUInt8OrDefault

Introduzido em: v1.1.0 Converte um valor de atributo do dicionário para o tipo de dado UInt8, independentemente da configuração do dicionário, ou retorna o valor padrão fornecido se a chave não for encontrada.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetUInt8OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Expressão que retorna um valor do tipo da chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)
default_value_expr — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave id_expr. Expression ou Tuple(T)

Valor retornado Retorna o valor do atributo do dicionário correspondente a id_expr; caso contrário, retorna o valor informado no parâmetro default_value_expr.

O ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

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

Response

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

dictGetUUID

Introduzido em: v1.1.0 Converte o valor de um atributo de dicionário para o tipo de dado UUID, independentemente da configuração do dicionário.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetUUID(dict_name, attr_name, id_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Uma expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)

O ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

Response

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

dictGetUUIDOrDefault

Introduzido em: v1.1.0 Converte o valor de um atributo de dicionário para o tipo de dado UUID, independentemente da configuração do dicionário, ou retorna o valor padrão fornecido caso a chave não seja encontrada.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictGetUUIDOrDefault(dict_name, attr_name, id_expr, default_value_expr)

Argumentos

dict_name — Nome do dicionário. String
attr_name — Nome da coluna do dicionário. String ou Tuple(String)
id_expr — Valor da chave. Expressão que retorna um valor do tipo de chave do dicionário ou um valor de tupla (dependendo da configuração do dicionário). Expression ou Tuple(T)
default_value_expr — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave id_expr. Expression ou Tuple(T)

Valor retornado Retorna o valor do atributo do dicionário correspondente a id_expr; caso contrário, retorna o valor informado no parâmetro default_value_expr.

O ClickHouse lança uma exceção se não conseguir interpretar o valor do atributo ou se o valor não corresponder ao tipo de dado do atributo.

Exemplos Exemplo de uso

Query

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

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

Response

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

dictHas

Introduzido em: v1.1.0 Verifica se uma chave está presente em um dicionário.

Esta função é não determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictHas('dict_name', id_expr)

Argumentos

dict_name — Nome do dicionário. String
id_expr — Valor da chave const String

Valor retornado Retorna 1 se a chave existir; caso contrário, 0. UInt8 Exemplos Verificar a existência de uma chave em um dicionário

Query

CREATE TABLE hierarchy_source (id UInt64, parent_id UInt64, name String) ENGINE = Memory;
INSERT INTO hierarchy_source VALUES (0, 0, 'Root'), (1, 0, 'Level 1 - Node 1'), (2, 1, 'Level 2 - Node 2'), (3, 1, 'Level 2 - Node 3'), (4, 2, 'Level 3 - Node 4'), (5, 2, 'Level 3 - Node 5'), (6, 3, 'Level 3 - Node 6');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- consider the following hierarchical dictionary:
-- 0 (Root)
-- └── 1 (Level 1 - Node 1)
--     ├── 2 (Level 2 - Node 2)
--     │   ├── 4 (Level 3 - Node 4)
--     │   └── 5 (Level 3 - Node 5)
--     └── 3 (Level 2 - Node 3)
--         └── 6 (Level 3 - Node 6)

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

Response

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

dictIsIn

Introduzido em: v1.1.0 Verifica o ancestral de uma chave ao longo de toda a cadeia hierárquica do dicionário.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

dictIsIn(dict_name, child_id_expr, ancestor_id_expr)

Argumentos

dict_name — Nome do dicionário. String
child_id_expr — Chave a ser verificada. String
ancestor_id_expr — Suposto ancestral da chave child_id_expr. const String

Valor retornado Retorna 0 se child_id_expr não for filho de ancestor_id_expr e 1 se child_id_expr for filho de ancestor_id_expr ou se child_id_expr for o próprio ancestor_id_expr. UInt8 Exemplos Verificar a relação hierárquica

Query

CREATE TABLE hierarchy_source (id UInt64, parent_id UInt64, name String) ENGINE = Memory;
INSERT INTO hierarchy_source VALUES (0, 0, 'Root'), (1, 0, 'Level 1 - Node 1'), (2, 1, 'Level 2 - Node 2'), (3, 1, 'Level 2 - Node 3'), (4, 2, 'Level 3 - Node 4'), (5, 2, 'Level 3 - Node 5'), (6, 3, 'Level 3 - Node 6');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- valid hierarchy
SELECT dictIsIn('hierarchical_dictionary', 6, 3);

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

Response

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

​Dicionários de exemplo

​Passando chaves para funções de dicionário

​dictGet

​dictGetAll

​dictGetChildren

​dictGetDate

​dictGetDateOrDefault

​dictGetDateTime

​dictGetDateTimeOrDefault

​dictGetDescendants

​dictGetFloat32

​dictGetFloat32OrDefault

​dictGetFloat64

​dictGetFloat64OrDefault

​dictGetHierarchy

​dictGetIPv4

​dictGetIPv4OrDefault

​dictGetIPv6

​dictGetIPv6OrDefault

​dictGetInt16

​dictGetInt16OrDefault

​dictGetInt32

​dictGetInt32OrDefault

​dictGetInt64

​dictGetInt64OrDefault

​dictGetInt8

​dictGetInt8OrDefault

​dictGetKeys

​dictGetOrDefault

​dictGetOrNull

​dictGetRoot

​dictGetString

​dictGetStringOrDefault

​dictGetUInt16

​dictGetUInt16OrDefault

​dictGetUInt32

​dictGetUInt32OrDefault

​dictGetUInt64

​dictGetUInt64OrDefault

​dictGetUInt8

​dictGetUInt8OrDefault

​dictGetUUID

​dictGetUUIDOrDefault

​dictHas

​dictIsIn

Dicionários de exemplo

Passando chaves para funções de dicionário

dictGet

dictGetAll

dictGetChildren

dictGetDate

dictGetDateOrDefault

dictGetDateTime

dictGetDateTimeOrDefault

dictGetDescendants

dictGetFloat32

dictGetFloat32OrDefault

dictGetFloat64

dictGetFloat64OrDefault

dictGetHierarchy

dictGetIPv4

dictGetIPv4OrDefault

dictGetIPv6

dictGetIPv6OrDefault

dictGetInt16

dictGetInt16OrDefault

dictGetInt32

dictGetInt32OrDefault

dictGetInt64

dictGetInt64OrDefault

dictGetInt8

dictGetInt8OrDefault

dictGetKeys

dictGetOrDefault

dictGetOrNull

dictGetRoot

dictGetString

dictGetStringOrDefault

dictGetUInt16

dictGetUInt16OrDefault

dictGetUInt32

dictGetUInt32OrDefault

dictGetUInt64

dictGetUInt64OrDefault

dictGetUInt8

dictGetUInt8OrDefault

dictGetUUID

dictGetUUIDOrDefault

dictHas

dictIsIn