Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

s3Cluster

View as MarkdownEdit this pageReport an issueSet up docs MCP

Это расширение табличной функции 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:

Для использования в production-среде рекомендуется использовать именованные коллекции. Вот пример:


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 см. в нашем подробном руководстве.

Navigation