Pular para o conteúdo principal
O ClickHouse pode determinar automaticamente a estrutura dos dados de entrada em quase todos os formatos de entrada suportados. Este documento descreve quando a inferência de esquema é usada, como funciona com diferentes formatos de entrada e quais configurações podem controlá-la.

​
Uso

A inferência de esquema é usada quando o ClickHouse precisa ler dados em um formato específico e a estrutura é desconhecida.

​
Funções de tabela file, s3, url, hdfs, azureBlobStorage.

Essas funções de tabela aceitam o argumento opcional structure, com a estrutura dos dados de entrada. Se esse argumento não for especificado ou estiver definido como auto, a estrutura será inferida a partir dos dados. Exemplo: Suponha que haja um arquivo hobbies.jsonl no formato JSONEachRow no diretório user_files com o seguinte conteúdo:
O ClickHouse pode ler esses dados sem que você precise especificar sua estrutura:
Observação: o formato JSONEachRow foi identificado automaticamente com base na extensão de arquivo .jsonl. Você pode ver a estrutura identificada automaticamente usando a consulta DESCRIBE:

​
Motores de tabela File, S3, URL, HDFS, azureBlobStorage

Se a lista de colunas não for especificada na consulta CREATE TABLE, a estrutura da tabela será inferida automaticamente com base nos dados. Exemplo: Vamos usar o arquivo hobbies.jsonl. Podemos criar uma tabela com o motor File usando os dados desse arquivo:

​
clickhouse-local

clickhouse-local tem um parâmetro opcional -S/--structure para a estrutura dos dados de entrada. Se esse parâmetro não for especificado ou for definido como auto, a estrutura será inferida a partir dos dados. Exemplo: Vamos usar o arquivo hobbies.jsonl. Podemos consultar os dados desse arquivo usando clickhouse-local:

​
Usando a estrutura da tabela de inserção

Quando as funções de tabela file/s3/url/hdfs são usadas para inserir dados em uma tabela, há a opção de usar a estrutura da tabela de inserção em vez de extraí-la dos dados. Isso pode melhorar o desempenho da inserção, porque a inferência de esquema pode levar algum tempo. Além disso, isso é útil quando a tabela tem um esquema otimizado, de modo que nenhuma conversão entre tipos será realizada. Há uma configuração especial use_structure_from_insertion_table_in_table_functions que controla esse comportamento. Ela tem 3 valores possíveis:
  • 0 - a função de tabela extrairá a estrutura dos dados.
  • 1 - a função de tabela usará a estrutura da tabela de inserção.
  • 2 - o ClickHouse determinará automaticamente se é possível usar a estrutura da tabela de inserção ou recorrer à inferência de esquema. Valor padrão.
Exemplo 1: Vamos criar a tabela hobbies1 com a seguinte estrutura:
E insira os dados do arquivo hobbies.jsonl:
Nesse caso, todas as colunas do arquivo são inseridas na tabela sem alterações, então o ClickHouse usará a estrutura da tabela de inserção em vez da inferência de esquema. Exemplo 2: Vamos criar a tabela hobbies2 com a seguinte estrutura:
E insira os dados do arquivo hobbies.jsonl:
Nesse caso, todas as colunas da consulta SELECT estão presentes na tabela, então o ClickHouse usará a estrutura da tabela de inserção. Observe que isso só funciona para formatos de entrada que oferecem suporte à leitura de um subconjunto de colunas, como JSONEachRow, TSKV, Parquet etc. (ou seja, não funciona, por exemplo, com o formato TSV). Exemplo 3: Vamos criar a tabela hobbies3 com a seguinte estrutura:
E insira dados a partir do arquivo hobbies.jsonl:
Neste caso, a coluna id é usada na consulta SELECT, mas a tabela n’o tem essa coluna (ela tem uma coluna chamada identifier), portanto, o ClickHouse n’o pode usar a estrutura da tabela de inserção, e será usada a inferência de esquema. Exemplo 4: Vamos criar a tabela hobbies4 com a seguinte estrutura:
E insira dados a partir do arquivo hobbies.jsonl:
Nesse caso, algumas operações são realizadas na coluna hobbies na consulta SELECT para inseri-la na tabela; por isso, o ClickHouse não pode usar a estrutura da tabela de inserção, e será usada a inferência de esquema.

