> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> Documentação de funções para trabalhar com dicionários

# Funções para Trabalhar com Dicionários

<Note>
  Para dicionários criados com [consultas DDL](/docs/pt-BR/reference/statements/create/dictionary), o parâmetro `dict_name` deve ser especificado por completo, como `<database>.<dict_name>`. Caso contrário, será usado o banco de dados atual.
</Note>

Para obter informações sobre como conectar e configurar dicionários, consulte [Dicionários](/docs/pt-BR/reference/statements/create/dictionary).

<div id="example-dictionary">
  ## Dicionários de exemplo
</div>

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.

<Accordion title="Dicionário de exemplo para as funções dictGet\<T\> e dictGet\<T\>OrDefault">
  ```sql theme={null}
  -- 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;
  ```

  ```sql theme={null}
  -- 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
  )
  ```

  ```sql theme={null}
  -- 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);
  ```
</Accordion>

<Accordion title="Dicionário de exemplo para dictGetAll">
  Crie uma tabela para armazenar os dados do dicionário regexp tree:

  ```sql theme={null}
  CREATE TABLE regexp_os(
      id UInt64,
      parent_id UInt64,
      regexp String,
      keys Array(String),
      values Array(String)
  )
  ENGINE = Memory;
  ```

  Insira os dados na tabela:

  ```sql theme={null}
  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:

  ```sql theme={null}
  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);
  ```
</Accordion>

<Accordion title="Exemplo de dicionário com chave de intervalo">
  Crie a tabela de entrada:

  ```sql theme={null}
  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:

  ```sql theme={null}
  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:

  ```sql theme={null}
  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);
  ```
</Accordion>

<Accordion title="Exemplo de dicionário com chave complexa">
  Crie a tabela de origem:

  ```sql theme={null}
  CREATE TABLE dict_mult_source
  (
  id UInt32,
  c1 UInt32,
  c2 String
  ) ENGINE = Memory;
  ```

  Insira os dados na tabela de origem:

  ```sql theme={null}
  INSERT INTO dict_mult_source VALUES
  (1, 1, '1'),
  (2, 2, '2'),
  (3, 3, '3');
  ```

  Crie o dicionário:

  ```sql theme={null}
  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);
  ```
</Accordion>

<Accordion title="Exemplo de dicionário hierárquico">
  Crie a tabela de origem:

  ```sql theme={null}
  CREATE TABLE hierarchy_source
  (
    id UInt64,
    parent_id UInt64,
    name String
  ) ENGINE = Memory;
  ```

  Insira os dados na tabela de origem:

  ```sql theme={null}
  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:

  ```sql theme={null}
  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);
  ```
</Accordion>

<div id="passing-keys">
  ## Passando chaves para funções de dicionário
</div>

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:

```sql theme={null}
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:

```sql theme={null}
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:

```sql theme={null}
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:

```sql theme={null}
SELECT dictGet('ip_trie_dictionary', 'attr_name', toIPv4('202.79.32.10'));
```

{/*AUTOGENERATED_START*/}

<div id="dictGet">
  ## dictGet
</div>

Introduzido em: v18.16.0

Recupera valores de um dicionário.

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

**Sintaxe**

```sql theme={null}
dictGet('dict_name', attr_names, id_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_names` — Nome da coluna do dicionário ou tupla de nomes de colunas. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/int-uint) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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**

```sql title=Query theme={null}
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 title=Response theme={null}
1
```

**Vários atributos**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─val─────┬─type───────────┐
│ (1,'1') │ Tuple(        ↴│
│         │↳    c1 UInt32,↴│
│         │↳    c2 String) │
│ (2,'2') │ Tuple(        ↴│
│         │↳    c1 UInt32,↴│
│         │↳    c2 String) │
│ (3,'3') │ Tuple(        ↴│
│         │↳    c1 UInt32,↴│
│         │↳    c2 String) │
└─────────┴────────────────┘
```

<div id="dictGetAll">
  ## dictGetAll
</div>

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](/docs/pt-BR/reference/statements/create/dictionary/layouts/regexp-tree).

