Интеграция Google Cloud Storage с ClickHouse Cloud

GCS ClickPipe обеспечивает полностью управляемый и отказоустойчивый способ приёма данных из Google Cloud Storage (GCS). Он поддерживает как однократную, так и непрерывную ингестию с гарантией exactly-once.

GCS ClickPipes могут быть развернуты и управляться вручную через ClickPipes UI, а также программно с помощью OpenAPI и Terraform.

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

Возможности

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

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

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

При включённой непрерывной ингестии ClickPipes осуществляет непрерывную ингестию данных из указанного пути. Чтобы определить порядок ингестии, GCS ClickPipe полагается на неявный лексикографический порядок файлов по умолчанию. Также его можно настроить на приём файлов в любом порядке, используя подписку Google Cloud Pub/Sub, настроенную на отправку уведомлений для бакета.

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

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

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

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

Примечание

Режим без упорядочивания не поддерживается для публичных бакетов. Он требует аутентификации с помощью Service Account и подписки Google Cloud Pub/Sub, подключённой к бакету.

Можно настроить GCS ClickPipe для выполнения ингестии файлов, которые не имеют неявного порядка, с помощью подписки Google Cloud Pub/Sub, получающей уведомления от бакета. Это позволяет ClickPipes отслеживать события создания объектов и принимать все новые файлы независимо от соглашения об их именовании.

В этом режиме GCS ClickPipe выполняет первоначальную загрузку всех файлов по указанному пути, а затем прослушивает через подписку Pub/Sub уведомления об объектах, которые соответствуют этому пути. Любое сообщение о ранее обработанном файле, файле, не соответствующем пути, или событии другого типа будет проигнорировано. Нельзя начать ингестию с конкретного файла или с определённого момента времени — ClickPipes всегда будет загружать все файлы по указанному пути.

Настройка уведомлений Pub/Sub

Чтобы использовать неупорядоченный режим, необходимо настроить автоматические уведомления из бакета GCS в тему Pub/Sub. Следуйте официальной документации по уведомлениям Pub/Sub, чтобы создать тему и подписку Pub/Sub, а затем настроить уведомления для бакета.

Чтобы создать уведомление:

# Create a Pub/Sub notification for new objects in the bucket
gcloud storage buckets notifications create "gs://${YOUR_BUCKET_NAME}" \
    --topic="projects/${YOUR_PROJECT_ID}/topics/${YOUR_TOPIC_NAME}" \
    --event-types="OBJECT_FINALIZE" \
    --payload-format="json"

Предоставление прав учетной записи службы

Режим произвольного порядка требует аутентификации с использованием Service Account. Учетная запись службы, используемая ClickPipes, должна иметь следующие права:

Чтение объектов из бакета GCS — для получения файлов с данными.
Чтение сообщений из подписки Pub/Sub — для получения уведомлений об объектах.
Получение подписки Pub/Sub — для проверки существования подписки и получения её метаданных.

Предоставьте эти права с помощью следующих команд gcloud:

# 1. Grant read access to the GCS bucket
gcloud storage buckets add-iam-policy-binding "gs://${YOUR_BUCKET_NAME}" \
  --member="serviceAccount:${YOUR_SERVICE_ACCOUNT}@${YOUR_PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/storage.objectViewer"

# 2. Grant read access to the Pub/Sub subscription
gcloud pubsub subscriptions add-iam-policy-binding "${YOUR_SUBSCRIPTION_NAME}" \
  --member="serviceAccount:${YOUR_SERVICE_ACCOUNT}@${YOUR_PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/pubsub.subscriber"

# 3. Grant permission to get the Pub/Sub subscription metadata
gcloud pubsub subscriptions add-iam-policy-binding "${YOUR_SUBSCRIPTION_NAME}" \
  --member="serviceAccount:${YOUR_SERVICE_ACCOUNT}@${YOUR_PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/pubsub.viewer"

Настройка ClickPipe

В консоли ClickHouse Cloud перейдите в Data Sources > Create ClickPipe, затем выберите Google Cloud Storage. Введите данные для подключения к вашему бакету GCS, используя Service Account в качестве метода аутентификации, и загрузите JSON-файл ключа сервисного аккаунта. Затем нажмите Incoming data.

Включите Continuous ingestion, где вы увидите новый вариант ингестии Any order. Затем введите путь подписки Pub/Sub в следующем формате:

projects/${YOUR_PROJECT_ID}/subscriptions/${YOUR_SUBSCRIPTION_NAME}

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

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/*.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

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

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

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

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

Контроль доступа

Права доступа

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

Роль roles/storage.objectViewer должна быть назначена на уровне бакета. Эта роль содержит разрешения IAM storage.objects.list и storage.objects.get, которые позволяют ClickPipes просматривать список и получать объекты в указанном бакете.

Подписка Pub/Sub

При использовании неупорядоченного режима сервисному аккаунту требуются следующие роли на подписке Pub/Sub:

roles/pubsub.subscriber — для получения и подтверждения сообщений.
roles/pubsub.viewer — для получения метаданных подписки.

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

Service account

Аутентификация через Service Account требуется при использовании неупорядоченного режима с уведомлениями Pub/Sub. Выберите Service Account в качестве метода аутентификации и загрузите JSON-файл ключа сервисного аккаунта.

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

Чтобы использовать ключи HMAC для аутентификации, выберите Credentials в разделе Authentication method при настройке подключения ClickPipe. Затем укажите access key (например, GOOGTS7C7FUP3AIRVJTE2BCDKINBTES3HC2GY5CBFJDCQ2SYHV6A6XXVTJFSA) и secret key (например, bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ) в полях Access key и Secret key соответственно.

Воспользуйтесь этим руководством, чтобы создать учетную запись службы с ключом и секретом HMAC.

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

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

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

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

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

Setting	Default value	Description
`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	Настройка параллельной distributed INSERT SELECT.
`Parallel view processing`	false	Определяет, выполнять ли запись в присоединённые представления параллельно, а не последовательно.
`Use cluster function`	true	Определяет, нужно ли обрабатывать файлы параллельно на нескольких узлах.

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

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

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

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

Размер файла

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

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

GCS ClickPipe использует в Cloud Storage интерфейс XML API для обеспечения совместимости, что требует использования префикса buckethttps://storage.googleapis.com/ (вместо gs://) и применения HMAC-ключей для аутентификации.

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

Поддерживаются также materialized views, основанные на целевой таблице. ClickPipes будут создавать промежуточные таблицы не только для целевой таблицы, но и для всех зависящих от неё materialized views.

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

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

Возможности​

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

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

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

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

Настройка уведомлений Pub/Sub​

Предоставление прав учетной записи службы​

Настройка ClickPipe​

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

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

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

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

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

Контроль доступа​

Права доступа​

Подписка Pub/Sub​

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

Service account​

Учетные данные HMAC​

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

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

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

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

Размер файла​

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

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