> ## 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.

> 对 s3 表函数的扩展，允许在指定集群中由多个节点并行处理来自 Amazon S3 和 Google Cloud Storage 的文件。

# s3Cluster

这是对 [s3](/zh/reference/functions/table-functions/s3) 表函数的扩展。

它允许在指定集群中由多个节点并行处理来自 [Amazon S3](https://aws.amazon.com/s3/) 和 Google Cloud Storage [Google Cloud Storage](https://cloud.google.com/storage/) 的文件。在发起节点上，它会与集群中的所有节点建立连接，展开 S3 文件路径中的星号，并动态分发每个文件。在工作节点上，它会向发起节点请求下一个要处理的任务并执行处理。此过程会不断重复，直到所有任务都完成。

<div id="syntax">
  ## 语法
</div>

```sql theme={null}
s3Cluster(cluster_name, url[, NOSIGN | access_key_id, secret_access_key,[session_token]][, format][, structure][, compression_method][, headers][, extra_credentials])
s3Cluster(cluster_name, named_collection[, option=value [,..]])
```

<div id="arguments">
  ## 参数
</div>

| 参数                                      | 描述                                                                                                                                                                                                 |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cluster_name`                          | 用于构建远程和本地服务器地址集合及连接参数的集群名称。                                                                                                                                                                        |
| `url`                                   | 文件或一组文件的路径。在只读模式下支持以下 wildcards：`*`、`**`、`?`、`{'abc','def'}` 和 `{N..M}`，其中 `N`、`M` 表示数字，`abc`、`def` 表示字符串。更多信息请参见[路径中的通配符](/zh/reference/engines/table-engines/integrations/s3#wildcards-in-path)。 |
| `NOSIGN`                                | 如果用此关键字代替 credentials，则所有请求都不会被签名。                                                                                                                                                                 |
| `access_key_id` and `secret_access_key` | 用于指定在给定端点上使用的 credentials 的 key。可选。                                                                                                                                                                |
| `session_token`                         | 与给定 keys 一起使用的 session 标记。传递 keys 时可选。                                                                                                                                                             |
| `format`                                | 文件的 [format](/zh/reference/formats)。                                                                                                                                                               |
| `structure`                             | 表的结构。格式为 `'column1_name column1_type, column2_name column2_type, ...'`。                                                                                                                            |
| `compression_method`                    | 此参数为可选。支持的值：`none`、`gzip` 或 `gz`、`brotli` 或 `br`、`xz` 或 `LZMA`、`zstd` 或 `zst`。默认情况下，会根据文件扩展名自动检测压缩方法。                                                                                              |
| `headers`                               | 此参数为可选。允许在 S3 请求中传递请求头。请按 `headers(key=value)` 格式传递，例如 `headers('x-amz-request-payer' = 'requester')`。有关用法示例，请参见[此处](/zh/reference/functions/table-functions/s3#accessing-requester-pays-buckets)。 |
| `extra_credentials`                     | 可选。可通过此参数传递 `roleARN`。示例请参见[此处](/zh/products/cloud/guides/data-sources/accessing-s3-data-securely#access-your-s3-bucket-with-the-clickhouseaccess-role)。                                           |

参数也可以通过 [命名集合](/zh/concepts/features/configuration/server-config/named-collections) 传递。在这种情况下，`url`、`access_key_id`、`secret_access_key`、`format`、`structure`、`compression_method` 的用法相同，并且还支持一些额外参数：

| 参数                            | 描述                                                                                                                                                                  |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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。                                                                                                                                                           |

<div id="returned_value">
  ## 返回值
</div>

一个具有指定结构的表，用于读取或写入指定文件中的数据。

<div id="examples">
  ## 示例
</div>

使用 `cluster_simple` 集群中的所有节点，查询 `/root/data/clickhouse` 和 `/root/data/database/` 文件夹中所有文件的数据：

```sql theme={null}
SELECT * FROM s3Cluster(
    'cluster_simple',
    'http://minio1:9001/root/data/{clickhouse,database}/*',
    'minio',
    'ClickHouse_Minio_P@ssw0rd',
    'CSV',
    'name String, value UInt32, polygon Array(Array(Tuple(Float64, Float64)))'
) ORDER BY (name, value, polygon);
```

统计集群 `cluster_simple` 中所有文件的总行数：

<Tip>
  如果文件列表中包含带前导零的数字范围，请对每一位分别使用花括号写法，或使用 `?`。
</Tip>

对于生产环境，建议使用 [命名集合](/zh/concepts/features/configuration/server-config/named-collections)。示例如下：

```sql theme={null}

CREATE NAMED COLLECTION creds AS
        access_key_id = 'minio',
        secret_access_key = 'ClickHouse_Minio_P@ssw0rd';
SELECT count(*) FROM s3Cluster(
    'cluster_simple', creds, url='https://s3-object-url.csv',
    format='CSV', structure='name String, value UInt32, polygon Array(Array(Tuple(Float64, Float64)))'
)
```

<div id="accessing-private-and-public-buckets">
  ## 访问私有和公共存储桶
</div>

用户可以采用与[此处](/zh/reference/functions/table-functions/s3#accessing-public-buckets)文档中 `s3` 函数相同的访问方式。

<div id="optimizing-performance">
  ## 优化性能
</div>

有关如何优化 s3 函数性能的详细信息，请参阅[详细指南](/zh/integrations/connectors/data-ingestion/AWS/performance)。

<div id="related">
  ## 相关
</div>

* [S3 引擎](/zh/reference/engines/table-engines/integrations/s3)
* [s3 表函数](/zh/reference/functions/table-functions/s3)