​
Cache de inferência de esquema

Na maioria dos formatos de entrada, a inferência de esquema lê parte dos dados para determinar sua estrutura, e esse processo pode levar algum tempo. Para evitar inferir o mesmo esquema sempre que o ClickHouse lê dados do mesmo arquivo, o esquema inferido é armazenado em cache e, ao acessar o mesmo arquivo novamente, o ClickHouse usa o esquema em cache. Há configurações especiais que controlam esse cache:
  • schema_inference_cache_max_elements_for_{file/s3/hdfs/url/azure} - o número máximo de esquemas em cache para a função de tabela correspondente. O valor padrão é 4096. Essas configurações devem ser definidas na configuração do servidor.
  • schema_inference_use_cache_for_{file,s3,hdfs,url,azure} - permite ativar ou desativar o uso de cache para inferência de esquema. Essas configurações podem ser usadas em consultas.
O esquema do arquivo pode mudar com a modificação dos dados ou com alterações nas configurações de formato. Por esse motivo, o cache de inferência de esquema identifica o esquema pela origem do arquivo, pelo nome do formato, pelas configurações de formato usadas e pelo horário da última modificação do arquivo. Observação: alguns arquivos acessados por URL na função de tabela url podem não conter informações sobre o horário da última modificação; nesse caso, existe uma configuração especial schema_inference_cache_require_modification_time_for_url. Desativar essa configuração permite usar o esquema em cache sem o horário da última modificação para esses arquivos. Também há uma system table schema_inference_cache com todos os esquemas atualmente em cache e a consulta de sistema SYSTEM CLEAR SCHEMA CACHE [FOR File/S3/URL/HDFS] que permite limpar o cache de esquema de todas as origens ou de uma origem específica. Exemplos: Vamos tentar inferir a estrutura de um conjunto de dados de exemplo do S3 github-2022.ndjson.gz e ver como o cache de inferência de esquema funciona:
Como você pode ver, a segunda consulta foi concluída quase instantaneamente. Vamos tentar alterar algumas configurações que podem afetar o esquema inferido:
Como você pode ver, o esquema do cache não foi usado para o mesmo arquivo, porque a configuração capaz de afetar o esquema inferido foi alterada. Vamos verificar o conteúdo da tabela system.schema_inference_cache:
Como você pode ver, há dois esquemas diferentes para o mesmo arquivo. Podemos limpar o cache de esquema usando uma consulta de sistema:

​
Formatos de texto

Para formatos de texto, o ClickHouse lê os dados linha por linha, extrai os valores das colunas de acordo com o formato e, em seguida, usa parsers recursivos e heurísticas para determinar o tipo de cada valor. O número máximo de linhas e bytes lidos dos dados durante a inferência de esquema é controlado pelas configurações input_format_max_rows_to_read_for_schema_inference (25000 por padrão) e input_format_max_bytes_to_read_for_schema_inference (32Mb por padrão). Por padrão, todos os tipos inferidos são Nullable, mas você pode alterar isso definindo schema_inference_make_columns_nullable (veja exemplos na seção configurações).

​
Formatos JSON

Nos formatos JSON, o ClickHouse analisa os valores de acordo com a especificação JSON e tenta encontrar o tipo de dado mais adequado para eles. Veja como funciona, quais tipos podem ser inferidos e quais configurações específicas podem ser usadas nos formatos JSON. Exemplos Aqui e nas seções seguintes, a table function format será usada nos exemplos. Integers, Floats, Bools, Strings:
Datas, DateTimes:
Arrays:
Se um array contiver null, o ClickHouse usará os tipos dos demais elementos do array:
Se um array contiver valores de tipos diferentes e a configuração input_format_json_infer_array_of_dynamic_from_array_of_different_types estiver habilitada (habilitada por padrão), ele terá o tipo Array(Dynamic):
Tuples nomeadas: Quando a configuração input_format_json_try_infer_named_tuples_from_objects estiver habilitada, durante a inferência de esquema o ClickHouse tentará inferir uma Tuple nomeada com base em objetos JSON. A Tuple nomeada resultante conterá todos os elementos de todos os objetos JSON correspondentes nos dados de amostra.
Tuples sem nome: Se a configuração input_format_json_infer_array_of_dynamic_from_array_of_different_types estiver desativada, tratamos Arrays com elementos de tipos distintos como Tuples sem nome em formatos JSON.
Se alguns valores forem null ou estiverem vazios, usamos os tipos dos valores correspondentes nas outras linhas:
Maps: Em JSON, podemos ler objetos com valores do mesmo tipo do tipo Map. Observação: isso só funciona quando as configurações input_format_json_read_objects_as_strings e input_format_json_try_infer_named_tuples_from_objects estão desabilitadas.
Tipos complexos aninhados:
Se o ClickHouse não conseguir determinar o tipo de alguma chave porque os dados contêm apenas valores nulos/objetos vazios/arrays vazios, o tipo String será usado se a configuração input_format_json_infer_incomplete_types_as_strings estiver habilitada; caso contrário, será gerada uma exceção:

