Шаблон Dataflow BigQuery в ClickHouse

Шаблон BigQuery в ClickHouse представляет собой пакетный конвейер, который загружает данные из таблицы BigQuery в таблицу ClickHouse. Шаблон может читать всю таблицу или фильтровать конкретные записи, используя предоставленный SQL-запрос.

• Требования к конвейеру
• Параметры шаблона
• Схема исходных и целевых таблиц
• Сопоставление типов данных
• Запуск шаблона
• Устранение неполадок
• Исходный код шаблона

Требования к конвейеру

• Исходная таблица BigQuery должна существовать.
• Целевая таблица ClickHouse должна существовать.
• Хост ClickHouse должен быть доступен с машин-работников Dataflow.

Параметры шаблона

Имя параметра	Описание параметра	Обязательно	Примечания
jdbcUrl	JDBC URL ClickHouse в формате jdbc:clickhouse://<host>:<port>/<schema>.	✅	Не добавляйте имя пользователя и пароль в параметры JDBC. Любые другие параметры JDBC можно добавлять в конце URL JDBC. Для пользователей ClickHouse Cloud добавьте ssl=true&sslmode=NONE в jdbcUrl.
clickHouseUsername	Имя пользователя ClickHouse для аутентификации.	✅
clickHousePassword	Пароль ClickHouse для аутентификации.	✅
clickHouseTable	Целевая таблица ClickHouse, в которую будут вставлены данные.	✅
maxInsertBlockSize	Максимальный размер блока для вставки, если мы контролируем создание блоков для вставки (параметр ClickHouseIO).		Параметр ClickHouseIO.
insertDistributedSync	Если данный параметр включен, запрос вставки в распределенной таблице будет ожидать, пока данные будут отправлены на все узлы в кластере. (параметр ClickHouseIO).		Параметр ClickHouseIO.
insertQuorum	Для запросов INSERT в реплицированной таблице ожидает записи для указанного числа реплик и линейно добавляет данные. 0 - отключено.		Параметр ClickHouseIO. Этот параметр по умолчанию отключен в настройках сервера.
insertDeduplicate	Для запросов INSERT в реплицированной таблице указывает, что должна выполняться дедупликация вставляемых блоков.		Параметр ClickHouseIO.
maxRetries	Максимальное количество повторных попыток для каждой вставки.		Параметр ClickHouseIO.
InputTableSpec	Таблица BigQuery для чтения. Укажите либо inputTableSpec, либо query. Когда оба указаны, предпочтение отдается параметру query. Пример: <BIGQUERY_PROJECT>:<DATASET_NAME>.<INPUT_TABLE>.		Данные читаются прямо из хранилища BigQuery с использованием API чтения данных BigQuery. Обратите внимание на ограничения API чтения данных.
outputDeadletterTable	Таблица BigQuery для сообщений, которые не смогли достичь выходной таблицы. Если таблица не существует, она создается во время выполнения конвейера. Если не указано, используется <outputTableSpec>_error_records. Например, <PROJECT_ID>:<DATASET_NAME>.<DEADLETTER_TABLE>.
query	SQL-запрос для чтения данных из BigQuery. Если набор данных BigQuery находится в другом проекте, чем рабочая задача Dataflow, укажите полное имя набора данных в SQL-запросе, например: <PROJECT_ID>.<DATASET_NAME>.<TABLE_NAME>. По умолчанию используется GoogleSQL, если useLegacySql не равно true.		Вы должны указать либо inputTableSpec, либо query. Если вы установите оба параметра, шаблон использует параметр query. Пример: SELECT * FROM sampledb.sample_table.
useLegacySql	Установите в true, чтобы использовать устаревший SQL. Этот параметр применяется только при использовании параметра query. По умолчанию false.
queryLocation	Необходимо при чтении из авторизованного представления без разрешений на основную таблицу. Например, US.
queryTempDataset	Укажите существующий набор данных для создания временной таблицы для хранения результатов запроса. Например, temp_dataset.
KMSEncryptionKey	При чтении из BigQuery с использованием источника запроса используйте этот ключ Cloud KMS для шифрования любых временных таблиц, созданных. Например, projects/your-project/locations/global/keyRings/your-keyring/cryptoKeys/your-key.

примечание

Значения по умолчанию для всех параметров ClickHouseIO можно найти в ClickHouseIO Apache Beam Connector

Схема исходных и целевых таблиц

Чтобы эффективно загрузить набор данных BigQuery в ClickHouse, конвейер выполняет процесс вывода схемы с следующими фазами:

1. Шаблоны строят объект схемы на основе целевой таблицы ClickHouse.
2. Шаблоны перебирают набор данных BigQuery и пытаются сопоставить колонки на основе их имен.

к сведению

При этом набор данных BigQuery (таблица или запрос) должен иметь точно такие же имена колонок, как ваша целевая таблица ClickHouse.

Сопоставление типов данных

Типы BigQuery преобразуются на основе определения вашей таблицы ClickHouse. Поэтому в приведенной выше таблице указано рекомендованное сопоставление, которое вам следует иметь в целевой таблице ClickHouse (для данной таблицы/запроса BigQuery):

