Работа с Parquet в ClickHouse

Parquet — это эффективный файловый формат для хранения данных в столбцовом виде. ClickHouse поддерживает как чтение, так и запись файлов Parquet.

Когда вы указываете путь к файлу в запросе, место, откуда ClickHouse будет читать данные, зависит от используемого варианта ClickHouse.Если вы используете clickhouse-local, чтение будет выполняться по пути относительно каталога, из которого вы запустили ClickHouse Local. Если вы используете ClickHouse Server или ClickHouse Cloud через clickhouse client, чтение будет выполняться по пути относительно каталога /var/lib/clickhouse/user_files/ на сервере.

Импорт из Parquet

Перед загрузкой данных можно использовать функцию file(), чтобы посмотреть структуру примерного файла Parquet:

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

В качестве второго аргумента мы использовали Parquet, чтобы ClickHouse определил формат файла. Будут выведены столбцы с типами:

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

Мы также можем просмотреть файлы перед фактическим импортом данных, используя всю мощь 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 │
└───────────────────────────┴────────────┴──────┘

Можно не указывать format явно для file() и INFILE/OUTFILE. В этом случае ClickHouse автоматически определит format по расширению файла.

Импорт в существующую таблицу

Создадим таблицу, в которую будем импортировать данные Parquet:

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

Теперь мы можем импортировать данные с помощью конструкции 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 │
└───────────────────────────────┴────────────┴──────┘

Обратите внимание: ClickHouse автоматически преобразовал строки Parquet (в столбце date) в тип Date. Это связано с тем, что ClickHouse автоматически приводит типы на основе типов в целевой таблице.

Вставка локального файла на удалённый сервер

Если вам нужно выполнить вставку данных из локального файла Parquet на удалённый сервер ClickHouse, это можно сделать, передав содержимое файла в clickhouse-client, как показано ниже:

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

Создание новых таблиц из файлов Parquet

Поскольку ClickHouse считывает схему файла Parquet, таблицы можно создавать на лету:

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

Это автоматически создаст и заполнит таблицу на основе указанного файла Parquet:

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

По умолчанию ClickHouse строго проверяет имена столбцов, типы и значения. Но иногда при импорте можно пропускать несуществующие столбцы или неподдерживаемые значения. Это можно настроить с помощью настроек Parquet.

Экспорт в формат Parquet

При использовании INTO OUTFILE с ClickHouse Cloud команды нужно запускать в clickhouse client на той машине, на которую будет записан файл.

Чтобы экспортировать любую таблицу или результат запроса в файл Parquet, можно использовать предложение INTO OUTFILE:

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

В рабочем каталоге будет создан файл export.parquet.

Типы данных ClickHouse и Parquet

Типы данных в ClickHouse и Parquet в основном совпадают, но всё же слегка различаются. Например, ClickHouse экспортирует тип DateTime в Parquet как int64. Если затем импортировать эти данные обратно в ClickHouse, мы увидим числа (файл time.parquet):

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

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

В этом случае можно использовать преобразование типов:

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

Дополнительные материалы

ClickHouse поддерживает множество форматов — как текстовых, так и двоичных, — для самых разных сценариев и платформ. Подробнее о форматах и способах работы с ними читайте в следующих статьях:

Также обратите внимание на clickhouse-local — это переносимый полнофункциональный инструмент для работы с локальными и удалёнными файлами без необходимости использовать сервер ClickHouse.

Руководства по ClickHouse

Руководства по сценариям использования

Импорт из Parquet

Импорт в существующую таблицу

Вставка локального файла на удалённый сервер

Создание новых таблиц из файлов Parquet

Экспорт в формат Parquet

Типы данных ClickHouse и Parquet

Дополнительные материалы

​Импорт из Parquet

​Импорт в существующую таблицу

​Вставка локального файла на удалённый сервер

​Создание новых таблиц из файлов Parquet

​Экспорт в формат Parquet

​Типы данных ClickHouse и Parquet

​Дополнительные материалы

Импорт из Parquet

Импорт в существующую таблицу

Вставка локального файла на удалённый сервер

Создание новых таблиц из файлов Parquet

Экспорт в формат Parquet

Типы данных ClickHouse и Parquet

Дополнительные материалы