メインコンテンツへスキップ
メインコンテンツへスキップ

ClickHouse におけるネイティブ形式とバイナリ形式の利用

ClickHouse は複数のバイナリ形式をサポートしており、高いパフォーマンスと優れたスペース効率を実現します。バイナリ形式では、データがバイナリのまま保存されるため、文字エンコーディングの点でも安全です。

このガイドでは、デモ用に some_data テーブル と データ を使用します。お使いの ClickHouse インスタンスでも自由に再現して試してみてください。

ネイティブ ClickHouse 形式でのエクスポート​

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

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

これにより、ネイティブ形式の data.clickhouse ファイルが作成されます。

ネイティブ形式からのインポート​

データをインポートするには、小さなファイルやデータ探索の目的であれば、file() を使用できます。

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

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

file() 関数を使用する場合、ClickHouse Cloud を利用しているときは、ファイルが存在するマシン上で clickhouse client を実行する必要があります。別の方法として、clickhouse-local を使用してローカルでファイルを確認できます。

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

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

ネイティブ形式での圧縮​

COMPRESSION 句を使用して、データをネイティブ形式（およびほとんどの他の形式）でエクスポートする際に圧縮を有効にすることもできます。

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 を使用した単一のバイナリ値のインポート​

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

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​

Not supported in 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​

Not supported in 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 サーバーを起動せずに、ローカル／リモートのファイルを操作できる、ポータブルなフル機能ツールです。