SeaTunnel GoogleFirestore Sink 连接器完整指南:配置、类型映射与写入原理
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):
- FirestoreSink:继承
AbstractSimpleSink,插件名GoogleFirestore,负责基于CatalogTable与FirestoreParameters创建 Writer; - FirestoreSinkWriter:负责构建 Firestore 客户端、持有集合引用并执行写入;
- FirestoreSinkFactory:通过
@AutoService(Factory.class)注册工厂,factoryIdentifier()返回"GoogleFirestore"; - FirestoreParameters:把
ReadonlyConfig解析为projectId、credentials、collection三个字段; - SeaTunnelRowSerializer 及其默认实现 DefaultSeaTunnelRowSerializer:完成“行 → Firestore 文档 Map”的转换。
凭证与客户端初始化
FirestoreSinkWriter 构造时的凭证解析逻辑如下:
- 如果配置了
credentials,先用Base64.getDecoder().decode(...)解码,再通过GoogleCredentials.fromStream(...)从解码后的字节流构建服务账号凭证; - 如果没有配置,则调用
GoogleCredentials.getApplicationDefault()走应用默认凭证链路; - 随后用
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 语义——每条记录都会触发一次 Firestoreadd调用生成新文档,即使上游是 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 编码的字节串,序列化时会被还原为字节数组并包装成 FirestoreBlob;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 只用于作业状态管理,并不代表数据已落库。
常见问题与使用建议
结合官方文档的“注意事项”与源码实现,给出如下实践建议:
- 凭证不能直接填 JSON 原文:
credentials字段必须为 Base64 编码后的服务账号 JSON;如果选择不配置,则务必保证运行环境的GOOGLE_APPLICATION_CREDENTIALS环境变量或默认凭证链路可用。 - 多集合写入要拆多个 Sink 块:每个
GoogleFirestoreSink 块只写一个collection,需要写入 N 个集合就配置 N 个 Sink 块。 - 不要依赖固定文档 ID:文档 ID 由 Firestore
add自动生成;如需固定 ID,需在写入前用其他连接器或转换处理。 - CDC 数据请勿期望 UPDATE/DELETE 语义:每条记录都会追加生成新文档,Firestore 中的历史数据会不断累积。
- 正确看待 checkpoint 与数据可见性:
FirestoreSinkWriter.write()对每条记录直接调用add(...),没有缓冲与批量刷写逻辑;因此作业 checkpoint 完成不代表所有写入都已到达 Firestore,恰好一次语义需要额外的幂等设计与对账机制。 - 字段名会原样写入:上游 schema 字段名即 Firestore 文档字段名,需遵守 Firestore 字段命名规范。
- 索引需要自建:连接器不创建/管理索引,查询前请先在 Google Cloud 侧创建所需索引。
变更日志
该连接器的历史变更与版本演进记录见 connector-google-firestore 变更日志。