跳到主要内容
跳到主要内容

Dataflow BigQuery to ClickHouse 模板

BigQuery 到 ClickHouse 模板是一个批处理管道，用于将数据从 BigQuery 表导入 ClickHouse 表。该模板可以读取整个表或使用提供的 SQL 查询过滤特定记录。

管道要求​

  • 源 BigQuery 表必须存在。
  • 目标 ClickHouse 表必须存在。
  • ClickHouse 主机必须可从 Dataflow 工作节点访问。

模板参数​



参数名称参数描述是否必需备注
jdbcUrlClickHouse JDBC URL，格式为 jdbc:clickhouse://<host>:<port>/<schema>。✅不要将用户名和密码作为 JDBC 选项添加。可以在 JDBC URL 的末尾添加其他 JDBC 选项。对于 ClickHouse Cloud 用户，请在 jdbcUrl 中添加 ssl=true&sslmode=NONE。
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 Storage Read API 直接从 BigQuery 存储读取数据。请注意 Storage Read API 限制。
outputDeadletterTable用于存储未能到达输出表的消息的 BigQuery 表。如果表不存在，则在管道执行期间创建。如果未指定，则使用 <outputTableSpec>_error_records。例如，<PROJECT_ID>:<DATASET_NAME>.<DEADLETTER_TABLE>。
query用于从 BigQuery 读取数据的 SQL 查询。如果 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 参数的默认值可以在 ClickHouseIO Apache Beam Connector 中找到。

源和目标表架构​

为了有效地将 BigQuery 数据集加载到 ClickHouse，管道执行以下阶段的列推断过程：

  1. 模板根据目标 ClickHouse 表构建架构对象。
  2. 模板遍历 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 执行。

备注

务必查看本文档，特别是上述部分，以全面了解模板的配置要求和先决条件。

登录到您的 Google Cloud 控制台并搜索 DataFlow。

  1. 按下 CREATE JOB FROM TEMPLATE 按钮
    DataFlow console
  2. 模板表单打开后，输入作业名称并选择所需区域。
    DataFlow template initial form
  3. 在 DataFlow Template 输入框中，输入 ClickHouse 或 BigQuery，并选择 BigQuery 到 ClickHouse 模板
    Select BigQuery to ClickHouse template
  4. 选中后，表单将展开以允许您提供其他详细信息：
    • ClickHouse 服务器 JDBC URL，格式为 jdbc:clickhouse://host:port/schema。
    • ClickHouse 用户名。
    • ClickHouse 目标表名称。

备注

ClickHouse 密码选项被标记为可选，适用于未配置密码的用例。 要添加它，请向下滚动到 Password for ClickHouse Endpoint 选项。

BigQuery to ClickHouse extended template form
  1. 根据 模板参数 部分的详细信息自定义并添加任何与 BigQuery/ClickHouseIO 相关的配置。

监控作业​

导航到您的 Google Cloud 控制台中的 Dataflow Jobs tab 以监控作业的状态。您将找到作业的详细信息，包括进度和任何错误：

DataFlow console showing a running BigQuery to ClickHouse job

故障排除​

内存限制（总）超出错误（代码 241）​

当 ClickHouse 在处理大型数据批次时内存不足时，会出现此错误。为解决此问题：

  • 增加实例资源：将 ClickHouse 服务器升级到更大的实例，以便拥有更多内存来处理数据处理负荷。
  • 减少批量大小：调整 Dataflow 作业配置中的批量大小，以便将较小的数据块发送到 ClickHouse，降低每个批次的内存消耗。这些更改可以帮助在数据摄取期间平衡资源使用。

模板源代码​

模板的源代码可在 ClickHouse 的 DataflowTemplates 分支中找到。