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

Простое подключение объектного хранилища к ClickHouse Cloud.

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

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

​

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

• JSON
• CSV
• TSV
• Parquet
• Avro

​

Возможности

​

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

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

​

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

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

​

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

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

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

​

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

См. Настройка неупорядоченного режима для непрерывной ингестии с пошаговыми инструкциями.

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

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

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

​

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

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 для GCS поддерживает публичные и приватные бакеты. Бакеты Requester Pays не поддерживаются.

​

GCS-бакет

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

• roles/storage.objectViewer

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

​

Подписка Pub/Sub

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

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

​

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

​

Сервисный аккаунт

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

​

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

Чтобы использовать HMAC-ключи для аутентификации, при настройке подключения ClickPipe выберите Credentials в разделе метод аутентификации. Затем укажите ключ доступа (например, GOOGTS7C7FUP3AIRVJTE2BCDKINBTES3HC2GY5CBFJDCQ2SYHV6A6XXVTJFSA) и секретный ключ (например, 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 предоставляет разумные значения по умолчанию, которые подходят для большинства сценариев использования. Если вашему сценарию требуется более тонкая настройка, вы можете изменить следующие параметры:

Настройка	Значение по умолчанию	Описание
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	Для неупорядоченной непрерывной ингестии пропускает начальное сканирование существующих файлов и обрабатывает только уведомления об объектах из настроенной подписки Pub/Sub.
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.

​

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

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

​

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

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

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