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

Google Cloud Storage と ClickHouse Cloud の連携

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

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

サポートされる形式​

機能​

一回限りのインジェスト​

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

継続的なインジェスト​

継続的なインジェストが有効な場合、ClickPipes は指定されたパスからデータを継続的にインジェストし続けます。インジェストの順序を決定するために、GCS ClickPipe はファイルの暗黙的な辞書式順序に依存します。

Lexicographical order​

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

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

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

Object Storage ClickPipes は、ファイルパターンマッチングに POSIX 標準に準拠します。すべてのパターンは大文字と小文字を区別し、バケット名の後ろのフルパス全体に対してマッチします。パフォーマンスを向上させるため、可能な限り具体的なパターンを使用してください（例: *.csv ではなく data-2024-*.csv）。

サポートされているパターン​

Pattern説明例一致例
?/ を除く 1 文字だけ にマッチdata-?.csvdata-1.csv, data-a.csv, data-x.csv
*/ を除く 0 文字以上 にマッチdata-*.csvdata-1.csv, data-001.csv, data-report.csv, data-.csv
**
再帰		/ を含む 0 文字以上 にマッチ。ディレクトリを再帰的に走査できる。logs/**/error.loglogs/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

サポート対象外のパターン​

パターン説明例代替案
{abc,def}ブレース展開（代替候補の列挙）{logs,data}/file.csv各パスごとに個別の ClickPipes を作成します。
{N..M}数値範囲のブレース展開file-{1..100}.csvfile-*.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 セマンティクス​

大規模なデータセットを取り込む際にはさまざまな種類の障害が発生し得るため、insert が部分的にしか行われなかったり、データが重複したりする可能性があります。Object Storage ClickPipes は insert の失敗に対して堅牢で、Exactly-once セマンティクスを提供します。これは一時的な「staging」テーブルを使用することで実現されています。まずデータは staging テーブルに insert されます。この insert で問題が発生した場合、staging テーブルを truncate し、クリーンな状態から insert を再試行できます。insert が完了して成功した場合にのみ、staging テーブル内のパーティションがターゲットテーブルへ移動されます。この戦略の詳細については、このブログ記事を参照してください。

仮想カラム​

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

アクセス制御​

権限​

GCS ClickPipe は、パブリックバケットおよびプライベートバケットをサポートします。Requester Pays バケットはサポートされていません。

roles/storage.objectViewer ロールをバケットレベルで付与する必要があります。このロールには、storage.objects.list および storage.objects.get IAM 権限が含まれており、指定したバケット内のオブジェクトを ClickPipes が一覧表示および取得できるようにします。

認証​

注記

サービス アカウントによる認証は現在サポートされていません。

HMAC 資格情報​

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

GCS ClickPipes 用の HMAC 資格情報

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

詳細設定​

ClickPipes には、多くのユースケースの要件を満たす妥当なデフォルト値が用意されています。ユースケースによっては、さらに細かい調整が必要な場合は、次の設定を変更できます。

設定デフォルト値説明
Max insert bytes10GB1 回の挿入バッチで処理するバイト数。
Max file count1001 回の挿入バッチで処理するファイルの最大数。
Max threadsauto(3)ファイル処理に使用する同時実行スレッド数の上限。
Max insert threads1ファイル処理に使用する同時実行挿入スレッド数の上限。
Min insert block size bytes1GBテーブルに挿入できるブロック内の最小バイトサイズ。
Max download threads4同時実行ダウンロードスレッド数の上限。
Object storage polling interval30sClickHouse クラスターにデータを挿入する前に待機する最大時間を設定します。
Parallel distributed insert select2Parallel distributed insert select の設定。
Parallel view processingfalseアタッチされた VIEW へのプッシュを逐次ではなく並行して実行するかどうか。
Use cluster functiontrue複数ノード間でファイルを並列処理するかどうか。
ClickPipes の詳細設定

スケーリング​

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

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

既知の制限事項​

ファイルサイズ​

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

互換性​

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

View support​

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

通常の（非 materialized）view に対してはステージングテーブルを作成しません。つまり、対象テーブルに 1 つ以上の下流の materialized view がある場合、それらの materialized view では、対象テーブルに対する view を経由してデータを SELECT しないようにする必要があります。そうしないと、その materialized view 内でデータ欠損が発生する可能性があります。