> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Tipos de layout de dicionários para armazená-los na memória

# Layouts de dicionários

<div id="storing-dictionaries-in-memory">
  ## Tipos de layout de dicionário
</div>

Há várias formas de armazenar dicionários em memória, cada uma com diferentes compensações entre uso de CPU e de RAM.

| Layout | Descrição |
| - | - |
| [flat](/pt-BR/reference/statements/create/dictionary/layouts/flat) | Armazena dados em arrays simples indexados por chave. É o layout mais rápido, mas as chaves devem ser `UInt64` e estar dentro do limite de `max_array_size`. |
| [hashed](/pt-BR/reference/statements/create/dictionary/layouts/hashed) | Armazena dados em uma tabela hash. Não há limite para o tamanho da chave, e ele suporta qualquer número de elementos. |
| [sparse\_hashed](/pt-BR/reference/statements/create/dictionary/layouts/hashed#sparse_hashed) | Como `hashed`, mas reduz o uso de memória à custa de CPU. |
| [complex\_key\_hashed](/pt-BR/reference/statements/create/dictionary/layouts/hashed#complex_key_hashed) | Como `hashed`, para chaves compostas. |
| [complex\_key\_sparse\_hashed](/pt-BR/reference/statements/create/dictionary/layouts/hashed#complex_key_sparse_hashed) | Como `sparse_hashed`, para chaves compostas. |
| [hashed\_array](/pt-BR/reference/statements/create/dictionary/layouts/hashed-array) | Atributos armazenados em arrays com uma tabela hash que mapeia chaves para índices do array. Eficiente em termos de memória para muitos atributos. |
| [complex\_key\_hashed\_array](/pt-BR/reference/statements/create/dictionary/layouts/hashed-array#complex_key_hashed_array) | Como `hashed_array`, para chaves compostas. |
| [range\_hashed](/pt-BR/reference/statements/create/dictionary/layouts/range-hashed) | Tabela hash com intervalos ordenados. Suporta buscas por chave + intervalo de data/hora. |
| [complex\_key\_range\_hashed](/pt-BR/reference/statements/create/dictionary/layouts/range-hashed#complex_key_range_hashed) | Como `range_hashed`, para chaves compostas. |
| [cache](/pt-BR/reference/statements/create/dictionary/layouts/cache) | Cache em memória de tamanho fixo. Apenas as chaves acessadas com frequência são armazenadas. |
| [complex\_key\_cache](/pt-BR/reference/statements/create/dictionary/layouts/hashed#complex_key_hashed) | Como `cache`, para chaves compostas. |
| [ssd\_cache](/pt-BR/reference/statements/create/dictionary/layouts/ssd-cache) | Como `cache`, mas armazena dados em SSD com um índice em memória. |
| [complex\_key\_ssd\_cache](/pt-BR/reference/statements/create/dictionary/layouts/ssd-cache#complex_key_ssd_cache) | Como `ssd_cache`, para chaves compostas. |
| [direct](/pt-BR/reference/statements/create/dictionary/layouts/direct) | Sem armazenamento em memória — consulta a origem diretamente a cada solicitação. |
| [complex\_key\_direct](/pt-BR/reference/statements/create/dictionary/layouts/direct#complex_key_direct) | Como `direct`, para chaves compostas. |
| [ip\_trie](/pt-BR/reference/statements/create/dictionary/layouts/ip-trie) | Estrutura trie para buscas rápidas de prefixos de IP (baseadas em CIDR). |
| [hierarchical](/pt-BR/reference/statements/create/dictionary/layouts/hierarchical) | Suporte a hierarquias com uma chave numérica que descreve relações entre pai e filho. |
| [polygon](/pt-BR/reference/statements/create/dictionary/layouts/polygon) | Buscas eficientes de ponto em polígono (geocodificação reversa). |
| [regexp\_tree](/pt-BR/reference/statements/create/dictionary/layouts/regexp-tree) | Compara chaves com uma árvore de expressões regulares. |

<Tip>
  **Layouts recomendados**

  [flat](/pt-BR/reference/statements/create/dictionary/layouts/flat), [hashed](/pt-BR/reference/statements/create/dictionary/layouts/hashed) e [complex\_key\_hashed](/pt-BR/reference/statements/create/dictionary/layouts/hashed#complex_key_hashed) oferecem o melhor desempenho de consultas.
  Layouts com cache não são recomendados devido ao desempenho potencialmente ruim e à dificuldade de ajustar os parâmetros — veja [cache](/pt-BR/reference/statements/create/dictionary/layouts/cache) para mais detalhes.
</Tip>

<div id="specify-dictionary-layout">
  ## Especifique o layout de dicionário
</div>

<Tip>
  Se você estiver usando um dicionário com o ClickHouse Cloud, use a opção de consulta DDL para criar seus dicionários e crie o dicionário como o usuário `default`.
  Além disso, verifique a lista de fontes de dicionário compatíveis no [guia de compatibilidade com a Cloud](/pt-BR/products/cloud/guides/cloud-compatibility).
</Tip>

Você pode configurar um layout de dicionário com a cláusula `LAYOUT` (para DDL) ou com a configuração `layout` em definições de arquivo de configuração.

<Tabs>
  <Tab title="DDL">
    ```sql theme={null}
    CREATE DICTIONARY (...)
    ...
    LAYOUT(LAYOUT_TYPE(param value)) -- configurações de layout
    ...
    ```
  </Tab>

  <Tab title="Arquivo de configuração">
    ```xml theme={null}
    <clickhouse>
        <dictionary>
            ...
            <layout>
                <layout_type>
                    <!-- configurações de layout -->
                </layout_type>
            </layout>
            ...
        </dictionary>
    </clickhouse>
    ```
  </Tab>
</Tabs>

<br />

Consulte também [CREATE DICTIONARY](/pt-BR/reference/statements/create/dictionary) para ver a sintaxe DDL completa.

Dicionários cujo layout não contém a palavra `complex-key*` têm uma chave do tipo [UInt64](/pt-BR/reference/data-types/int-uint); dicionários `complex-key*` têm uma chave composta (complexa, com tipos arbitrários).

**Exemplo de chave numérica** (a coluna key\_column é do tipo [UInt64](/pt-BR/reference/data-types/int-uint)):

<Tabs>
  <Tab title="DDL">
    ```sql theme={null}
    CREATE DICTIONARY dict_name (
        key_column UInt64,
        ...
    )
    PRIMARY KEY key_column
    ```
  </Tab>

  <Tab title="Arquivo de configuração">
    ```xml theme={null}
    <structure>
        <id>
            <name>key_column</name>
        </id>
        ...
    </structure>
    ```
  </Tab>
</Tabs>

<br />

**Exemplo de chave composta** (a chave tem um elemento do tipo [String](/pt-BR/reference/data-types/string)):

<Tabs>
  <Tab title="DDL">
    ```sql theme={null}
    CREATE DICTIONARY dict_name (
        country_code String,
        ...
    )
    PRIMARY KEY country_code
    ```
  </Tab>

  <Tab title="Arquivo de configuração">
    ```xml theme={null}
    <structure>
        <key>
            <attribute>
                <name>country_code</name>
                <type>String</type>
            </attribute>
        </key>
        ...
    </structure>
    ```
  </Tab>
</Tabs>

<div id="improve-performance">
  ## Melhore o desempenho do dicionário
</div>

Há várias formas de melhorar o desempenho do dicionário:

* Chame a função usada para trabalhar com o dicionário após o `GROUP BY`.
* Marque como injetivos os atributos a serem extraídos.
  Um atributo é considerado injetivo se chaves diferentes corresponderem a valores de atributo diferentes.
  Portanto, quando o `GROUP BY` usa uma função que busca um valor de atributo pela chave, essa função é automaticamente removida do `GROUP BY`.

O ClickHouse retorna uma exceção em caso de erros relacionados a dicionários.
Exemplos de erros podem ser:

* Não foi possível carregar o dicionário acessado.
* Erro ao consultar um dicionário `cached`.

Você pode consultar a lista de dicionários e seus status na tabela [system.dictionaries](/pt-BR/reference/system-tables/dictionaries).