Formatos para dados de entrada e saída

Visão geral dos formatos de dados suportados para entrada e saída no ClickHouse

O ClickHouse oferece suporte à maioria dos formatos de dados textuais e binários conhecidos. Isso permite uma integração fácil com praticamente qualquer pipeline de dados existente para aproveitar os benefícios do ClickHouse.

​

Formatos de entrada

Os formatos de entrada são usados para:

• Analisar os dados fornecidos às instruções INSERT
• Executar consultas SELECT em tabelas baseadas em arquivo, como File, URL ou HDFS
• Ler dicionários

Escolher o formato de entrada certo é crucial para uma ingestão de dados eficiente no ClickHouse. Com mais de 70 formatos suportados, selecionar a opção com melhor desempenho pode impactar significativamente a velocidade de inserção, o uso de CPU e memória e a eficiência geral do sistema. Para ajudar na escolha, fizemos um benchmark do desempenho de ingestão entre os formatos, revelando os principais pontos:

• O formato Native é o formato de entrada mais eficiente, oferecendo a melhor compressão, o menor uso de recursos e a menor sobrecarga de processamento no lado do servidor.
• A compressão é essencial - LZ4 reduz o tamanho dos dados com custo mínimo de CPU, enquanto ZSTD oferece maior compressão às custas de uso adicional de CPU.
• A pré-ordenação tem impacto moderado, já que o ClickHouse já ordena com eficiência.
• O processamento em lotes melhora significativamente a eficiência - lotes maiores reduzem a sobrecarga de inserção e melhoram a taxa de transferência.

Para uma análise detalhada dos resultados e das melhores práticas, leia a análise completa do benchmark. Para ver os resultados completos dos testes, explore o dashboard online FastFormats.

​

Formatos de saída

Os formatos de saída compatíveis são usados para:

• Organizar os resultados de uma consulta SELECT
• Realizar operações de INSERT em tabelas baseadas em arquivo

​

Visão geral dos formatos

Os formatos compatíveis são:

Formato	Entrada	Saída
TabSeparated	✔	✔
TabSeparatedRaw	✔	✔
TabSeparatedWithNames	✔	✔
TabSeparatedWithNamesAndTypes	✔	✔
TabSeparatedRawWithNames	✔	✔
TabSeparatedRawWithNamesAndTypes	✔	✔
Template	✔	✔
TemplateIgnoreSpaces	✔	✗
CSV	✔	✔
CSVWithNames	✔	✔
CSVWithNamesAndTypes	✔	✔
CustomSeparated	✔	✔
CustomSeparatedWithNames	✔	✔
CustomSeparatedWithNamesAndTypes	✔	✔
SQLInsert	✗	✔
Values	✔	✔
Vertical	✗	✔
JSON	✔	✔
JSONAsString	✔	✗
JSONAsObject	✔	✗
JSONStrings	✔	✔
JSONColumns	✔	✔
JSONColumnsWithMetadata	✔	✔
JSONCompact	✔	✔
JSONCompactStrings	✗	✔
JSONCompactColumns	✔	✔
JSONEachRow	✔	✔
PrettyJSONEachRow	✗	✔
JSONEachRowWithProgress	✗	✔
JSONStringsEachRow	✔	✔
JSONStringsEachRowWithProgress	✗	✔
JSONCompactEachRow	✔	✔
JSONCompactEachRowWithNames	✔	✔
JSONCompactEachRowWithNamesAndTypes	✔	✔
JSONCompactEachRowWithProgress	✗	✔
JSONCompactStringsEachRow	✔	✔
JSONCompactStringsEachRowWithNames	✔	✔
JSONCompactStringsEachRowWithNamesAndTypes	✔	✔
JSONCompactStringsEachRowWithProgress	✗	✔
JSONObjectEachRow	✔	✔
BSONEachRow	✔	✔
TSKV	✔	✔
Pretty	✗	✔
PrettyNoEscapes	✗	✔
PrettyMonoBlock	✗	✔
PrettyNoEscapesMonoBlock	✗	✔
PrettyCompact	✗	✔
PrettyCompactNoEscapes	✗	✔
PrettyCompactMonoBlock	✗	✔
PrettyCompactNoEscapesMonoBlock	✗	✔
PrettySpace	✗	✔
PrettySpaceNoEscapes	✗	✔
PrettySpaceMonoBlock	✗	✔
PrettySpaceNoEscapesMonoBlock	✗	✔
Prometheus	✗	✔
Protobuf	✔	✔
ProtobufSingle	✔	✔
ProtobufList	✔	✔
Avro	✔	✔
AvroConfluent	✔	✔
Parquet	✔	✔
ParquetMetadata	✔	✗
Arrow	✔	✔
ArrowStream	✔	✔
ORC	✔	✔
One	✔	✗
Npy	✔	✔
RowBinary	✔	✔
RowBinaryWithNames	✔	✔
RowBinaryWithNamesAndTypes	✔	✔
RowBinaryWithDefaults	✔	✗
Native	✔	✔
Buffers	✔	✔
Null	✗	✔
Hash	✗	✔
XML	✗	✔
CapnProto	✔	✔
LineAsString	✔	✔
LineAsStringWithNames	✔	✔
LineAsStringWithNamesAndTypes	✔	✔
Regexp	✔	✗
RawBLOB	✔	✔
MsgPack	✔	✔
MySQLDump	✔	✗
DWARF	✔	✗
Markdown	✗	✔
Form	✔	✗

Você pode controlar alguns parâmetros de processamento de formatos usando as configurações do ClickHouse. Para mais informações, leia a seção Configurações.

​

Esquema de formato

O nome do arquivo que contém o esquema de formato é definido pela configuração format_schema. É necessário definir essa configuração ao usar um dos formatos Cap'n Proto e Protobuf. O esquema de formato é uma combinação de um nome de arquivo e do nome de um tipo de mensagem nesse arquivo, separados por dois-pontos, por exemplo, schemafile.proto:MessageType. Se o arquivo tiver a extensão padrão do formato (por exemplo, .proto para Protobuf), ela poderá ser omitida e, nesse caso, o esquema de formato ficará como schemafile:MessageType.

Se você inserir ou gerar dados por meio do client no modo interativo, o nome do arquivo especificado no esquema de formato pode conter um caminho absoluto ou um caminho relativo ao diretório atual no client. Se você usar o client no batch mode, o caminho para o esquema deverá ser relativo por motivos de segurança.

Se você inserir ou gerar dados por meio da interface HTTP, o nome do arquivo especificado no esquema de formato deve estar localizado no diretório especificado em format_schema_path na configuração do servidor.

​

Ignorar erros

Alguns formatos, como CSV, TabSeparated, TSKV, JSONEachRow, Template, CustomSeparated e Protobuf, podem ignorar uma linha inválida se ocorrer um erro de parsing e continuar o parsing a partir do início da próxima linha. Veja as configurações input_format_allow_errors_num e input_format_allow_errors_ratio. Limitações:

• Em caso de erro de parsing, JSONEachRow ignora todos os dados até a quebra de linha (ou EOF), portanto as linhas devem ser delimitadas por \n para que os erros sejam contados corretamente.
• Template e CustomSeparated usam o delimitador após a última coluna e o delimitador entre linhas para localizar o início da próxima linha, portanto ignorar erros só funciona se pelo menos um deles não estiver vazio.