Шаблон Dataflow BigQuery в ClickHouse
Шаблон BigQuery в ClickHouse представляет собой пакетный конвейер, который загружает данные из таблицы BigQuery в таблицу ClickHouse. Шаблон может либо читать всю таблицу, либо читать конкретные записи с помощью предоставленного запроса.
Требования к конвейеру
- Исходная таблица 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 можно найти в Коннекторе Apache Beam ClickHouseIO
Схема исходных и целевых таблиц
Для эффективной загрузки набора данных BigQuery в ClickHouse выполняется процесс колоночной инвазии с следующими фазами:
- Шаблоны строят объект схемы на основе целевой таблицы ClickHouse.
- Шаблоны проходят по набору данных BigQuery и пытаются сопоставить колонки по их именам.
Сказав это, ваш набор данных BigQuery (либо таблица, либо запрос) должен иметь точно такие же имена колонок, как и ваша целевая таблица ClickHouse.
Сопоставление типов данных
Типы BigQuery конвертируются на основе определения вашей таблицы ClickHouse. Поэтому вышеуказанная таблица перечисляет рекомендуемое сопоставление, которое вы должны иметь в своей целевой таблице ClickHouse (для данной таблицы/запроса BigQuery):
| Тип BigQuery | Тип ClickHouse | Примечания |
|---|---|---|
| Array Type | Array Type | Внутренний тип должен быть одним из поддерживаемых примитивных типов данных, перечисленных в этой таблице. |
| Boolean Type | Bool Type | |
| Date Type | Date Type | |
| Datetime Type | Datetime Type | Также работает с Enum8, Enum16 и FixedString. |
| String Type | String Type | В BigQuery все целочисленные типы (INT, SMALLINT, INTEGER, BIGINT, TINYINT, BYTEINT) являются псевдонимами для INT64. Мы рекомендуем вам установить правильный размер целого числа в ClickHouse, так как шаблон будет конвертировать столбец на основе определенного типа столбца (Int8, Int16, Int32, Int64). |
| Numeric - Integer Types | Integer Types | В BigQuery все целочисленные типы (INT, SMALLINT, INTEGER, BIGINT, TINYINT, BYTEINT) являются псевдонимами для INT64. Мы рекомендуем вам установить правильный размер целого числа в ClickHouse, так как шаблон будет конвертировать столбец на основе определенного типа столбца (Int8, Int16, Int32, Int64). Шаблон также преобразует неуказанные целочисленные типы, если они используются в таблице ClickHouse (UInt8, UInt16, UInt32, UInt64). |
| Numeric - Float Types | Float Types | Поддерживаемые типы ClickHouse: Float32 и Float64 |
Запуск шаблона
Шаблон BigQuery в ClickHouse доступен для выполнения через Google Cloud CLI.
Обязательно ознакомьтесь с этим документом, а также с вышеупомянутыми разделами, чтобы полностью понять требования и предварительные условия конфигурации шаблона.
Установка и настройка gcloud CLI
- Если еще не установлен, установите
gcloudCLI. - Следуйте разделу
Перед тем как начатьв этом руководстве, чтобы настроить необходимые конфигурации, настройки и разрешения для запуска шаблона DataFlow.
Команда запуска
Используйте команду gcloud dataflow flex-template run для запуска задания Dataflow, использующего гибкий шаблон.
Ниже приведен пример команды:
Разбор команды
- Имя задания: Текст после ключевого слова
run- это уникальное имя задания. - Файл шаблона: JSON-файл, указанный с помощью
--template-file-gcs-location, определяет структуру шаблона и детали обAccepted parameters. Указанный путь файла является открытым и готовым к использованию. - Параметры: Параметры разделяются запятыми. Для параметров строкового типа значения следует заключать в двойные кавычки.
Ожидаемый ответ
После выполнения команды вы должны увидеть ответ, похожий на следующий:
Мониторинг задания
Перейдите на вкладку Jobs Dataflow в вашей Google Cloud Console, чтобы мониторить статус задания. Вы найдете детали задания, включая прогресс и любые ошибки:
Устранение неполадок
Код: 241. DB::Exception: Превышен лимит памяти (всего)
Эта ошибка возникает, когда ClickHouse исчерпывает память во время обработки больших пакетов данных. Чтобы решить эту проблему:
- Увеличьте ресурсы экземпляра: обновите сервер ClickHouse до более крупного экземпляра с большим объемом памяти, чтобы обработать нагрузку обработки данных.
- Уменьшите размер пакета: отрегулируйте размер пакета в конфигурации задания Dataflow, чтобы отправлять меньшие порции данных в ClickHouse, что снизит потребление памяти на пакет. Эти изменения могут помочь сбалансировать использование ресурсов во время приема данных.
Исходный код шаблона
Исходный код шаблона доступен в форке DataflowTemplates ClickHouse.