S3Queue Engine

S3Queue Engine решает задачу непрерывной потоковой загрузки файлов из S3-prefix в ClickHouse. В отличие от s3() table function (одноразовое чтение) или S3 engine (ручные запросы), S3Queue автоматически отслеживает новые файлы в S3-prefix и загружает их последовательно — файл за файлом, без ручного вмешательства.

Механизм работы

S3Queue работает аналогично Kafka Engine: ClickHouse периодически сканирует S3-prefix, находит новые (необработанные) файлы и читает их.

Отслеживание обработанных файлов через Keeper:

• Каждый обработанный файл записывается в Keeper (путь: /clickhouse/s3queue/{table_uuid}/)
• При следующем сканировании уже обработанные файлы пропускаются
• Keeper — единственный источник правды о состоянии обработки

Паттерн с Materialized View

Как и Kafka Engine, S3Queue используется в паттерне с Materialized View:

-- Шаг 1: Target MergeTree таблица
CREATE TABLE events_local
(
    event_time DateTime,
    user_id    UInt64,
    event_type LowCardinality(String),
    payload    String
)
ENGINE = MergeTree
ORDER BY (event_type, user_id, event_time);

-- Шаг 2: S3Queue Engine — streaming cursor над S3-prefix
CREATE TABLE events_s3queue
(
    event_time DateTime,
    user_id    UInt64,
    event_type String,
    payload    String
)
ENGINE = S3Queue(
    'http://minio:9000/clickhouse-data/events/*.parquet',
    'minioadmin',
    'minioadmin123',
    'Parquet'
)
SETTINGS
    s3queue_loading_retries = 3;

-- Шаг 3: Materialized View — автоматический перенос в target
CREATE MATERIALIZED VIEW events_s3queue_mv TO events_local AS
SELECT event_time, user_id, event_type, payload
FROM events_s3queue;

После создания MV ClickHouse начинает сканировать S3-prefix и загружать файлы автоматически в фоновом режиме.

Настройка для multi-replica среды

В multi-replica setup (несколько реплик ClickHouse читают из одного S3-prefix) каждая реплика независимо видит S3-объекты. Без дополнительной настройки один файл может быть обработан несколькими репликами одновременно — это приведёт к дублям.

-- use_persistent_processing_nodes=1 обязателен в multi-replica
CREATE TABLE events_s3queue
(...)
ENGINE = S3Queue(
    'http://minio:9000/clickhouse-data/events/*.parquet',
    'minioadmin',
    'minioadmin123',
    'Parquet'
)
SETTINGS
    use_persistent_processing_nodes = 1,   -- 26.3 LTS: координация через Keeper
    s3queue_loading_retries = 3;

С use_persistent_processing_nodes=1 (доступно в 26.3 LTS) обработка файлов координируется через Keeper: файл назначается одной реплике и другие его не трогают.

S3Queue vs s3() Table Function: ключевые различия

-- s3() function: читает ВСЕ matching файлы каждый раз
SELECT * FROM s3('http://minio:9000/bucket/events/*.parquet', ...);

-- S3Queue: читает только НОВЫЕ файлы, пропускает обработанные
-- (работает через Keeper, координирует multi-replica)
SELECT * FROM events_s3queue;  -- обычно не нужен напрямую — используется через MV

Мониторинг

-- Состояние S3Queue processing
SELECT *
FROM system.s3queue
WHERE database = 'default'
ORDER BY event_time DESC;

-- Файлы в очереди обработки
SELECT file_name, status, rows_processed
FROM system.s3queue_log
WHERE table = 'events_s3queue'
ORDER BY event_time DESC
LIMIT 20;

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

1. S3Queue Engine — потоковый загрузчик файлов из S3-prefix: автоматически отслеживает новые файлы и загружает их без ручного вмешательства.
2. Отслеживание обработанных файлов ведётся через Keeper — именно поэтому S3Queue требует Keeper в production.
3. Паттерн с Materialized View: S3Queue table (cursor) + MV (автоматический перенос) + MergeTree target (хранилище).
4. В multi-replica setup обязателен use_persistent_processing_nodes=1 (26.3 LTS) — иначе один файл будет обработан несколькими репликами, создавая дубли.
5. S3Queue — для непрерывного streaming. s3() function — для одноразового batch-чтения. Это разные инструменты для разных задач.