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

> Documentação do tipo de dado Enum no ClickHouse, que representa um conjunto de valores constantes nomeados

# Enum

Tipo enumerado composto por valores nomeados.

Os valores nomeados podem ser declarados como pares `'string' = integer` ou como nomes `'string'`. O ClickHouse armazena apenas números, mas oferece suporte a operações com os valores por meio de seus nomes.

O ClickHouse oferece suporte a:

* `Enum` de 8 bits. Pode conter até 256 valores enumerados no intervalo `[-128, 127]`.
* `Enum` de 16 bits. Pode conter até 65536 valores enumerados no intervalo `[-32768, 32767]`.

O ClickHouse escolhe automaticamente o tipo de `Enum` quando os dados são inseridos. Você também pode usar os tipos `Enum8` ou `Enum16` para garantir o tamanho de armazenamento.

<div id="usage-examples">
  ## Exemplos de uso
</div>

Aqui, criamos uma tabela com uma coluna do tipo `Enum8('hello' = 1, 'world' = 2)`:

```sql theme={null}
CREATE TABLE t_enum
(
    x Enum('hello' = 1, 'world' = 2)
)
ENGINE = TinyLog
```

Da mesma forma, você pode omitir os números. O ClickHouse atribuirá automaticamente números consecutivos. Por padrão, os números são atribuídos a partir de 1.

```sql theme={null}
CREATE TABLE t_enum
(
    x Enum('hello', 'world')
)
ENGINE = TinyLog
```

Você também pode especificar um número inicial permitido para o primeiro nome.

```sql theme={null}
CREATE TABLE t_enum
(
    x Enum('hello' = 1, 'world')
)
ENGINE = TinyLog
```

```sql theme={null}
CREATE TABLE t_enum
(
    x Enum8('hello' = -129, 'world')
)
ENGINE = TinyLog
```

```text theme={null}
Exception on server:
Code: 69. DB::Exception: Value -129 for element 'hello' exceeds range of Enum8.
```

A coluna `x` só pode armazenar valores listados na definição do tipo: `'hello'` ou `'world'`. Se você tentar salvar qualquer outro valor, o ClickHouse lançará uma exceção. O tamanho de 8 bits para este `Enum` é selecionado automaticamente.

```sql theme={null}
INSERT INTO t_enum VALUES ('hello'), ('world'), ('hello')
```

```text theme={null}
Ok.
```

```sql theme={null}
INSERT INTO t_enum VALUES('a')
```

```text theme={null}
Exception on client:
Code: 49. DB::Exception: Unknown element 'a' for type Enum('hello' = 1, 'world' = 2)
```

Ao consultar dados da tabela, o ClickHouse retorna os valores string de `Enum`.

```sql theme={null}
SELECT * FROM t_enum
```

```text theme={null}
┌─x─────┐
│ hello │
│ world │
│ hello │
└───────┘
```

Se você precisar ver os equivalentes numéricos das linhas, será necessário converter o valor `Enum` para um tipo inteiro.

```sql theme={null}
SELECT CAST(x, 'Int8') FROM t_enum
```

```text theme={null}
┌─CAST(x, 'Int8')─┐
│               1 │
│               2 │
│               1 │
└─────────────────┘
```

Para criar um valor de Enum em uma consulta, também é necessário usar `CAST`.

```sql theme={null}
SELECT toTypeName(CAST('a', 'Enum(\'a\' = 1, \'b\' = 2)'))
```

```text theme={null}
┌─toTypeName(CAST('a', 'Enum(\'a\' = 1, \'b\' = 2)'))─┐
│ Enum8('a' = 1, 'b' = 2)                             │
└─────────────────────────────────────────────────────┘
```

<div id="general-rules-and-usage">
  ## Regras gerais e uso
</div>

Cada um dos valores recebe um número no intervalo `-128 ... 127` para `Enum8` ou no intervalo `-32768 ... 32767` para `Enum16`. Todas as strings e todos os números devem ser diferentes. Uma string vazia é permitida. Se esse tipo for especificado (na definição da tabela), os números podem estar em qualquer ordem. No entanto, a ordem não importa.

Nem a string nem o valor numérico em um `Enum` podem ser [NULL](/pt-BR/reference/syntax).

Um `Enum` pode estar contido no tipo [Nullable](/pt-BR/reference/data-types/nullable). Portanto, se você criar uma tabela usando a consulta

```sql theme={null}
CREATE TABLE t_enum_nullable
(
    x Nullable( Enum8('hello' = 1, 'world' = 2) )
)
ENGINE = TinyLog
```

ele pode armazenar não só `'hello'` e `'world'`, mas também `NULL`.

```sql theme={null}
INSERT INTO t_enum_nullable VALUES('hello'),('world'),(NULL)
```

Na RAM, uma coluna `Enum` é armazenada da mesma forma que `Int8` ou `Int16` dos valores numéricos correspondentes.

Ao ler em formato de texto, o ClickHouse interpreta o valor como uma string e procura a string correspondente no conjunto de valores do Enum. Se não a encontrar, uma exceção é lançada. Ao ler em formato de texto, a string é lida e o valor numérico correspondente é buscado. Uma exceção será lançada se ele não for encontrado.
Ao gravar em formato de texto, o valor é gravado como a string correspondente. Se os dados da coluna contiverem lixo (números que não pertencem ao conjunto válido), uma exceção é lançada. Ao ler e gravar em formato binário, funciona da mesma forma que para os tipos de dados Int8 e Int16.
O valor padrão implícito é o valor com o menor número.

Durante `ORDER BY`, `GROUP BY`, `IN`, `DISTINCT` e assim por diante, Enums se comportam da mesma forma que os números correspondentes. Por exemplo, ORDER BY os classifica numericamente. Os operadores de igualdade e comparação funcionam da mesma forma para Enums e para os valores numéricos subjacentes.

Valores Enum não podem ser comparados com números. Enums podem ser comparados com uma string constante. Se a string usada na comparação não for um valor válido para o Enum, uma exceção será lançada. O operador IN é compatível com o Enum no lado esquerdo e um conjunto de strings no lado direito. As strings são os valores do Enum correspondente.

A maioria das operações numéricas e de string não está definida para valores Enum, por exemplo, somar um número a um Enum ou concatenar uma string a um Enum.
No entanto, o Enum tem uma função `toString` nativa que retorna seu valor em string.

Os valores Enum também podem ser convertidos para tipos numéricos usando a função `toT`, em que T é um tipo numérico. Quando T corresponde ao tipo numérico subjacente do enum, essa conversão não tem custo.
O tipo Enum pode ser alterado sem custo usando ALTER, se apenas o conjunto de valores for alterado. É possível tanto adicionar quanto remover membros do Enum usando ALTER (remover só é seguro se o valor removido nunca tiver sido usado na tabela). Como medida de proteção, alterar o valor numérico de um membro do Enum definido anteriormente lançará uma exceção.

Usando ALTER, é possível alterar um Enum8 para um Enum16 ou vice-versa, assim como ao alterar um Int8 para Int16.