gcs テーブル関数

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

これは s3 テーブル関数 の別名です。

クラスターに複数のレプリカがある場合、s3Cluster 関数（GCS と共に動作します）を使用して挿入を並列化できます。

構文

gcs(url [, NOSIGN | hmac_key, hmac_secret] [,format] [,structure] [,compression_method])
gcs(named_collection[, option=value [,..]])

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.googleapis.com/<bucket>/<folder>/<filename(s)>

  であり、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行を選択する例：

SELECT *
FROM gcs('https://storage.googleapis.com/my-test-bucket-768/data.csv', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32')
LIMIT 2;

┌─column1─┬─column2─┬─column3─┐
│       1 │       2 │       3 │
│       3 │       2 │       1 │
└─────────┴─────────┴─────────┘

gzip 圧縮方法を使用した同様の例：

SELECT *
FROM gcs('https://storage.googleapis.com/clickhouse_public_datasets/my-test-bucket-768/data.csv.gz', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32', 'gzip')
LIMIT 2;

┌─column1─┬─column2─┬─column3─┐
│       1 │       2 │       3 │
│       3 │       2 │       1 │
└─────────┴─────────┴─────────┘

使用方法

GCS上の以下のURIを持つ複数のファイルがあるとします：

• '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までのファイル内の行数をカウントします：

SELECT count(*)
FROM gcs('https://storage.googleapis.com/clickhouse_public_datasets/my-test-bucket-768/{some,another}_prefix/some_file_{1..3}.csv', 'CSV', 'name String, value UInt32')

┌─count()─┐
│      18 │
└─────────┘

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

SELECT count(*)
FROM gcs('https://storage.googleapis.com/clickhouse_public_datasets/my-test-bucket-768/{some,another}_prefix/*', 'CSV', 'name String, value UInt32')

┌─count()─┐
│      24 │
└─────────┘

Danger

先頭にゼロを含む数字の範囲を含むファイルリストを持っている場合は、個別の数字用にブレースを使用するか、? を使用してください。

ファイル名が file-000.csv、file-001.csv、...、file-999.csv のファイル内の総行数をカウントします：

SELECT count(*)
FROM gcs('https://storage.googleapis.com/clickhouse_public_datasets/my-test-bucket-768/big_prefix/file-{000..999}.csv', 'CSV', 'name String, value UInt32');

┌─count()─┐
│      12 │
└─────────┘

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

INSERT INTO FUNCTION gcs('https://storage.googleapis.com/my-test-bucket-768/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip')
VALUES ('test-data', 1), ('test-data-2', 2);

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

INSERT INTO FUNCTION gcs('https://storage.googleapis.com/my-test-bucket-768/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip')
SELECT name, value FROM existing_table;

グロブ ** は再帰的なディレクトリトラバーサルに使用できます。以下の例では、my-test-bucket-768 ディレクトリ内のすべてのファイルを再帰的に取得します：

SELECT * FROM gcs('https://storage.googleapis.com/my-test-bucket-768/**', 'CSV', 'name String, value UInt32', 'gzip');

以下は my-test-bucket ディレクトリ内の任意のフォルダーから test-data.csv.gz ファイルを再帰的に取得する例です：

SELECT * FROM gcs('https://storage.googleapis.com/my-test-bucket-768/**/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip');

実用化のケースでは 名前付きコレクション を使用することをお勧めします。以下がその例です：

CREATE NAMED COLLECTION creds AS
        access_key_id = '***',
        secret_access_key = '***';
SELECT count(*)
FROM gcs(creds, url='https://s3-object-url.csv')

パーティション書き込み

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

例

1. キーにパーティションIDを使用して個別のファイルを作成：

INSERT INTO TABLE FUNCTION
    gcs('http://bucket.amazonaws.com/my_bucket/file_{_partition_id}.csv', 'CSV', 'a String, b UInt32, c UInt32')
    PARTITION BY a VALUES ('x', 2, 3), ('x', 4, 5), ('y', 11, 12), ('y', 13, 14), ('z', 21, 22), ('z', 23, 24);

この結果、データは file_x.csv、file_y.csv、file_z.csv の3つのファイルに書き込まれます。

2. パーティションIDをバケット名に使用して、異なるバケットにファイルを作成：

INSERT INTO TABLE FUNCTION
    gcs('http://bucket.amazonaws.com/my_bucket_{_partition_id}/file.csv', 'CSV', 'a UInt32, b UInt32, c UInt32')
    PARTITION BY a VALUES (1, 2, 3), (1, 4, 5), (10, 11, 12), (10, 13, 14), (20, 21, 22), (20, 23, 24);

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

関連項目

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