Layouts de dicionários

Tipos de layout de dicionário

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	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	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	Como `hashed`, mas reduz o uso de memória à custa de CPU.
complex_key_hashed	Como `hashed`, para chaves compostas.
complex_key_sparse_hashed	Como `sparse_hashed`, para chaves compostas.
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	Como `hashed_array`, para chaves compostas.
range_hashed	Tabela hash com intervalos ordenados. Suporta buscas por chave + intervalo de data/hora.
complex_key_range_hashed	Como `range_hashed`, para chaves compostas.
cache	Cache em memória de tamanho fixo. Apenas as chaves acessadas com frequência são armazenadas.
complex_key_cache	Como `cache`, para chaves compostas.
ssd_cache	Como `cache`, mas armazena dados em SSD com um índice em memória.
complex_key_ssd_cache	Como `ssd_cache`, para chaves compostas.
direct	Sem armazenamento em memória — consulta a origem diretamente a cada solicitação.
complex_key_direct	Como `direct`, para chaves compostas.
ip_trie	Estrutura trie para buscas rápidas de prefixos de IP (baseadas em CIDR).
hierarchical	Suporte a hierarquias com uma chave numérica que descreve relações entre pai e filho.
polygon	Buscas eficientes de ponto em polígono (geocodificação reversa).
regexp_tree	Compara chaves com uma árvore de expressões regulares.

Layouts recomendadosflat, hashed e 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 para mais detalhes.

Layouts baseados em cache não são adequados para um enriquecimento confiável no momento da inserção, pois suas entradas já aquecidas ficam restritas a cada servidor e se perdem quando um servidor é reiniciado ou substituído. O autoscaling do ClickHouse Cloud e a substituição gerenciada de nós tornam essa situação mais provável. Em vez disso, use um layout totalmente carregado; veja Dicionários com cache em caminhos de ingestão.

Especifique o layout de dicionário

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.

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.

DDL
Arquivo de configuração

CREATE DICTIONARY (...)
...
LAYOUT(LAYOUT_TYPE(param value)) -- configurações de layout
...

<clickhouse>
    <dictionary>
        ...
        <layout>
            <layout_type>
                <!-- configurações de layout -->
            </layout_type>
        </layout>
        ...
    </dictionary>
</clickhouse>

Consulte também 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; 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):

DDL
Arquivo de configuração

CREATE DICTIONARY dict_name (
    key_column UInt64,
    ...
)
PRIMARY KEY key_column

<structure>
    <id>
        <name>key_column</name>
    </id>
    ...
</structure>

Exemplo de chave composta (a chave tem um elemento do tipo String):

DDL
Arquivo de configuração

CREATE DICTIONARY dict_name (
    country_code String,
    ...
)
PRIMARY KEY country_code

<structure>
    <key>
        <attribute>
            <name>country_code</name>
            <type>String</type>
        </attribute>
    </key>
    ...
</structure>

Melhore o desempenho do dicionário

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.

Referência de SQL

Tipos de dados

Motores

Funções

Formatos

Configurações

Tabelas de sistema

Lagos de dados

Tipos de layout de dicionário

Especifique o layout de dicionário

Melhore o desempenho do dicionário

​Tipos de layout de dicionário

​Especifique o layout de dicionário

​Melhore o desempenho do dicionário

Tipos de layout de dicionário

Especifique o layout de dicionário

Melhore o desempenho do dicionário