Интеграция Azure Blob Storage с ClickHouse Cloud
ABS ClickPipe предоставляет полностью управляемый и отказоустойчивый способ приёма данных из Azure Blob Storage в ClickHouse Cloud. Он поддерживает как однократную, так и непрерывную ингестию с семантикой «exactly-once».
ABS ClickPipes можно развернуть и управлять ими вручную через ClickPipes UI, а также программно с помощью OpenAPI и Terraform.
Поддерживаемые форматы
Возможности
Однократная ингестия
ABS ClickPipe загрузит все файлы, соответствующие указанному шаблону, из заданного контейнера в целевую таблицу ClickHouse в рамках одного пакетного выполнения. После завершения задачи ингестии ClickPipe автоматически останавливается. Этот режим однократной ингестии обеспечивает семантику exactly-once, гарантируя, что каждый файл будет надёжно обработан без дубликатов.
Непрерывная ингестия
Когда включена непрерывная ингестия, ClickPipes осуществляет непрерывный приём данных по указанному пути. Для определения порядка ингестии данных ABS ClickPipe полагается на неявный лексикографический порядок файлов.
Лексикографический порядок
ABS ClickPipe предполагает, что файлы добавляются в контейнер в лексикографическом порядке и полагается на этот неявный порядок для их последовательного приёма. Это означает, что любой новый файл должен быть лексикографически больше последнего принятого файла. Например, файлы с именами file1, file2 и file3 будут приниматься последовательно, но если в контейнер будет добавлен новый file0, он будет проигнорирован, потому что имя файла лексикографически не больше имени последнего принятого файла.
В этом режиме ABS ClickPipe выполняет начальную загрузку всех файлов по указанному пути, а затем периодически опрашивает источник на наличие новых файлов с настраиваемым интервалом (по умолчанию 30 секунд). Невозможно начать ингестию с конкретного файла или момента времени — ClickPipes всегда будут загружать все файлы по указанному пути.
Сопоставление с шаблонами файлов
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://storageaccount.blob.core.windows.net/container/folder/*.csvhttps://storageaccount.blob.core.windows.net/container/logs/**/data.jsonhttps://storageaccount.blob.core.windows.net/container/file-?.parquethttps://storageaccount.blob.core.windows.net/container/data-2024-*.csv.gz
Неподдерживаемые шаблоны
| Шаблон | Описание | Пример | Альтернативы |
|---|---|---|---|
{abc,def} | Расширение с фигурными скобками (альтернативы) | {logs,data}/file.csv | Создайте отдельные ClickPipes для каждого пути. |
{N..M} | Расширение числового диапазона | file-{1..100}.csv | Используйте file-*.csv или file-?.csv. |
Примеры:
https://storageaccount.blob.core.windows.net/container/{documents-01,documents-02}.jsonhttps://storageaccount.blob.core.windows.net/container/file-{1..100}.csvhttps://storageaccount.blob.core.windows.net/container/{logs,metrics}/data.parquet
Семантика «ровно один раз»
При приёме больших объёмов данных могут происходить различные сбои, которые приводят к частичным вставкам или дублированию данных. Object Storage ClickPipes устойчивы к ошибкам вставки и обеспечивают семантику «ровно один раз». Это достигается с помощью временных таблиц «staging». Сначала данные вставляются во staging-таблицы. Если при вставке что-то идёт не так, staging-таблицу можно очистить (TRUNCATE), а вставку повторить с чистого состояния. Только после того, как вставка завершена и выполнена успешно, партиции в staging-таблице перемещаются в целевую таблицу. Чтобы подробнее изучить этот подход, ознакомьтесь с этой записью в блоге.
Виртуальные столбцы
Чтобы отслеживать, какие файлы были загружены (приняты), включите виртуальный столбец _file в список сопоставления столбцов. Виртуальный столбец _file содержит имя файла исходного объекта, по которому можно выполнять запросы, чтобы определить, какие файлы были обработаны.
Контроль доступа
Разрешения
ABS ClickPipe поддерживает только частные контейнеры. Открытые контейнеры не поддерживаются.
В политике корзины (bucket) для контейнеров должны быть разрешены действия s3:GetObject и s3:ListBucket.
Аутентификация
Аутентификация Microsoft Entra ID (включая Managed Identities) в настоящее время не поддерживается.
Для аутентификации в Azure Blob Storage используется строка подключения, которая поддерживает как ключи доступа, так и общие сигнатуры доступа (SAS, Shared Access Signatures).
Ключ доступа
Для аутентификации с помощью ключа доступа к учетной записи укажите строку подключения в следующем формате:
Имя учетной записи хранилища и ключ доступа можно найти на портале Azure в разделе Storage Account > Access keys.
Подпись общего доступа (SAS)
Для аутентификации с использованием Shared Access Signature (SAS) укажите строку подключения, содержащую SAS-токен:
Сгенерируйте SAS-токен в Azure Portal в разделе Storage Account > Shared access signature с соответствующими правами (Read, List) для контейнера и BLOB-объектов, данные из которых вы хотите принимать.
Расширенные настройки
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 будет добавлена запись об этой ошибке.
Задержка
Для контейнеров с более чем 100 000 файлов операции LIST в Azure Blob Storage добавляют дополнительную задержку при обнаружении новых файлов, сверх стандартного интервала опроса:
- < 100k файлов: ~30 секунд (стандартный интервал опроса)
- 100k файлов: ~40–45 секунд
- 250k файлов: ~55–70 секунд
- 500k+ файлов: может превышать 90 секунд
Для непрерывной ингестии ClickPipes необходимо просканировать контейнер, чтобы определить новые файлы, лексикографически больше, чем последний проингестированный файл. Рекомендуется организовывать файлы в более мелкие контейнеры или использовать иерархические структуры каталогов, чтобы уменьшить количество файлов на одну операцию LIST.
Поддержка view
Поддерживаются также materialized view, зависящие от таблицы-приёмника. ClickPipes создаст промежуточные таблицы не только для таблицы-приёмника, но и для всех зависимых materialized view.
Мы не создаём промежуточные таблицы для нематериализованных view. Это означает, что если у вас есть таблица-приёмник с одним или несколькими производными materialized view, этим materialized view не следует выбирать данные через обычное view, построенное над таблицей-приёмником. В противном случае вы можете столкнуться с отсутствием данных в materialized view.
Зависимости
Любые изменения в целевой таблице, её materialized view (включая каскадные materialized view) или в целевых таблицах этих materialized view во время работы ClickPipe приведут к ошибкам, которые могут быть устранены повторной попыткой. Чтобы внести изменения в схему этих зависимостей, необходимо приостановить ClickPipe, применить изменения, а затем возобновить его.
