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

Protobuf

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

説明​

ProtobufフォーマットはProtocol Buffersフォーマットです。

このフォーマットは、クエリ間でキャッシュされる外部フォーマットスキーマを必要とします。

ClickHouseは以下をサポートしています：

  • proto2およびproto3構文の両方。
  • Repeated/optional/requiredフィールド。

使用例​

基本的な例​

使用例：

SELECT * FROM test.table FORMAT Protobuf SETTINGS format_schema = 'schemafile:MessageType'

cat protobuf_messages.bin | clickhouse-client --query "INSERT INTO test.table SETTINGS format_schema='schemafile:MessageType' FORMAT Protobuf"

ファイルschemafile.protoは次のようになります：

syntax = "proto3";

message MessageType {
  string name = 1;
  string surname = 2;
  uint32 birthDate = 3;
  repeated string phoneNumbers = 4;
};

ClickHouseは、テーブルのカラムとProtocol Buffersのメッセージタイプのフィールドの対応を見つけるために、それらの名前を比較します。 この比較は大文字と小文字を区別せず、_（アンダースコア）と.（ドット）の文字は等しいと見なされます。 カラムとProtocol Buffersのメッセージのフィールドの型が異なる場合、必要な変換が適用されます。

ネストされたメッセージがサポートされています。例えば、以下のメッセージタイプのフィールドzについて：

message MessageType {
  message XType {
    message YType {
      int32 z;
    };
    repeated YType y;
  };
  XType x;
};

ClickHouseはx.y.z（またはx_y_z、X.y_Zなど）の名前のカラムを探します。

ネストされたメッセージは、ネストされたデータ構造の入力または出力に適しています。

以下のようなprotobufスキーマで定義されたデフォルト値は適用されず、代わりにテーブルデフォルトが使用されます：

syntax = "proto2";

message MessageType {
  optional int32 result_per_page = 3 [default = 10];
}

メッセージがoneofを含む場合で、input_format_protobuf_oneof_presenceが設定されている場合、ClickHouseはどのoneofフィールドが見つかったかを示すカラムを埋めます。

syntax = "proto3";

message StringOrString {
  oneof string_oneof {
    string string1 = 1;
    string string2 = 42;
  }
}

CREATE TABLE string_or_string ( string1 String, string2 String, string_oneof Enum('no'=0, 'hello' = 1, 'world' = 42))  Engine=MergeTree ORDER BY tuple();
INSERT INTO string_or_string from INFILE '$CURDIR/data_protobuf/String1' SETTINGS format_schema='$SCHEMADIR/string_or_string.proto:StringOrString' FORMAT ProtobufSingle;
SELECT * FROM string_or_string

   ┌─────────┬─────────┬──────────────┐
   │ string1 │ string2 │ string_oneof │
   ├─────────┼─────────┼──────────────┤
1. │         │ string2 │ world        │
   ├─────────┼─────────┼──────────────┤
2. │ string1 │         │ hello        │
   └─────────┴─────────┴──────────────┘

出現を示すカラムの名前はoneofの名前と同じでなければなりません。ネストされたメッセージもサポートされています（basic-examplesを参照）。 許可されている型はInt8、UInt8、Int16、UInt16、Int32、UInt32、Int64、UInt64、Enum、Enum8またはEnum16です。 Enum（およびEnum8またはEnum16）は、すべてのoneofの可能なタグと0を含む必要があり、0は不在を示します。文字列表現は重要ではありません。

設定input_format_protobuf_oneof_presenceはデフォルトで無効です。

ClickHouseはlength-delimitedフォーマットでprotobufメッセージを入力および出力します。 これは、各メッセージの前にその長さを可変幅の整数（varint）として書き込む必要があることを意味します。

詳細については、人気のある言語での長さ区切りのprotobufメッセージの読み取り/書き込み方法を参照してください。

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

データの外部Protobufスキーマがない場合でも、自動生成されたスキーマを使用してProtobufフォーマットでデータを出力/入力できます。

例えば：

SELECT * FROM test.hits format Protobuf SETTINGS format_protobuf_use_autogenerated_schema=1

この場合、ClickHouseはテーブル構造に基づいてProtobufスキーマを自動生成し、structureToProtobufSchemaを使用します。 次に、このスキーマを使用してProtobufフォーマットでデータをシリアル化します。

自動生成されたスキーマでProtobufファイルを読み取ることもできます。この場合、ファイルは同じスキーマを使用して作成されている必要があります：

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

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

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

SELECT * FROM test.hits format Protobuf SETTINGS format_protobuf_use_autogenerated_schema=1, output_format_schema='path/to/schema/schema.proto'

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

protobufキャッシュの削除​

format_schema_pathからロードされたProtobufスキーマを再読み込みするには、SYSTEM DROP ... FORMAT CACHEステートメントを使用します。

SYSTEM DROP FORMAT SCHEMA CACHE FOR Protobuf

フォーマット設定​