S3 ClickPipe обеспечивает полностью управляемый и отказоустойчивый приём данных из Amazon S3 и S3-совместимых объектных хранилищ в ClickHouse Cloud. Он поддерживает как разовую ингестию, так и непрерывную ингестию с семантикой «ровно один раз».
S3 ClickPipes можно вручную развёртывать и настраивать через интерфейс ClickPipes, а также программно с помощью OpenAPI и Terraform.
Поддерживаемые источники данных
| Название | Логотип | Подробности |
|---|
| Amazon S3 |  | Для непрерывной ингестии по умолчанию требуется лексикографический порядок, но её можно настроить на приём файлов в любом порядке. |
Cloudflare R2
S3-compatible |  | Для непрерывной ингестии требуется лексикографический порядок. Неупорядоченный режим не поддерживается. |
DigitalOcean Spaces
S3-compatible |  | Для непрерывной ингестии требуется лексикографический порядок. Неупорядоченный режим не поддерживается. |
OVH Object Storage
S3-compatible |  | Для непрерывной ингестии требуется лексикографический порядок. Неупорядоченный режим не поддерживается. |
Из-за различий в форматах URL и реализациях API у разных провайдеров Объектного хранилища не все S3-compatible сервисы поддерживаются без дополнительной настройки. Если у вас возникают проблемы с сервисом, которого нет в списке выше, свяжитесь с нашей командой. Лексикографический порядок
file1, file2 и file3 будут обработаны последовательно, но если в бакет будет добавлен новый file 0, он будет проигнорирован, поскольку имя этого файла не лексикографически больше имени последнего обработанного файла.
В этом режиме S3 ClickPipe выполняет начальную загрузку всех файлов по указанному пути, а затем с настраиваемым интервалом проверяет наличие новых файлов (по умолчанию каждые 30 секунд). Невозможно начать загрузку с определённого файла или момента времени — ClickPipes всегда загружает все файлы по указанному пути.
Можно настроить S3 ClickPipe для приёма файлов, у которых нет естественного порядка, создав очередь Amazon SQS, подключённую к бакету, и при необходимости используя Amazon EventBridge как маршрутизатор событий. Это позволяет ClickPipes отслеживать события создания объектов и принимать новые файлы независимо от схемы их именования.
Неупорядоченный режим поддерживается только для Amazon S3 и не поддерживается для публичных бакетов или S3-совместимых сервисов. Для него требуется настроить очередь Amazon SQS, подключённую к бакету, и при необходимости использовать Amazon EventBridge как маршрутизатор событий. ObjectCreated:*, соответствующие указанному пути. Любое сообщение о файле, который уже был обработан, о файле, не соответствующем пути, или о событии другого типа будет игнорироваться.
Настройка префикса/постфикса для событий необязательна. Если вы её задаёте, убедитесь, что она соответствует пути, заданному для ClickPipe. S3 не позволяет использовать несколько пересекающихся правил уведомлений для одних и тех же типов событий.
max insert bytes или max file count, либо по истечении настраиваемого интервала (по умолчанию 30 секунд). Невозможно начать ингестию с определённого файла или момента времени — ClickPipes всегда загружает все файлы по выбранному пути. Если настроена DLQ, сообщения с ошибками будут повторно помещаться в очередь и обрабатываться заново до числа раз, заданного в параметре DLQ maxReceiveCount.
Мы настоятельно рекомендуем настроить Dead-Letter-Queue (DLQ) для очереди SQS, чтобы упростить отладку и повторную обработку сообщений с ошибками.
EventBridge в SQS
Также можно отправлять уведомления о событиях S3 в SQS через Amazon EventBridge. Это рекомендуемый подход для большинства сценариев, поскольку EventBridge поддерживает более гибкую фильтрацию событий, рассылку в несколько целевых систем и не имеет ограничения S3, допускающего только одно правило уведомлений для каждого типа события на каждый префикс. Пошаговые инструкции см. в разделе Настройка неупорядоченного режима для непрерывной ингестии.
SNS в SQS
Также можно отправлять уведомления о событиях S3 в SQS через topic SNS. Это может пригодиться, если вы столкнулись с ограничениями прямой интеграции S3 → SQS. В этом случае нужно включить опцию доставки сообщений в исходном формате.
Сопоставление имён файлов с шаблоном
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/*.csvhttps://bucket.s3.amazonaws.com/logs/**/data.jsonhttps://bucket.s3.amazonaws.com/file-?.parquethttps://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}.jsonhttps://bucket.s3.amazonaws.com/file-{1..100}.csvhttps://bucket.s3.amazonaws.com/{logs,metrics}/data.parquet
Семантика «ровно один раз»
TRUNCATE, а затем повторить вставку из чистого состояния. Только после того, как вставка успешно завершена, партиции из staging-таблицы перемещаются в целевую таблицу. Подробнее об этой стратегии читайте в этой статье блога.
Чтобы отслеживать, какие файлы были приняты, добавьте виртуальный столбец _file в список сопоставления столбцов. Виртуальный столбец _file содержит имя файла объекта-источника, которое можно использовать в запросах, чтобы определить, какие файлы были обработаны.
ClickPipe для S3 поддерживает публичные и приватные бакеты. Бакеты Requester Pays не поддерживаются.
В политике бакета должны быть разрешены следующие действия:
При использовании неупорядоченного режима в политике очереди SQS должны быть разрешены следующие действия:
Чтобы использовать ключи доступа для аутентификации, при настройке подключения ClickPipe выберите Credentials в поле Authentication method. Затем введите идентификатор ключа доступа (например, AKIAIOSFODNN7EXAMPLE) и секретный ключ доступа (например, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY) в полях Access key и Secret key соответственно.
Чтобы использовать доступ на основе ролей для аутентификации, выберите IAM role в поле Authentication method при настройке подключения ClickPipe.
Следуйте этому руководству, чтобы создать роль с необходимой политикой доверия для доступа к 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. |
Parallel distributed insert select | 2 | Настройка parallel distributed insert select. |
Parallel view processing | false | Включать ли отправку в присоединённые представления параллельно, а не последовательно. |
Use cluster function | true | Нужно ли обрабатывать файлы параллельно на нескольких узлах. |
Последнее изменение 10 июня 2026 г.
