Это расширение табличной функции s3.
Позволяет параллельно обрабатывать файлы из Amazon S3 и Google Cloud Storage Google Cloud Storage на множестве узлов в указанном кластере. На узле-инициаторе создаётся соединение со всеми узлами кластера, раскрываются звёздочки в пути к файлам S3, после чего каждый файл динамически распределяется. На узле-воркере запрашивается у инициатора следующая задача для обработки, и она обрабатывается. Это повторяется, пока не будут завершены все задачи.
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 [,..]])
| Аргумент | Описание |
|---|
cluster_name | Имя кластера, используемого для построения набора адресов и параметров подключения к удалённым и локальным серверам. |
url | Путь к файлу или набору файлов. В режиме только для чтения поддерживаются следующие подстановочные шаблоны: *, **, ?, {'abc','def'} и {N..M}, где N, M — числа, abc, def — строки. Подробнее см. в разделе Wildcards In Path. |
NOSIGN | Если указать это ключевое слово вместо учётных данных, все запросы будут отправляться без подписи. |
access_key_id and secret_access_key | Ключи, задающие учётные данные для использования с указанной конечной точкой. Необязательны. |
session_token | Токен сеанса для использования с указанными ключами. Необязателен при передаче ключей. |
format | Формат файла. |
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'). Пример использования см. здесь. |
extra_credentials | Необязательный параметр. Через него можно передать roleARN. Пример см. здесь. |
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. |
/root/data/clickhouse и /root/data/database/, используя все узлы кластера cluster_simple:
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:
Если список файлов содержит диапазоны чисел с ведущими нулями, используйте конструкцию с фигурными скобками для каждой цифры отдельно или символ ?.
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)))'
)
Доступ к приватным и публичным бакетам
s3 здесь.
Подробнее об оптимизации производительности функции s3 см. в нашем подробном руководстве.
Последнее изменение 10 июня 2026 г.
