Google Cloud Storage を ClickHouse Cloud と統合する

オブジェクトストレージを ClickHouse Cloud にシームレスに接続します。

GCS ClickPipe は、Google Cloud Storage (GCS) からデータを取り込むための、フルマネージドで高い耐障害性を備えた仕組みです。一回限りと継続的インジェストの両方をサポートし、exactly-once セマンティクスを提供します。

GCS ClickPipes は、ClickPipes UI を使用して手動でデプロイおよび管理できるほか、OpenAPI や Terraform を使用してプログラムから実行することもできます。

​

対応フォーマット

• JSON
• CSV
• TSV
• Parquet
• Avro

​

機能

​

一回限りのインジェスト

デフォルトでは、GCS ClickPipe は、指定したバケット内でパターンに一致するすべてのファイルを、1 回のバッチ処理で ClickHouse の宛先テーブルに読み込みます。インジェスト タスクが完了すると、ClickPipe は自動的に停止します。この一回限りのインジェスト モードでは exactly-once セマンティクスが提供されるため、各ファイルは重複なく確実に処理されます。

​

継続的インジェスト

継続的インジェストが有効な場合、ClickPipes は指定されたパスからデータを継続的に取り込みます。インジェスト順序の判定には、GCS ClickPipe はデフォルトでファイルの暗黙的な辞書式順序を使用します。また、バケット通知を行うよう設定した Google Cloud Pub/Sub サブスクリプションを使用して、ファイルを任意の順序で取り込むように構成することもできます。

​

辞書式順序

GCS ClickPipe は、ファイルがバケットに辞書式順序で追加されることを前提としており、この暗黙的な順序に基づいてファイルを順番に取り込みます。つまり、新しいファイルは、最後に取り込まれたファイルよりも辞書式で後に来る名前である必要があります。たとえば、file1、file2、file3 という名前のファイルは順番に取り込まれますが、新たに file 0 がバケットに追加された場合、ファイル名が最後に取り込まれたファイルよりも辞書式で後ではないため、無視されます。

このモードでは、GCS ClickPipe は指定されたパス内のすべてのファイルを初期ロードし、その後、設定可能な間隔 (デフォルトでは 30 秒) で新しいファイルがないかポーリングします。特定のファイルや時点からインジェストを開始することはできません — ClickPipes は常に指定されたパス内のすべてのファイルを読み込みます。

​

順不同

手順については、継続的インジェストの順不同モードの設定を参照してください。

バケットから通知を受け取る Google Cloud Pub/Sub サブスクリプションを設定すると、暗黙的な順序を持たないファイルを取り込むように GCS ClickPipe を構成できます。これにより、ClickPipes はオブジェクト作成イベントを監視し、ファイル名の命名規則に関係なく新しいファイルを取り込めるようになります。

公開バケットでは順不同モードはサポートされていません。これを使用するには、サービス アカウント認証と、バケットに接続された Google Cloud Pub/Sub サブスクリプションが必要です。

このモードでは、GCS ClickPipe は選択したパス内のすべてのファイルを初期ロードし、その後、指定したパスに一致する Pub/Sub サブスクリプション経由の OBJECT_FINALIZE 通知を待ち受けます。すでに確認済みのファイル、パスに一致しないファイル、または別種のイベントに対するメッセージは、すべて無視されます。特定のファイルまたは時点からインジェストを開始することはできません。ClickPipes は常に、選択したパス内のすべてのファイルを読み込みます。

​

ファイルパターンのマッチング

Object Storage 用 ClickPipes では、ファイルパターンのマッチングに POSIX 標準を採用しています。すべてのパターンは大文字と小文字を区別し、バケット名の後ろにあるフルパス全体に対して照合されます。パフォーマンスを高めるため、できるだけ具体的なパターンを使用してください (例: *.csv ではなく data-2024-*.csv) 。

​

対応しているパターン

パターン	説明	例	一致するもの
?	1 文字に一致します (/ を除く)	data-?.csv	data-1.csv, data-a.csv, data-x.csv
*	0 文字以上に一致します (/ を除く)	data-*.csv	data-1.csv, data-001.csv, data-report.csv, data-.csv
** 再帰	0 文字以上に一致します (/ を含む) 。ディレクトリを再帰的に走査できます。	logs/**/error.log	logs/error.log, logs/2024/error.log, logs/2024/01/error.log

例:

• https://bucket.s3.amazonaws.com/folder/*.csv
• https://bucket.s3.amazonaws.com/logs/**/data.json
• https://bucket.s3.amazonaws.com/file-?.parquet
• https://bucket.s3.amazonaws.com/data-2024-*.csv.gz

​

サポートされていないパターン

Pattern	説明	例	代替手段
{abc,def}	ブレース展開 (代替指定)	{logs,data}/file.csv	各パスごとに別々の ClickPipes を作成してください。
{N..M}	数値範囲の展開	file-{1..100}.csv	file-*.csv または file-?.csv を使用してください。

例:

• https://bucket.s3.amazonaws.com/{documents-01,documents-02}.json
• https://bucket.s3.amazonaws.com/file-{1..100}.csv
• https://bucket.s3.amazonaws.com/{logs,metrics}/data.parquet

​

exactly-once セマンティクス

大規模なデータセットを取り込む際には、さまざまな障害が発生する可能性があり、その結果、挿入が一部しか行われなかったり、データが重複したりすることがあります。Object Storage 用 ClickPipes は挿入の失敗に対して耐性があり、exactly-once セマンティクスを提供します。これは、一時的な「ステージングテーブル」を使用して実現されます。まず、データはステージングテーブルに挿入されます。この挿入中に問題が発生した場合は、ステージングテーブルを空にして、クリーンな状態から挿入を再試行できます。挿入が正常に完了した場合にのみ、ステージングテーブル内のパーティションがターゲットテーブルに移動されます。この戦略について詳しくは、こちらのブログ記事をご覧ください。

