CREATE TABLE

Cria uma nova tabela. Por padrão, as tabelas são criadas apenas no servidor atual. As consultas DDL distribuídas são implementadas por meio da cláusula ON CLUSTER, que é descrita separadamente.

Formas de sintaxe

Esta consulta pode assumir várias variações de sintaxe, dependendo do caso de uso.

Criar uma tabela com um esquema explícito

CREATE TABLE [IF NOT EXISTS] [db.]table_name [ON CLUSTER cluster]
(
    name1 [type1] [NULL|NOT NULL] [DEFAULT|MATERIALIZED|EPHEMERAL|ALIAS expr1] [COMMENT 'comment for column'] [compression_codec] [TTL expr1],
    name2 [type2] [NULL|NOT NULL] [DEFAULT|MATERIALIZED|EPHEMERAL|ALIAS expr2] [COMMENT 'comment for column'] [compression_codec] [TTL expr2],
    ...
) ENGINE = engine
  [COMMENT 'comment for table']

Cria uma tabela chamada table_name no banco de dados db ou no banco de dados atual, se db não estiver definido, com a estrutura especificada entre colchetes e o engine especificado. A estrutura da tabela é uma lista de descrições de colunas, índices secundários, projeções e restrições. Se a chave primária for compatível com o engine, ela será indicada como parâmetro do motor de tabela. Uma descrição de coluna é name type no caso mais simples. Exemplo: RegionID UInt32. Os modificadores que seguem o tipo — COMMENT, compression_codec, STATISTICS, TTL, COLLATE, PRIMARY KEY e SETTINGS por coluna — podem ser escritos em qualquer ordem, e cada um deles pode aparecer no máximo uma vez. Por exemplo, RegionID UInt32 CODEC(ZSTD) COMMENT 'comment for column' e RegionID UInt32 COMMENT 'comment for column' CODEC(ZSTD) são equivalentes. Observe que SHOW CREATE TABLE normaliza a declaração de coluna: os modificadores que permanecem nela são sempre impressos na ordem canônica COMMENT, CODEC, STATISTICS, TTL, COLLATE, SETTINGS, enquanto uma PRIMARY KEY por coluna é movida da declaração de coluna para a cláusula PRIMARY KEY no nível da tabela. Expressões também podem ser definidas para valores padrão (veja abaixo). Se necessário, a chave primária pode ser especificada com uma ou mais expressões-chave. Comentários podem ser adicionados às colunas e à tabela.

Criar uma tabela com o esquema de uma tabela existente

CREATE TABLE [IF NOT EXISTS] [db2.]table_clone AS [db.]table [ENGINE = engine]

O ClickHouse permite copiar o esquema e os dados de uma tabela existente. Para replicar o esquema de uma tabela existente: Isso cria uma tabela com a mesma estrutura de outra tabela.

Crie uma tabela com o esquema e os dados de tabelas existentes

Para replicar o esquema e os dados de uma tabela existente:

CREATE TABLE [IF NOT EXISTS] [db2.]table_clone CLONE AS [db.]table [ENGINE = engine]

Isso cria uma tabela com o mesmo esquema e os mesmos dados que uma tabela existente. Depois que a nova tabela é criada, todas as partições de db.table são anexadas a ela. Em outras palavras, os dados de db.table são clonados para db2.table_clone no momento da criação. Esta consulta é equivalente à seguinte:

CREATE TABLE [IF NOT EXISTS] [db2.]table_clone AS [db.]table [ENGINE = engine];
ALTER TABLE [db2.]table_clone ATTACH PARTITION ALL FROM [db.]table;

Para ambas as funcionalidades, você pode especificar um motor diferente para a tabela. Se o motor não for especificado, será usado o mesmo motor da tabela original (db.table).

Criar uma tabela com uma função de tabela

CREATE TABLE [IF NOT EXISTS] [db.]table_name AS table_function()

Cria uma tabela com o mesmo resultado da função de tabela especificada. A tabela criada também funcionará da mesma forma que a função de tabela correspondente.

