S3: Table Function, Engine и Named Collections

S3 — универсальный источник и приёмник данных для ClickHouse. Читать Parquet-файлы из S3 bucket, писать результаты запросов обратно в S3, строить persistent таблицы поверх объектного хранилища — всё это доступно через три встроенных механизма: s3() table function, S3 engine и Named Collections.

s3() Table Function: ad-hoc запросы

s3() table function позволяет выполнять ad-hoc запросы к S3 объектам без создания постоянных таблиц. Функция ведёт себя как обычная таблица в контексте SELECT/INSERT:

-- Простой SELECT из одного файла
SELECT count()
FROM s3(
    'http://minio:9000/clickhouse-cold/events/2026-01.parquet',
    'minioadmin',
    'minioadmin123',
    'Parquet'
);

-- Glob pattern: читать все Parquet-файлы из prefix
SELECT user_id, event_type, count() AS cnt
FROM s3(
    'http://minio:9000/clickhouse-cold/events/*.parquet',
    'minioadmin',
    'minioadmin123',
    'Parquet'
)
GROUP BY user_id, event_type
ORDER BY cnt DESC
LIMIT 10;

Glob pattern *.parquet работает на уровне имён объектов в S3 bucket. Это удобно для чтения partitioned данных (например, events/2026-01/*.parquet, events/2026-02/*.parquet).

Поддерживаемые форматы

ClickHouse поддерживает чтение и запись S3-объектов в нативных форматах аналитических данных:

-- INSERT в S3 в формате Parquet
INSERT INTO FUNCTION s3(
    'http://minio:9000/clickhouse-cold/export/2026-01.parquet',
    'minioadmin', 'minioadmin123',
    'Parquet'
)
SELECT * FROM events WHERE toYYYYMM(event_time) = 202601;

S3 Engine: постоянные таблицы над S3

Если нужно обращаться к одному S3-пути многократно, создайте постоянную таблицу на основе S3 Engine:

-- S3 Engine: таблица над S3-prefix (все Parquet в папке)
CREATE TABLE events_archive
ENGINE = S3(
    'http://minio:9000/clickhouse-cold/events/*.parquet',
    'minioadmin',
    'minioadmin123',
    'Parquet'
);

-- Теперь можно делать обычные SELECT без повторения credentials
SELECT count() FROM events_archive WHERE event_type = 'purchase';

Разница между s3() function и S3 engine:

• s3() function — однократный запрос, credentials в каждом вызове
• S3 engine — постоянная таблица, credentials хранятся в DDL

Named Collections: централизованное управление credentials

Хранить credentials (access key, secret) в каждом SQL-запросе или DDL — плохая практика: credentials появляются в query log, трудно обновить при ротации ключей.

Named Collections решают эту проблему: credentials хранятся централизованно с контролем доступа через RBAC.

Создание Named Collection

-- Создать Named Collection для MinIO
CREATE NAMED COLLECTION minio_cold
    ACCESS MANAGEMENT 1
AS
    url = 'http://minio:9000/clickhouse-cold/',
    access_key_id = 'minioadmin',
    secret_access_key = 'minioadmin123';

Использование Named Collection

-- s3() function с Named Collection — credentials скрыты
SELECT count()
FROM s3(minio_cold, filename = 'events/*.parquet', format = 'Parquet');

-- S3 engine с Named Collection
CREATE TABLE events_archive
ENGINE = S3(minio_cold, filename = 'events/*.parquet', format = 'Parquet');

MinIO и path-style URL

MinIO и другие S3-совместимые хранилища требуют специальной настройки для path-style доступа:

-- use_path_style_url=1 обязателен для MinIO и S3-compatible storage
SELECT count()
FROM s3(
    'http://minio:9000/clickhouse-cold/events/*.parquet',
    'minioadmin',
    'minioadmin123',
    'Parquet',
    SETTINGS use_path_style_url = 1
);

По умолчанию ClickHouse использует virtual-hosted style (bucket.endpoint/key), что несовместимо с MinIO. Параметр use_path_style_url=1 переключает на path-style (endpoint/bucket/key).

Сравнение подходов

Ключевые выводы

1. s3() table function — ad-hoc запросы к S3 с glob pattern для чтения нескольких файлов.
2. S3 engine — постоянная таблица над S3-путём, credentials хранятся в DDL.
3. Named Collections — централизованное хранение credentials с RBAC; credentials не появляются в query log при ротации достаточно обновить одну запись.
4. use_path_style_url=1 обязателен для MinIO и S3-compatible хранилищ.
5. Поддерживаемые форматы: Parquet, ORC, Arrow, Avro, CSV, JSONEachRow — выбирайте Parquet для аналитических нагрузок (колоночный, сжатый, широко поддерживаемый).