メインコンテンツまでスキップ
メインコンテンツまでスキップ

CapnProto

Not supported in ClickHouse Cloud
入力出力別名
✔✔

説明​

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

フォーマットスキーマも参照してください。

データ型の一致​

以下の表は、サポートされているデータ型とそれらが 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 型もネスト可能です。

使用例​

データの挿入と選択​

以下のコマンドを使用して、ファイルから ClickHouse テーブルに CapnProto データを挿入できます。

$ 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 に保存されます。