Criar uma tabela com uma consulta SELECT

CREATE TABLE [IF NOT EXISTS] [db.]table_name[(name1 [type1], name2 [type2], ...)] ENGINE = engine AS SELECT ...

Cria uma tabela com uma estrutura igual à do resultado da consulta SELECT, com o motor engine, e a preenche com os dados de SELECT. Você também pode especificar explicitamente a definição das colunas. Se a tabela já existir e IF NOT EXISTS for especificado, a consulta não fará nada. Pode haver outras cláusulas após a cláusula ENGINE na consulta. Veja a documentação detalhada sobre como criar tabelas nas descrições de motores de tabela. Exemplo

Query

CREATE TABLE t1 (x String) ENGINE = Memory AS SELECT 1;
SELECT x, toTypeName(x) FROM t1;

Response

┌─x─┬─toTypeName(x)─┐
│ 1 │ String        │
└───┴───────────────┘

Especificar valores padrão de colunas

A descrição da coluna pode especificar uma expressão de valor padrão na forma de DEFAULT expr, MATERIALIZED expr ou ALIAS expr. Exemplo: URLDomain String DEFAULT domain(URL). A expressão expr é opcional. Se for omitida, o tipo da coluna deve ser especificado explicitamente, e o valor padrão será 0 para colunas numéricas, '' (a string vazia) para colunas de string, [] (o array vazio) para colunas de array, 1970-01-01 para colunas de data ou NULL para colunas Nullable. O tipo da coluna com valor padrão pode ser omitido; nesse caso, ele é inferido a partir do tipo de expr. Por exemplo, o tipo da coluna EventDate DEFAULT toDate(EventTime) será date. Se um tipo de dado e uma expressão de valor padrão forem especificados, será inserida uma função implícita de conversão de tipo que converte a expressão para o tipo especificado. Exemplo: Hits UInt32 DEFAULT 0 é representado internamente como Hits UInt32 DEFAULT toUInt32(0). Uma expressão de valor padrão expr pode referenciar colunas arbitrárias da tabela e constantes. O ClickHouse verifica se alterações na estrutura da tabela não introduzem loops no cálculo da expressão. Para INSERT, ele verifica se as expressões podem ser resolvidas — isto é, se todas as colunas a partir das quais elas podem ser calculadas foram fornecidas.

DEFAULT

DEFAULT expr Valor padrão comum. Se o valor dessa coluna não for especificado em uma consulta INSERT, ele será calculado com base em expr. Exemplo:

CREATE OR REPLACE TABLE test
(
    id UInt64,
    updated_at DateTime DEFAULT now(),
    updated_at_date Date DEFAULT toDate(updated_at)
)
ENGINE = MergeTree
ORDER BY id;

INSERT INTO test (id) VALUES (1);

SELECT * FROM test;
┌─id─┬──────────updated_at─┬─updated_at_date─┐
│  1 │ 2023-02-24 17:06:46 │      2023-02-24 │
└────┴─────────────────────┴─────────────────┘

MATERIALIZED

MATERIALIZED expr Expressão materializada. Os valores dessas colunas são calculados automaticamente de acordo com a expressão materializada especificada quando as linhas são inseridas. Não é possível especificar explicitamente esses valores durante INSERTs. Além disso, colunas com valor padrão desse tipo não são incluídas no resultado de SELECT *. Isso preserva a invariante de que o resultado de um SELECT * sempre pode ser inserido de volta na tabela usando INSERT. Esse comportamento pode ser desativado com a configuração asterisk_include_materialized_columns. Exemplo:

CREATE OR REPLACE TABLE test
(
    id UInt64,
    updated_at DateTime MATERIALIZED now(),
    updated_at_date Date MATERIALIZED toDate(updated_at)
)
ENGINE = MergeTree
ORDER BY id;

INSERT INTO test VALUES (1);

SELECT * FROM test;
┌─id─┐
│  1 │
└────┘