​
Configurações do JSON

input_format_json_try_infer_numbers_from_strings
Ao habilitar esta configuração, é possível inferir números a partir de valores em string. Essa configuração vem desabilitada por padrão. Exemplo:
input_format_json_try_infer_named_tuples_from_objects
Ao habilitar essa configuração, é possível inferir Tuplas nomeadas a partir de objetos JSON. A Tupla nomeada resultante conterá todos os elementos de todos os objetos JSON correspondentes na amostra de dados. Isso pode ser útil quando os dados JSON não são esparsos, de modo que a amostra de dados contenha todas as chaves de objeto possíveis. Essa configuração vem habilitada por padrão. Exemplo
Query
Response
Query
Response
input_format_json_use_string_type_for_ambiguous_paths_in_named_tuples_inference_from_objects
Ao habilitar essa configuração, é possível usar o tipo String para caminhos ambíguos durante a inferência de Tuples nomeadas a partir de objetos JSON (quando input_format_json_try_infer_named_tuples_from_objects está habilitado), em vez de gerar uma exceção. Isso permite ler objetos JSON como Tuples nomeadas mesmo quando há caminhos ambíguos. Desabilitada por padrão. Exemplos Com a configuração desabilitada:
Query
Response
Com a configuração ativada:
Query
Response
input_format_json_read_objects_as_strings
Ativar esta configuração permite ler objetos JSON aninhados como strings. Ela pode ser usada para ler objetos JSON aninhados sem usar o tipo de objeto JSON. Esta configuração vem habilitada por padrão. Observação: ativar esta configuração só terá efeito se a configuração input_format_json_try_infer_named_tuples_from_objects estiver desabilitada.
input_format_json_read_numbers_as_strings
Ao habilitar essa configuração, é possível ler valores numéricos como strings. Essa configuração vem habilitada por padrão. Exemplo
input_format_json_read_bools_as_numbers
Ao ativar essa configuração, é possível ler valores Bool como números. Essa configuração vem ativada por padrão. Exemplo:
input_format_json_read_bools_as_strings
Ao habilitar essa configuração, é possível ler valores Bool como strings. Essa configuração vem habilitada por padrão. Exemplo:
input_format_json_read_arrays_as_strings
Ao habilitar essa configuração, é possível ler valores de arrays JSON como strings. Essa configuração vem habilitada por padrão. Exemplo
input_format_json_infer_incomplete_types_as_strings
Ativar essa configuração permite usar o tipo String para chaves JSON que contenham apenas Null/{}/[] na amostra de dados durante a inferência de esquema. Nos formatos JSON, qualquer valor pode ser lido como String se todas as configurações correspondentes estiverem habilitadas (todas elas ficam habilitadas por padrão), e podemos evitar erros como Cannot determine type for column 'column_name' by first 25000 rows of data, most likely this column contains only Nulls or empty Arrays/Maps durante a inferência de esquema usando o tipo String para chaves com tipos desconhecidos. Exemplo:
Query
Response

​
CSV

