> ## 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](/ru/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`                                   | Путь к файлу или набору файлов. В режиме только для чтения поддерживаются следующие подстановочные шаблоны: `*`, `**`, `?`, `{'abc','def'}` и `{N..M}`, где `N`, `M` — числа, `abc`, `def` — строки. Подробнее см. в разделе [Wildcards In Path](/ru/reference/engines/table-engines/integrations/s3#wildcards-in-path). |
| `NOSIGN`                                | Если указать это ключевое слово вместо учётных данных, все запросы будут отправляться без подписи.                                                                                                                                                                                                                       |
| `access_key_id` and `secret_access_key` | Ключи, задающие учётные данные для использования с указанной конечной точкой. Необязательны.                                                                                                                                                                                                                             |
| `session_token`                         | Токен сеанса для использования с указанными ключами. Необязателен при передаче ключей.                                                                                                                                                                                                                                   |
| `format`                                | [Формат](/ru/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')`. Пример использования см. [здесь](/ru/reference/functions/table-functions/s3#accessing-requester-pays-buckets).                               |
| `extra_credentials`                     | Необязательный параметр. Через него можно передать `roleARN`. Пример см. [здесь](/ru/products/cloud/guides/data-sources/accessing-s3-data-securely#access-your-s3-bucket-with-the-clickhouseaccess-role).                                                                                                                |

Аргументы также можно передавать с помощью [именованных коллекций](/ru/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>

Выберите данные из всех файлов в каталогах `/root/data/clickhouse` и `/root/data/database/`, используя все узлы кластера `cluster_simple`:

```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>

Для использования в production-среде рекомендуется использовать [именованные коллекции](/ru/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>

Пользователи могут использовать те же подходы, что описаны в документации по функции `s3` [здесь](/ru/reference/functions/table-functions/s3#accessing-public-buckets).

<div id="optimizing-performance">
  ## Оптимизация производительности
</div>

Подробнее об оптимизации производительности функции s3 см. в [нашем подробном руководстве](/ru/integrations/connectors/data-ingestion/AWS/performance).

<div id="related">
  ## См. также
</div>

* [Движок S3](/ru/reference/engines/table-engines/integrations/s3)
* [табличная функция S3](/ru/reference/functions/table-functions/s3)