Como usar formatos Native e binários no ClickHouse

Página que descreve o uso de formatos Native e binários no ClickHouse

O ClickHouse oferece suporte a vários formatos binários, que proporcionam melhor desempenho e uso mais eficiente de espaço. Os formatos binários também são seguros em termos de codificação de caracteres, já que os dados são salvos em formato binário.

Vamos usar some_data table e data para demonstração; sinta-se à vontade para reproduzir isso na sua instância do ClickHouse.

​

Exportando em um formato Native do ClickHouse

O formato de dados mais eficiente para exportar e importar dados entre nós do ClickHouse é o formato Native. A exportação é feita com a cláusula INTO OUTFILE:

SELECT * FROM some_data
INTO OUTFILE 'data.clickhouse' FORMAT Native

Isso criará o arquivo data.clickhouse no formato Native.

​

Importando de um formato Native

Para importar dados, podemos usar file() para arquivos menores ou para exploração:

DESCRIBE file('data.clickhouse', Native);

┌─name──┬─type───┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐
│ path  │ String │              │                    │         │                  │                │
│ month │ Date   │              │                    │         │                  │                │
│ hits  │ UInt32 │              │                    │         │                  │                │
└───────┴────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘

Ao usar a função file(), no ClickHouse Cloud você precisará executar os comandos no clickhouse client na máquina onde o arquivo está localizado. Outra opção é usar clickhouse-local para explorar arquivos localmente.

Em produção, usamos FROM INFILE para importar dados:

INSERT INTO sometable
FROM INFILE 'data.clickhouse'
FORMAT Native

​

Compressão no formato Native

Também é possível habilitar a compressão ao exportar dados no formato Native (assim como na maioria dos outros formatos) usando a cláusula COMPRESSION:

SELECT * FROM some_data
INTO OUTFILE 'data.clickhouse'
COMPRESSION 'lz4'
FORMAT Native

Usamos compressão LZ4 na exportação. Precisaremos especificá-la ao importar os dados:

INSERT INTO sometable
FROM INFILE 'data.clickhouse'
COMPRESSION 'lz4'
FORMAT Native

​

Exportando para RowBinary

Outro formato binário compatível é o RowBinary, que permite importar e exportar dados como linhas em formato binário:

SELECT * FROM some_data
INTO OUTFILE 'data.binary' FORMAT RowBinary

Isso gerará o arquivo data.binary em formato binário de linhas.

​

Explorando arquivos RowBinary

Este formato não oferece suporte à inferência automática de esquema, portanto, para explorá-lo antes de carregá-lo, precisamos definir o esquema explicitamente:

SELECT *
FROM file('data.binary', RowBinary, 'path String, month Date, hits UInt32')
LIMIT 5

┌─path───────────────────────────┬──────month─┬─hits─┐
│ Bangor_City_Forest             │ 2015-07-01 │   34 │
│ Alireza_Afzal                  │ 2017-02-01 │   24 │
│ Akhaura-Laksam-Chittagong_Line │ 2015-09-01 │   30 │
│ 1973_National_500              │ 2017-10-01 │   80 │
│ Attachment                     │ 2017-09-01 │ 1356 │
└────────────────────────────────┴────────────┴──────┘

Considere usar RowBinaryWithNames, que também adiciona uma linha de cabeçalho com a lista de colunas. RowBinaryWithNamesAndTypes também adiciona uma linha de cabeçalho adicional com os tipos das colunas.

​

Importação de arquivos RowBinary

Para carregar dados de um arquivo RowBinary, podemos usar a cláusula FROM INFILE:

INSERT INTO sometable
FROM INFILE 'data.binary'
FORMAT RowBinary

​

Importando um único valor binário usando RawBLOB

Suponha que queiramos ler um arquivo binário inteiro e salvá-lo em um campo de uma tabela. Esse é um caso em que o formato RawBLOB pode ser usado. Esse formato só pode ser usado diretamente com uma tabela de coluna única:

CREATE TABLE images(data String) ENGINE = Memory

Vamos salvar um arquivo de imagem na tabela images:

cat image.jpg | clickhouse-client -q "INSERT INTO images FORMAT RawBLOB"

Podemos verificar o tamanho do campo data, que será igual ao tamanho original do arquivo:

SELECT length(data) FROM images

┌─length(data)─┐
│         6121 │
└──────────────┘

​

Exportando dados em RawBLOB

Este formato também pode ser usado para exportar dados com a cláusula INTO OUTFILE:

SELECT * FROM images LIMIT 1
INTO OUTFILE 'out.jpg'
FORMAT RawBLOB

Observe que tivemos que usar LIMIT 1, pois exportar mais de um valor criará um arquivo corrompido.

​

MessagePack

O ClickHouse oferece suporte à importação e à exportação em MessagePack usando o MsgPack. Para exportar no formato MessagePack:

SELECT *
FROM some_data
INTO OUTFILE 'data.msgpk'
FORMAT MsgPack

Para importar dados de um arquivo no formato MessagePack:

INSERT INTO sometable
FROM INFILE 'data.msgpk'
FORMAT MsgPack

​

Protocol Buffers

Para trabalhar com Protocol Buffers, primeiro precisamos definir um arquivo de esquema:

syntax = "proto3";

message MessageType {
  string path = 1;
  date month = 2;
  uint32 hits = 3;
};

O caminho para esse arquivo de schema (schema.proto, no nosso caso) é definido na opção de configuração format_schema do formato Protobuf:

SELECT * FROM some_data
INTO OUTFILE 'proto.bin'
FORMAT Protobuf
SETTINGS format_schema = 'schema:MessageType'

Isso salva os dados no arquivo proto.bin. O ClickHouse também oferece suporte à importação de dados em Protobuf, bem como de mensagens aninhadas. Considere usar ProtobufSingle para trabalhar com uma única mensagem do Protocol Buffer (nesse caso, os delimitadores de comprimento serão omitidos).

​

Cap’n Proto

Outro formato popular de serialização binária compatível com o ClickHouse é o Cap’n Proto. Assim como no formato Protobuf, precisamos definir um arquivo de esquema (schema.capnp) no nosso exemplo:

@0xec8ff1a10aa10dbe;

struct PathStats {
  path @0 :Text;
  month @1 :UInt32;
  hits @2 :UInt32;
}

Agora podemos importar e exportar usando o formato CapnProto e este schema:

SELECT
    path,
    CAST(month, 'UInt32') AS month,
    hits
FROM some_data
INTO OUTFILE 'capnp.bin'
FORMAT CapnProto
SETTINGS format_schema = 'schema:PathStats'

Note que tivemos de converter a coluna Date para UInt32 para compatibilizá-la com os tipos correspondentes.

​

Outros formatos

O ClickHouse oferece suporte a muitos formatos, tanto de texto quanto binários, para atender a diversos cenários e plataformas. Explore mais formatos e formas de trabalhar com eles nos artigos a seguir:

• Formatos CSV e TSV
• Parquet
• Formatos JSON
• Regex e templates
• Formatos Native e binários
• Formatos SQL

Confira também o clickhouse-local — uma ferramenta portátil e completa para trabalhar com arquivos locais e remotos sem iniciar o servidor ClickHouse.