Интеграция Amazon S3 с ClickHouse Cloud
S3 ClickPipe обеспечивает полностью управляемый и отказоустойчивый способ ингестии данных из Amazon S3 и S3-совместимых объектных хранилищ в ClickHouse Cloud. Поддерживаются режимы однократной и непрерывной ингестии с гарантиями exactly-once.
S3 ClickPipes можно разворачивать и управлять ими вручную через ClickPipes UI, а также программно с использованием OpenAPI и Terraform.
Поддерживаемые источники данных
| Name | Logo | Details |
|---|---|---|
| Amazon S3 | Для непрерывной ингестии по умолчанию требуется лексикографический порядок, но её можно настроить на приём файлов в произвольном порядке. | |
| Cloudflare R2 S3-compatible | Непрерывная ингестия требует лексикографического порядка. | |
| DigitalOcean Spaces S3-compatible | Непрерывная ингестия требует лексикографического порядка. |
Из-за различий в форматах URL и реализациях API у разных провайдеров объектного хранилища не все S3-совместимые сервисы поддерживаются «из коробки». Если вы сталкиваетесь с проблемами при работе с сервисом, который не указан выше, свяжитесь с нашей командой.
Поддерживаемые форматы
Возможности
Однократная ингестия
По умолчанию S3 ClickPipe загружает все файлы, соответствующие заданному шаблону, из указанного бакета в целевую таблицу ClickHouse в рамках одной пакетной операции. После завершения задачи по ингестии ClickPipe автоматически останавливается. Этот режим однократной ингестии обеспечивает семантику exactly-once, гарантируя надёжную обработку каждого файла без дублирования.
Непрерывная ингестия
Когда непрерывная ингестия включена, ClickPipes непрерывно принимает данные из указанного пути. Чтобы определить порядок ингестии, S3 ClickPipe по умолчанию полагается на неявный лексикографический порядок файлов. Также можно настроить приём файлов в произвольном порядке с использованием очереди Amazon SQS, привязанной к бакету.
Лексикографический порядок
По умолчанию S3 ClickPipe предполагает, что файлы добавляются в бакет в лексикографическом порядке и опирается на этот неявный порядок для последовательного приёма файлов. Это означает, что любой новый файл должен быть лексикографически больше последнего принятого файла. Например, файлы с именами file1, file2 и file3 будут приниматься последовательно, но если в бакет будет добавлен новый file 0, он будет проигнорирован, потому что имя файла лексикографически не больше, чем у последнего принятого файла.
В этом режиме S3 ClickPipe выполняет начальную загрузку всех файлов по указанному пути, а затем с настраиваемым интервалом (по умолчанию 30 секунд) периодически проверяет наличие новых файлов. Невозможно запустить ингестию, начиная с конкретного файла или момента времени — ClickPipes всегда загружает все файлы по указанному пути.
Любой порядок
Режим без упорядочивания поддерживается только для Amazon S3 и не поддерживается для публичных бакетов. Для него требуется настроить очередь Amazon SQS, подключённую к бакету.
Можно настроить S3 ClickPipe для приёма файлов, не имеющих неявного порядка, настроив очередь Amazon SQS, подключённую к бакету. Это позволяет ClickPipes прослушивать события создания объектов и выполнять ингестию любых новых файлов независимо от схемы именования.
В этом режиме S3 ClickPipe сначала выполняет начальную загрузку всех файлов по указанному пути, а затем прослушивает в очереди события ObjectCreated:*, которые соответствуют этому пути. Любое сообщение о ранее обработанном файле, о файле, не соответствующем пути, или о событии другого типа будет игнорироваться.
Указание префикса/постфикса для событий необязательно. Если вы его задаёте, убедитесь, что он совпадает с путём, указанным для ClickPipe. S3 не допускает несколько перекрывающихся правил уведомлений для одних и тех же типов событий.
Файлы ингестируются при достижении порога, заданного в max insert bytes или max file count, либо по истечении настраиваемого интервала (по умолчанию 30 секунд). Невозможно запустить ингестию с конкретного файла или момента времени — ClickPipes всегда будут загружать все файлы по выбранному пути. Если настроен DLQ, неудачно обработанные сообщения будут повторно помещаться в очередь и переобрабатываться до числа раз, указанного в параметре DLQ maxReceiveCount.
Настоятельно рекомендуем настроить Dead-Letter-Queue (DLQ) для очереди SQS, чтобы упростить отладку и повторную обработку неудачных сообщений.
SNS в SQS
Также можно отправлять уведомления о событиях S3 в SQS через тему SNS. Это полезно, если вы сталкиваетесь с ограничениями прямой интеграции S3 → SQS. В этом случае необходимо включить опцию raw message delivery.
Сопоставление шаблонов файлов
Object Storage 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/*.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
Семантика «ровно один раз»
При приёме больших наборов данных могут происходить различные сбои, которые приводят к частичным вставкам или дублированию данных. ClickPipes для объектного хранилища устойчивы к ошибкам вставки и обеспечивают семантику «ровно один раз». Это достигается с помощью временных промежуточных (staging) таблиц. Сначала данные вставляются в staging-таблицы. Если при этой вставке что-то идёт не так, staging-таблицу можно очистить (TRUNCATE) и повторить вставку из чистого состояния. Только когда вставка завершена и прошла успешно, партиции в staging-таблице переносятся в целевую таблицу. Чтобы узнать больше об этой стратегии, ознакомьтесь с этой записью в блоге.
Виртуальные столбцы
Чтобы отслеживать, какие файлы были приняты при приёме данных, добавьте виртуальный столбец _file в список сопоставления столбцов. Виртуальный столбец _file содержит имя файла исходного объекта, которое можно использовать в запросах, чтобы определить, какие файлы были обработаны.
Контроль доступа
Права доступа
S3 ClickPipe поддерживает как общедоступные, так и приватные бакеты. Бакеты типа Requester Pays не поддерживаются.
Бакет S3
В политике бакета должны быть разрешены следующие действия:
Очередь SQS
При использовании неупорядоченного режима в политике очереди должны быть разрешены следующие действия:
Аутентификация
Учетные данные IAM
Чтобы использовать ключи доступа для аутентификации, при настройке подключения ClickPipe в поле Authentication method выберите Credentials. Затем укажите идентификатор ключа доступа (например, AKIAIOSFODNN7EXAMPLE) и секретный ключ доступа (например, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY) в полях Access key и Secret key соответственно.
Роль IAM
Чтобы использовать управление доступом на основе ролей для аутентификации, выберите IAM role в разделе Authentication method при настройке подключения ClickPipe.
Воспользуйтесь этим руководством, чтобы создать роль с необходимой политикой доверия для доступа к S3. Затем укажите ARN роли IAM в поле IAM role ARN.
Расширенные настройки
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 | Выполнять ли обработку файлов параллельно на нескольких узлах. |
Масштабирование
Object Storage ClickPipes масштабируются исходя из минимального размера сервиса ClickHouse, определённого настроенными параметрами вертикального автомасштабирования. Размер ClickPipe фиксируется при создании конвейера. Последующие изменения настроек сервиса ClickHouse не повлияют на размер ClickPipe.
Чтобы увеличить пропускную способность при крупных задачах по приёму данных, рекомендуется масштабировать сервис ClickHouse перед созданием ClickPipe.
Известные ограничения
Размер файла
ClickPipes будет пытаться принимать только объекты, размер которых 10 ГБ или меньше. Если файл превышает 10 ГБ, в специализированную таблицу ошибок ClickPipes будет добавлена запись об ошибке.
Совместимость
Несмотря на совместимость с S3, некоторые сервисы используют иную структуру URL-адресов, которую S3 ClickPipe может оказаться не в состоянии корректно разобрать (например, Backblaze B2), или требуют интеграции с зависящими от провайдера сервисами очередей для непрерывного неупорядоченного приёма данных. Если вы сталкиваетесь с проблемами при работе с сервисом, который не указан в разделе Поддерживаемые источники данных, пожалуйста, обратитесь к нашей команде.
Поддержка представлений
Поддерживаются также materialized view для целевой таблицы. ClickPipes создаст промежуточные таблицы не только для целевой таблицы, но и для любых зависящих от неё materialized view.
Мы не создаём промежуточные таблицы для нематериализованных представлений. Это означает, что если у вас есть целевая таблица с одной или несколькими нижестоящими materialized view, этим materialized view не следует выбирать данные из целевой таблицы через обычное представление. В противном случае вы можете столкнуться с отсутствующими данными в соответствующей materialized view.