No formato CSV, o ClickHouse extrai os valores das colunas da linha de acordo com os delimitadores. O ClickHouse espera que todos os tipos, exceto números e strings, estejam entre aspas duplas. Se o valor estiver entre aspas duplas, o ClickHouse tentará analisar os dados dentro das aspas usando o parser recursivo e, em seguida, tentará encontrar o tipo de dado mais apropriado para eles. Se o valor não estiver entre aspas duplas, o ClickHouse tentará analisá-lo como um número e, se o valor não for um número, o ClickHouse o tratará como uma string. Se você não quiser que o ClickHouse tente determinar tipos complexos usando alguns parsers e heurísticas, pode desabilitar a configuração input_format_csv_use_best_effort_in_schema_inference e o ClickHouse tratará todas as colunas como Strings. Se a configuração input_format_csv_detect_header estiver habilitada, o ClickHouse tentará detectar o cabeçalho com nomes de colunas (e talvez tipos) ao inferir o esquema. Essa configuração vem habilitada por padrão. Exemplos: Inteiros, Floats, Bools, Strings:
Strings sem aspas:
Datas, DateTimes:
Arrays:
Se um array contiver NULL, ClickHouse usará os tipos dos demais elementos do array:
Maps:
Arrays e maps aninhados:
Se o ClickHouse não conseguir determinar o tipo entre aspas, porque os dados contêm apenas valores nulos, ele o tratará como String:
Exemplo com a configuração input_format_csv_use_best_effort_in_schema_inference desativada:
Exemplos de detecção automática de cabeçalho (quando input_format_csv_detect_header está ativado): Apenas nomes:
Nomes e tipos:
Observe que o cabeçalho só pode ser detectado se houver pelo menos uma coluna de tipo diferente de String. Se todas as colunas forem do tipo String, o cabeçalho não será detectado:

​
Configurações do CSV

input_format_csv_try_infer_numbers_from_strings
Ativar esta configuração permite inferir números a partir de valores de texto. Esta configuração vem desativada por padrão. Exemplo:

​
TSV/TSKV

Nos formatos TSV/TSKV, o ClickHouse extrai o valor da coluna da linha de acordo com os delimitadores tabulares e, em seguida, analisa o valor extraído usando o parser recursivo para determinar o tipo mais apropriado. Se o tipo não puder ser determinado, o ClickHouse tratará esse valor como String. Se você não quiser que o ClickHouse tente determinar tipos complexos usando alguns parsers e heurísticas, pode desativar a configuração input_format_tsv_use_best_effort_in_schema_inference e o ClickHouse tratará todas as colunas como Strings. Se a configuração input_format_tsv_detect_header estiver habilitada, o ClickHouse tentará detectar o cabeçalho com nomes de colunas (e talvez tipos) ao inferir o esquema. Essa configuração vem habilitada por padrão. Exemplos: Inteiros, Floats, Bool, Strings:
Dates, DateTimes:
Arrays:
Se um array contiver NULL, o ClickHouse usará os tipos dos demais elementos do array:
Tuplas:
Maps:
Arrays, Tuples e Maps aninhados:
Se o ClickHouse não conseguir determinar o tipo porque os dados contêm apenas valores NULL, o ClickHouse os tratará como String:
Exemplo com a configuração input_format_tsv_use_best_effort_in_schema_inference desativada:
Exemplos de detecção automática de cabeçalho (quando input_format_tsv_detect_header está ativado): Somente nomes:
Nomes e tipos:
Note que o cabeçalho só é detectado se houver pelo menos uma coluna com um tipo diferente de String. Se todas as colunas tiverem o tipo String, o cabeçalho não será detectado:

​
Valores

No formato Values, o ClickHouse extrai o valor da coluna da linha e o analisa usando o parser recursivo, de maneira semelhante à forma como os literais são analisados. Exemplos: Inteiros, Floats, Bools, Strings:
Datas, DateTimes:
Arrays:
Se um array contiver null, o ClickHouse usará os tipos dos demais elementos do array:
Tuples:
Maps:
Arrays, Tuples e Maps aninhados:
Se o ClickHouse não conseguir determinar o tipo, pois os dados contêm apenas valores nulos, será gerada uma exceção:
Exemplo com a configuração input_format_tsv_use_best_effort_in_schema_inference desativada:

​
CustomSeparated

No formato CustomSeparated, o ClickHouse primeiro extrai todos os valores das colunas da linha de acordo com os delimitadores especificados e, em seguida, tenta inferir o tipo de dado de cada valor com base na regra de escape. Se a configuração input_format_custom_detect_header estiver habilitada, o ClickHouse tentará detectar o cabeçalho com nomes de colunas (e talvez tipos) ao inferir o esquema. Essa configuração é habilitada por padrão. Exemplo
Exemplo de detecção automática de cabeçalho (quando input_format_custom_detect_header está ativado):

