Enum

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

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.

​

Exemplos de uso

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

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.

CREATE TABLE t_enum
(
    x Enum('hello', 'world')
)
ENGINE = TinyLog

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

CREATE TABLE t_enum
(
    x Enum('hello' = 1, 'world')
)
ENGINE = TinyLog

CREATE TABLE t_enum
(
    x Enum8('hello' = -129, 'world')
)
ENGINE = TinyLog

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.

INSERT INTO t_enum VALUES ('hello'), ('world'), ('hello')

Ok.

INSERT INTO t_enum VALUES('a')

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.

SELECT * FROM t_enum

┌─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.

SELECT CAST(x, 'Int8') FROM t_enum

┌─CAST(x, 'Int8')─┐
│               1 │
│               2 │
│               1 │
└─────────────────┘

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

SELECT toTypeName(CAST('a', 'Enum(\'a\' = 1, \'b\' = 2)'))

┌─toTypeName(CAST('a', 'Enum(\'a\' = 1, \'b\' = 2)'))─┐
│ Enum8('a' = 1, 'b' = 2)                             │
└─────────────────────────────────────────────────────┘

​

Regras gerais e uso

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.

Um Enum pode estar contido no tipo Nullable. Portanto, se você criar uma tabela usando a consulta

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.

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.