SeaTunnel GoogleFirestore Sink 连接器完整指南:配置、类型映射与写入原理

原创2026-09-18 11:30:361,391 阅读
文章标签:数据集成ETL大数据数据同步变更数据捕获流处理批处理

SeaTunnel GoogleFirestore Sink 连接器完整指南:配置、类型映射与写入原理

Google Firestore 是 Google Cloud 提供的无服务器 NoSQL 文档数据库。SeaTunnel 的 GoogleFirestore Sink 连接器负责把 SeaTunnel 作业中的每一条数据行转换为一个 Firestore 文档,写入指定的集合(Collection),同时支持 Spark、Flink 与 SeaTunnel Zeta 三种引擎。读完本文,你将掌握该连接器的全部配置项、Base64 凭证生成方式、SeaTunnel 与 Firestore 之间的数据类型映射,以及其“逐条 add 追加写入、文档 ID 自动生成”的底层实现原理,并能直接照抄示例运行批量或流式写入作业。

概述与适用场景

GoogleFirestore 是 SeaTunnel Connector V2 体系中的一个 Sink(写入端) 连接器,源码位于 connector-google-firestore 模块。它面向如下典型场景:

  • 将批处理任务产出的结果集(如来自 JDBC、Hive、文件等 Source 的数据)落地到 Firestore 集合;
  • 将实时数据流(如 Kafka、Pulsar、CDC 数据)持续追加写入 Firestore 集合,供前端应用实时读取;
  • 在数据集成管道中,把 Firestore 作为最终存储或灾备副本。

需要特别注意的是:该连接器只提供 Sink,不提供 Firestore Source,且写入语义是“追加生成新文档”,不会按用户指定的文档 ID 更新已有文档。

支持的引擎与特性矩阵

该连接器可以在以下引擎上运行(见 GoogleFirestore 官方文档):

  • Spark
  • Flink
  • SeaTunnel Zeta

从特性矩阵来看(特性定义参见 Connector V2 特性说明):

特性 支持情况
精确一次(Exactly Once) 不支持
CDC 不支持
批处理(BATCH) 支持
流处理(STREAMING) 支持
多表写入 不支持
定时刷新 不支持

其中“多表写入”不支持的具体含义是:每个 Sink 配置块只写入一个固定的 collection,不会根据多表输入自动切换集合;如果要把数据写入多个集合,需要为每个目标集合分别配置一个 Sink 块。

依赖安装

使用该连接器需要先安装依赖,既可以通过 SeaTunnel 自带的 install-plugin.sh 脚本安装,也可以直接从 Maven 中央仓库下载构件 org.apache.seatunnel:connector-google-firestore。

从 pom.xml 可以看到,该模块的核心依赖是 com.google.cloud:google-cloud-firestore(当前仓库锁定版本为 3.7.10),并显式声明了 guava 31.1-android;在打包阶段,maven-shade-plugin 会把 com.google.common 与 com.google.protobuf 两个包重定位到 org.apache.seatunnel.shade.google.firestore.* 命名空间下,从而避免与作业中其他组件产生类冲突。这一隔离策略与 连接器隔离依赖说明 中描述的 Connector 运行时边界思路一致。

配置选项详解

连接器的全部配置项由 FirestoreSinkOptions 定义,并通过 FirestoreSinkFactory 中的 OptionRule 完成必填/可选与“非空白”校验:

名称 类型 必填 默认值 说明
project_id string 是 - Firestore 数据库所在的非空白 Google Cloud 项目 ID
collection string 是 - 要写入的非空白 Firestore 集合名称
credentials string 否 - Base64 编码后的 Google Cloud 服务账号 JSON;配置时不能为空白
common-options - 否 - Sink 通用选项,详见 Sink 通用选项

project_id [string]

Firestore 数据库所在的 Google Cloud 项目 ID。此选项必填,且不能为空白。在 OptionRule 中通过 required(PROJECT_ID, notBlank(PROJECT_ID)) 声明,也就是说既不能缺失,也不能是空字符串或纯空白字符。

collection [string]

要写入的 Firestore 集合名称。此选项必填,且不能为空白。每个 sink 配置块写入一个集合;多集合场景需配置多个 Sink 块。

credentials [string]

可选的 Base64 编码 Google Cloud 服务账号 JSON。配置此选项时,值不能为空白。

如果不配置该参数,连接器会使用 Google 应用默认凭证(Application Default Credentials,ADC)。此时需要确保环境变量 GOOGLE_APPLICATION_CREDENTIALS 指向服务账号 JSON 文件,或者运行环境本身已经提供了默认凭证(如 GCE/GAE/GKE 上的元数据服务)。

可以用下面的命令生成该配置值(Linux/macOS 通用写法):

base64 -w 0 service-account.json

macOS 也可以使用:

base64 service-account.json | tr -d '\n'

