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

> Documentação para criar e configurar dicionários

# CREATE DICTIONARY

export const CloudSupportedBadge = () => <div className="cloudBadge">
    <div className="cloudIcon">
      <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
        <path fillRule="evenodd" clipRule="evenodd" d="M5.33395 12.6667H12.3739C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00004 12.3739 8.00004H12.0839V7.33337C12.0839 5.12671 10.2906 3.33337 8.08395 3.33337C6.09928 3.33337 4.45395 4.78537 4.14195 6.68204C2.55728 6.76271 1.29395 8.06204 1.29395 9.66671C1.29395 11.3234 2.63728 12.6667 4.29395 12.6667H5.33395Z" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
      </svg>
    </div>
    {"Supported in ClickHouse Cloud"}
  </div>;

export const CloudNotSupportedBadge = () => {
  return <div className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            Not supported in ClickHouse Cloud
        </div>;
};

Um dicionário é um mapeamento (`key -> attributes`) útil para vários tipos de listas de referência.
O ClickHouse oferece funções especiais para trabalhar com dicionários que podem ser usadas em consultas. Usar dicionários com funções é mais fácil e mais eficiente do que fazer um `JOIN` com tabelas de referência.

Os dicionários podem ser criados de duas formas:

* [Com uma consulta DDL](#creating-a-dictionary-with-a-ddl-query) (recomendado)
* [Com um arquivo de configuração](#creating-a-dictionary-with-a-configuration-file)

<div id="creating-a-dictionary-with-a-ddl-query">
  ## Criando um Dicionário com uma consulta DDL
</div>

<CloudSupportedBadge />

Os dicionários podem ser criados com consultas DDL.
Este é o método recomendado porque, com dicionários criados por DDL:

* Nenhum registro adicional é adicionado aos arquivos de configuração do servidor.
* Os dicionários podem ser usados como entidades de primeira classe, como tabelas ou views.
* Os dados podem ser lidos diretamente, usando a sintaxe familiar de `SELECT` em vez de funções de tabela de dicionário. Observe que, ao acessar um dicionário diretamente por meio de uma instrução `SELECT`, um dicionário em cache retornará apenas os dados armazenados em cache, enquanto um dicionário sem cache retornará todos os dados que armazena.
* Os dicionários podem ser renomeados facilmente.

<div id="syntax">
  ### Sintaxe
</div>

```sql theme={null}
CREATE [OR REPLACE] DICTIONARY [IF NOT EXISTS] [db.]dictionary_name [ON CLUSTER cluster]
(
    key1  type1  [DEFAULT | EXPRESSION expr1] [IS_OBJECT_ID],
    key2  type2  [DEFAULT | EXPRESSION expr2],
    attr1 type2  [DEFAULT | EXPRESSION expr3] [HIERARCHICAL|INJECTIVE],
    attr2 type2  [DEFAULT | EXPRESSION expr4] [HIERARCHICAL|INJECTIVE]
)
PRIMARY KEY key1, key2
SOURCE(SOURCE_NAME([param1 value1 ... paramN valueN]))
LAYOUT(LAYOUT_NAME([param_name param_value]))
LIFETIME({MIN min_val MAX max_val | max_val})
SETTINGS(setting_name = setting_value, setting_name = setting_value, ...)
COMMENT 'Comment'
```

| Cláusula                                                                   | Descrição                                                                                                                                                                      |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Atributos](/pt-BR/reference/statements/create/dictionary/attributes)      | Os atributos do dicionário são especificados de forma semelhante às colunas de uma tabela. A única propriedade obrigatória é o tipo; todas as outras podem ter valores padrão. |
| PRIMARY KEY                                                                | Define a(s) coluna(s)-chave para buscas no dicionário. Dependendo do layout, um ou mais atributos podem ser especificados como chaves.                                         |
| [`SOURCE`](/pt-BR/reference/statements/create/dictionary/sources/overview) | Define a fonte de dados do dicionário (por exemplo, tabela do ClickHouse, HTTP, PostgreSQL).                                                                                   |
| [`LAYOUT`](/pt-BR/reference/statements/create/dictionary/layouts/overview) | Controla como o dicionário é armazenado em memória (por exemplo, `FLAT`, `HASHED`, `CACHE`).                                                                                   |
| [`LIFETIME`](/pt-BR/reference/statements/create/dictionary/lifetime)       | Define o intervalo de atualização do dicionário.                                                                                                                               |
| [`ON CLUSTER`](/pt-BR/reference/statements/distributed-ddl)                | Cria o dicionário em um cluster. Opcional.                                                                                                                                     |
| `SETTINGS`                                                                 | Configurações adicionais do dicionário. Opcional.                                                                                                                              |
| `COMMENT`                                                                  | Adiciona um comentário ao dicionário. Opcional.                                                                                                                                |

<div id="creating-a-dictionary-with-a-configuration-file">
  ## Criando um dicionário com um arquivo de configuração
</div>

<Note>
  Criar um dicionário com um arquivo de configuração não se aplica ao ClickHouse Cloud. Use DDL (veja acima) e crie o dicionário como o usuário `default`.
</Note>

O arquivo de configuração do dicionário tem o seguinte formato:

```xml theme={null}
<clickhouse>
    <comment>An optional element with any content. Ignored by the ClickHouse server.</comment>

    <!--Elemento opcional. Nome do arquivo com substituições-->
    <include_from>/etc/metrika.xml</include_from>

    <dictionary>
        <!-- Configuração do dicionário. -->
        <!-- É possível ter qualquer número de seções de dicionário em um arquivo de configuração. -->
    </dictionary>

</clickhouse>
```

Você pode configurar quantos dicionários quiser no mesmo arquivo.

<div id="related-content">
  ## Conteúdo relacionado
</div>

* [Layouts](/pt-BR/reference/statements/create/dictionary/layouts/overview) — Como os dicionários são armazenados na memória
* [Fontes](/pt-BR/reference/statements/create/dictionary/sources/overview) — Conexão com fontes de dados
* [Tempo de vida](/pt-BR/reference/statements/create/dictionary/lifetime) — Configuração de atualização automática
* [Atributos](/pt-BR/reference/statements/create/dictionary/attributes) — Configuração de chave e atributos
* [Dicionários incorporados](/pt-BR/reference/statements/create/dictionary/embedded) — Dicionários geobase integrados
* [system.dictionaries](/pt-BR/reference/system-tables/dictionaries) — Tabela de sistema com informações sobre dicionários