Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Funções para Trabalhar com Dicionários

View as MarkdownEdit this pageReport an issueSet up docs MCP

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.

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

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
1

Vários atributos

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

dictGetAll

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.

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.

Array(T)

Exemplos

Exemplo de uso

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

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

    -- This returns only the first match
    dictGet('regexp_tree', 'os_replacement', 'Mozilla/5.0 (Linux; Android 12; SM-G998B) Mobile Safari/537.36') AS first_match;
┌─user_agent─────────────────────────────────────────────────────┬─all_matches─────────────────────────────┬─first_match─┐
│ Mozilla/5.0 (Linux; Android 12; SM-G998B) Mobile Safari/537.36 │ ['Android','Android','Android','Linux'] │ Android     │
└────────────────────────────────────────────────────────────────┴─────────────────────────────────────────┴─────────────┘

dictGetChildren

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.

Sintaxe

dictGetChildren(dict_name, key)

Argumentos

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

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

dictGetDate

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.

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.

Exemplos

Exemplo de uso

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

dictGetDateOrDefault

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.

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.

Exemplos

Exemplo de uso

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

-- for key which does not exist, returns the provided default value
SELECT dictGetDateOrDefault('all_types_dict', 'Date_value', 999, toDate('1970-01-01'));
┌─dictGetDate('all_types_dict', 'Date_value', 1)─┐
│                                     2024-01-15 │
└────────────────────────────────────────────────┘
┌─dictGetDateOrDefault('all_types_dict', 'Date_value', 999, toDate('1970-01-01'))─┐
│                                                                      1970-01-01 │
└─────────────────────────────────────────────────────────────────────────────────┘

dictGetDateTime

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.

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)

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.

Exemplos

Exemplo de uso

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

dictGetDateTimeOrDefault

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.

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.

Exemplos

Exemplo de uso

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

-- for key which does not exist, returns the provided default value
SELECT dictGetDateTimeOrDefault('all_types_dict', 'DateTime_value', 999, toDateTime('1970-01-01 00:00:00'));
┌─dictGetDateTime('all_types_dict', 'DateTime_value', 1)─┐
│                                    2024-01-15 10:30:00 │
└────────────────────────────────────────────────────────┘
┌─dictGetDateTimeOrDefault('all_types_dict', 'DateTime_value', 999, toDateTime('1970-01-01 00:00:00'))─┐
│                                                                                  1970-01-01 00:00:00 │
└──────────────────────────────────────────────────────────────────────────────────────────────────────┘

dictGetDescendants

Introduzido em: v21.4.0

Retorna todos os descendentes como se a função dictGetChildren fosse aplicada recursivamente level vezes.

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

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

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

dictGetFloat32

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.

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)

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.

Exemplos

Exemplo de uso

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

dictGetFloat32OrDefault

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.

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.

Exemplos

Exemplo de uso

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

-- for key which does not exist, returns the provided default value (-1.0)
SELECT dictGetFloat32OrDefault('all_types_dict', 'Float32_value', 999, -1.0);
┌─dictGetFloat32('all_types_dict', 'Float32_value', 1)─┐
│                                               123.45 │
└──────────────────────────────────────────────────────┘
┌─dictGetFloat32OrDefault('all_types_dict', 'Float32_value', 999, -1.)─┐
│                                                                   -1 │
└──────────────────────────────────────────────────────────────────────┘

dictGetFloat64

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.

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)

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.

Exemplos

Exemplo de uso

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

dictGetFloat64OrDefault

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.

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.

Exemplos

Exemplo de uso

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

-- for key which does not exist, returns the provided default value (nan)
SELECT dictGetFloat64OrDefault('all_types_dict', 'Float64_value', 999, nan);
┌─dictGetFloat64('all_types_dict', 'Float64_value', 1)─┐
│                                        987654.123456 │
└──────────────────────────────────────────────────────┘
┌─dictGetFloat64OrDefault('all_types_dict', 'Float64_value', 999, nan)─┐
│                                                                  nan │
└──────────────────────────────────────────────────────────────────────┘

dictGetHierarchy

Introduzido em: v1.1.0

Cria um array contendo todos os ancestrais de uma chave no dicionário hierárquico.

Sintaxe

dictGetHierarchy(dict_name, key)

Argumentos

Valor retornado

Retorna os ancestrais da chave. Array(UInt64)

Exemplos

Obter a hierarquia de uma chave

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

dictGetIPv4

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.

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)

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.

Exemplos

Exemplo de uso

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

dictGetIPv4OrDefault

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.

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.

Exemplos