注意:credentials 不能直接填写服务账号 JSON 原文,必须先做 Base64 编码;如果该字段一旦配置,就不能为空白(空串、空格、制表符等都会被校验拒绝)。

通用选项

Sink 插件通用参数(如 plugin_input、common-options 中定义的其他能力),请参考 Sink 通用选项。

参数校验行为(测试用例佐证)

FirestoreFactoryTest 对该连接器的参数校验行为给出了明确验证:

  • 合法的配置(仅 project_id + collection,或额外带上 credentials)可以通过校验;
  • 缺失 project_id 或 collection 会抛出 OptionValidationException;
  • project_id、collection、credentials 若取值为 ""、" "、"\t"、"\n"、"\r"、" \t\r\n " 等空白字符串,均会被拒绝;
  • 配置中混入未知键(如 unknown_option)同样会被 validateUnknownKeys 拒绝。

这说明该连接器对配置的约束非常严格,作业启动前即可快速暴露配置错误,而不是等到写数据时才失败。

支持的数据类型映射

SeaTunnel 行中的字段会由 DefaultSeaTunnelRowSerializer 逐一转换为 Firestore 支持的值类型,映射关系如下:

SeaTunnel 类型 Firestore 值
TINYINT 整数
SMALLINT 整数
INT 整数
BIGINT 整数
FLOAT 双精度浮点数
DOUBLE 双精度浮点数
DECIMAL 十进制数
STRING 字符串
BOOLEAN 布尔值
BYTES 二进制 Blob
DATE UTC 当天零点日期
TIMESTAMP 时间戳
ARRAY 数组
MAP Map
NULL null

从源码实现来看,序列化过程有几个值得注意的细节:

  • TINYINT/SMALLINT/INT 统一收敛为 int,BIGINT 保留为 long;
  • FLOAT 会先转成 Double 再写入,因此 Float 类型的数据在 Firestore 中一律以双精度浮点数存储;
  • DECIMAL 保留为 java.math.BigDecimal,精度不受损失;
  • BYTES 被包装成 Firestore 的 Blob 类型;
  • DATE 会按 LocalDate.atStartOfDay(ZoneOffset.UTC) 转换为 UTC 当天的零点时刻;
  • TIMESTAMP 使用 com.google.cloud.Timestamp 表示;
  • ARRAY 会递归转换元素类型后输出为 List,MAP 会递归转换 value 类型后输出为 Map;
  • 字段值为 null 时直接写入 null。

上游 SeaTunnel schema 中的字段名会原样作为 Firestore 文档的字段名,因此在设计上游字段时要注意 Firestore 对字段名的命名约束(不能以特殊字符开头等)。

写入行为与底层原理

连接器类结构

从源码结构看,该连接器由以下核心类组成(包路径均为 org.apache.seatunnel.connectors.seatunnel.google.firestore):

凭证与客户端初始化

FirestoreSinkWriter 构造时的凭证解析逻辑如下:

  1. 如果配置了 credentials,先用 Base64.getDecoder().decode(...) 解码,再通过 GoogleCredentials.fromStream(...) 从解码后的字节流构建服务账号凭证;
  2. 如果没有配置,则调用 GoogleCredentials.getApplicationDefault() 走应用默认凭证链路;
  3. 随后用 FirestoreOptions.getDefaultInstance().toBuilder().setProjectId(...).setCredentials(...).build() 构建客户端选项,getService() 取得 Firestore 客户端,firestore.collection(...) 取得目标集合引用。

逐条 add 写入:无缓冲、无批量

写入方法是整个连接器最核心的行为(FirestoreSinkWriter.write()):

@Override
public void write(SeaTunnelRow seaTunnelRow) throws IOException {
    collectionReference.add(serializer.serialize(seaTunnelRow));
}

也就是说:

  • 每一条 SeaTunnel 记录都会直接触发一次 Firestore 客户端的 add(...) 调用,生成一个文档 ID 由 Firestore 自动分配的新文档;
  • 写入过程中不会缓冲、不会攒批,因此并没有“checkpoint 前把内存写缓冲刷到 Firestore”这一行为;
  • 在 STREAMING 模式下,checkpoint 完成并不意味着此前调用过的所有写入都已真正到达 Firestore——因为 add 返回的是异步 ApiFuture,而当前实现并未等待其完成。这一点对“精确一次”语义有直接影响,也解释了为什么特性矩阵中“精确一次”为不支持。

另外,Writer 在 close() 时会关闭 Firestore 客户端,若关闭失败会抛出携带错误码 FIRESTORE-01("Close Firestore client failed")的 FirestoreConnectorException。

