Шаблон Dataflow BigQuery в ClickHouse
Шаблон BigQuery в ClickHouse является пакетным конвейером, который загружает данные из таблицы BigQuery в таблицу ClickHouse. Шаблон может как считывать всю таблицу, так и извлекать конкретные записи, используя предоставленный запрос.
Требования к конвейеру
- Исходная таблица BigQuery должна существовать.
- Целевая таблица ClickHouse должна существовать.
- Хост ClickHouse должен быть доступен с машин-работников Dataflow.
Параметры шаблона
| Название параметра | Описание параметра | Обязательный | Примечания |
|---|---|---|---|
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 | Если настройка включена, запрос вставки в распределенной системе ожидает, пока данные будут отправлены на все узлы в кластере. (опция 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 не истинно. | Вы должны указать либо 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 (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.
Обязательно ознакомьтесь с этим документом, и особенно с вышеуказанными разделами, чтобы полностью понять требования к конфигурации шаблона и предварительные условия.
Установка и настройка gcloud CLI
- Если еще не установлено, установите
gcloudCLI. - Следуйте разделу
Перед тем как начатьв этом руководстве, чтобы настроить необходимые конфигурации, параметры и разрешения для запуска шаблона DataFlow.
Команда Запуска
Используйте команду gcloud dataflow flex-template run
для запуска задания Dataflow, которое использует гибкий шаблон.
Ниже приведен пример команды:
Разбор Команды
- Имя задания: Текст, следующий за ключевым словом
run, является уникальным именем задания. - Файл шаблона: JSON-файл, указанный в
--template-file-gcs-location, определяет структуру шаблона и детали о принимаемых параметрах. Указанный путь к файлу является публичным и готовым к использованию. - Параметры: Параметры разделяются запятыми. Для параметров строкового типа заключайте значения в двойные кавычки.
Ожидаемый Ответ
После выполнения команды вы должны увидеть ответ, похожий на следующий:
Мониторинг задания
Перейдите на вкладку Работы Dataflow в вашей консоли Google Cloud, чтобы мониторить статус задания. Вы найдёте детали задания, включая прогресс и любые ошибки:
Устранение неполадок
Код: 241. DB::Exception: Превышен лимит памяти (всего)
Эта ошибка возникает, когда ClickHouse исчерпывает память при обработке больших партий данных. Чтобы решить эту проблему:
- Увеличьте ресурсы экземпляра: Upgrade your ClickHouse server to a larger instance with more memory to handle the data processing load.
- Уменьшите размер партии: Настройте размер партии в конфигурации задания Dataflow, чтобы отправлять меньшие объемы данных в ClickHouse, уменьшая потребление памяти на партию. Эти изменения могут помочь сбалансировать использование ресурсов во время приема данных.
Исходный код шаблона
Исходный код шаблона доступен в форке ClickHouse DataflowTemplates