> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > オブジェクトストレージを ClickHouse Cloud にシームレスに接続します。 # Google Cloud Storage を ClickHouse Cloud と統合する export const Image = ({img, alt, size}) => { return {alt} ; }; GCS ClickPipe は、Google Cloud Storage (GCS) からデータを取り込むための、フルマネージドで高い耐障害性を備えた仕組みです。**一回限り**と**継続的インジェスト**の両方をサポートし、exactly-once セマンティクスを提供します。 GCS ClickPipes は、ClickPipes UI を使用して手動でデプロイおよび管理できるほか、[OpenAPI](/ja/integrations/clickpipes/programmatic-access/openapi) や [Terraform](/ja/integrations/clickpipes/programmatic-access/terraform) を使用してプログラムから実行することもできます。
## 対応フォーマット
* [JSON](/ja/reference/formats/JSON/JSON) * [CSV](/ja/reference/formats/CSV/CSV) * [TSV](/ja/reference/formats/TabSeparated/TabSeparated) * [Parquet](/ja/reference/formats/Parquet/Parquet) * [Avro](/ja/reference/formats/Avro/Avro)
## 機能
### 一回限りのインジェスト
デフォルトでは、GCS ClickPipe は、指定したバケット内でパターンに一致するすべてのファイルを、1 回のバッチ処理で ClickHouse の宛先テーブルに読み込みます。インジェスト タスクが完了すると、ClickPipe は自動的に停止します。この一回限りのインジェスト モードでは exactly-once セマンティクスが提供されるため、各ファイルは重複なく確実に処理されます。
### 継続的インジェスト
継続的インジェストが有効な場合、ClickPipes は指定されたパスからデータを継続的に取り込みます。インジェスト順序の判定には、GCS ClickPipe はデフォルトでファイルの暗黙的な[辞書式順序](#continuous-ingestion-lexicographical-order)を使用します。また、[バケット通知を行うよう設定した](https://docs.cloud.google.com/storage/docs/reporting-changes#command-line) [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) サブスクリプションを使用して、ファイルを[任意の順序](#continuous-ingestion-any-order)で取り込むように構成することもできます。
#### 辞書式順序
GCS ClickPipe は、ファイルがバケットに辞書式順序で追加されることを前提としており、この暗黙的な順序に基づいてファイルを順番に取り込みます。つまり、新しいファイルは、最後に取り込まれたファイルよりも辞書式で後に来る名前である**必要があります**。たとえば、`file1`、`file2`、`file3` という名前のファイルは順番に取り込まれますが、新たに `file 0` がバケットに追加された場合、ファイル名が最後に取り込まれたファイルよりも辞書式で後ではないため、**無視**されます。 このモードでは、GCS ClickPipe は指定されたパス内の**すべてのファイル**を初期ロードし、その後、設定可能な間隔 (デフォルトでは 30 秒) で新しいファイルがないかポーリングします。特定のファイルや時点からインジェストを開始することは**できません** — ClickPipes は常に指定されたパス内のすべてのファイルを読み込みます。
#### 順不同
手順については、[継続的インジェストの順不同モードの設定](/ja/integrations/clickpipes/object-storage/google-cloud-storage/unordered-mode)を参照してください。 バケットから通知を受け取る [Google Cloud Pub/Sub](https://docs.cloud.google.com/storage/docs/pubsub-notifications) サブスクリプションを設定すると、暗黙的な順序を持たないファイルを取り込むように GCS ClickPipe を構成できます。これにより、ClickPipes はオブジェクト作成イベントを監視し、ファイル名の命名規則に関係なく新しいファイルを取り込めるようになります。 公開バケットでは**順不同モード**はサポートされていません。これを使用するには、**サービス アカウント**認証と、バケットに接続された [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) サブスクリプションが必要です。 このモードでは、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 セマンティクスを提供します。これは、一時的な「ステージングテーブル」を使用して実現されます。まず、データはステージングテーブルに挿入されます。この挿入中に問題が発生した場合は、ステージングテーブルを空にして、クリーンな状態から挿入を再試行できます。挿入が正常に完了した場合にのみ、ステージングテーブル内のパーティションがターゲットテーブルに移動されます。この戦略について詳しくは、[こちらのブログ記事](https://clickhouse.com/blog/supercharge-your-clickhouse-data-loads-part3)をご覧ください。
### 仮想カラム
どのファイルが取り込まれたかを追跡するには、カラムマッピングのリストに `_file` 仮想カラムを含めます。`_file` 仮想カラムにはソースオブジェクトのファイル名が含まれており、これを使ってどのファイルが処理されたかをクエリできます。
## アクセス制御
### 権限
GCS ClickPipe は公開バケットと非公開バケットに対応しています。[Requester Pays](https://docs.cloud.google.com/storage/docs/requester-pays) バケットは**サポートしていません**。
#### GCS バケット
ClickPipes が使用するサービス アカウントでは、バケット レベルで次の操作が許可されている必要があります。 * [`roles/storage.objectViewer`](https://docs.cloud.google.com/storage/docs/access-control/iam-roles#storage.objectViewer) このロールには [`storage.objects.list`](https://docs.cloud.google.com/storage/docs/json_api/v1/objects/list) と [\`storage.objects.get](https://docs.cloud.google.com/storage/docs/json_api/v1/objects/get#required-permissions) の IAM 権限が含まれており、これにより ClickPipes は指定されたバケット内のオブジェクトを一覧表示し、取得できます。
#### Pub/Sub サブスクリプション
[順不同モード](#continuous-ingestion-any-order)を使用する場合、サービス アカウントには、Pub/Sub サブスクリプションに対して次のロールが必要です。 * [`roles/pubsub.subscriber`](https://cloud.google.com/pubsub/docs/access-control#roles) — メッセージを受信し、確認応答するため。 * [`roles/pubsub.viewer`](https://cloud.google.com/pubsub/docs/access-control#roles) — サブスクリプションのメタデータを取得するため。
### 認証
#### サービス アカウント
Pub/Sub 通知で[順不同モード](#continuous-ingestion-any-order)を使用する場合は、サービス アカウント認証が必要です。認証方法として **Service Account** を選択し、サービス アカウントの秘密鍵の JSON ファイルをアップロードします。
#### HMAC認証情報
[HMACキー](https://docs.cloud.google.com/storage/docs/authentication/hmackeys) を使用して認証するには、ClickPipe 接続を設定する際に **Authentication method** で `Credentials` を選択します。次に、`Access key` と `Secret key` に、それぞれアクセスキー (例: `GOOGTS7C7FUP3AIRVJTE2BCDKINBTES3HC2GY5CBFJDCQ2SYHV6A6XXVTJFSA`) とシークレットキー (例: `bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ`) を入力します。 GCS ClickPipes の HMAC認証情報 HMACキーを持つサービス アカウントを作成するには、[このガイド](/ja/integrations/connectors/data-sources/gcs#create-a-service-account-hmac-key-and-secret) に従ってください。
### ネットワークアクセス
GCS ClickPipes では、メタデータの検出とデータのインジェストに、それぞれ ClickPipes サービスと ClickHouse Cloud サービスという 2 つの異なるネットワーク経路を使用します。ネットワークセキュリティをさらに強化したい場合 (たとえば、コンプライアンス要件への対応のため) 、**両方の経路でネットワークアクセスを設定する必要があります**。 * **IP ベースのアクセス制御**では、GCS バケットの [IP フィルタリング ルール](https://docs.cloud.google.com/storage/docs/ip-filtering-overview) で、[こちら](/ja/integrations/clickpipes/home#list-of-static-ips)に記載されている ClickPipes サービスリージョンの静的 IP と、ClickHouse Cloud サービスの [静的 IP](/ja/products/cloud/guides/data-sources/cloud-endpoints-api) の両方を許可する必要があります。ご利用の ClickHouse Cloud リージョンの静的 IP を取得するには、ターミナルを開いて次を実行します。 ```bash theme={null} # Replace with your ClickHouse Cloud region curl -s https://api.clickhouse.cloud/static-ips.json | jq -r '.gcp[] | select(.region == "") | .egress_ips[]' ```
## 詳細設定
ClickPipes には、ほとんどのユースケースの要件を満たす妥当なデフォルト設定が用意されています。さらに細かなチューニングが必要な場合は、以下の設定を調整できます。 | Setting | Default value | Description | | ------------------------------------ | ------------- | --------------------------------------------------------------------------------------------------------------------- | | `Max insert bytes` | 10GB | 1 回の挿入バッチで処理するバイト数。 | | `Max file count` | 100 | 1 回の挿入バッチで処理するファイルの最大数。 | | `Max threads` | auto(3) | ファイル処理に使用する[同時実行スレッドの最大数](/ja/reference/settings/session-settings#max_threads)。 | | `Max insert threads` | 1 | ファイル処理に使用する[同時実行される挿入スレッドの最大数](/ja/reference/settings/session-settings#max_insert_threads)。 | | `Min insert block size bytes` | 1GB | テーブルに挿入可能な[ブロックの最小バイトサイズ](/ja/reference/settings/session-settings#min_insert_block_size_bytes)。 | | `Max download threads` | 4 | [同時実行されるダウンロードスレッドの最大数](/ja/reference/settings/session-settings#max_download_threads)。 | | `Object storage polling interval` | 30s | ClickHouse クラスターにデータを挿入するまでの最大待機時間を設定します。 | | `Parallel distributed insert select` | 2 | [parallel distributed insert select の設定](/ja/reference/settings/session-settings#parallel_distributed_insert_select)。 | | `Parallel view processing` | false | アタッチされたビューへのプッシュを、[順次ではなく同時実行で](/ja/reference/settings/session-settings#parallel_view_processing)行うかどうか。 | | `Use cluster function` | true | 複数ノードにまたがってファイルを並列処理するかどうか。 | ClickPipes の詳細設定
### スケーリング
Object Storage 用 ClickPipes は、[構成された垂直オートスケーリング設定](/ja/products/cloud/features/autoscaling/vertical#configuring-vertical-auto-scaling)によって決まる ClickHouse サービスの最小サイズに基づいてスケーリングされます。ClickPipe のサイズは、パイプの作成時に決定されます。作成後に ClickHouse サービスの設定を変更しても、ClickPipe のサイズには影響しません。 大規模な取り込みジョブのスループットを向上させるには、ClickPipe を作成する前に ClickHouse サービスをスケーリングすることを推奨します。
## 既知の制約事項
### ファイルサイズ
ClickPipes は、サイズが**10GB以下**のオブジェクトのみを取り込みます。ファイルが 10GB を超える場合、エラーは ClickPipes 専用のエラーテーブルに追記されます。
### 互換性
GCS ClickPipe では、相互運用性を確保するために Cloud ストレージの [XML API](https://docs.cloud.google.com/storage/docs/interoperability) を使用します。そのため、`gs://` ではなく `https://storage.googleapis.com/` のバケットプレフィックスを使用し、認証には [HMAC キー](https://docs.cloud.google.com/storage/docs/authentication/hmackeys) を使用する必要があります。
### ビューのサポート
ターゲットテーブルに対する materialized view もサポートされています。ClickPipes は、ターゲットテーブルだけでなく、それに依存する materialized view に対してもステージングテーブルを作成します。 non-materialized view に対してはステージングテーブルを作成しません。つまり、1 つ以上の下流の materialized view を持つターゲットテーブルがある場合、それらの materialized view では、ターゲットテーブルのデータをビュー経由で参照しないようにしてください。そうしないと、materialized view でデータの一部が欠落する可能性があります。