关于索引与文档 ID 的注意事项

  • 该 Sink 不会创建或管理 Firestore 索引;如果后续查询需要索引,请先在 Google Cloud 控制台或通过 gcloud 创建;
  • Firestore 文档 ID 一律自动生成。如果需要固定文档 ID,请在写入前使用其他连接器或转换(Transform)预先处理(例如把目标文档 ID 作为字段、通过后续处理或自定义逻辑写入);
  • Sink 不会按 UPDATE 或 DELETE 行类型执行 CDC 语义——每条记录都会触发一次 Firestore add 调用生成新文档,即使上游是 CDC 变更数据,到达 Firestore 后也是追加的新文档。

任务示例

以下示例来自 GoogleFirestore 官方文档,可直接保存为 .conf 文件后用 seatunnel.sh 提交运行。

批量写入带类型的记录

该示例用 FakeSource 生成一条覆盖全部受支持数据类型的记录,并批量写入 Firestore:

env {
  parallelism = 1
  job.mode = "BATCH"
}

source {
  FakeSource {
    schema = {
      fields {
        c_map = "map<string, string>"
        c_array = "array<int>"
        c_string = string
        c_boolean = boolean
        c_tinyint = tinyint
        c_smallint = smallint
        c_int = int
        c_bigint = bigint
        c_float = float
        c_double = double
        c_decimal = "decimal(30, 8)"
        c_null = "null"
        c_bytes = bytes
        c_date = date
        c_timestamp = timestamp
      }
    }
    rows = [
      {
        kind = INSERT
        fields = [{"a": "b"}, [10], "c_string", true, 117, 15987, 56387395, 7084913402530365000, 1.23, 1.23, "2924137191386439303744.39292216", null, "bWlJWmo=", "2023-04-22", "2023-04-22T23:20:58"]
      }
    ]
  }
}

sink {
  GoogleFirestore {
    project_id = "dummy-project"
    collection = "dummy-collection"
    credentials = "base64-service-account-json"
  }
}

示例要点:

  • c_decimal 使用 decimal(30, 8) 声明高精度十进制,写入 Firestore 时保留 BigDecimal 精度;
  • c_bytes 的取值 "bWlJWmo=" 是 Base64 编码的字节串,序列化时会被还原为字节数组并包装成 Firestore Blob;
  • c_null 声明为 null 类型,序列化时直接写入 null;
  • 实际运行时请把 dummy-project、dummy-collection、base64-service-account-json 替换为真实值。

流式写入并启用 Checkpoint 间隔

该示例演示 STREAMING 模式下通过 plugin_input / plugin_output 显式连接 Source 与 Sink,并配置 checkpoint.interval:

env {
  parallelism = 1
  job.mode = "STREAMING"
  checkpoint.interval = 30000
}

source {
  FakeSource {
    row.num = 100
    schema = {
      fields {
        c_string = string
        c_int = int
        c_timestamp = timestamp
      }
    }
    plugin_output = "firestore_stream"
  }
}

sink {
  GoogleFirestore {
    plugin_input = "firestore_stream"
    project_id = "my-gcp-project"
    collection = "events"
    credentials = "base64-service-account-json"
  }
}

示例要点:

  • plugin_output = "firestore_stream" 与 plugin_input = "firestore_stream" 必须成对出现,用于在多 Source / 多 Sink 场景下显式绑定数据流;
  • checkpoint.interval = 30000 表示每 30 秒触发一次 checkpoint;
  • 结合前文的原理分析,该模式下每条记录仍会直接 add 到 Firestore,checkpoint 只用于作业状态管理,并不代表数据已落库。

常见问题与使用建议

结合官方文档的“注意事项”与源码实现,给出如下实践建议:

  1. 凭证不能直接填 JSON 原文:credentials 字段必须为 Base64 编码后的服务账号 JSON;如果选择不配置,则务必保证运行环境的 GOOGLE_APPLICATION_CREDENTIALS 环境变量或默认凭证链路可用。
  2. 多集合写入要拆多个 Sink 块:每个 GoogleFirestore Sink 块只写一个 collection,需要写入 N 个集合就配置 N 个 Sink 块。
  3. 不要依赖固定文档 ID:文档 ID 由 Firestore add 自动生成;如需固定 ID,需在写入前用其他连接器或转换处理。
  4. CDC 数据请勿期望 UPDATE/DELETE 语义:每条记录都会追加生成新文档,Firestore 中的历史数据会不断累积。
  5. 正确看待 checkpoint 与数据可见性:FirestoreSinkWriter.write() 对每条记录直接调用 add(...),没有缓冲与批量刷写逻辑;因此作业 checkpoint 完成不代表所有写入都已到达 Firestore,恰好一次语义需要额外的幂等设计与对账机制。
  6. 字段名会原样写入:上游 schema 字段名即 Firestore 文档字段名,需遵守 Firestore 字段命名规范。
  7. 索引需要自建:连接器不创建/管理索引,查询前请先在 Google Cloud 侧创建所需索引。

变更日志

该连接器的历史变更与版本演进记录见 connector-google-firestore 变更日志。

登录后查看全文
seatunnel