HBase CDC Pipeline Sink Connector 用于将火山引擎流式计算 Flink 版 Pipeline 作业捕获的全量数据和增量变更持续写入 HBase。每张源表会按表名模板路由到一张独立的 HBase 表。

功能概述 #

版本兼容性 #

特色功能 #

• 多表同步：每张源表可按模板路由到独立的 HBase namespace 和表。
• row key 映射：可使用源表主键，或通过 rowkey.fields 显式选择一个或多个字段构造 row key。
• 自动资源准备：源端 database 映射为 HBase 的同名 namespace；namespace、表或列族不存在时，Connector 会动态创建对应资源。
• 批量写入：通过大小、条数和时间间隔控制 mutation 缓冲刷新。
• 客户端参数透传：通过 properties.* 传递 HBase 客户端配置。

前提条件 #

1. 已准备可访问的 HBase 2.2 或 2.3 集群，并取得 ZooKeeper quorum 和根 znode。原则上支持火山引擎 HBase 和自建 HBase。
2. Flink 资源池与 HBase ZooKeeper、RegionServer 之间网络可达。
3. 已为作业身份授予创建 HBase namespace、表和列族所需的权限，或已预先创建目标资源。
4. 每张源表已定义主键，或已选择稳定、唯一且非空的字段配置 rowkey.fields。
5. 已确认目标表名模板不会使不同源表写入同一张 HBase 表。

使用限制 #

• Connector 仅支持作为 Flink CDC Pipeline Sink。
• 源表必须存在可用于构造 row key 的字段；未配置 rowkey.fields 时使用源表主键。
• 多字段 row key 通过分隔符拼接。字段内容本身包含分隔符时可能造成歧义，应选择不会出现在字段值中的分隔符。
• Connector 使用 At-Least-Once 语义。故障恢复时近期事件可能被重新写入，稳定 row key 可使覆盖写入结果收敛。
• UPDATE 只覆盖本次事件涉及的列，不会先删除 row key 对应的整行；未参与本次更新的 qualifier 保持不变。
• DELETE 会按 row key 删除整行。
• DROP_TABLE 和 TRUNCATE_TABLE 事件会被忽略，不会删除或清空 HBase 目标表。
• HBase 的列为 schema-less。列类型变化和删除列不会自动清理 HBase 中已有的历史字节值。
• 数据写入前目标列族必须已经存在。可以预先创建，也可以由 Connector 在列族不存在时动态创建。
• 默认情况下，源端 database 映射为 HBase 的同名 namespace；namespace 不存在时 Connector 会自动创建。
• 重命名列会使用新列名写入数据，但旧列名对应的 qualifier 不会自动删除。
• 修改用于构造 row key 的字段时，旧 row key 对应的数据会保留，可能形成新旧两行。
• HBase 版本必须与 type 参数匹配。
• 连接火山引擎 HBase 时，必须将 zookeeper.znode.parent 设置为目标实例实际使用的父路径，例如 /hbase/hb-cnxxxxxxxxxxxxxx，不能直接沿用默认值 /hbase。
• 日期时间字段的编码方式与 Flink SQL HBase Connector 不同，读取端必须按本文的 Pipeline Connector 映射解码。

语法结构 #

source:
  type: <source_type> 
  # Source 参数

sink:
  type: hbase-2.3
  name: HBase Sink
  zookeeper.quorum: <host1:port,host2:port,host3:port>
  zookeeper.znode.parent: <hbase_znode_parent>
  table-name: "${schema}:${table}"
  column.family: cf
  rowkey.fields: id

pipeline:
  name: <pipeline_name>
  parallelism: 2
  local-time-zone: Asia/Shanghai

参数说明 #

连接与路由参数 #

row key 与列族参数 #

缓冲刷新参数 #

透传与建表参数 #

类型映射 #

HBase 将字段值存储为字节数组。下表描述本 Pipeline Connector 的编码方式，下游程序必须使用相同规则解码。

使用示例 #

将 MySQL 表同步到 HBase #