SELECT id, updated_at, updated_at_date FROM test;
┌─id─┬──────────updated_at─┬─updated_at_date─┐
│  1 │ 2023-02-24 17:08:08 │      2023-02-24 │
└────┴─────────────────────┴─────────────────┘

SELECT * FROM test SETTINGS asterisk_include_materialized_columns=1;
┌─id─┬──────────updated_at─┬─updated_at_date─┐
│  1 │ 2023-02-24 17:08:08 │      2023-02-24 │
└────┴─────────────────────┴─────────────────┘

EPHEMERAL

EPHEMERAL [expr] Coluna efêmera. Colunas desse tipo não são armazenadas na tabela e não é possível consultá-las com SELECT. O único propósito das colunas efêmeras é servir de base para expressões de valor padrão de outras colunas. Um insert sem colunas explicitamente especificadas ignorará colunas desse tipo. Isso preserva a invariante de que o resultado de um SELECT * sempre pode ser inserido de volta na tabela usando INSERT. Exemplo:

CREATE OR REPLACE TABLE test
(
    id UInt64,
    unhexed String EPHEMERAL,
    hexed FixedString(4) DEFAULT unhex(unhexed)
)
ENGINE = MergeTree
ORDER BY id;

INSERT INTO test (id, unhexed) VALUES (1, '5a90b714');

SELECT
    id,
    hexed,
    hex(hexed)
FROM test
FORMAT Vertical;

Row 1:
──────
id:         1
hexed:      Z��
hex(hexed): 5A90B714

ALIAS

ALIAS expr Colunas calculadas (sinônimo). Colunas desse tipo não são armazenadas na tabela, e não é possível fazer INSERT de valores nelas. Quando consultas SELECT fazem referência explícita a colunas desse tipo, o valor é calculado no momento da consulta a partir de expr. Por padrão, SELECT * exclui colunas ALIAS. Esse comportamento pode ser desativado com a configuração asterisk_include_alias_columns. Ao usar a consulta ALTER para adicionar novas colunas, os dados antigos dessas colunas não são gravados. Em vez disso, ao ler dados antigos que não têm valores para as novas colunas, as expressões são calculadas dinamicamente por padrão. No entanto, se a execução dessas expressões exigir colunas diferentes que não estejam indicadas na consulta, essas colunas também serão lidas, mas apenas para os blocos de dados que precisarem disso. Se você adicionar uma nova coluna a uma tabela, mas depois alterar sua expressão padrão, os valores usados para os dados antigos mudarão (para dados cujos valores não foram armazenados em disco). Observe que, ao executar mesclagens em segundo plano, os dados das colunas que estiverem ausentes em uma das partes que estão sendo mescladas serão gravados na parte mesclada. Não é possível definir valores padrão para elementos em estruturas de dados aninhadas.

CREATE OR REPLACE TABLE test
(
    id UInt64,
    size_bytes Int64,
    size String ALIAS formatReadableSize(size_bytes)
)
ENGINE = MergeTree
ORDER BY id;

INSERT INTO test VALUES (1, 4678899);

SELECT id, size_bytes, size FROM test;
┌─id─┬─size_bytes─┬─size─────┐
│  1 │    4678899 │ 4.46 MiB │
└────┴────────────┴──────────┘

SELECT * FROM test SETTINGS asterisk_include_alias_columns=1;
┌─id─┬─size_bytes─┬─size─────┐
│  1 │    4678899 │ 4.46 MiB │
└────┴────────────┴──────────┘

Modificadores `NULL` ou `NOT NULL`

Os modificadores NULL e NOT NULL, quando usados após o tipo de dado na definição da coluna, indicam se ela pode ou não ser Nullable. Se o tipo não for Nullable e NULL for especificado, ele será tratado como Nullable; se NOT NULL for especificado, não será. Por exemplo, INT NULL é o mesmo que Nullable(INT). Se o tipo for Nullable e os modificadores NULL ou NOT NULL forem especificados, uma exceção será gerada. Veja também a configuração data_type_default_nullable.