​
Template

No formato Template, o ClickHouse primeiro extrai todos os valores das colunas da linha de acordo com o template especificado e depois tenta inferir o tipo de dado de cada valor com base na respectiva regra de escape. Exemplo Digamos que temos um arquivo resultset com o seguinte conteúdo:
E um arquivo row_format com o conteúdo a seguir:
Em seguida, podemos executar as consultas a seguir:

​
Regexp

Semelhante ao Template, no formato Regexp o ClickHouse primeiro extrai todos os valores das colunas da linha de acordo com a expressão regular especificada e, em seguida, tenta inferir o tipo de dado de cada valor de acordo com a regra de escape especificada. Exemplo

​
Configurações para formatos de texto

​
input_format_max_rows_to_read_for_schema_inference/input_format_max_bytes_to_read_for_schema_inference

Estas configurações controlam a quantidade de dados lida durante a inferência de esquema. Quanto mais linhas/bytes forem lidos, mais tempo será gasto na inferência de esquema, mas maior será a chance de determinar corretamente os tipos (especialmente quando os dados contêm muitos valores nulos). Valores padrão:
  • 25000 para input_format_max_rows_to_read_for_schema_inference.
  • 33554432 (32 Mb) para input_format_max_bytes_to_read_for_schema_inference.

​
column_names_for_schema_inference

A lista de nomes de colunas a serem usados na inferência de esquema para formatos sem nomes de colunas explícitos. Os nomes especificados serão usados em vez do padrão c1,c2,c3,.... Formato: column1,column2,column3,.... Exemplo

​
schema_inference_hints

A lista de nomes e tipos de colunas a ser usada na inferência de esquema em vez dos tipos determinados automaticamente. O formato é: ‘column_name1 column_type1, column_name2 column_type2, …’. Essa configuração pode ser usada para especificar os tipos de colunas que não puderam ser determinados automaticamente ou para otimizar o esquema. Exemplo

​
schema_inference_make_columns_nullable $

Controla a criação de tipos inferidos como Nullable na inferência de esquema para formatos sem informações sobre nulabilidade. Valores possíveis:
  • 0 - o tipo inferido nunca será Nullable,
  • 1 - todos os tipos inferidos serão Nullable,
  • 2 ou ‘auto’ - para formatos de texto, o tipo inferido será Nullable somente se a coluna contiver NULL em uma amostra processada durante a inferência de esquema; para formatos fortemente tipados (Parquet, ORC, Arrow), as informações de nulidade são obtidas dos metadados do arquivo,
  • 3 - para formatos de texto, use Nullable; para formatos com tipagem forte, use os metadados do arquivo.
Padrão: 3. Exemplos

​
input_format_try_infer_integers

Esta configuração não se aplica ao tipo de dado JSON.
Se estiver habilitada, o ClickHouse tentará inferir inteiros em vez de números de ponto flutuante na inferência de esquema para formatos de texto. Se todos os números na coluna dos dados de amostra forem inteiros, o tipo resultante será Int64; se pelo menos um número for de ponto flutuante, o tipo resultante será Float64. Se os dados de amostra contiverem apenas inteiros e pelo menos um deles for positivo e exceder o limite de Int64, o ClickHouse inferirá UInt64. Habilitada por padrão. Exemplos

​
input_format_try_infer_datetimes

Se estiver habilitado, o ClickHouse tentará inferir o tipo DateTime ou DateTime64 a partir de campos do tipo string na inferência de esquema para formatos de texto. Se todos os campos de uma coluna nos dados de amostra forem analisados com sucesso como datetimes, o tipo resultante será DateTime ou DateTime64(9) (se algum datetime tiver parte fracionária), se pelo menos um campo não for analisado como datetime, o tipo resultante será String. Habilitado por padrão. Exemplos

​
input_format_try_infer_datetimes_only_datetime64

