ClickHouseでParquetを扱う - ClickHouse Documentation

Parquetは、データを列指向で格納するための効率的なファイルフォーマットです。 ClickHouseは、Parquetファイルの読み取りと書き込みの両方をサポートしています。

クエリでファイルパスを参照する場合、ClickHouseがどこから読み取ろうとするかは、使用しているClickHouseのバリアントによって異なります。clickhouse-local を使用している場合は、ClickHouse Localを起動した場所からの相対パスで読み取ります。 clickhouse client 経由でClickHouse ServerまたはClickHouse Cloudを使用している場合は、サーバー上の /var/lib/clickhouse/user_files/ ディレクトリからの相対パスで読み取ります。

Parquet からのインポート

データを読み込む前に、file() 関数を使って、サンプルの Parquet ファイルの構造を確認できます。

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

2 番目の引数として 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 │
└───────────────────────────┴────────────┴──────┘

file() と INFILE/OUTFILE では、フォーマットを明示的に指定しなくても構いません。その場合、ClickHouse がファイル拡張子に基づいてフォーマットを自動的に判別します。

既存のテーブルへのインポート

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 serverに挿入するには、以下のようにファイルの内容を 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フォーマットへのエクスポート

ClickHouse Cloud で INTO OUTFILE を使用する場合は、ファイルの書き込み先となるマシンで 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 file) :

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

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

この場合、型変換を使用できます:

SELECT
    n,
    toDateTime(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 server を必要とせず、ローカル/リモートファイルを扱える移植性の高いフル機能ツールです。

​Parquet からのインポート

​既存のテーブルへのインポート

​ローカルファイルをリモートサーバーに挿入する

​Parquetファイルから新しいテーブルを作成する

​Parquetフォーマットへのエクスポート

​ClickHouse と Parquet のデータ型

​関連記事

Parquet からのインポート

既存のテーブルへのインポート

ローカルファイルをリモートサーバーに挿入する

Parquetファイルから新しいテーブルを作成する

Parquetフォーマットへのエクスポート

ClickHouse と Parquet のデータ型

関連記事