Chave primária

Você pode definir uma chave primária ao criar uma tabela. A chave primária pode ser especificada de duas formas:

Na lista de colunas

CREATE TABLE [db.]table_name
(
    name1 type1, name2 type2, ...,
    PRIMARY KEY(expr1[, expr2,...])
)
ENGINE = engine;

Fora da lista de colunas

CREATE TABLE [db.]table_name
(
    name1 type1, name2 type2, ...
)
ENGINE = engine
PRIMARY KEY(expr1[, expr2,...]);

Não é possível combinar as duas formas em uma única consulta.

Especificar restrições de tabela

Além das descrições das colunas, também é possível definir restrições:

CONSTRAINT

CREATE TABLE [IF NOT EXISTS] [db.]table_name [ON CLUSTER cluster]
(
    name1 [type1] [DEFAULT|MATERIALIZED|ALIAS expr1] [compression_codec] [TTL expr1],
    ...
    CONSTRAINT constraint_name_1 CHECK boolean_expr_1,
    ...
) ENGINE = engine

boolean_expr_1 pode ser qualquer expressão booleana. Se forem definidas restrições para a tabela, cada uma delas será verificada para cada linha na consulta INSERT. Se alguma restrição não for atendida — o servidor gerará uma exceção com o nome da restrição e a expressão de verificação. Adicionar um grande número de restrições pode afetar negativamente o desempenho de consultas INSERT grandes. As restrições existentes em todas as tabelas podem ser inspecionadas por meio da tabela system.constraints.

ASSUME

A cláusula ASSUME é usada para definir uma CONSTRAINT em uma tabela que se presume ser true. Essa restrição pode então ser usada pelo otimizador para melhorar o desempenho das consultas SQL. Veja este exemplo em que ASSUME CONSTRAINT é usado na criação da tabela users_a:

CREATE TABLE users_a (
    uid Int16, 
    name String, 
    age Int16, 
    name_len UInt8 MATERIALIZED length(name), 
    CONSTRAINT c1 ASSUME length(name) = name_len
) 
ENGINE=MergeTree 
ORDER BY (name_len, name);

Aqui, ASSUME CONSTRAINT é usado para declarar que a função length(name) é sempre igual ao valor da coluna name_len. Isso significa que, sempre que length(name) for chamada em uma consulta, o ClickHouse poderá substituí-la por name_len, o que tende a ser mais rápido, pois evita chamar a função length(). Assim, ao executar a consulta SELECT name FROM users_a WHERE length(name) < 5;, o ClickHouse pode otimizá-la para SELECT name FROM users_a WHERE name_len < 5; por causa de ASSUME CONSTRAINT. Isso pode fazer com que a consulta seja executada mais rapidamente, pois evita calcular o comprimento de name para cada linha. ASSUME CONSTRAINT não impõe a restrição; ele apenas informa ao otimizador que a restrição é válida. Se a restrição não for realmente válida, os resultados das consultas poderão estar incorretos. Portanto, você só deve usar ASSUME CONSTRAINT se tiver certeza de que a restrição é válida.

Defina o tempo de armazenamento com TTL

Define por quanto tempo os valores são armazenados. Pode ser especificada apenas para tabelas da família MergeTree. Para uma descrição detalhada, consulte TTL para colunas e tabelas.

Selecionar codecs de compressão para colunas

Por padrão, o ClickHouse usa a compressão lz4 na versão autogerenciada e zstd no ClickHouse Cloud. Também é possível definir o método de compressão de cada coluna na consulta CREATE TABLE:

CREATE TABLE codec_example
(
    dt Date CODEC(ZSTD),
    ts DateTime CODEC(LZ4HC),
    float_value Float32 CODEC(NONE),
    double_value Float64 CODEC(LZ4HC(9)),
    value Float32 CODEC(Delta, ZSTD)
)
ENGINE = <Engine>
...

Para ver os codecs de uso geral, especializados e de criptografia disponíveis, consulte Codecs de compressão de colunas.

