Google Cloud Storage を 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 秒) で新しいファイルがないかポーリングします。特定のファイルの後から継続的インジェストを開始するには、Start after を設定します。ClickPipes は、設定値以下の辞書式順序のファイルをスキップし、その時点から新しいファイルの取り込みを継続します。

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

このモードでは、GCS ClickPipe は選択したパス内のすべてのファイルを初期ロードし、その後、指定したパスに一致する Pub/Sub サブスクリプション経由の OBJECT_FINALIZE 通知を待ち受けます。すでに確認済みのファイル、パスに一致しないファイル、または別種のイベントに対するメッセージは、すべて無視されます。サブスクリプション経由で配信されたファイルのみを取り込むには、初期ロードをスキップを有効にします。有効にすると、ClickPipes は選択したパス内の既存ファイルの初期スキャンをスキップし、Pub/Sub サブスクリプション経由で配信されたファイルのみを処理します。

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

例:

• 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

例:

• 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

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

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

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

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

• roles/storage.objectViewer

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

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

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

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

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

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 でデータの一部が欠落する可能性があります。