Trabalhando com Parquet no ClickHouse - ClickHouse Documentation

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.

Quando você faz referência a um caminho de arquivo em uma consulta, o local de onde o ClickHouse tentará ler dependerá da variante do ClickHouse que você está usando.Se você estiver usando clickhouse-local, ele lerá de um local relativo a onde você iniciou o ClickHouse Local. Se você estiver usando ClickHouse Server ou ClickHouse Cloud por meio do clickhouse client, ele lerá de um local relativo ao diretório /var/lib/clickhouse/user_files/ no servidor.

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 │
└───────────────────────────┴────────────┴──────┘

Podemos dispensar a definição explícita do formato para file() e INFILE/OUTFILE. Nesse caso, o ClickHouse detectará automaticamente o formato com base na extensão do arquivo.

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

Ao usar INTO OUTFILE com o ClickHouse Cloud, você precisará executar os comandos no clickhouse client na máquina em que o arquivo será salvo.

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.

​Importando de Parquet

​Importando para uma tabela existente

​Inserindo um arquivo local em um servidor remoto

​Criando novas tabelas a partir de arquivos Parquet

​Exportando para o formato Parquet

​Tipos de dados do ClickHouse e do Parquet

​Leitura adicional

Importando de Parquet

Importando para uma tabela existente

Inserindo um arquivo local em um servidor remoto

Criando novas tabelas a partir de arquivos Parquet

Exportando para o formato Parquet

Tipos de dados do ClickHouse e do Parquet

Leitura adicional