Criar tabelas temporárias

O ClickHouse oferece suporte a tabelas temporárias, que desaparecem quando a sessão é encerrada. Para mais detalhes, consulte CREATE TEMPORARY TABLE.

Atualize uma tabela atomicamente com REPLACE TABLE

A instrução REPLACE permite atualizar uma tabela atomicamente. Para obter detalhes, consulte REPLACE TABLE.

Adicionar um comentário à tabela

Você pode adicionar um comentário à tabela ao criá-la. Sintaxe

CREATE TABLE [db.]table_name
(
    name1 type1, name2 type2, ...
)
ENGINE = engine
COMMENT 'Comment'

A cláusula COMMENT deve ser especificada depois de quaisquer cláusulas específicas de armazenamento, como PARTITION BY, ORDER BY e SETTINGS específicos de armazenamento.Após a cláusula COMMENT, apenas SETTINGS específicos da consulta (como max_threads etc.) serão interpretados, e não as configurações relacionadas ao armazenamento.Isso significa que a ordem correta das cláusulas é:

ENGINE
cláusulas de armazenamento
COMMENT
configurações da consulta (se houver)

Exemplo

Query

CREATE TABLE t1 (x String) ENGINE = Memory COMMENT 'The temporary table';
SELECT name, comment FROM system.tables WHERE name = 't1';

Response

┌─name─┬─comment─────────────┐
│ t1   │ The temporary table │
└──────┴─────────────────────┘

Referência SQL

Tipos de dados

Motores

Funções

Formatos

Interfaces

Configurações

Tabelas do sistema

Lagos de dados

Formas de sintaxe

Criar uma tabela com um esquema explícito

Criar uma tabela com o esquema de uma tabela existente

Crie uma tabela com o esquema e os dados de tabelas existentes

Criar uma tabela com uma função de tabela

Criar uma tabela com uma consulta SELECT

Especificar valores padrão de colunas

DEFAULT

MATERIALIZED

EPHEMERAL

ALIAS

Modificadores `NULL` ou `NOT NULL`

Chave primária

Especificar restrições de tabela

CONSTRAINT

ASSUME

Defina o tempo de armazenamento com TTL

Selecionar codecs de compressão para colunas

Criar tabelas temporárias

Atualize uma tabela atomicamente com REPLACE TABLE

Adicionar um comentário à tabela

​Formas de sintaxe

​Criar uma tabela com um esquema explícito

​Criar uma tabela com o esquema de uma tabela existente

​Crie uma tabela com o esquema e os dados de tabelas existentes

​Criar uma tabela com uma função de tabela

​Criar uma tabela com uma consulta SELECT

​Especificar valores padrão de colunas

​DEFAULT

​MATERIALIZED

​EPHEMERAL

​ALIAS

​Modificadores NULL ou NOT NULL

​Chave primária

​Especificar restrições de tabela

​CONSTRAINT

​ASSUME

​Defina o tempo de armazenamento com TTL

​Selecionar codecs de compressão para colunas

​Criar tabelas temporárias

​Atualize uma tabela atomicamente com REPLACE TABLE

​Adicionar um comentário à tabela

​Conteúdo relacionado

Formas de sintaxe

Criar uma tabela com um esquema explícito

Criar uma tabela com o esquema de uma tabela existente

Crie uma tabela com o esquema e os dados de tabelas existentes

Criar uma tabela com uma função de tabela

Criar uma tabela com uma consulta SELECT

Especificar valores padrão de colunas

DEFAULT

MATERIALIZED

EPHEMERAL

ALIAS

Modificadores `NULL` ou `NOT NULL`

Chave primária

Especificar restrições de tabela

CONSTRAINT

ASSUME

Defina o tempo de armazenamento com TTL

Selecionar codecs de compressão para colunas

Criar tabelas temporárias

Atualize uma tabela atomicamente com REPLACE TABLE

Adicionar um comentário à tabela

Conteúdo relacionado