ClickHouse での Parquet の利用

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 が date 列の Parquet の文字列データを自動的に 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 形式へのエクスポート

ヒント

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 ファイルのように）数値として表示されます：

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

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

この場合には、型変換を利用できます。

SELECT
    n,
    toDateTime(time)                 <--- int を日時型に変換
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 サーバーを用意することなく、ローカル／リモートファイルを扱えるポータブルでフル機能のツールです。

Parquet からのインポート​

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

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

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

Parquet 形式へのエクスポート​

ClickHouse と Parquet のデータ型​

さらに読む​