gcs テーブル関数

Google Cloud Storage からデータを SELECT および INSERT するためのテーブルのようなインターフェースを提供します。Storage Object User IAM ロールが必要です。

これはs3 テーブル関数のエイリアスです。

クラスターに複数のレプリカがある場合、挿入を並列化するために s3Cluster 関数（GCS と連携します）を代わりに使用できます。

構文

GCS

GCS テーブル関数は GCS XML API と HMAC キーを使用して Google Cloud Storage と統合されます。エンドポイントと HMAC の詳細については、Google の相互運用性ドキュメントを参照してください。

パラメーター

• url — ファイルのバケットパス。読み取り専用モードで以下のワイルドカードをサポートします: *, **, ?, {abc,def} および {N..M} （N, M — 数字、'abc', 'def' — 文字列）。
  GCS

  GCS パスはこの形式であり、Google XML API のエンドポイントは JSON API とは異なります:

https://storage.cloud.google.com ではありません。 :::

• NOSIGN — このキーワードを認証情報の代わりに提供すると、すべてのリクエストは署名されません。
• hmac_key および hmac_secret — 指定されたエンドポイントで使用する認証情報を指定するキー。オプション。
• format — ファイルのフォーマット。
• structure — テーブルの構造。形式 'column1_name column1_type, column2_name column2_type, ...'。
• compression_method — パラメーターはオプションです。サポートされている値: none, gzip または gz, brotli または br, xz または LZMA, zstd または zst。デフォルトでは、ファイル拡張子によって圧縮方法を自動検出します。

引数は名付けられたコレクションを使用して渡すこともできます。この場合、url, format, structure, compression_methodは同じように機能し、いくつかの追加パラメーターがサポートされます:

• access_key_id — hmac_key、オプション。
• secret_access_key — hmac_secret、オプション。
• filename — 指定された場合、url に追加されます。
• use_environment_credentials — デフォルトで有効、環境変数 AWS_CONTAINER_CREDENTIALS_RELATIVE_URI, AWS_CONTAINER_CREDENTIALS_FULL_URI, AWS_CONTAINER_AUTHORIZATION_TOKEN, AWS_EC2_METADATA_DISABLED を使用して追加のパラメーターを渡すことを許可します。
• no_sign_request — デフォルトでは無効。
• expiration_window_seconds — デフォルト値は 120。

戻り値

指定されたファイルでデータを読み書きするための指定された構造のテーブル。

例

GCS ファイル https://storage.googleapis.com/my-test-bucket-768/data.csv から最初の 2 行を選択:

圧縮方法が gzip のファイルからの同様のクエリ:

使用法

以下の URI を持ついくつかの GCS ファイルがあるとしましょう:

• 'https://storage.googleapis.com/my-test-bucket-768/some_prefix/some_file_1.csv'
• 'https://storage.googleapis.com/my-test-bucket-768/some_prefix/some_file_2.csv'
• 'https://storage.googleapis.com/my-test-bucket-768/some_prefix/some_file_3.csv'
• 'https://storage.googleapis.com/my-test-bucket-768/some_prefix/some_file_4.csv'
• 'https://storage.googleapis.com/my-test-bucket-768/another_prefix/some_file_1.csv'
• 'https://storage.googleapis.com/my-test-bucket-768/another_prefix/some_file_2.csv'
• 'https://storage.googleapis.com/my-test-bucket-768/another_prefix/some_file_3.csv'
• 'https://storage.googleapis.com/my-test-bucket-768/another_prefix/some_file_4.csv'

数字が 1 から 3 のファイルの行数をカウント:

これら 2 つのディレクトリ内のすべてのファイルの総行数をカウント:

危険

ファイルのリストに先頭ゼロを含む数字の範囲が含まれている場合は、各桁ごとに波括弧を使った構文を使用するか、? を使用してください。

file-000.csv, file-001.csv, ... , file-999.csv という名前のファイルの総行数をカウント:

ファイル test-data.csv.gz にデータを挿入:

既存のテーブルからファイル test-data.csv.gz にデータを挿入:

グロブ ** を使用して再帰的にディレクトリを横断できます。以下の例では、my-test-bucket-768 ディレクトリからすべてのファイルを再帰的に取得します:

以下は、my-test-bucket ディレクトリ内の任意のフォルダから再帰的にすべての test-data.csv.gz ファイルからデータを取得します:

本番使用の場合は、名付けられたコレクションを使用することをお勧めします。以下はその例です:

パーティション化された書き込み

GCS テーブルにデータを挿入する際に PARTITION BY 式を指定すると、各パーティション値に対して別々のファイルが作成されます。データを別々のファイルに分割することで、読み取り操作の効率が向上します。

例

1. キー内のパーティション ID を使用すると、別々のファイルが作成されます:

その結果、データは 3 つのファイルに書き込まれます: file_x.csv, file_y.csv, および file_z.csv。

2. バケット名内のパーティション ID を使用すると、異なるバケットにファイルが作成されます:

その結果、データは異なるバケット内の 3 つのファイルに書き込まれます: my_bucket_1/file.csv, my_bucket_10/file.csv, および my_bucket_20/file.csv。

関連情報

• S3 テーブル関数
• S3 エンジン