Template Dataflow: из BigQuery в ClickHouse

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

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

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

Параметры Template

Имя параметра	Описание параметра	Обязательный	Примечания
`jdbcUrl`	JDBC URL ClickHouse в формате `jdbc:clickhouse://<host>:<port>/<schema>`.	✅	Не добавляйте имя пользователя и пароль как параметры JDBC. Любые другие параметры JDBC можно добавить в конец JDBC URL. Для пользователей ClickHouse Cloud добавьте `ssl=true&sslmode=NONE` в `jdbcUrl`.
`clickHouseUsername`	Имя пользователя ClickHouse для аутентификации.	✅
`clickHousePassword`	Пароль ClickHouse для аутентификации.	✅
`clickHouseTable`	Целевая таблица ClickHouse, в которую будут вставляться данные.	✅
`maxInsertBlockSize`	Максимальный размер блока для вставки, если создание блоков для вставки контролируется нами (опция ClickHouseIO).		Опция `ClickHouseIO`.
`insertDistributedSync`	Если настройка включена, запрос INSERT в `Distributed` будет ждать, пока данные не будут отправлены на все узлы cluster. (опция ClickHouseIO).		Опция `ClickHouseIO`.
`insertQuorum`	Для запросов INSERT в replicated table ждать записи на указанное количество реплик и обеспечивать линейный порядок добавления данных. 0 — отключено.		Опция `ClickHouseIO`. Эта настройка по умолчанию отключена в настройках сервера.
`insertDeduplicate`	Для запросов INSERT в replicated table указывает, что для вставляемых блоков должна выполняться дедупликация.		Опция `ClickHouseIO`.
`maxRetries`	Максимальное количество повторных попыток для одной вставки.		Опция `ClickHouseIO`.
`InputTableSpec`	Таблица BigQuery, из которой нужно читать данные. Укажите либо `inputTableSpec`, либо `query`. Если заданы оба параметра, приоритет имеет `query`. Пример: `<BIGQUERY_PROJECT>:<DATASET_NAME>.<INPUT_TABLE>`.		Читает данные напрямую из хранилища BigQuery с помощью BigQuery Storage Read API. Учитывайте ограничения Storage Read 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`, чтобы использовать legacy SQL. Этот параметр применяется только при использовании параметра `query`. По умолчанию — `false`.
`queryLocation`	Требуется при чтении из authorized view без разрешения на базовую таблицу. Например, `US`.
`queryTempDataset`	Укажите существующий dataset для создания temporary table, в которой будут храниться результаты запроса. Например, `temp_dataset`.
`KMSEncryptionKey`	Если чтение из BigQuery выполняется с использованием `query` в качестве источника, используйте этот ключ Cloud KMS для шифрования всех создаваемых временных таблиц. Например, `projects/your-project/locations/global/keyRings/your-keyring/cryptoKeys/your-key`.

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

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

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

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

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

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

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

Тип BigQuery	Тип ClickHouse	Примечания
Тип Array	Тип Array	Внутренний тип должен быть одним из поддерживаемых примитивных типов данных, перечисленных в этой таблице.
Тип Boolean	Тип Bool
Тип Date	Тип Date
Тип Datetime	Тип Datetime	Также работает с `Enum8`, `Enum16` и `FixedString`.
Тип String	Тип String	В BigQuery все типы Int (`INT`, `SMALLINT`, `INTEGER`, `BIGINT`, `TINYINT`, `BYTEINT`) являются псевдонимами `INT64`. Мы рекомендуем выбирать в ClickHouse подходящий размер целочисленного типа, так как шаблон будет преобразовывать столбец на основе заданного типа столбца (`Int8`, `Int16`, `Int32`, `Int64`).
Numeric — целочисленные типы	Целочисленные типы	В BigQuery все типы Int (`INT`, `SMALLINT`, `INTEGER`, `BIGINT`, `TINYINT`, `BYTEINT`) являются псевдонимами `INT64`. Мы рекомендуем выбирать в ClickHouse подходящий размер целочисленного типа, так как шаблон будет преобразовывать столбец на основе заданного типа столбца (`Int8`, `Int16`, `Int32`, `Int64`). Шаблон также будет преобразовывать беззнаковые типы Int, если они используются в таблице ClickHouse (`UInt8`, `UInt16`, `UInt32`, `UInt64`).
Numeric — типы с плавающей точкой	Типы с плавающей точкой	Поддерживаемые типы ClickHouse: `Float32` и `Float64`

Запуск Template

Template BigQuery to ClickHouse можно запустить через Google Cloud CLI.

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

Google Cloud Console
Google Cloud CLI

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

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

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

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

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

Если gcloud CLI ещё не установлен, установите его по инструкции.
Следуйте разделу Before you begin в этом руководстве, чтобы настроить необходимые конфигурации, параметры и разрешения для запуска Template DataFlow.

Запуск команды

Используйте команду gcloud dataflow flex-template run, чтобы запустить задачу Dataflow, использующую Flex Template.Ниже приведён пример такой команды:

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 — это уникальное имя задачи.
Файл Template: JSON‑файл, указанный в --template-file-gcs-location, определяет структуру Template и сведения о принимаемых параметрах. Указанный путь к файлу является общедоступным и готов к использованию.
Параметры: Параметры разделяются запятыми. Для строковых параметров заключайте значения в двойные кавычки.

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

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

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'

Отслеживание задачи

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

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

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

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

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

Исходный код Template

Исходный код Template доступен в следующих репозиториях:

GoogleCloudPlatform/DataflowTemplates — основной репозиторий Google Cloud Platform.
ClickHouse/DataflowTemplates — форк ClickHouse.

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

​Параметры Template

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

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

​Запуск Template

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

​Запуск команды

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

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

​Отслеживание задачи

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

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

​Исходный код Template

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

Параметры Template

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

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

Запуск Template

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

Запуск команды

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

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

Отслеживание задачи

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

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

Исходный код Template