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

Amazon S3 と ClickHouse Cloud の統合

S3 ClickPipe は、Amazon S3 および S3 互換オブジェクトストアから ClickHouse Cloud へデータを取り込むための、フルマネージドで高い耐障害性を備えた手段を提供します。1 回限りと継続的なインジェストの両方を、exactly-once セマンティクスでサポートします。

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

サポートされているデータソース​

NameLogoDetails
Amazon S3継続的なインジェストはデフォルトでは辞書式順序が必要ですが、任意の順序でファイルを取り込むように構成することもできます。
Cloudflare R2
S3-compatible		継続的なインジェストには辞書式順序が必要です。
DigitalOcean Spaces
S3-compatible		継続的なインジェストには辞書式順序が必要です。
ヒント

オブジェクトストレージサービスプロバイダーごとに URL 形式や API 実装が異なるため、そのままではすべての S3 互換サービスがサポートされるわけではありません。上記に記載されていないサービスで問題が発生している場合は、弊社チームまでお問い合わせください。

サポート対象フォーマット​

機能​

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

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

継続的インジェスト​

継続的インジェストが有効になっている場合、ClickPipes は指定されたパスからデータを継続的にインジェストします。インジェスト順序を決定するために、S3 ClickPipe はデフォルトでファイルの暗黙的な辞書式順序に依存します。また、バケットに接続された Amazon SQS キューを使用して、ファイルを任意の順序でインジェストするように設定することもできます。

辞書順​

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

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

任意の順序​

注記

順不同モードは Amazon S3 に対してのみサポートされており、パブリックバケットには対応していません。このモードでは、バケットに接続された Amazon SQS キューのセットアップが必要です。

S3 ClickPipe では、バケットに接続された Amazon SQS キューをセットアップすることで、暗黙的な順序付けを持たないファイルを取り込むように構成できます。これにより、ClickPipes はオブジェクト作成イベントをリッスンし、ファイル命名規則に関係なく新しいファイルをインジェストできるようになります。

このモードでは、S3 ClickPipe は選択したパス内のすべてのファイルを初期ロードした後、キュー内で指定したパスに一致する ObjectCreated:* イベントをリッスンします。すでに処理済みのファイルに対するメッセージ、パスに一致しないファイル、または異なる種類のイベントはすべて無視されます。

注記

イベントに対して prefix/postfix を設定することは任意です。設定する場合は、ClickPipe に設定したパスと一致していることを確認してください。S3 では、同じイベントタイプに対して複数の重複する通知ルールは許可されません。

ファイルは、max insert bytes または max file count に設定されたしきい値に達するか、または設定可能な間隔（デフォルトでは 30 秒）が経過するとインジェストされます。特定のファイルや時点からインジェストを開始することはできません — ClickPipes は常に選択したパス内のすべてのファイルをロードします。DLQ が設定されている場合、失敗したメッセージは再キューイングされ、DLQ の maxReceiveCount パラメータで設定された回数まで再処理されます。

ヒント

SQS キューには Dead-Letter-Queue (DLQ) を設定することを強く推奨します。これにより、失敗したメッセージのデバッグおよび再試行が容易になります。

SNS から SQS へ​

SNS トピック経由で S3 イベント通知を SQS に送信することも可能です。これは、S3 から SQS への直接連携でいくつかの制約に抵触するケースで利用できます。この場合は、raw message delivery オプションを有効にする必要があります。

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

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

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

パターン説明例マッチするパス
?/ を除く ちょうど 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

非対応のパターン​

PatternDescriptionExampleAlternatives
{abc,def}ブレース展開（brace expansion）{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 セマンティクス​

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

仮想カラム​

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

アクセス制御​

権限​

S3 ClickPipe は、パブリックバケットとプライベートバケットをサポートします。Requester Pays バケットはサポートされません。

S3 バケット​

バケットポリシーで、次のアクションを許可する必要があります。

SQS キュー​

unordered mode を使用する場合、SQS キューのポリシーで次のアクションを許可する必要があります：

認証​

IAM 認証情報​

アクセスキー を使用して認証するには、ClickPipe 接続を設定する際に、Authentication method で Credentials を選択します。次に、Access key と Secret key にそれぞれ、アクセスキー ID（例: AKIAIOSFODNN7EXAMPLE）とシークレットアクセスキー（例: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY）を入力します。

S3 ClickPipes 用の IAM 認証情報

IAM ロール​

ロールベースのアクセスで認証を行うには、ClickPipe 接続を設定する際に、Authentication method で IAM role を選択します。

S3 ClickPipes 用の IAM 認証

S3 へのアクセスに必要な信頼ポリシーを持つロールを作成するには、このガイドに従い、ロールを作成してください。その後、IAM role ARN に IAM ロール ARN を入力します。

高度な設定​

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 は、vertical autoscaling 設定 で決定される最小の ClickHouse サービスサイズに基づいてスケールされます。ClickPipe のサイズはパイプ作成時に決定され、その後に ClickHouse サービス設定を変更しても、ClickPipe のサイズには影響しません。

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

既知の制限事項​

ファイルサイズ​

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

互換性​

S3 互換であっても、一部のサービスは S3 ClickPipe が解析できない可能性のある異なる URL 構造を使用していたり（例: Backblaze B2）、連続的で順不同なインジェストのためにプロバイダー固有のキューサービスとの連携を必要とする場合があります。Supported data sources に記載されていないサービスで問題が発生している場合は、弊社チームまでお問い合わせください。

View support​

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

非 materialized view に対してはステージングテーブルを作成しません。つまり、ターゲットテーブルに 1 つ以上の下流の materialized view がある場合、それらの materialized view では、ターゲットテーブル上の view を介してデータを SELECT しないようにする必要があります。そうしないと、その materialized view 内でデータが欠落する可能性があります。