​

仮想カラム

どのファイルが取り込まれたかを追跡するには、カラムマッピングのリストに _file 仮想カラムを含めます。_file 仮想カラムにはソースオブジェクトのファイル名が含まれており、これを使ってどのファイルが処理されたかをクエリできます。

​

アクセス制御

​

権限

GCS ClickPipe は公開バケットと非公開バケットに対応しています。Requester Pays バケットはサポートしていません。

​

GCS バケット

ClickPipes が使用するサービス アカウントでは、バケット レベルで次の操作が許可されている必要があります。

• roles/storage.objectViewer

このロールには storage.objects.list と `storage.objects.get の IAM 権限が含まれており、これにより ClickPipes は指定されたバケット内のオブジェクトを一覧表示し、取得できます。

​

Pub/Sub サブスクリプション

順不同モードを使用する場合、サービス アカウントには、Pub/Sub サブスクリプションに対して次のロールが必要です。

• roles/pubsub.subscriber — メッセージを受信し、確認応答するため。
• roles/pubsub.viewer — サブスクリプションのメタデータを取得するため。

​

認証

​

サービス アカウント

Pub/Sub 通知で順不同モードを使用する場合は、サービス アカウント認証が必要です。認証方法として Service Account を選択し、サービス アカウントの秘密鍵の JSON ファイルをアップロードします。

​

HMAC認証情報

HMACキー を使用して認証するには、ClickPipe 接続を設定する際に Authentication method で Credentials を選択します。次に、Access key と Secret key に、それぞれアクセスキー (例: GOOGTS7C7FUP3AIRVJTE2BCDKINBTES3HC2GY5CBFJDCQ2SYHV6A6XXVTJFSA) とシークレットキー (例: bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ) を入力します。

HMACキーを持つサービス アカウントを作成するには、このガイド に従ってください。

​

ネットワークアクセス

GCS ClickPipes では、メタデータの検出とデータのインジェストに、それぞれ ClickPipes サービスと ClickHouse Cloud サービスという 2 つの異なるネットワーク経路を使用します。ネットワークセキュリティをさらに強化したい場合 (たとえば、コンプライアンス要件への対応のため) 、両方の経路でネットワークアクセスを設定する必要があります。

• IP ベースのアクセス制御では、GCS バケットの IP フィルタリング ルール で、こちらに記載されている ClickPipes サービスリージョンの静的 IP と、ClickHouse Cloud サービスの 静的 IP の両方を許可する必要があります。ご利用の ClickHouse Cloud リージョンの静的 IP を取得するには、ターミナルを開いて次を実行します。

  # Replace <your-region> with your ClickHouse Cloud region
  curl -s https://api.clickhouse.cloud/static-ips.json | jq -r '.gcp[] | select(.region == "<your-region>") | .egress_ips[]'
  

​

詳細設定

ClickPipes には、ほとんどのユースケースの要件を満たす妥当なデフォルト設定が用意されています。さらに細かなチューニングが必要な場合は、以下の設定を調整できます。

Setting	Default value	Description
Max insert bytes	10GB	1 回の挿入バッチで処理するバイト数。
Max file count	100	1 回の挿入バッチで処理するファイルの最大数。
Max threads	auto(3)	ファイル処理に使用する同時実行スレッドの最大数。
Max insert threads	1	ファイル処理に使用する同時実行される挿入スレッドの最大数。
Min insert block size bytes	1GB	テーブルに挿入可能なブロックの最小バイトサイズ。
Max download threads	4	同時実行されるダウンロードスレッドの最大数。
Object storage polling interval	30s	ClickHouse クラスターにデータを挿入するまでの最大待機時間を設定します。
Parallel distributed insert select	2	parallel distributed insert select の設定。
Parallel view processing	false	アタッチされたビューへのプッシュを、順次ではなく同時実行で行うかどうか。
Use cluster function	true	複数ノードにまたがってファイルを並列処理するかどうか。

​

スケーリング

Object Storage 用 ClickPipes は、構成された垂直オートスケーリング設定によって決まる ClickHouse サービスの最小サイズに基づいてスケーリングされます。ClickPipe のサイズは、パイプの作成時に決定されます。作成後に ClickHouse サービスの設定を変更しても、ClickPipe のサイズには影響しません。

大規模な取り込みジョブのスループットを向上させるには、ClickPipe を作成する前に ClickHouse サービスをスケーリングすることを推奨します。

​

既知の制約事項

​

ファイルサイズ

ClickPipes は、サイズが10GB以下のオブジェクトのみを取り込みます。ファイルが 10GB を超える場合、エラーは ClickPipes 専用のエラーテーブルに追記されます。

​

互換性

GCS ClickPipe では、相互運用性を確保するために Cloud ストレージの XML API を使用します。そのため、gs:// ではなく https://storage.googleapis.com/ のバケットプレフィックスを使用し、認証には HMAC キー を使用する必要があります。

​

ビューのサポート

ターゲットテーブルに対する materialized view もサポートされています。ClickPipes は、ターゲットテーブルだけでなく、それに依存する materialized view に対してもステージングテーブルを作成します。

non-materialized view に対してはステージングテーブルを作成しません。つまり、1 つ以上の下流の materialized view を持つターゲットテーブルがある場合、それらの materialized view では、ターゲットテーブルのデータをビュー経由で参照しないようにしてください。そうしないと、materialized view でデータの一部が欠落する可能性があります。