gcs

Google Cloud Storage のデータに対して SELECT および INSERT を行うためのテーブル形式インターフェイスを提供します。Storage Object User IAM role が必要です。

クラスター内に複数のレプリカがある場合は、代わりに s3Cluster function (GCS でも使用可能) を使うことで、挿入を並列化できます。

構文

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

引数

引数	説明
`url`	ファイルへのバケットパスです。読み取り専用モードでは、次のワイルドカードをサポートします: ``, `*`, `?`, `{abc,def}`、`{N..M}`。ここで `N`、`M` は数値、`'abc'`、`'def'` は文字列です。
`NOSIGN`	認証情報の代わりにこのキーワードを指定すると、すべてのリクエストが署名されなくなります。
`hmac_key` and `hmac_secret`	指定したエンドポイントで使用する認証情報を指定するオプションです。省略可能です。
`format`	ファイルのフォーマットです。
`structure`	テーブルの構造です。形式は `'column1_name column1_type, column2_name column2_type, ...'` です。
`compression_method`	この parameter は省略可能です。サポートされる値は `none`、`gzip` または `gz`、`brotli` または `br`、`xz` または `LZMA`、`zstd` または `zst` です。デフォルトでは、ファイル拡張子から圧縮方式を自動判別します。
`partition_strategy`	省略可能です。サポートされる値は `wildcard` または `hive` です。`wildcard` ではパスに `{_partition_id}` が必要です。明示的な戦略を指定しない場合、`{_partition_id}` を含むパスでは `wildcard` が使用されます。別の glob を含むパスではパーティション方式は使用されず、`PARTITION BY` は無視されます。glob を含まないパスでは、`file_like_engine_default_partition_strategy` が `hive` の場合は `hive` が使用され、それ以外ではパーティション方式は使用されません。

Info - GCS

Google XML API のエンドポイントは JSON API と異なるため、GCS パスは次の形式になります:

  https://storage.googleapis.com/<bucket>/<folder>/<filename(s)>

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

引数は named collections を使って渡すこともできます。この場合、url、format、structure、compression_method、partition_strategy は同様に機能し、追加のパラメータもいくつかサポートされます:

パラメータ	説明
`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/clickhouse_public_datasets/my-test-bucket-768/data.csv.gz から先頭2行を選択する例です。圧縮方式は .gz ファイル拡張子から自動的に検出されます:

SELECT *
FROM gcs('https://storage.googleapis.com/clickhouse_public_datasets/my-test-bucket-768/data.csv.gz', '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 を持つ複数のファイルがあるとします。

末尾の数字が 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', 'column1 UInt32, column2 UInt32, column3 UInt32')

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

これら2つのディレクトリ内のすべてのファイルに含まれる行数の合計を数えます:

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

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

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;

Glob ** は、ディレクトリを再帰的にたどるために使用できます。以下の例では、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');

本番環境で利用する場合は、named collectionsの使用を推奨します。以下はその例です。


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 式を指定すると、パーティション値ごとに個別のファイルが作成されます。データをファイルごとに分割することで、読み取り処理の効率向上につながります。

{_partition_id} を含むパスでは wildcard パーティション方式が使用されるため、以下の例の partition_strategy='wildcard' の明示的な指定は省略可能です。別の glob を含むパスではパーティション方式は使用されず、PARTITION BY は無視されます。glob を含まないパスでは、file_like_engine_default_partition_strategy が hive の場合は hive が使用され、それ以外の場合はパーティション方式は使用されません。

例

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

INSERT INTO TABLE FUNCTION
    gcs('http://bucket.amazonaws.com/my_bucket/file_{_partition_id}.csv', 'CSV', 'a String, b UInt32, c UInt32', partition_strategy='wildcard')
    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つのファイルに書き込まれます。

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

INSERT INTO TABLE FUNCTION
    gcs('http://bucket.amazonaws.com/my_bucket_{_partition_id}/file.csv', 'CSV', 'a UInt32, b UInt32, c UInt32', partition_strategy='wildcard')
    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 という3つのファイルに書き込まれます。

構文

引数

戻り値

例

使用例

パーティション単位での書き込み

関連