> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> 提供类似表的接口，可对 Google Cloud Storage 中的数据执行 `SELECT` 和 `INSERT`。需要 `Storage Object User` IAM role。
# gcs
提供类似表的接口，可对 [Google Cloud Storage](https://cloud.google.com/storage/) 中的数据执行 `SELECT` 和 `INSERT`。需要 [`Storage Object User` IAM role](https://cloud.google.com/storage/docs/access-control/iam-roles)。
这是 [s3 表函数](/zh/reference/functions/table-functions/s3) 的别名。
如果你的集群中有多个副本，可以改用 [s3Cluster 函数](/zh/reference/functions/table-functions/s3Cluster) (可与 GCS 配合使用) 来并行执行插入操作。
## 语法
```sql theme={null}
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 互操作性文档](https://cloud.google.com/storage/docs/interoperability)。
## 参数
| 参数 | 描述 |
| ---------------------------- | --------------------------------------------------------------------------------------------------- |
| `url` | 指向文件的存储桶路径。在只读模式下支持以下通配符：`*`、`**`、`?`、`{abc,def}` 和 `{N..M}`，其中 `N`、`M` 表示数字，`'abc'`、`'def'` 表示字符串。 |
| `NOSIGN` | 如果提供此关键字来代替认证凭据，则所有请求都不会被签名。 |
| `hmac_key` and `hmac_secret` | 用于指定给定端点所使用认证凭据的键。可选。 |
| `format` | 文件的[格式](/zh/reference/formats)。 |
| `structure` | 表的结构。格式为 `'column1_name column1_type, column2_name column2_type, ...'`。 |
| `compression_method` | 此参数可选。支持的值有：`none`、`gzip` 或 `gz`、`brotli` 或 `br`、`xz` 或 `LZMA`、`zstd` 或 `zst`。默认会根据文件扩展名自动检测压缩方法。 |
**GCS**
GCS 路径格式如下，因为 Google XML API 的端点与 JSON API 不同：
```text theme={null}
https://storage.googleapis.com///
```
而不是 \~\~[https://storage.cloud.google.com\~\~。](https://storage.cloud.google.com~~。)
参数也可以通过[命名集合](/zh/concepts/features/configuration/server-config/named-collections)传递。在这种情况下，`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` 对应的表中选取前两行：
```sql theme={null}
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;
```
```text theme={null}
┌─column1─┬─column2─┬─column3─┐
│ 1 │ 2 │ 3 │
│ 3 │ 2 │ 1 │
└─────────┴─────────┴─────────┘
```
类似，不过是来自使用 `gzip` 压缩方法的文件：
```sql theme={null}
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;
```
```text theme={null}
┌─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\_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\_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\_3.csv\');
* '[https://storage.googleapis.com/my-test-bucket-768/some\_prefix/some\_file\_4.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\_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\_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\_3.csv\');
* '[https://storage.googleapis.com/my-test-bucket-768/another\_prefix/some\_file\_4.csv\'](https://storage.googleapis.com/my-test-bucket-768/another\_prefix/some\_file\_4.csv\');
统计文件名以 1 到 3 结尾的文件中的行数：
```sql theme={null}
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')
```
```text theme={null}
┌─count()─┐
│ 18 │
└─────────┘
```
统计这两个目录中所有文件的总行数：
```sql theme={null}
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')
```
```text theme={null}
┌─count()─┐
│ 24 │
└─────────┘
```
如果文件列表中包含带前导零的数字范围，请对每一位数字分别使用花括号，或使用 `?`。
统计名为 `file-000.csv`、`file-001.csv`、...、`file-999.csv` 的文件中的总行数：
```sql theme={null}
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');
```
```text theme={null}
┌─count()─┐
│ 12 │
└─────────┘
```
向文件 `test-data.csv.gz` 中插入数据：
```sql theme={null}
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`：
```sql theme={null}
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` 目录中递归拉取所有文件：
```sql theme={null}
SELECT * FROM gcs('https://storage.googleapis.com/my-test-bucket-768/**', 'CSV', 'name String, value UInt32', 'gzip');
```
以下内容会递归地从 `my-test-bucket` 目录下任意文件夹中的所有 `test-data.csv.gz` 文件获取数据：
```sql theme={null}
SELECT * FROM gcs('https://storage.googleapis.com/my-test-bucket-768/**/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip');
```
对于生产环境，建议使用[命名集合](/zh/concepts/features/configuration/server-config/named-collections)。示例如下：
```sql theme={null}
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. 在 key 中使用分区 ID 会创建单独的文件：
```sql theme={null}
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`。
2. 在 存储桶 名称中使用分区 ID，会在不同的 存储桶 中创建文件：
```sql theme={null}
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);
```
因此，数据会被写入不同存储桶中的三个文件：`my_bucket_1/file.csv`、`my_bucket_10/file.csv` 和 `my_bucket_20/file.csv`。
## 相关
* [S3 表函数](/zh/reference/functions/table-functions/s3)
* [S3 引擎](/zh/reference/engines/table-engines/integrations/s3)