以下示例将 MySQL 中匹配的表同步到对应的 HBase namespace 和表。运行前请替换地址、表名和加密变量名称。

source:
  type: mysql
  name: MySQL Source
  hostname: <mysql_host> 
  port: 3306
  username: ${secret_values.mysql-username}
  password: ${secret_values.mysql-password}
  tables: <source_database>.<source_table>
  server-id: 5401-5404

sink:
  type: hbase-2.3
  name: HBase Sink
  zookeeper.quorum: <zk_host_1:2181,zk_host_2:2181,zk_host_3:2181>
  # 火山引擎 HBase 请替换为目标实例实际的父路径。
  zookeeper.znode.parent: /hbase/hb-cnxxxxxxxxxxxxxx
  table-name: "${schema}:${table}"
  column.family: cf
  rowkey.fields: id
  rowkey.delimiter: _
  charset: UTF-8
  sink.buffer-flush.max-size: 2mb
  sink.buffer-flush.max-rows: 1000
  sink.buffer-flush.interval: 1s

pipeline:
  name: MySQL to HBase Pipeline
  parallelism: 2
  local-time-zone: Asia/Shanghai

预期结果：​作业进入运行状态后，源端 database 映射为 HBase 的同名 namespace。Connector 会在需要时创建 namespace、目标表或列族。源表数据按 id 构造 row key，并写入 ${schema}:${table} 对应的 HBase 表；普通字段写入 cf 列族，family:qualifier 格式的字段写入其显式指定的列族。源端后续变更会持续同步到相同 row key。

运行机制 #

数据写入 #

Connector 将源端记录转换为 HBase mutation，并使用缓冲批量提交。达到 sink.buffer-flush.max-size、sink.buffer-flush.max-rows 或 sink.buffer-flush.interval 任一条件时触发刷新。
INSERT 按 row key 写入记录。UPDATE 按 row key 覆盖本次事件涉及的列，不会先删除整行，未参与本次更新的 qualifier 保持不变。DELETE 按 row key 删除整行。UPDATE 修改 row key 字段时，Connector 会按新的 row key 写入数据，但不会删除旧 row key。

Schema 事件 #

源端 database 映射为 HBase 的同名 namespace；namespace、目标表或列族不存在时，Connector 会动态创建对应资源。新增列会写入新的 qualifier。重命名列会使用新列名写入，但旧 qualifier 不会删除。列类型变化和删除列不会自动修改或清理 HBase 中已有的字段值，作业继续运行。另外不支持DROP_TABLE 和 TRUNCATE_TABLE 事件。

Checkpoint 与故障恢复 #

Connector 提供 At-Least-Once 语义，算子不持久化 mutation 缓冲状态。故障恢复后，近期事件可能被重新处理和刷新。使用稳定且唯一的 row key，可以让相同记录的重复覆盖写入收敛；端到端结果仍取决于 DELETE、主键变化和列清理等业务语义。

常见问题 #

注意事项 #

• At-Least-Once 可能导致重复写入请求。不要使用不稳定字段或随机值构造 row key。
• 更改 rowkey.fields、rowkey.delimiter 或 charset 会改变 row key，可能使同一业务记录写入新行。
• 更改 table-name 模板可能将后续数据路由到新表，变更前应核对实际展开结果。
• HBase row key 设计会影响 Region 分布和热点。高吞吐场景应在建表前完成 row key 分布评估。
• properties.* 和 table.create.properties.* 会直接影响 HBase 客户端或目标表配置，仅使用目标集群已验证的参数。
• table.create.properties.* 没有适用于所有集群的推荐值，不要直接复制其他集群的表或列族属性。
• 列删除不会自动清理历史 qualifier。若业务要求物理删除历史数据，需要单独制定清理方案。
• DROP_TABLE、TRUNCATE_TABLE 会被忽略，源端删除或清空表不会同步删除 HBase 目标数据。

相关文档 #

• 火山引擎流式计算 Flink 版：CDC Connector 列表
• Apache Flink：HBase SQL Connector
• Apache HBase 官方文档