Интеграция Amazon S3 с ClickHouse Cloud

S3 ClickPipe обеспечивает полностью управляемый и отказоустойчивый приём данных из Amazon S3 и S3-совместимых объектных хранилищ в ClickHouse Cloud. Он поддерживает как разовую ингестию, так и непрерывную ингестию с семантикой «ровно один раз».

S3 ClickPipes можно вручную развёртывать и настраивать через интерфейс ClickPipes, а также программно с помощью OpenAPI и Terraform.

Поддерживаемые источники данных

Название	Логотип	Подробности
Amazon S3		Для непрерывной ингестии по умолчанию требуется лексикографический порядок, но её можно настроить на приём файлов в любом порядке.
Cloudflare R2 S3-совместимый		Для непрерывной ингестии требуется лексикографический порядок. Неупорядоченный режим не поддерживается.
DigitalOcean Spaces S3-совместимый		Для непрерывной ингестии требуется лексикографический порядок. Неупорядоченный режим не поддерживается.
OVH Object Storage S3-совместимый		Для непрерывной ингестии требуется лексикографический порядок. Неупорядоченный режим не поддерживается.

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

Возможности

Одноразовая ингестия

По умолчанию S3 ClickPipe загружает все файлы из указанного бакета, соответствующие шаблону регулярного выражения, в целевую таблицу ClickHouse одним батчем. После завершения задачи ингестии ClickPipe автоматически останавливается. Этот режим одноразовой ингестии обеспечивает семантику «ровно один раз», гарантируя надёжную обработку каждого файла без дубликатов.

Непрерывная ингестия

Когда непрерывная ингестия включена, ClickPipes непрерывно принимает данные по указанному пути. Для определения порядка ингестии S3 ClickPipe по умолчанию опирается на неявный лексикографический порядок файлов. S3 ClickPipe также можно настроить на прием файлов в любом порядке с помощью очереди Amazon SQS, подключенной к бакету.

Лексикографический порядок

По умолчанию S3 ClickPipe предполагает, что файлы добавляются в бакет в лексикографическом порядке, и использует этот неявный порядок для последовательной обработки файлов. Это означает, что любой новый файл должен быть лексикографически больше последнего обработанного файла. Например, файлы с именами file1, file2 и file3 будут обработаны последовательно, но если в бакет будет добавлен новый file 0, он будет проигнорирован, поскольку имя этого файла не лексикографически больше имени последнего обработанного файла.

В этом режиме S3 ClickPipe выполняет начальную загрузку всех файлов по указанному пути, а затем с настраиваемым интервалом проверяет наличие новых файлов (по умолчанию каждые 30 секунд). Чтобы начать непрерывную ингестию после определённого файла, настройте Start after. ClickPipes пропустит файлы, лексикографически меньшие или равные заданному значению, и продолжит загружать более новые файлы начиная с него.

В любом порядке

Можно настроить S3 ClickPipe для приёма файлов, у которых нет естественного порядка, создав очередь Amazon SQS, подключённую к бакету, и при необходимости используя Amazon EventBridge как маршрутизатор событий. Это позволяет ClickPipes отслеживать события создания объектов и принимать новые файлы независимо от схемы их именования.

В этом режиме S3 ClickPipe выполняет начальную загрузку всех файлов по выбранному пути, а затем отслеживает в очереди события ObjectCreated:*, соответствующие указанному пути. Любое сообщение о файле, который уже был обработан, о файле, не соответствующем пути, или о событии другого типа будет игнорироваться. Чтобы принимать только файлы, доставленные через очередь, включите Skip initial load. При включении этого параметра ClickPipes пропускает первоначальное сканирование существующих файлов по выбранному пути и обрабатывает только файлы, доставленные через очередь SQS.

Ингестия файлов начинается при достижении порога, заданного в max insert bytes или max file count, либо по истечении настраиваемого интервала (по умолчанию 30 секунд). Если настроена DLQ, сообщения с ошибками будут повторно помещаться в очередь и обрабатываться заново до числа раз, заданного в параметре DLQ maxReceiveCount.

EventBridge в SQS

Также можно отправлять уведомления о событиях S3 в SQS через Amazon EventBridge. Это рекомендуемый подход для большинства сценариев, поскольку EventBridge поддерживает более гибкую фильтрацию событий, рассылку в несколько целевых систем и не имеет ограничения S3, допускающего только одно правило уведомлений для каждого типа события на каждый префикс. Пошаговые инструкции см. в разделе Настройка неупорядоченного режима для непрерывной ингестии.

