Trabalhando com Parquet no ClickHouse

Parquet é um formato de arquivo eficiente para armazenar dados de forma colunar. O ClickHouse oferece suporte tanto para leitura quanto para gravação de arquivos Parquet.

Importando de Parquet

Antes de carregar os dados, podemos usar a função file() para explorar a estrutura de um arquivo Parquet de exemplo:

DESCRIBE TABLE file('data.parquet', Parquet);

Usamos Parquet como segundo argumento, para que o ClickHouse saiba qual é o formato do arquivo. Isso exibirá as colunas com os tipos:

┌─name─┬─type─────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐
│ path │ Nullable(String) │              │                    │         │                  │                │
│ date │ Nullable(String) │              │                    │         │                  │                │
│ hits │ Nullable(Int64)  │              │                    │         │                  │                │
└──────┴──────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘

Também podemos explorar arquivos antes de realmente importar os dados, aproveitando todo o poder do SQL:

SELECT *
FROM file('data.parquet', Parquet)
LIMIT 3;

┌─path──────────────────────┬─date───────┬─hits─┐
│ Akiba_Hebrew_Academy      │ 2017-08-01 │  241 │
│ Aegithina_tiphia          │ 2018-02-01 │   34 │
│ 1971-72_Utah_Stars_season │ 2016-10-01 │    1 │
└───────────────────────────┴────────────┴──────┘

Importando para uma tabela existente

Vamos criar uma tabela na qual importaremos dados Parquet:

CREATE TABLE sometable
(
    `path` String,
    `date` Date,
    `hits` UInt32
)
ENGINE = MergeTree
ORDER BY (date, path);

Agora podemos importar os dados usando a cláusula FROM INFILE:

INSERT INTO sometable
FROM INFILE 'data.parquet' FORMAT Parquet;

SELECT *
FROM sometable
LIMIT 5;

┌─path──────────────────────────┬───────date─┬─hits─┐
│ 1988_in_philosophy            │ 2015-05-01 │   70 │
│ 2004_Green_Bay_Packers_season │ 2015-05-01 │  970 │
│ 24_hours_of_lemans            │ 2015-05-01 │   37 │
│ 25604_Karlin                  │ 2015-05-01 │   20 │
│ ASCII_ART                     │ 2015-05-01 │    9 │
└───────────────────────────────┴────────────┴──────┘

Observe que o ClickHouse converteu automaticamente as strings do Parquet (na coluna date) para o tipo Date. Isso acontece porque o ClickHouse faz essa conversão de tipo automaticamente com base nos tipos da tabela de destino.

Inserindo um arquivo local em um servidor remoto

Se você quiser inserir um arquivo Parquet local em um servidor remoto do ClickHouse, pode fazer isso enviando o conteúdo do arquivo por pipe para o clickhouse-client, como mostrado abaixo:

clickhouse client -q "INSERT INTO sometable FORMAT Parquet" < data.parquet

Criando novas tabelas a partir de arquivos Parquet

Como o ClickHouse lê o esquema do arquivo Parquet, podemos criar tabelas dinamicamente:

CREATE TABLE imported_from_parquet
ENGINE = MergeTree
ORDER BY tuple() AS
SELECT *
FROM file('data.parquet', Parquet)

Isso criará e preencherá automaticamente uma tabela a partir de um arquivo Parquet especificado:

DESCRIBE TABLE imported_from_parquet;

┌─name─┬─type─────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐
│ path │ Nullable(String) │              │                    │         │                  │                │
│ date │ Nullable(String) │              │                    │         │                  │                │
│ hits │ Nullable(Int64)  │              │                    │         │                  │                │
└──────┴──────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘

Por padrão, o ClickHouse é rigoroso com nomes de colunas, tipos e valores. Mas, às vezes, é possível ignorar colunas inexistentes ou valores não compatíveis durante a importação. Isso pode ser controlado com as configurações do Parquet.

Exportando para o formato Parquet

Para exportar qualquer tabela ou resultado de consulta para um arquivo Parquet, podemos usar uma cláusula INTO OUTFILE:

SELECT *
FROM sometable
INTO OUTFILE 'export.parquet'
FORMAT Parquet

Isso criará o arquivo export.parquet no diretório de trabalho.

Tipos de dados do ClickHouse e do Parquet

Os tipos de dados do ClickHouse e do Parquet são, em sua maioria, idênticos, mas ainda apresentam algumas diferenças. Por exemplo, o ClickHouse exporta o tipo DateTime como int64 do Parquet. Se depois importarmos isso de volta para o ClickHouse, veremos números (arquivo time.parquet):

SELECT * FROM file('time.parquet', Parquet);

┌─n─┬───────time─┐
│ 0 │ 1673622611 │
│ 1 │ 1673622610 │
│ 2 │ 1673622609 │
│ 3 │ 1673622608 │
│ 4 │ 1673622607 │
└───┴────────────┘

Nesse caso, conversão de tipo pode ser usada:

SELECT
    n,
    toDateTime(time)                 <--- int to time
FROM file('time.parquet', Parquet);

┌─n─┬────toDateTime(time)─┐
│ 0 │ 2023-01-13 15:10:11 │
│ 1 │ 2023-01-13 15:10:10 │
│ 2 │ 2023-01-13 15:10:09 │
│ 3 │ 2023-01-13 15:10:08 │
│ 4 │ 2023-01-13 15:10:07 │
└───┴─────────────────────┘

Leitura adicional

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

E confira também o clickhouse-local — uma ferramenta portátil e completa para trabalhar com arquivos locais/remotos sem precisar de um servidor ClickHouse.