ClickHouseでNative フォーマットとバイナリ形式を使う

ClickHouse は複数のバイナリ形式をサポートしており、これによりパフォーマンスと容量効率が向上します。バイナリ形式ではデータがバイナリで保存されるため、文字エンコーディングの面でも安全です。

ここではデモ用に some_data のテーブルとデータを使用します。必要に応じて、ご自身の ClickHouse インスタンスで再現してみてください。

ClickHouseNative フォーマットでのエクスポート

ClickHouseノード間でデータをエクスポートおよびインポートする際に最も効率的なデータフォーマットは、Native フォーマットフォーマットです。エクスポートはINTO OUTFILE句を使用して行います。

SELECT * FROM some_data
INTO OUTFILE 'data.clickhouse' FORMAT Native

これにより、data.clickhouse ファイルがNative フォーマットフォーマットで作成されます。

Native フォーマットからのインポート

データをインポートするには、小さなファイルや確認用途であれば、file() を使用できます:

DESCRIBE file('data.clickhouse', Native);

┌─name──┬─type───┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐
│ path  │ String │              │                    │         │                  │                │
│ month │ Date   │              │                    │         │                  │                │
│ hits  │ UInt32 │              │                    │         │                  │                │
└───────┴────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘

本番環境では、データのインポートに FROM INFILE を使用します。

INSERT INTO sometable
FROM INFILE 'data.clickhouse'
FORMAT Native

Native フォーマットでの圧縮

COMPRESSION 句を使用すると、データをNative フォーマット (およびそのほかのほとんどのフォーマット) でエクスポートする際にも圧縮を有効にできます。

SELECT * FROM some_data
INTO OUTFILE 'data.clickhouse'
COMPRESSION 'lz4'
FORMAT Native

エクスポートにはLZ4圧縮を使用しました。データをインポートする際にも、これを指定する必要があります。

INSERT INTO sometable
FROM INFILE 'data.clickhouse'
COMPRESSION 'lz4'
FORMAT Native

RowBinary へのエクスポート

サポートされている別のバイナリ形式として、RowBinary があります。これを使用すると、データをバイナリ表現の行としてインポートおよびエクスポートできます。

SELECT * FROM some_data
INTO OUTFILE 'data.binary' FORMAT RowBinary

これにより、data.binary ファイルがバイナリ行形式で生成されます。

RowBinary ファイルの内容確認

このフォーマットでは自動スキーマ推論がサポートされていないため、読み込む前に内容を確認するには、スキーマを明示的に定義する必要があります。

SELECT *
FROM file('data.binary', RowBinary, 'path String, month Date, hits UInt32')
LIMIT 5

┌─path───────────────────────────┬──────month─┬─hits─┐
│ Bangor_City_Forest             │ 2015-07-01 │   34 │
│ Alireza_Afzal                  │ 2017-02-01 │   24 │
│ Akhaura-Laksam-Chittagong_Line │ 2015-09-01 │   30 │
│ 1973_National_500              │ 2017-10-01 │   80 │
│ Attachment                     │ 2017-09-01 │ 1356 │
└────────────────────────────────┴────────────┴──────┘

RowBinaryWithNames の使用も検討してください。これを使うと、カラム一覧を含むヘッダー行も追加されます。RowBinaryWithNamesAndTypes を使うと、さらにカラムの型を含むヘッダー行も追加されます。

RowBinaryファイルからのインポート

RowBinaryファイルからデータを読み込むには、FROM INFILE句を使用します。

INSERT INTO sometable
FROM INFILE 'data.binary'
FORMAT RowBinary

RawBLOB を使用した単一のバイナリ値のインポート

バイナリファイル全体を読み取り、テーブル内の1つのフィールドに保存したいとします。このような場合に使用できるのが、RawBLOB フォーマットです。このフォーマットは、単一カラムのテーブルでのみ直接使用できます。

CREATE TABLE images(data String) ENGINE = Memory

画像ファイルを images テーブルに保存しましょう。

cat image.jpg | clickhouse-client -q "INSERT INTO images FORMAT RawBLOB"

元のファイルサイズと一致する data フィールドの長さを確認できます:

SELECT length(data) FROM images

┌─length(data)─┐
│         6121 │
└──────────────┘

RawBLOBデータのエクスポート

このフォーマットでは、INTO OUTFILE句を使ってデータをエクスポートすることもできます。

SELECT * FROM images LIMIT 1
INTO OUTFILE 'out.jpg'
FORMAT RawBLOB

複数の値をエクスポートするとファイルが破損してしまうため、LIMIT 1 を使用する必要があった点に注意してください。

MessagePack

ClickHouse は、MsgPack を使用した MessagePack 形式のインポートとエクスポートをサポートしています。MessagePack フォーマットでエクスポートするには:

SELECT *
FROM some_data
INTO OUTFILE 'data.msgpk'
FORMAT MsgPack

MessagePackファイルからデータをインポートするには、

INSERT INTO sometable
FROM INFILE 'data.msgpk'
FORMAT MsgPack

Protocol Buffers

ClickHouse Cloud ではサポートされていません

Protocol Buffers を扱うには、まずスキーマファイルを定義します。

syntax = "proto3";

message MessageType {
  string path = 1;
  date month = 2;
  uint32 hits = 3;
};

このスキーマファイル (この場合は schema.proto) へのパスは、Protobufフォーマットのformat_schema設定オプションで指定します。

SELECT * FROM some_data
INTO OUTFILE 'proto.bin'
FORMAT Protobuf
SETTINGS format_schema = 'schema:MessageType'

これにより、データは proto.bin ファイルに保存されます。ClickHouse では、ネストされたメッセージに加えて、Protobuf データのインポートもサポートしています。単一の Protocol Buffer メッセージを扱う場合は、ProtobufSingle の使用を検討してください (この場合、長さを示す区切り文字は省略されます) 。

Cap'n Proto

ClickHouse Cloud ではサポートされていません

ClickHouse がサポートする、もう 1 つの一般的なバイナリシリアライゼーションフォーマットとして、Cap'n Proto があります。Protobuf 形式と同様に、この例でもスキーマファイル (schema.capnp) を定義する必要があります。

@0xec8ff1a10aa10dbe;

struct PathStats {
  path @0 :Text;
  month @1 :UInt32;
  hits @2 :UInt32;
}

これで、CapnProtoフォーマットとこのスキーマを使用して、インポートとエクスポートができるようになりました。

SELECT
    path,
    CAST(month, 'UInt32') AS month,
    hits
FROM some_data
INTO OUTFILE 'capnp.bin'
FORMAT CapnProto
SETTINGS format_schema = 'schema:PathStats'

Date カラムは、対応する型に合わせるために UInt32 にキャストする必要があった点に注意してください。

その他のフォーマット

ClickHouse は、さまざまな用途やプラットフォームに対応するため、テキスト形式とバイナリ形式の両方を含む多くのフォーマットをサポートしています。さらに多くのフォーマットやその扱い方については、以下の記事を参照してください。

あわせて、clickhouse-local もご覧ください。これは、ClickHouse server を起動せずにローカル/リモートファイルを扱える、持ち運び可能なフル機能ツールです。