Além de retornar valores do tipo `Array(T)` em vez de `T`, esta função se comporta de forma semelhante a [`dictGet`](#dictGet).

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

**Sintaxe**

```sql theme={null}
dictGetAll(dict_name, attr_names, id_expr[, limit])
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_names` — Nome da coluna do dicionário ou tupla de nomes de colunas. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)
* `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*`](/docs/pt-BR/reference/data-types/int-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.

<Note>
  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.
</Note>

[`Array(T)`](/docs/pt-BR/reference/data-types/array)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─user_agent─────────────────────────────────────────────────────┬─all_matches─────────────────────────────┬─first_match─┐
│ Mozilla/5.0 (Linux; Android 12; SM-G998B) Mobile Safari/537.36 │ ['Android','Android','Android','Linux'] │ Android     │
└────────────────────────────────────────────────────────────────┴─────────────────────────────────────────┴─────────────┘
```

<div id="dictGetChildren">
  ## dictGetChildren
</div>

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](#dictGetHierarchy).

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

**Sintaxe**

```sql theme={null}
dictGetChildren(dict_name, key)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `key` — Chave a ser verificada. [`const String`](/docs/pt-BR/reference/data-types/string)

**Valor retornado**

Retorna os filhos de primeiro nível da chave. [`Array(UInt64)`](/docs/pt-BR/reference/data-types/array)

**Exemplos**

**Obter os filhos de primeiro nível de um dicionário**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetChild⋯ionary', 2)─┐
│ [4,5]                    │
└──────────────────────────┘
```

<div id="dictGetDate">
  ## dictGetDate
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetDate(dict_name, attr_name, id_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetDate(⋯_value', 1)─┐
│               2020-01-01 │
└──────────────────────────┘
```

<div id="dictGetDateOrDefault">
  ## dictGetDateOrDefault
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetDateOrDefault(dict_name, attr_name, id_expr, default_value_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)
* `default_value_expr` — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave `id_expr`. [`Expression`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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`.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetDate(⋯_value', 1)─┐
│               2024-01-15 │
└──────────────────────────┘
┌─dictGetDateO⋯70-01-01'))─┐
│               1970-01-01 │
└──────────────────────────┘
```

<div id="dictGetDateTime">
  ## dictGetDateTime
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetDateTime(dict_name, attr_name, id_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetDateT⋯_value', 1)─┐
│      2024-01-15 10:30:00 │
└──────────────────────────┘
```

<div id="dictGetDateTimeOrDefault">
  ## dictGetDateTimeOrDefault
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetDateTimeOrDefault(dict_name, attr_name, id_expr, default_value_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)
* `default_value_expr` — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave `id_expr`. [`Expression`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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`.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetDateT⋯_value', 1)─┐
│      2024-01-15 10:30:00 │
└──────────────────────────┘
┌─dictGetDateT⋯0:00:00'))──┐
│      1970-01-01 00:00:00 │
└──────────────────────────┘
```

<div id="dictGetDescendants">
  ## dictGetDescendants
</div>

Introduzido em: v21.4.0

Retorna todos os descendentes como se a função [`dictGetChildren`](#dictGetChildren) fosse aplicada recursivamente `level` vezes.

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

**Sintaxe**

```sql theme={null}
dictGetDescendants(dict_name, key, level)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `key` — Chave a ser verificada. [`const String`](/docs/pt-BR/reference/data-types/string)
* `level` — Chave a ser verificada. Nível da hierarquia. Se `level = 0`, retorna todos os descendentes até o final. [`UInt8`](/docs/pt-BR/reference/data-types/int-uint)

**Valor retornado**

Retorna os descendentes da chave. [`Array(UInt64)`](/docs/pt-BR/reference/data-types/array)

**Exemplos**

**Obter os filhos de primeiro nível de um dicionário**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetDesce⋯ary', 0, 2)─┐
│ [3,2]                    │
└──────────────────────────┘
```

<div id="dictGetFloat32">
  ## dictGetFloat32
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetFloat32(dict_name, attr_name, id_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetFloat⋯_value', 1)─┐
│               -123.123   │
└──────────────────────────┘
```

<div id="dictGetFloat32OrDefault">
  ## dictGetFloat32OrDefault
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetFloat32OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)
* `default_value_expr` — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave `id_expr`. [`Expression`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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`.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetFloat32('all_types_dict', 'Float32_value', 1)─┐
│                                               123.45 │
└──────────────────────────────────────────────────────┘
┌─dictGetFloat32OrDefault('all_types_dict', 'Float32_value', 999, -1.)─┐
│                                                                   -1 │
└──────────────────────────────────────────────────────────────────────┘
```

<div id="dictGetFloat64">
  ## dictGetFloat64
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetFloat64(dict_name, attr_name, id_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetFloat⋯_value', 1)─┐
│                 -123.123 │
└──────────────────────────┘
```

<div id="dictGetFloat64OrDefault">
  ## dictGetFloat64OrDefault
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetFloat64OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)
* `default_value_expr` — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave `id_expr`. [`Expression`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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`.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetFloat⋯_value', 1)─┐
│            987654.123456 │
└──────────────────────────┘
┌─dictGetFloat⋯, 999, nan)─┐
│                      nan │
└──────────────────────────┘
```

<div id="dictGetHierarchy">
  ## dictGetHierarchy
</div>

Introduzido em: v1.1.0

Cria um array contendo todos os ancestrais de uma chave no [dicionário hierárquico](/docs/pt-BR/reference/statements/create/dictionary/layouts/hierarchical#hierarchical-dictionaries).

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

**Sintaxe**

```sql theme={null}
dictGetHierarchy(dict_name, key)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `key` — Valor da chave. [`const String`](/docs/pt-BR/reference/data-types/string)

**Valor retornado**

Retorna os ancestrais da chave. [`Array(UInt64)`](/docs/pt-BR/reference/data-types/array)

**Exemplos**

**Obter a hierarquia de uma chave**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetHiera⋯ionary', 5)─┐
│ [5,2,1]                  │
└──────────────────────────┘
```

<div id="dictGetIPv4">
  ## dictGetIPv4
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetIPv4(dict_name, attr_name, id_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetIPv4('all_⋯ 'IPv4_value', 1)─┐
│ 192.168.0.1                         │
└─────────────────────────────────────┘
```

<div id="dictGetIPv4OrDefault">
  ## dictGetIPv4OrDefault
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetIPv4OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)
* `default_value_expr` — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave `id_expr`. [`Expression`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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`.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─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                                                                      │
└──────────────────────────────────────────────────────────────────────────────┘
```

<div id="dictGetIPv6">
  ## dictGetIPv6
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetIPv6(dict_name, attr_name, id_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetIPv6('all_⋯ 'IPv6_value', 1)─┐
│ 2001:db8:85a3::8a2e:370:7334        │
└─────────────────────────────────────┘
```

<div id="dictGetIPv6OrDefault">
  ## dictGetIPv6OrDefault
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetIPv6OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)
* `default_value_expr` — Valor ou valores retornados se o dicionário não contiver uma linha com a chave `id_expr`. [`Expression`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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`.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetIPv6('all_types_dict', 'IPv6_value', 1)─┐
│ 2001:db8:85a3::8a2e:370:7334                   │
└────────────────────────────────────────────────┘
┌─dictGetIPv6OrDefault('all_types_dict', 'IPv6_value', 999, CAST('::1', 'IPv6'))─┐
│ ::1                                                                            │
└────────────────────────────────────────────────────────────────────────────────┘
```

<div id="dictGetInt16">
  ## dictGetInt16
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetInt16(dict_name, attr_name, id_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetInt16⋯_value', 1)─┐
│                    -5000 │
└──────────────────────────┘
```

<div id="dictGetInt16OrDefault">
  ## dictGetInt16OrDefault
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetInt16OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)
* `default_value_expr` — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave `id_expr`. [`Expression`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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`.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetInt16⋯_value', 1)─┐
│                    -5000 │
└──────────────────────────┘
┌─dictGetInt16⋯', 999, -1)─┐
│                       -1 │
└──────────────────────────┘
```

<div id="dictGetInt32">
  ## dictGetInt32
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetInt32(dict_name, attr_name, id_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetInt32⋯_value', 1)─┐
│                -1000000  │
└──────────────────────────┘
```

<div id="dictGetInt32OrDefault">
  ## dictGetInt32OrDefault
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetInt32OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)
* `default_value_expr` — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave `id_expr`. [`Expression`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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`.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetInt32⋯_value', 1)─┐
│                -1000000  │
└──────────────────────────┘
┌─dictGetInt32⋯', 999, -1)─┐
│                       -1 │
└──────────────────────────┘
```

<div id="dictGetInt64">
  ## dictGetInt64
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetInt64(dict_name, attr_name, id_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetInt64⋯_value', 1)───┐
│       -9223372036854775807 │
└────────────────────────────┘
```

<div id="dictGetInt64OrDefault">
  ## dictGetInt64OrDefault
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetInt64OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)
* `default_value_expr` — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave `id_expr`. [`Expression`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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`.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetInt64⋯_value', 1)─┐
│     -9223372036854775808 │
└──────────────────────────┘
┌─dictGetInt64⋯', 999, -1)─┐
│                       -1 │
└──────────────────────────┘
```

<div id="dictGetInt8">
  ## dictGetInt8
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetInt8(dict_name, attr_name, id_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetInt8(⋯_value', 1)─┐
│                     -100 │
└──────────────────────────┘
```

<div id="dictGetInt8OrDefault">
  ## dictGetInt8OrDefault
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetInt8OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)
* `default_value_expr` — Valor(es) retornado(s) se o dicionário não contiver nenhuma linha com a chave `id_expr`. [`Expression`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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`.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetInt8(⋯_value', 1)─┐
│                     -100 │
└──────────────────────────┘
┌─dictGetInt8O⋯', 999, -1)─┐
│                       -1 │
└──────────────────────────┘
```

<div id="dictGetKeys">
  ## dictGetKeys
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetKeys('dict_name', 'attr_name', value_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Atributo a ser comparado. [`String`](/docs/pt-BR/reference/data-types/string)
* `value_expr` — Valor a ser comparado com o atributo. [`Expression`](/docs/pt-BR/reference/data-types/special-data-types/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**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─ids───┐
│ [2,4] │
└───────┘
```

<div id="dictGetOrDefault">
  ## dictGetOrDefault
</div>

Introduzido em: v18.16.0

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

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

**Sintaxe**

```sql theme={null}
dictGetOrDefault('dict_name', attr_names, id_expr, default_value)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_names` — Nome da coluna do dicionário ou tupla de nomes de colunas. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/int-uint) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)
* `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**

```sql title=Query theme={null}
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 title=Response theme={null}
0
```

<div id="dictGetOrNull">
  ## dictGetOrNull
</div>

Introduzido em: v21.4.0

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

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

**Sintaxe**

```sql theme={null}
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**

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

```response title=Response theme={null}
(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
```

<div id="dictGetRoot">
  ## dictGetRoot
</div>

Introduzido em: v26.7.0

Retorna o ancestral mais alto (a raiz) de uma chave em um [dicionário hierárquico](/docs/pt-BR/reference/statements/create/dictionary/layouts/hierarchical#hierarchical-dictionaries).

Este é um equivalente prático a obter o último elemento do array retornado por [dictGetHierarchy](#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.

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

**Sintaxe**

```sql theme={null}
dictGetRoot(dict_name, key)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `key` — Valor da chave. [`UInt64`](/docs/pt-BR/reference/data-types/int-uint)

**Valor retornado**

Retorna o ancestral de nível mais alto (a raiz) da chave. [`UInt64`](/docs/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Obter a raiz de uma chave**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetRoot(⋯ionary', 5)─┐
│                        1 │
└──────────────────────────┘
```

<div id="dictGetString">
  ## dictGetString
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetString(dict_name, attr_name, id_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetString(⋯_value', 1)─┐
│ test string                │
└────────────────────────────┘
```

<div id="dictGetStringOrDefault">
  ## dictGetStringOrDefault
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetStringOrDefault(dict_name, attr_name, id_expr, default_value_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)
* `default_value_expr` — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave `id_expr`. [`Expression`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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`.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetString('all_types_dict', 'String_value', 1)─┐
│ test string                                        │
└────────────────────────────────────────────────────┘
┌─dictGetStringOrDefault('all_types_dict', 'String_value', 999, 'default')─┐
│ default                                                                  │
└──────────────────────────────────────────────────────────────────────────┘
```

<div id="dictGetUInt16">
  ## dictGetUInt16
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetUInt16(dict_name, attr_name, id_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetUInt1⋯_value', 1)─┐
│                     5000 │
└──────────────────────────┘
```

<div id="dictGetUInt16OrDefault">
  ## dictGetUInt16OrDefault
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetUInt16OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)
* `default_value_expr` — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave `id_expr`. [`Expression`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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`.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetUInt1⋯_value', 1)─┐
│                     5000 │
└──────────────────────────┘
┌─dictGetUInt1⋯e', 999, 0)─┐
│                        0 │
└──────────────────────────┘
```

<div id="dictGetUInt32">
  ## dictGetUInt32
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetUInt32(dict_name, attr_name, id_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetUInt3⋯_value', 1)─┐
│                  1000000 │
└──────────────────────────┘
```

<div id="dictGetUInt32OrDefault">
  ## dictGetUInt32OrDefault
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetUInt32OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)
* `default_value_expr` — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave `id_expr`. [`Expression`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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`.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetUInt3⋯_value', 1)─┐
│                  1000000 │
└──────────────────────────┘
┌─dictGetUInt3⋯e', 999, 0)─┐
│                        0 │
└──────────────────────────┘
```

<div id="dictGetUInt64">
  ## dictGetUInt64
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetUInt64(dict_name, attr_name, id_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetUInt6⋯_value', 1)─┐
│      9223372036854775807 │
└──────────────────────────┘
```

<div id="dictGetUInt64OrDefault">
  ## dictGetUInt64OrDefault
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetUInt64OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)
* `default_value_expr` — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave `id_expr`. [`Expression`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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`.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetUInt6⋯_value', 1)─┐
│      9223372036854775807 │
└──────────────────────────┘
┌─dictGetUInt6⋯e', 999, 0)─┐
│                        0 │
└──────────────────────────┘
```

<div id="dictGetUInt8">
  ## dictGetUInt8
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetUInt8(dict_name, attr_name, id_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetUInt8⋯_value', 1)─┐
│                      100 │
└──────────────────────────┘
```

<div id="dictGetUInt8OrDefault">
  ## dictGetUInt8OrDefault
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetUInt8OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)
* `default_value_expr` — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave `id_expr`. [`Expression`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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`.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetUInt8⋯_value', 1)─┐
│                      100 │
└──────────────────────────┘
┌─dictGetUInt8⋯e', 999, 0)─┐
│                        0 │
└──────────────────────────┘
```

<div id="dictGetUUID">
  ## dictGetUUID
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetUUID(dict_name, attr_name, id_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictGetUUID(⋯_value', 1)─────────────┐
│ 123e4567-e89b-12d3-a456-426614174000 │
└──────────────────────────────────────┘
```

<div id="dictGetUUIDOrDefault">
  ## dictGetUUIDOrDefault
</div>

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.

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

**Sintaxe**

```sql theme={null}
dictGetUUIDOrDefault(dict_name, attr_name, id_expr, default_value_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `attr_name` — Nome da coluna do dicionário. [`String`](/docs/pt-BR/reference/data-types/string) ou [`Tuple(String)`](/docs/pt-BR/reference/data-types/tuple)
* `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`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)
* `default_value_expr` — Valor(es) retornado(s) se o dicionário não contiver uma linha com a chave `id_expr`. [`Expression`](/docs/pt-BR/reference/data-types/special-data-types/expression) ou [`Tuple(T)`](/docs/pt-BR/reference/data-types/tuple)

**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`.

<Note>
  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.
</Note>

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─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                                                                            │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="dictHas">
  ## dictHas
</div>

Introduzido em: v1.1.0

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

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

**Sintaxe**

```sql theme={null}
dictHas('dict_name', id_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `id_expr` — Valor da chave [`const String`](/docs/pt-BR/reference/data-types/string)

**Valor retornado**

Retorna `1` se a chave existir; caso contrário, `0`. [`UInt8`](/docs/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Verificar a existência de uma chave em um dicionário**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictHas('hie⋯ionary', 2)─┐
│                        1 │
└──────────────────────────┘
┌─dictHas('hie⋯ionary', 7)─┐
│                        0 │
└──────────────────────────┘
```

<div id="dictIsIn">
  ## dictIsIn
</div>

Introduzido em: v1.1.0

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

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

**Sintaxe**

```sql theme={null}
dictIsIn(dict_name, child_id_expr, ancestor_id_expr)
```

**Argumentos**

* `dict_name` — Nome do dicionário. [`String`](/docs/pt-BR/reference/data-types/string)
* `child_id_expr` — Chave a ser verificada. [`String`](/docs/pt-BR/reference/data-types/string)
* `ancestor_id_expr` — Suposto ancestral da chave `child_id_expr`. [`const String`](/docs/pt-BR/reference/data-types/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`](/docs/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Verificar a relação hierárquica**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dictIsIn('hi⋯ary', 6, 3)─┐
│                        1 │
└──────────────────────────┘
┌─dictIsIn('hi⋯ary', 3, 5)─┐
│                        0 │
└──────────────────────────┘
```