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