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

Kafka と ClickHouse で Vector を使用する

Vector は、Kafka から読み取ったイベントを ClickHouse に送信できる、ベンダー非依存のデータパイプラインです。 ClickHouse 向け Vector の入門ガイドでは、ログのユースケースとファイルからのイベント読み取りに重点を置いています。ここでは、Kafka トピックに保持されたイベントを含むGithub sample datasetを使用します。 Vector は、プッシュまたはプルのモデルでデータを取得するためにログソースを使用します。一方、Sinksはイベントの宛先となります。そのため、ここでは Kafka ログソース と ClickHouse sink を使用します。なお、Kafka は Sink としてサポートされていますが、ClickHouse ログソース は利用できません。したがって、ClickHouse から Kafka にデータを転送したい場合、Vector は適していません。 Vector はデータのtransformationにも対応しています。これはこのガイドの対象外です。データセットに対してこの機能が必要な場合は、Vector のドキュメントを参照してください。 なお、現在の ClickHouse sink の実装では HTTP インターフェイスを使用しています。現時点では、ClickHouse sink は JSON スキーマの使用をサポートしていません。データは、プレーンな JSON フォーマットまたは String として Kafka に公開する必要があります。

ライセンス

Vector は MPL-2.0 ライセンス のもとで配布されています

接続情報を確認する

HTTP(S) で ClickHouse に接続するには、次の情報が必要です。 ClickHouse Cloud サービスの詳細は、ClickHouse Cloud コンソールで確認できます。 サービスを選択し、Connect をクリックします。 HTTPS を選択します。接続情報は curl コマンドの例として表示されます。 セルフマネージド ClickHouse を使用している場合、接続情報は ClickHouse 管理者によって設定されます。

手順

  1. Kafka の github トピックを作成し、GitHub データセットを投入します。
このデータセットは、ClickHouse/ClickHouse リポジトリを対象とした 200,000 行で構成されています。
  1. ターゲットテーブルが作成されていることを確認します。以下ではデフォルトのデータベースを使用します。
  1. Vector をダウンロードしてインストールしますkafka.toml の設定ファイルを作成し、Kafka と ClickHouse の各インスタンスに合わせて値を調整します。
この設定と Vector の動作に関して、いくつか重要な注意点があります。
  • この例は Confluent Cloud でテストされています。そのため、sasl.* および ssl.enabled のセキュリティオプションは、セルフマネージド環境には適さない可能性があります。
  • 構成パラメータ bootstrap_servers には、プロトコルのプレフィックスは不要です。例: pkc-2396y.us-east-1.aws.confluent.cloud:9092
  • ログソースパラメータ decoding.codec = "json" を指定すると、メッセージは 1 つの JSONオブジェクトとして ClickHouse sink に渡されます。メッセージを文字列として扱い、デフォルト値の bytes を使用する場合、メッセージの内容は message フィールドに追加されます。ほとんどの場合、これは Vector getting started ガイドで説明されているように、ClickHouse 側で処理する必要があります。
  • Vector はメッセージに 複数のフィールドを追加します。この例では、構成パラメータ skip_unknown_fields = true を使って、ClickHouse sink でこれらのフィールドを無視しています。これにより、ターゲットテーブルのスキーマに含まれないフィールドは無視されます。offset などのメタフィールドも含めたい場合は、必要に応じてスキーマを調整してください。
  • inputs パラメータを使って、sink がイベントログソースを参照している点に注目してください。
  • ClickHouse sink の動作については、こちら の説明も確認してください。最適なスループットを得るには、buffer.max_eventsbatch.timeout_secsbatch.max_bytes の各パラメータを調整するとよいでしょう。ClickHouse の推奨事項によれば、1 回のバッチに含めるイベント数は最低でも 1000 を目安にしてください。継続的に高スループットが見込まれるユースケースでは、buffer.max_events パラメータを増やすことを検討してください。スループットの変動が大きい場合は、batch.timeout_secs パラメータの調整が必要になることがあります。
  • auto_offset_reset = "smallest" パラメータを指定すると、Kafka ログソースはトピックの先頭から読み取りを開始します。これにより、手順 (1) で公開したメッセージを確実に消費できます。必要な動作が異なる場合もあります。詳しくは こちら を参照してください。
  1. Vector を起動します
既定では、ClickHouse への挿入を開始する前に ヘルスチェック が必要です。これにより、接続を確立でき、スキーマを読み取れることを確認できます。問題が発生した場合に役立つ追加のログを取得するには、先頭に VECTOR_LOG=debug を付けます。
  1. データが挿入されたことを確認します。
最終更新日 2026年6月12日