Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Template Dataflow: из BigQuery в ClickHouse

View as MarkdownEdit this pageReport an issueSet up docs MCP

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.

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

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

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

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

Типы 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.

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

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

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

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

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

Консоль Dataflow с выполняющейся задачей BigQuery в ClickHouse

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

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

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

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

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

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

Navigation