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

CapnProto

Not supported in ClickHouse Cloud
入力出力エイリアス
✔✔

説明​

CapnProto フォーマットは、Protocol Buffers フォーマットや Thrift に似たバイナリメッセージフォーマットであり、JSON や MessagePack とは異なります。 CapnProto メッセージは厳密に型付けされており、自己記述的ではないため、外部のスキーマ記述が必要です。スキーマは動的に適用され、クエリごとにキャッシュされます。

Format Schema も参照してください。

データ型の対応​

以下の表は、サポートされているデータ型と、それらが INSERT クエリおよび SELECT クエリで ClickHouse の データ型 とどのように対応するかを示します。

CapnProto データ型 (INSERT)ClickHouse データ型CapnProto データ型 (SELECT)
UINT8, BOOLUInt8UINT8
INT8Int8INT8
UINT16UInt16, DateUINT16
INT16Int16INT16
UINT32UInt32, DateTimeUINT32
INT32Int32, Decimal32INT32
UINT64UInt64UINT64
INT64Int64, DateTime64, Decimal64INT64
FLOAT32Float32FLOAT32
FLOAT64Float64FLOAT64
TEXT, DATAString, FixedStringTEXT, DATA
union(T, Void), union(Void, T)Nullable(T)union(T, Void), union(Void, T)
ENUMEnum(8/16)ENUM
LISTArrayLIST
STRUCTTupleSTRUCT
UINT32IPv4UINT32
DATAIPv6DATA
DATAInt128/UInt128/Int256/UInt256DATA
DATADecimal128/Decimal256DATA
STRUCT(entries LIST(STRUCT(key Key, value Value)))MapSTRUCT(entries LIST(STRUCT(key Key, value Value)))
  • 整数型は、入出力時に相互に変換できます。
  • CapnProto 形式で Enum を扱う場合は、format_capn_proto_enum_comparising_mode 設定を使用してください。
  • 配列は入れ子にでき、引数として Nullable 型の値を持つことができます。Tuple 型および Map 型も入れ子にできます。

使用例​

データの挿入と選択​

次のコマンドを実行すると、ファイル内の CapnProto データを ClickHouse のテーブルに挿入できます。

$ cat capnproto_messages.bin | clickhouse-client --query "INSERT INTO test.hits SETTINGS format_schema = 'schema:Message' FORMAT CapnProto"

schema.capnp は次のような内容です：

struct Message {
  SearchPhrase @0 :Text;
  c @1 :Uint64;
}

次のコマンドを使用して、ClickHouse テーブルからデータを抽出し、CapnProto 形式のファイルに保存できます。

$ clickhouse-client --query = "SELECT * FROM test.hits FORMAT CapnProto SETTINGS format_schema = 'schema:Message'"

自動生成スキーマの使用​

データ用の外部 CapnProto スキーマがない場合でも、自動生成されたスキーマを使用して、CapnProto 形式でデータを出力および入力できます。

例:

SELECT * FROM test.hits 
FORMAT CapnProto 
SETTINGS format_capn_proto_use_autogenerated_schema=1

この場合、ClickHouse はテーブル構造に基づいて関数 structureToCapnProtoSchema を使用して CapnProto スキーマを自動生成し、このスキーマを用いてデータを CapnProto 形式でシリアライズします。

自動生成されたスキーマを使って CapnProto ファイルを読み込むこともできます（この場合、そのファイルは同じスキーマから生成されている必要があります）:

$ cat hits.bin | clickhouse-client --query "INSERT INTO test.hits SETTINGS format_capn_proto_use_autogenerated_schema=1 FORMAT CapnProto"

フォーマット設定​

設定 format_capn_proto_use_autogenerated_schema はデフォルトで有効になっており、format_schema が設定されていない場合に適用されます。

また、output_format_schema 設定を使用して、入出力時に自動生成されたスキーマをファイルに保存することもできます。

例：

SELECT * FROM test.hits 
FORMAT CapnProto 
SETTINGS 
    format_capn_proto_use_autogenerated_schema=1,
    output_format_schema='path/to/schema/schema.capnp'

この場合、自動生成された CapnProto スキーマは path/to/schema/schema.capnp というファイルに保存されます。