リファレンス
サポートされているデータソース
| Name | Logo | Type | Status | Description |
|---|---|---|---|---|
| Apache Kafka | Streaming | Stable | ClickPipes を構成し、Apache Kafka から ClickHouse Cloud へストリーミングデータの取り込みを開始します。 | |
| Confluent Cloud | Streaming | Stable | 直接統合により、Confluent と ClickHouse Cloud を組み合わせた性能を最大限に引き出します。 | |
| Redpanda |  | Streaming | Stable | ClickPipes を構成し、Redpanda から ClickHouse Cloud へストリーミングデータの取り込みを開始します。 |
| AWS MSK | Streaming | Stable | ClickPipes を構成し、AWS MSK から ClickHouse Cloud へストリーミングデータの取り込みを開始します。 | |
| Azure Event Hubs | Streaming | Stable | ClickPipes を構成し、Azure Event Hubs から ClickHouse Cloud へストリーミングデータの取り込みを開始します。 | |
| WarpStream | Streaming | Stable | ClickPipes を構成し、WarpStream から ClickHouse Cloud へストリーミングデータの取り込みを開始します。 |
サポートされているデータ形式
サポートされているデータ形式は次のとおりです：
サポート対象のデータ型
標準
現在、ClickPipes でサポートされている標準的な ClickHouse データ型は次のとおりです:
- 基本的な数値型 - [U]Int8/16/32/64、Float32/64、および BFloat16
- 拡張整数型 - [U]Int128/256
- Decimal 型
- Boolean
- String
- FixedString
- Date, Date32
- DateTime, DateTime64 (UTC タイムゾーンのみ)
- Enum8/Enum16
- UUID
- IPv4
- IPv6
- Time, Time64
- JSON
- すべての ClickHouse LowCardinality 型
- 上記のいずれかの型 (Nullable を含む) をキーおよび値に使用する Map
- 上記のいずれかの型 (Nullable を含む、1 階層のみ) を要素に使用する Tuple および Array
- SimpleAggregateFunction 型 (AggregatingMergeTree または SummingMergeTree を出力先とする場合)
Variant 型のサポート
ClickPipes は、以下の状況で Variant 型をサポートします。
- Avro Union。Avro スキーマに複数の非 null 型を含む Union がある場合、ClickPipes は 適切な Variant 型を推論します。これ以外のケースでは、Avro データに対して Variant 型はサポートされません。
- JSON フィールド。ソースデータストリーム内の任意の JSON フィールドに対して、
Variant(String, Int64, DateTime)のように Variant 型を手動で指定できます。複雑なサブタイプ (array/map/tuple) はサポートされません。さらに、ClickPipes が 使用する適切な Variant のサブタイプを決定する方法の都合上、Variant 定義内で使用できる整数型または DateTime 型は 1 種類のみです。 たとえば、Variant(Int64, UInt32)はサポートされません。
JSON 型のサポート
ClickPipes は、次のような場合に JSON 型をサポートします。
- Avro の Record フィールドおよび Protobuf の Message フィールドは、常に JSON カラムに割り当てることができます。
- Avro の String フィールドおよび Bytes フィールドは、その Avro フィールドが実際に JSON 文字列オブジェクトを含んでいる場合、JSON カラムに割り当てることができます。
- Protobuf の String kind および Bytes kind は、その Protobuf フィールドが実際に JSON 文字列オブジェクトを含んでいる場合、JSON カラムに割り当てることができます。
- 常に JSON オブジェクトである JSON フィールドは、JSON の出力先カラムに割り当てることができます。
固定パスやスキップされたパスも含め、出力先カラムを目的の JSON 型に手動で変更する必要がある点に注意してください。
Avro
サポートされている Avro データ型
ClickPipes は、すべての Avro プリミティブ型および複合型と、local-timestamp-millis および local_timestamp-micros を除くすべての Avro 論理型をサポートします。Avro の record 型は Tuple に、array 型は Array に、map 型は Map (文字列キーのみ) に変換されます。一般に、こちら に記載されている変換が利用可能です。ClickPipes は型変換時のオーバーフローや精度損失を検査しないため、Avro の数値型については ClickHouse 側の型を正確に対応させることを推奨します。
あるいは、すべての Avro 型を String カラムに挿入することも可能であり、その場合は有効な JSON 文字列として表現されます。
Nullable 型と Avro Union
Avro における Nullable 型は、ベースとなる Avro 型を T としたときに、(T, null) または (null, T) という Union スキーマを用いて定義されます。スキーマ推論の過程で、そのような Union は ClickHouse の Nullable カラムにマッピングされます。なお、ClickHouse は
Nullable(Array)、Nullable(Map)、Nullable(Tuple) 型をサポートしていません。これらの型に対する Avro の null Union は、非 Nullable 型にマッピングされます（Avro の Record 型は ClickHouse の名前付き Tuple にマッピングされます）。これらの型に対する Avro の "null" は、次のように挿入されます。
- null の Avro array には空の Array
- null の Avro Map には空の Map
- null の Avro Record には、すべてのフィールドがデフォルト値/ゼロ値を持つ名前付き Tuple
Protobuf
サポートされる Protobuf データ型
ClickPipes は、長らく非推奨となっている proto 2 の group 型を除き、すべての Protobuf 2 および 3 の型をサポートしています。基本的な型変換は、
次の対応関係に従います。
すべての基本型で、Array、Map、Nullable の各バリアントもサポートされています。
| Protobuf 型 | ClickHouse 型 |
|---|---|
bool | UInt8 |
float | Float32 |
double | Float64 |
int32, sint32, sfixed32 | Int32 |
int64, sint64, sfixed64 | Int64 |
uint32, fixed32 | UInt32 |
uint64, fixed64 | UInt64 |
string, bytes | String |
enum | Enum |
repeated T | Array(T) |
message | Tuple |
数値型については、オーバーフローや精度低下を避けるため、厳密に一致する型を使用することを推奨します。
次の well-known types もサポートされています。
| Well-known type | ClickHouse 型 |
|---|---|
google.protobuf.Timestamp | DateTime, DateTime64 |
google.protobuf.Duration | Time, Time64 |
google.protobuf.StringValue, google.protobuf.BytesValue | Nullable(String) |
google.protobuf.Int32Value, google.protobuf.SInt32Value, google.protobuf.SFixed32Value | Nullable(Int32) |
google.protobuf.Int64Value, google.protobuf.SInt64Value, google.protobuf.SFixed64Value | Nullable(Int64) |
google.protobuf.UInt32Value, google.protobuf.Fixed32Value | Nullable(UInt32) |
google.protobuf.UInt64Value, google.protobuf.Fixed64Value | Nullable(UInt64) |
google.protobuf.FloatValue | Nullable(Float32) |
google.protobuf.DoubleValue | Nullable(Float64) |
google.protobuf.BoolValue | Nullable(UInt8) |
Protobuf oneof
スキーマ推論 では、Protobuf の oneof フィールドはデフォルトで名前付き Tuple にマッピングされ、この場合、デフォルト値以外の
値を持つフィールドは最大で 1 つだけです。これらのフィールドは、設定された構成フィールドの型をアクティブな値が取る Variant カラムに
自動的にマッピングすることもできます。あるいは、各構成フィールドをそれぞれ独立した ClickHouse カラムに手動でマッピングすることもできます。oneof
フィールドは相互排他的であるため、各レコードで値が入るカラムは常に 1 つだけです。
メッセージリスト
ClickPipe 用に定義された最上位の Protobuf schema に、protobuf Message 型の repeated field が 1 つだけ含まれている場合、スキーマ推論 とカラムの対応は、その「内包された」Message フィールドに基づいて行われます。Kafka メッセージはそのようなメッセージのリストとして処理され、1 つの Kafka メッセージが複数の ClickHouse の行に展開されます。
Kafka 仮想カラム
Kafka 互換のストリーミングデータソースでは、以下の仮想カラムがサポートされています。新しい宛先を作成する際は、Add Column ボタンを使用して仮想カラムを対象テーブルに追加できます。
| Name | Description | Recommended Data Type |
|---|---|---|
_key | Kafka メッセージキー | String |
_timestamp | Kafka タイムスタンプ (ミリ秒精度) | DateTime64(3) |
_partition | Kafka パーティション | Int32 |
_offset | Kafka オフセット | Int64 |
_topic | Kafka トピック | String |
_header_keys | レコードヘッダー内のキーの対応配列 | Array(String) |
_header_values | レコードヘッダー内のヘッダー値の対応配列 | Array(String) |
_raw_message | Kafka メッセージ全体 | String |
_raw_message カラムは JSON データに対してのみ推奨される点に注意してください。
JSON 文字列だけが必要なユースケース (下流の materialized view にデータを投入するために ClickHouse の JsonExtract* 関数を使用する場合など) では、すべての「非仮想」カラムを削除することで ClickPipes のパフォーマンスが向上する可能性があります。
