辞書式順序
GCS ClickPipe は、ファイルがバケットに辞書式順序で追加されることを前提としており、この暗黙的な順序に基づいてファイルを順番に取り込みます。つまり、新しいファイルは、最後に取り込まれたファイルよりも辞書式で後に来る名前である必要があります。たとえば、file1、file2、file3 という名前のファイルは順番に取り込まれますが、新たに file 0 がバケットに追加された場合、ファイル名が最後に取り込まれたファイルよりも辞書式で後ではないため、無視されます。
このモードでは、GCS ClickPipe は指定されたパス内のすべてのファイルを初期ロードし、その後、設定可能な間隔 (デフォルトでは 30 秒) で新しいファイルがないかポーリングします。特定のファイルの後から継続的インジェストを開始するには、Start after を設定します。ClickPipes は、設定値以下の辞書式順序のファイルをスキップし、その時点から新しいファイルの取り込みを継続します。
任意の順序
バケットから通知を受け取る Google Cloud Pub/Sub サブスクリプションを設定すると、暗黙的な順序を持たないファイルを取り込むように GCS ClickPipe を構成できます。これにより、ClickPipes はオブジェクト作成イベントを監視し、ファイル名の命名規則に関係なく新しいファイルを取り込めるようになります。公開バケットでは順不同モードはサポートされていません。これを使用するには、アップロードした秘密鍵または GCP Workload Identity のいずれかを用いた service account 認証と、バケットに接続された Google Cloud Pub/Sub サブスクリプションが必要です。
OBJECT_FINALIZE 通知を待ち受けます。すでに確認済みのファイル、パスに一致しないファイル、または別種のイベントに対するメッセージは、すべて無視されます。サブスクリプション経由で配信されたファイルのみを取り込むには、初回読み込みをスキップを有効にします。有効にすると、ClickPipes は選択したパス内の既存ファイルの初期スキャンをスキップし、Pub/Sub サブスクリプション経由で配信されたファイルのみを処理します。
Object Storage 用 ClickPipes では、ファイルパターンのマッチングに POSIX 標準を採用しています。すべてのパターンは大文字と小文字を区別し、バケット名の後ろにあるフルパス全体に対して照合されます。パフォーマンスを高めるため、できるだけ具体的なパターンを使用してください (例: *.csv ではなく data-2024-*.csv) 。
例:
https://bucket.s3.amazonaws.com/folder/*.csvhttps://bucket.s3.amazonaws.com/logs/**/data.jsonhttps://bucket.s3.amazonaws.com/file-?.parquethttps://bucket.s3.amazonaws.com/data-2024-*.csv.gz
例:
https://bucket.s3.amazonaws.com/{documents-01,documents-02}.jsonhttps://bucket.s3.amazonaws.com/file-{1..100}.csvhttps://bucket.s3.amazonaws.com/{logs,metrics}/data.parquet
_file 仮想カラムを含めます。_file 仮想カラムにはソースオブジェクトのファイル名が含まれており、これを使ってどのファイルが処理されたかをクエリできます。
GCS ClickPipe は公開バケットと非公開バケットに対応しています。Requester Pays バケットはサポートしていません。
ClickPipes が使用するサービス アカウントでは、バケット レベルで次の操作が許可されている必要があります。
このロールには storage.objects.list と `storage.objects.get の IAM 権限が含まれており、これにより ClickPipes は指定されたバケット内のオブジェクトを一覧表示し、取得できます。
順不同モードを使用する場合、サービス アカウントには、Pub/Sub サブスクリプションに対して次のロールが必要です。
roles/pubsub.subscriber— メッセージを受信し、確認応答するため。roles/pubsub.viewer— サブスクリプションのメタデータを取得するため。
GCP Workload Identity (ベータ)
GCP Workload Identity ガイドに従い、ClickPipes のサービスコンテキストからマネージドの service account を取得します。ソースバケットに対してこの service account にroles/storage.objectViewer を付与し、SERVICE_ACCOUNT_WORKLOAD_IDENTITY 認証でパイプを作成します。unordered モードでインジェストする場合は、既存の通知サブスクリプションに対して roles/pubsub.subscriber と roles/pubsub.viewer も付与し、サブスクリプションの完全修飾名 projects/<project-id>/subscriptions/<subscription-id> を指定してください。
HMAC認証情報
HMACキー を使用して認証するには、ClickPipe 接続を設定する際に Authentication method でCredentials を選択します。次に、Access key と Secret key に、それぞれアクセスキー (例: GOOGTS7C7FUP3AIRVJTE2BCDKINBTES3HC2GY5CBFJDCQ2SYHV6A6XXVTJFSA) とシークレットキー (例: bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ) を入力します。

-
IP ベースのアクセス制御では、GCS バケットの IP フィルタリング ルール で、こちらに記載されている ClickPipes サービスリージョンの静的 IP と、ClickHouse Cloud サービスの 静的 IP の両方を許可する必要があります。ご利用の ClickHouse Cloud リージョンの静的 IP を取得するには、ターミナルを開いて次を実行します。
詳細設定
ClickPipes には、ほとんどのユースケースの要件を満たす妥当なデフォルト設定が用意されています。さらに細かなチューニングが必要な場合は、以下の設定を調整できます。
gs:// ではなく https://storage.googleapis.com/ のバケットプレフィックスを使用し、認証には HMAC キー を使用する必要があります。
ターゲットテーブルに対する materialized view もサポートされています。ClickPipes は、ターゲットテーブルだけでなく、それに依存する materialized view に対してもステージングテーブルを作成します。
non-materialized view に対してはステージングテーブルを作成しません。つまり、1 つ以上の下流の materialized view を持つターゲットテーブルがある場合、それらの materialized view では、ターゲットテーブルのデータをビュー経由で参照しないようにしてください。そうしないと、materialized view でデータの一部が欠落する可能性があります。