Также можно отправлять уведомления о событиях S3 в SQS через topic SNS. Это может пригодиться, если вы столкнулись с ограничениями прямой интеграции S3 → SQS. В этом случае нужно включить опцию доставки сообщений в исходном формате.

Сопоставление имён файлов с шаблоном

ClickPipes для объектного хранилища используют стандарт POSIX для сопоставления имён файлов с шаблоном. Все шаблоны учитывают регистр и должны соответствовать полному пути после имени бакета. Для повышения производительности используйте как можно более конкретный шаблон (например, data-2024-*.csv вместо *.csv).

Поддерживаемые шаблоны

Шаблон	Описание	Пример	Совпадения
`?`	Соответствует ровно одному символу (кроме `/`)	`data-?.csv`	`data-1.csv`, `data-a.csv`, `data-x.csv`
`*`	Соответствует нулю, одному или нескольким символам (кроме `/`)	`data-*.csv`	`data-1.csv`, `data-001.csv`, `data-report.csv`, `data-.csv`
`**` Рекурсивно	Соответствует нулю, одному или нескольким символам (включая `/`). Поддерживает рекурсивный обход каталогов.	`logs/**/error.log`	`logs/error.log`, `logs/2024/error.log`, `logs/2024/01/error.log`

Примеры:

https://bucket.s3.amazonaws.com/folder/*.csv
https://bucket.s3.amazonaws.com/logs/**/data.json
https://bucket.s3.amazonaws.com/file-?.parquet
https://bucket.s3.amazonaws.com/data-2024-*.csv.gz

Неподдерживаемые шаблоны

Шаблон	Описание	Пример	Альтернативы
`{abc,def}`	Расширение фигурных скобок.	`{logs,data}/file.csv`	Создайте отдельные ClickPipes для каждого пути.
`{N..M}`	Расширение числового диапазона	`file-{1..100}.csv`	Используйте `file-*.csv` или `file-?.csv`.

Примеры:

https://bucket.s3.amazonaws.com/{documents-01,documents-02}.json
https://bucket.s3.amazonaws.com/file-{1..100}.csv
https://bucket.s3.amazonaws.com/{logs,metrics}/data.parquet

Семантика «ровно один раз»

При приёме больших наборов данных возможны различные сбои, которые могут приводить к частичным вставкам или дублированию данных. ClickPipes для объектного хранилища устойчивы к сбоям при вставке и обеспечивают семантику «ровно один раз». Это достигается за счёт использования временных staging-таблиц. Сначала данные вставляются в staging-таблицы. Если во время этой вставки что-то пойдёт не так, staging-таблицу можно очистить с помощью TRUNCATE, а затем повторить вставку из чистого состояния. Только после того, как вставка успешно завершена, партиции из staging-таблицы перемещаются в целевую таблицу. Подробнее об этой стратегии читайте в этой статье блога.

Виртуальные столбцы

Чтобы отслеживать, какие файлы были приняты, добавьте виртуальный столбец _file в список сопоставления столбцов. Виртуальный столбец _file содержит имя файла объекта-источника, которое можно использовать в запросах, чтобы определить, какие файлы были обработаны.

Управление доступом

Разрешения

ClickPipe для S3 поддерживает публичные и приватные бакеты. Бакеты Requester Pays не поддерживаются.

S3 бакет

В политике бакета должны быть разрешены следующие действия:

Очередь SQS

При использовании неупорядоченного режима в политике очереди SQS должны быть разрешены следующие действия:

Аутентификация

Учетные данные IAM

Чтобы использовать ключи доступа для аутентификации, при настройке подключения ClickPipe выберите Credentials в поле Authentication method. Затем введите идентификатор ключа доступа (например, AKIAIOSFODNN7EXAMPLE) и секретный ключ доступа (например, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY) в полях Access key и Secret key соответственно.

роль IAM

Чтобы использовать доступ на основе ролей для аутентификации, выберите IAM role в поле Authentication method при настройке подключения ClickPipe.

Аутентификация через IAM для S3 ClickPipes

Следуйте этому руководству, чтобы создать роль с необходимой политикой доверия для доступа к S3. Затем укажите ARN роли IAM в поле IAM role ARN.

Сетевой доступ

S3 ClickPipes используют два разных сетевых пути: один — для обнаружения метаданных, другой — для ингестии данных; их обеспечивают соответственно сервис ClickPipes и сервис ClickHouse Cloud. Если вы хотите настроить дополнительный уровень сетевой безопасности (например, по соображениям compliance), сетевой доступ необходимо настроить для обоих путей.