Se estiver habilitado, o ClickHouse sempre inferirá DateTime64(9) quando input_format_try_infer_datetimes estiver habilitado, mesmo que os valores de data e hora não contenham parte fracionária. Desabilitado por padrão. Exemplos
Observação: ao analisar valores de data e hora durante a inferência de esquema, a configuração date_time_input_format é respeitada

​
input_format_try_infer_dates

Se estiver habilitado, o ClickHouse tentará inferir o tipo Date a partir de campos do tipo string na inferência de esquema para formatos de texto. Se todos os campos de uma coluna nos dados de amostra forem analisados com sucesso como datas, o tipo resultante será Date; se pelo menos um campo não for analisado como data, o tipo resultante será String. Habilitado por padrão. Exemplos

​
input_format_try_infer_exponent_floats

Se estiver habilitado, o ClickHouse tentará inferir números de ponto flutuante em notação exponencial em formatos de texto (exceto JSON, em que números em notação exponencial são sempre inferidos). Desabilitado por padrão. Exemplo

​
Formatos autodescritivos

Os formatos autodescritivos contêm informações sobre a estrutura dos dados nos próprios dados; isso pode ser algum cabeçalho com uma descrição, uma árvore binária de tipos ou algum tipo de tabela. Para inferir automaticamente um esquema a partir de arquivos nesses formatos, o ClickHouse lê uma parte dos dados que contém informações sobre os tipos e as converte em um esquema da tabela do ClickHouse.

​
Formatos com o sufixo -WithNamesAndTypes

O ClickHouse oferece suporte a alguns formatos de texto com o sufixo -WithNamesAndTypes. Esse sufixo significa que os dados contêm duas linhas adicionais com os nomes e tipos das colunas antes dos dados propriamente ditos. Durante a inferência de esquema desses formatos, o ClickHouse lê as duas primeiras linhas e extrai os nomes e tipos das colunas. Exemplo

​
Formatos JSON com metadados

Alguns formatos de entrada JSON (JSON, JSONCompact, JSONColumnsWithMetadata) incluem metadados com nomes e tipos de colunas. Na inferência de esquema desses formatos, o ClickHouse lê esses metadados. Exemplo

​
Avro

No formato Avro, o ClickHouse lê o esquema dos dados e o converte para o esquema do ClickHouse usando as seguintes correspondências de tipos: Outros tipos do Avro não são compatíveis.

​
Parquet

No formato Parquet, o ClickHouse lê o esquema a partir dos dados e o converte para o esquema do ClickHouse usando as seguintes correspondências de tipos: Outros tipos do Parquet não são compatíveis.

​
Arrow

No formato Arrow, o ClickHouse lê o esquema dos dados e o converte para o esquema do ClickHouse usando as seguintes correspondências de tipos: Outros tipos do Arrow não são compatíveis.

​
ORC

No formato ORC, o ClickHouse lê o esquema dos dados e o converte para o esquema do ClickHouse usando as seguintes correspondências de tipos: Outros tipos de ORC não são compatíveis.

​
Native

O formato Native é usado internamente no ClickHouse e inclui o esquema nos dados. Na inferência de esquema, o ClickHouse lê o esquema diretamente dos dados, sem nenhuma transformação.

​
Formatos com esquema externo

Esses formatos exigem um esquema que descreva os dados em um arquivo separado, em uma linguagem de esquema específica. Para inferir automaticamente um esquema a partir de arquivos nesses formatos, o ClickHouse lê o esquema externo de um arquivo separado e o converte em um esquema de tabela do ClickHouse.

​
Protobuf

Na inferência de esquema do formato Protobuf, o ClickHouse usa as seguintes correspondências de tipos:

​
CapnProto

Na inferência de esquema do formato CapnProto, o ClickHouse usa as seguintes correspondências de tipos:

​
Formatos binários fortemente tipados

Nesses formatos, cada valor serializado contém informações sobre seu tipo (e possivelmente sobre seu nome), mas não há informações sobre a tabela como um todo. Na inferência de esquema para esses formatos, o ClickHouse lê os dados linha por linha (até input_format_max_rows_to_read_for_schema_inference linhas ou input_format_max_bytes_to_read_for_schema_inference bytes) e extrai o tipo (e possivelmente o nome) de cada valor a partir dos dados, convertendo então esses tipos em tipos do ClickHouse.

​
MsgPack