Exemplo de uso

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

-- for key which does not exist, returns the provided default value
SELECT dictGetIPv4OrDefault('all_types_dict', 'IPv4_value', 999, toIPv4('0.0.0.0'));
┌─dictGetIPv4('all_types_dict', 'IPv4_value', 1)─┐
│ 192.168.0.1                                    │
└────────────────────────────────────────────────┘
┌─dictGetIPv4OrDefault('all_types_dict', 'IPv4_value', 999, toIPv4('0.0.0.0'))─┐
│ 0.0.0.0                                                                      │
└──────────────────────────────────────────────────────────────────────────────┘

dictGetIPv6

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.

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)

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.

Exemplos

Exemplo de uso

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

dictGetIPv6OrDefault

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.

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.

Exemplos

Exemplo de uso

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

-- for key which does not exist, returns the provided default value
SELECT dictGetIPv6OrDefault('all_types_dict', 'IPv6_value', 999, '::1'::IPv6);
┌─dictGetIPv6('all_types_dict', 'IPv6_value', 1)─┐
│ 2001:db8:85a3::8a2e:370:7334                   │
└────────────────────────────────────────────────┘
┌─dictGetIPv6OrDefault('all_types_dict', 'IPv6_value', 999, CAST('::1', 'IPv6'))─┐
│ ::1                                                                            │
└────────────────────────────────────────────────────────────────────────────────┘

dictGetInt16

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.

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.

Exemplos

Exemplo de uso

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

dictGetInt16OrDefault

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.

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.

Exemplos

Exemplo de uso

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

-- for key which does not exist, returns the provided default value (-1)
SELECT dictGetInt16OrDefault('all_types_dict', 'Int16_value', 999, -1);
┌─dictGetInt16('all_types_dict', 'Int16_value', 1)─┐
│                                            -5000 │
└──────────────────────────────────────────────────┘
┌─dictGetInt16OrDefault('all_types_dict', 'Int16_value', 999, -1)─┐
│                                                              -1 │
└─────────────────────────────────────────────────────────────────┘

dictGetInt32

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.

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)

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.

Exemplos

Exemplo de uso

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

dictGetInt32OrDefault

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.

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.

Exemplos

Exemplo de uso

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

-- for key which does not exist, returns the provided default value (-1)
SELECT dictGetInt32OrDefault('all_types_dict', 'Int32_value', 999, -1);
┌─dictGetInt32('all_types_dict', 'Int32_value', 1)─┐
│                                         -1000000 │
└──────────────────────────────────────────────────┘
┌─dictGetInt32OrDefault('all_types_dict', 'Int32_value', 999, -1)─┐
│                                                              -1 │
└─────────────────────────────────────────────────────────────────┘

dictGetInt64

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.

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)

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.

Exemplos

Exemplo de uso

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

dictGetInt64OrDefault

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.

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.

Exemplos

Exemplo de uso

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

-- for key which does not exist, returns the provided default value (-1)
SELECT dictGetInt64OrDefault('all_types_dict', 'Int64_value', 999, -1);
┌─dictGetInt64('all_types_dict', 'Int64_value', 1)─┐
│                             -9223372036854775808 │
└──────────────────────────────────────────────────┘
┌─dictGetInt64OrDefault('all_types_dict', 'Int64_value', 999, -1)─┐
│                                                              -1 │
└─────────────────────────────────────────────────────────────────┘

dictGetInt8

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.

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)

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.

Exemplos

Exemplo de uso

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

dictGetInt8OrDefault

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.

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.

Exemplos

Exemplo de uso

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

-- for key which does not exist, returns the provided default value (-1)
SELECT dictGetInt8OrDefault('all_types_dict', 'Int8_value', 999, -1);
┌─dictGetInt8('all_types_dict', 'Int8_value', 1)─┐
│                                           -100 │
└────────────────────────────────────────────────┘
┌─dictGetInt8OrDefault('all_types_dict', 'Int8_value', 999, -1)─┐
│                                                            -1 │
└───────────────────────────────────────────────────────────────┘

dictGetKeys

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.

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

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

dictGetOrDefault

Introduzido em: v18.16.0

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

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

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
0

dictGetOrNull

Introduzido em: v21.4.0

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

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

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

dictGetRoot

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.

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

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

dictGetString

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.

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)

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.

Exemplos

Exemplo de uso

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

dictGetStringOrDefault

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.

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.

Exemplos

Exemplo de uso

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