Тип BigQuery	Тип ClickHouse	Примечания
Тип массива	Тип массива	Внутренний тип должен быть одним из поддерживаемых примитивных типов данных, перечисленных в этой таблице.
Логический тип	Тип boolean
Тип даты	Тип даты
Тип даты и времени	Тип даты и времени	Также работает с Enum8, Enum16 и FixedString.
Строковый тип	Строковый тип	В BigQuery все типы Int (INT, SMALLINT, INTEGER, BIGINT, TINYINT, BYTEINT) являются псевдонимами для INT64. Рекомендуется установить в ClickHouse правильный размер целого числа, так как шаблон будет конвертировать колонку на основе определенного типа колонки (Int8, Int16, Int32, Int64).
Числовые - Целочисленные типы	Целочисленные типы	В BigQuery все типы Int (INT, SMALLINT, INTEGER, BIGINT, TINYINT, BYTEINT) являются псевдонимами для INT64. Рекомендуется установить в ClickHouse правильный размер целого числа, так как шаблон будет конвертировать колонку на основе определенного типа колонки (Int8, Int16, Int32, Int64). Шаблон также будет конвертировать неуказанные типы Int, если они используются в таблице ClickHouse (UInt8, UInt16, UInt32, UInt64).
Числовые - Типы с плавающей точкой	Типы с плавающей точкой	Поддерживаемые типы ClickHouse: Float32 и Float64

Запуск шаблона

Шаблон BigQuery в ClickHouse доступен для выполнения через Google Cloud CLI.

примечание

Обязательно ознакомьтесь с этим документом, а особенно с приведенными выше разделами, чтобы полностью понять требования к конфигурации и предварительные условия шаблона.

Google Cloud Console

Войдите в свою Google Cloud Console и найдите DataFlow.

1. Нажмите кнопку CREATE JOB FROM TEMPLATE
   
2. Когда форма шаблона откроется, введите имя задания и выберите желаемый регион.
   
3. Введите в поле DataFlow Template ClickHouse или BigQuery и выберите шаблон BigQuery to ClickHouse
   
4. После выбора форма развернется, чтобы вы могли предоставить дополнительные детали:
   • JDBC URL сервера ClickHouse в формате jdbc:clickhouse://host:port/schema.
   • Имя пользователя ClickHouse.
   • Имя целевой таблицы ClickHouse.

примечание

Опция пароля ClickHouse помечена как необязательная для случаев, когда пароль не настроен. Чтобы добавить его, прокрутите вниз до опции Password for ClickHouse Endpoint.

5. Настройте и добавьте любые конфигурации, связанные с BigQuery/ClickHouseIO, как указано в разделе Параметры шаблона

Google Cloud CLI

Установка и настройка gcloud CLI

• Если еще не установлен, установите gcloud CLI.
• Следуйте разделу Перед началом в данном руководстве для настройки необходимых конфигураций, настроек и разрешений для выполнения шаблона DataFlow.

Команда запуска

Используйте команду gcloud dataflow flex-template run для запуска задания Dataflow, которое использует гибкий шаблон.

Вот пример команды:

gcloud dataflow flex-template run "bigquery-clickhouse-dataflow-$(date +%Y%m%d-%H%M%S)" \
 --template-file-gcs-location "gs://clickhouse-dataflow-templates/bigquery-clickhouse-metadata.json" \
 --parameters inputTableSpec="<bigquery table id>",jdbcUrl="jdbc:clickhouse://<clickhouse host>:<clickhouse port>/<schema>?ssl=true&sslmode=NONE",clickHouseUsername="<username>",clickHousePassword="<password>",clickHouseTable="<clickhouse target table>"

Разбор команды

• Имя задания: Текст после ключевого слова run - это уникальное имя задания.
• Файл шаблона: JSON-файл, указанный в --template-file-gcs-location, определяет структуру шаблона и детали принимаемых параметров. Указанный путь к файлу является публичным и готов к использованию.
• Параметры: Параметры разделяются запятыми. Для параметров на основе строк заключайте значения в двойные кавычки.

Ожидаемый ответ

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

job:
  createTime: '2025-01-26T14:34:04.608442Z'
  currentStateTime: '1970-01-01T00:00:00Z'
  id: 2025-01-26_06_34_03-13881126003586053150
  location: us-central1
  name: bigquery-clickhouse-dataflow-20250126-153400
  projectId: ch-integrations
  startTime: '2025-01-26T14:34:04.608442Z'

Мониторинг задания

Перейдите на вкладку Jobs Dataflow в вашей Google Cloud Console, чтобы отслеживать состояние задания. Вы найдете детали задания, включая прогресс и любые ошибки:

Устранение неполадок

Превышен лимит памяти (итого) (код 241)

Эта ошибка возникает, когда ClickHouse исчерпывает память при обработке больших пакетов данных. Чтобы решить эту проблему:

• Увеличьте ресурсы экземпляра: обновите сервер ClickHouse до более крупного экземпляра с большим объемом памяти для обработки нагрузок на обработку данных.
• Уменьшите размер пакета: отрегулируйте размер пакета в конфигурации задания Dataflow, чтобы отправлять меньшие объемы данных в ClickHouse, снижая потребление памяти на пакет. Эти изменения могут помочь сбалансировать использование ресурсов во время приема данных.

Исходный код шаблона

Исходный код шаблона доступен в форке DataflowTemplates ClickHouse.