No formato MsgPack, não há delimitador entre linhas. Para usar a inferência de esquema nesse formato, você deve especificar o número de colunas da tabela usando a configuração input_format_msgpack_number_of_columns. O ClickHouse usa as seguintes correspondências de tipos: Por padrão, todos os tipos inferidos são Nullable, mas isso pode ser alterado usando a configuração schema_inference_make_columns_nullable.

​
BSONEachRow

No BSONEachRow, cada linha de dados é apresentada como um documento BSON. Na inferência de esquema, o ClickHouse lê os documentos BSON um a um e extrai valores, nomes e tipos dos dados, transformando esses tipos em tipos do ClickHouse de acordo com as seguintes correspondências: Por padrão, todos os tipos inferidos ficam dentro de Nullable, mas isso pode ser alterado usando a configuração schema_inference_make_columns_nullable.

​
Formatos com esquema fixo

Os dados nesses formatos sempre seguem o mesmo esquema.

​
LineAsString

Nesse formato, o ClickHouse lê a linha inteira dos dados em uma única coluna do tipo String. O tipo inferido para esse formato é sempre String, e o nome da coluna é line. Exemplo

​
JSONAsString

Nesse formato, o ClickHouse lê o objeto JSON inteiro dos dados em uma única coluna do tipo String. O tipo inferido para esse formato é sempre String, e o nome da coluna é json. Exemplo

​
JSONAsObject

Nesse formato, o ClickHouse lê o objeto JSON inteiro dos dados em uma única coluna com o tipo de dados JSON. O tipo inferido para esse formato é sempre JSON, e o nome da coluna é json. Exemplo

​
Modos de inferência de esquema

A inferência de esquema a partir do conjunto de arquivos de dados pode funcionar em 2 modos distintos: default e union. O modo é controlado pela configuração schema_inference_mode.

​
Modo padrão

No modo padrão, o ClickHouse assume que todos os arquivos têm o mesmo esquema e tenta inferi-lo lendo os arquivos um a um até conseguir. Exemplo: Digamos que temos 3 arquivos data1.jsonl, data2.jsonl e data3.jsonl com o seguinte conteúdo: data1.jsonl:
data2.jsonl:
data3.jsonl:
Vamos tentar usar a inferência de esquema nestes 3 arquivos:
Query
Response
Como podemos ver, não temos field3 do arquivo data3.jsonl. Isso acontece porque o ClickHouse primeiro tentou inferir o esquema a partir do arquivo data1.jsonl, mas falhou porque o campo field2 continha apenas valores nulos, e então tentou inferir o esquema a partir de data2.jsonl e conseguiu, portanto os dados do arquivo data3.jsonl não foram lidos.

​
Modo union

No modo union, o ClickHouse assume que os arquivos podem ter esquemas diferentes, então infere os esquemas de todos os arquivos e depois os combina em um esquema comum. Digamos que temos 3 arquivos data1.jsonl, data2.jsonl e data3.jsonl com o seguinte conteúdo: data1.jsonl:
data2.jsonl:
data3.jsonl:
Vamos tentar usar a inferência de esquema nestes 3 arquivos:
Query
Response
Como podemos ver, temos todos os campos de todos os arquivos. Observação:
  • Como alguns arquivos podem não conter algumas colunas do esquema resultante, o modo union é compatível apenas com formatos que suportam a leitura de subconjuntos de colunas (como JSONEachRow, Parquet, TSVWithNames etc.) e não funcionará com outros formatos (como CSV, TSV, JSONCompactEachRow etc.).
  • Se o ClickHouse não conseguir inferir o esquema de um dos arquivos, uma exceção será lançada.
  • Se você tiver muitos arquivos, ler o esquema de todos eles pode levar bastante tempo.

​
Detecção automática de formato

Se o formato dos dados não for especificado e não puder ser determinado pela extensão do arquivo, o ClickHouse tentará detectar o formato do arquivo com base no conteúdo. Exemplos: Digamos que temos data com o seguinte conteúdo:
Podemos inspecionar e consultar este arquivo sem especificar o formato nem a estrutura:
O ClickHouse consegue detectar apenas alguns formatos, e essa detecção leva algum tempo; por isso, é sempre melhor especificar o formato explicitamente.
Última modificação em 2 de julho de 2026