-- for key which does not exist, returns the provided default value
SELECT dictGetStringOrDefault('all_types_dict', 'String_value', 999, 'default');
┌─dictGetString('all_types_dict', 'String_value', 1)─┐
│ test string                                        │
└────────────────────────────────────────────────────┘
┌─dictGetStringOrDefault('all_types_dict', 'String_value', 999, 'default')─┐
│ default                                                                  │
└──────────────────────────────────────────────────────────────────────────┘

dictGetUInt16

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.

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)

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.

Exemplos

Exemplo de uso

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

dictGetUInt16OrDefault

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.

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.

Exemplos

Exemplo de uso

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

-- for key which does not exist, returns the provided default value (0)
SELECT dictGetUInt16OrDefault('all_types_dict', 'UInt16_value', 999, 0);
┌─dictGetUInt16('all_types_dict', 'UInt16_value', 1)─┐
│                                               5000 │
└────────────────────────────────────────────────────┘
┌─dictGetUInt16OrDefault('all_types_dict', 'UInt16_value', 999, 0)─┐
│                                                                0 │
└──────────────────────────────────────────────────────────────────┘

dictGetUInt32

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.

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)

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.

Exemplos

Exemplo de uso

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

dictGetUInt32OrDefault

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.

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.

Exemplos

Exemplo de uso

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

-- for key which does not exist, returns the provided default value (0)
SELECT dictGetUInt32OrDefault('all_types_dict', 'UInt32_value', 999, 0);
┌─dictGetUInt32('all_types_dict', 'UInt32_value', 1)─┐
│                                            1000000 │
└────────────────────────────────────────────────────┘
┌─dictGetUInt32OrDefault('all_types_dict', 'UInt32_value', 999, 0)─┐
│                                                                0 │
└──────────────────────────────────────────────────────────────────┘

dictGetUInt64

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.

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)

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.

Exemplos

Exemplo de uso

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

dictGetUInt64OrDefault

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.

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.

Exemplos

Exemplo de uso

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

-- for key which does not exist, returns the provideddefault value (0)
SELECT dictGetUInt64OrDefault('all_types_dict', 'UInt64_value', 999, 0);
┌─dictGetUInt64('all_types_dict', 'UInt64_value', 1)─┐
│                                9223372036854775807 │
└────────────────────────────────────────────────────┘
┌─dictGetUInt64OrDefault('all_types_dict', 'UInt64_value', 999, 0)─┐
│                                                                0 │
└──────────────────────────────────────────────────────────────────┘

dictGetUInt8

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.

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)

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.

Exemplos

Exemplo de uso

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

dictGetUInt8OrDefault

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.

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.

Exemplos

Exemplo de uso

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

-- for key which does not exist, returns the provided default value (0)
SELECT dictGetUInt8OrDefault('all_types_dict', 'UInt8_value', 999, 0);
┌─dictGetUInt8('all_types_dict', 'UInt8_value', 1)─┐
│                                              100 │
└──────────────────────────────────────────────────┘
┌─dictGetUInt8OrDefault('all_types_dict', 'UInt8_value', 999, 0)─┐
│                                                              0 │
└────────────────────────────────────────────────────────────────┘

dictGetUUID

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.

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)

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.

Exemplos

Exemplo de uso

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

dictGetUUIDOrDefault

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.

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.

Exemplos

Exemplo de uso

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

-- for key which does not exist, returns the provided default value
SELECT dictGetUUIDOrDefault('all_types_dict', 'UUID_value', 999, '00000000-0000-0000-0000-000000000000'::UUID);
┌─dictGetUUID('all_types_dict', 'UUID_value', 1)─┐
│ 550e8400-e29b-41d4-a716-446655440000           │
└────────────────────────────────────────────────┘
┌─dictGetUUIDOrDefault('all_types_dict', 'UUID_value', 999, CAST('00000000-0000-0000-0000-000000000000', 'UUID'))─┐
│ 00000000-0000-0000-0000-000000000000                                                                            │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

dictHas

Introduzido em: v1.1.0

Verifica se uma chave está presente em um dicionário.

Sintaxe

dictHas('dict_name', id_expr)

Argumentos

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

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

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

dictIsIn

Introduzido em: v1.1.0

Verifica o ancestral de uma chave ao longo de toda a cadeia hierárquica do dicionário.

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

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

-- invalid hierarchy
SELECT dictIsIn('hierarchical_dictionary', 3, 5);
┌─dictIsIn('hierarchical_dictionary', 6, 3)─┐
│                                         1 │
└───────────────────────────────────────────┘
┌─dictIsIn('hierarchical_dictionary', 3, 5)─┐
│                                         0 │
└───────────────────────────────────────────┘
Navigation