Для управления доступом на основе IP-адресов политика S3 бакета должна разрешать статические IP-адреса региона сервиса ClickPipes, перечисленные здесь, а также статические IP-адреса сервиса ClickHouse Cloud. Чтобы получить статические IP-адреса для вашего региона ClickHouse Cloud, откройте терминал и выполните:
```
# Замените <your-region> на ваш регион ClickHouse Cloud
curl -s https://api.clickhouse.cloud/static-ips.json | jq -r '.aws[] | select(.region == "<your-region>") | .egress_ips[]'
```
Для управления доступом на основе VPC endpoint S3 бакет должен находиться в том же регионе, что и сервис ClickHouse Cloud, а операции GetObject должны быть ограничены Endpoint ID VPC endpoint сервиса ClickHouse Cloud. Чтобы получить VPC endpoint для вашего региона ClickHouse Cloud, откройте терминал и выполните:
```
# Замените <your-region> на ваш регион ClickHouse Cloud
curl -s https://api.clickhouse.cloud/static-ips.json | jq -r '.aws[] | select(.region == "<your-region>") | .s3_endpoints[]'
```

Расширенные настройки

ClickPipes предоставляет оптимальные настройки по умолчанию, которые покрывают требования большинства сценариев использования. Если вашему сценарию требуется более тонкая настройка, вы можете изменить следующие параметры:

Параметр	Значение по умолчанию	Описание
`Max insert bytes`	10GB	Количество байтов, обрабатываемых в одном батче вставки.
`Max file count`	100	Максимальное количество файлов, обрабатываемых в одном батче вставки.
`Max threads`	auto(3)	Максимальное количество параллельных потоков для обработки файлов.
`Max insert threads`	1	Максимальное количество параллельных потоков вставки для обработки файлов.
`Min insert block size bytes`	1GB	Минимальный размер блока в байтах, который может быть вставлен в таблицу.
`Max download threads`	4	Максимальное количество параллельных потоков загрузки.
`Object storage polling interval`	30s	Задаёт максимальный период ожидания перед вставкой данных в кластер ClickHouse.
`Start after`	None	Для упорядоченной непрерывной ингестии пропускает файлы, лексикографически меньшие или равные указанному имени файла или пути.
`Skip initial load`	false	Для неупорядоченной непрерывной ингестии пропускает начальное сканирование существующих файлов и обрабатывает только уведомления об объектах из настроенной очереди SQS.
`Parallel distributed insert select`	2	Настройка parallel distributed insert select.
`Parallel view processing`	false	Включать ли отправку в присоединённые представления параллельно, а не последовательно.
`Use cluster function`	true	Нужно ли обрабатывать файлы параллельно на нескольких узлах.

Масштабирование

ClickPipes для объектного хранилища масштабируются исходя из минимального размера сервиса ClickHouse, определяемого настроенными параметрами вертикального автомасштабирования. Размер ClickPipe определяется при создании пайпа. Последующие изменения настроек сервиса ClickHouse не повлияют на размер ClickPipe.

Чтобы повысить пропускную способность при больших объёмах приёма данных, мы рекомендуем масштабировать сервис ClickHouse до создания ClickPipe.

Известные ограничения

Размер файла

ClickPipes будет пытаться принимать только объекты размером 10 ГБ или меньше. Если размер файла превышает 10 ГБ, в специальную таблицу ошибок ClickPipes будет добавлена запись об ошибке.

Совместимость

Хотя некоторые сервисы совместимы с S3, они используют другую структуру URL, которую S3 ClickPipe может не суметь разобрать (например, Backblaze B2), либо требуют интеграции со специфичными для провайдера службами очередей для непрерывной неупорядоченной ингестии. Если у вас возникают проблемы с сервисом, которого нет в разделе Поддерживаемые источники данных, пожалуйста, свяжитесь с нашей командой.

Поддержка представлений

Также поддерживаются materialized view для целевой таблицы. ClickPipes создает staging-таблицы не только для целевой таблицы, но и для всех зависимых materialized view.

Мы не создаем staging-таблицы для нематериализованных представлений. Это означает, что если у вас есть целевая таблица с одной или несколькими зависимыми materialized view, эти materialized view не должны выбирать данные через представление от целевой таблицы. В противном случае в materialized view могут отсутствовать данные.