CapnProto

CapnProto に関するドキュメント

入力	出力	エイリアス
✔	✔

​

説明

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

関連項目: フォーマットスキーマ。

​

データ型の対応

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

CapnProto データ型 (INSERT)	ClickHouse データ型	CapnProto データ型 (SELECT)
UINT8, BOOL	UInt8	UINT8
INT8	Int8	INT8
UINT16	UInt16, Date	UINT16
INT16	Int16	INT16
UINT32	UInt32, DateTime	UINT32
INT32	Int32, Decimal32	INT32
UINT64	UInt64	UINT64
INT64	Int64, DateTime64, Decimal64	INT64
FLOAT32	Float32	FLOAT32
FLOAT64	Float64	FLOAT64
TEXT, DATA	String, FixedString	TEXT, DATA
union(T, Void), union(Void, T)	Nullable(T)	union(T, Void), union(Void, T)
ENUM	Enum(8/16)	ENUM
LIST	Array	LIST
STRUCT	Tuple	STRUCT
UINT32	IPv4	UINT32
DATA	IPv6	DATA
DATA	Int128/UInt128/Int256/UInt256	DATA
DATA	Decimal128/Decimal256	DATA
STRUCT(entries LIST(STRUCT(key Key, value Value)))	Map	STRUCT(entries LIST(STRUCT(key Key, value Value)))

• 整数型は、入出力時に相互変換できます。
• CapnProto フォーマットで Enum を扱うには、format_capn_proto_enum_comparising_mode 設定を使用してください。
• Array はネストでき、引数として 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ファイルに保存されます。