SeaTunnel GraphQL Sink Connector 完全指南:基于 Mutation 的实时数据写入实践
SeaTunnel GraphQL Sink Connector 完全指南:基于 Mutation 的实时数据写入实践
导读
本文围绕 SeaTunnel 的 GraphQL Sink Connector 展开,讲解如何将 SeaTunnel 中的数据行通过 GraphQL mutation(变更操作)以 HTTP POST 方式写入任意 GraphQL 服务。你将掌握 GraphQL Sink 的全部配置参数及其底层实现原理、variables 与 valueCover 的变量合并机制、基于重试与指数退避的容错策略,以及面向批处理、流处理和多表写入场景的完整 HOCON 配置实战示例。本文以官方文档 GraphQL.md 为主体,并结合 connector-graphql 模块源码进行深度佐证。
GraphQL Sink 是什么
GraphQL Sink 是一个将 SeaTunnel 行数据写入 GraphQL 服务的连接器。它针对每条输入行构造一次 GraphQL mutation 请求,通过 HTTP POST 发送到目标服务:
- 每条输入行的字段会被添加到 GraphQL 请求的
variables中,字段名与变量名一一对应; - 连接器会按配置发送预先定义好的 mutation 语句;
- Sink 模式强制要求请求为
mutation,不支持query与subscription。
从源码结构看,该连接器位于 connector-graphql 模块,其 Sink 实现(GraphQLSink.java)继承自 AbstractSimpleSink 并实现了 SupportMultiTableSink 接口,同时复用 HTTP 连接器基础模块(connector-http-base)的 HTTP 客户端能力。
支持引擎
GraphQL Sink 支持以下引擎运行环境:
- Spark
- Flink
- SeaTunnel Zeta
在 SeaTunnel Zeta 引擎下,无需额外部署 Flink/Spark 环境,直接提交任务即可运行。
Key Features(能力特性)
连接器能力矩阵(详见 connector-v2-features):
| 特性 | 是否支持 |
|---|---|
| exactly-once(精确一次) | ❌ 不支持 |
| cdc(变更数据捕获) | ❌ 不支持 |
| support multiple table write(多表写入) | ✅ 支持 |
| timer flush(定时刷新) | ❌ 不支持 |
其中“多表写入”能力来自 SupportMultiTableSink 接口,从源码可见 GraphQLSink.java 明确实现了该接口。
依赖引入
使用 GraphQL Sink 前需要引入连接器依赖,可通过 install-plugin.sh 脚本安装,或从 Maven 中央仓库获取:
| Datasource | Supported Versions | Dependency |
|---|---|---|
| GraphQL | universal(通用) | org.apache.seatunnel:connector-graphql |
从 connector-graphql/pom.xml 可以看到该模块的核心依赖:
connector-common与connector-http-base(项目内部依赖,提供 HTTP 客户端与通用 Sink 能力);com.graphql-java:graphql-java:20.0(用于解析并校验 GraphQL 语句的操作类型);gson:2.10.1(请求体 JSON 序列化);okhttp:4.12.0(底层 HTTP 通信)。
Sink 参数详解
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| url | String | Yes | - | GraphQL HTTP 端点。Sink 模式要求以 http:// 或 https:// 开头。 |
| query | String | Yes | - | GraphQL mutation 语句。Sink 仅支持 mutation 操作。 |
| variables | Map | No | - | 初始 GraphQL 变量。每次请求前,输入行的字段会被并入该 Map。 |
| valueCover | Boolean | No | false | 为 false 时,输入行字段会覆盖同名变量;为 true 时,保留配置中已有的变量值。 |
| timeout | Long | No | - | 请求超时时间,会传入 HTTP 客户端参数表。 |
| headers | Map | No | - | HTTP 请求头,如认证头 Authorization。 |
| params | Map | No | - | HTTP 请求参数。 |
| retry | Int | No | - | HTTP 请求抛出 IOException 时的最大重试次数。 |
| retry_backoff_multiplier_ms | Int | No | 100 | HTTP 重试退避倍数(毫秒)。 |
| retry_backoff_max_ms | Int | No | 10000 | HTTP 重试退避上限(毫秒)。 |
| connect_timeout_ms | Int | No | 12000 | HTTP 连接超时(毫秒)。 |
| socket_timeout_ms | Int | No | 60000 | HTTP socket 超时(毫秒)。 |
| multi_table_sink_replica | Int | No | - | Sink 通用参数,控制多表运行时 Sink 副本数。所有路由到该 Sink 的行仍使用同一条 mutation。 |
| common-options | Config | No | - | Sink 通用选项,详见 Sink Common Options。 |
参数背后的源码实现
上述参数中,url、retry、retry_backoff_multiplier_ms、retry_backoff_max_ms、headers、params 定义在 HTTP 基础模块的 HttpCommonOptions.java 中,GraphQL Sink 通过继承 HttpCommonOptions 复用;query、variables、timeout、valueCover 则是 GraphQL 专有参数,定义在 GraphQLSinkOptions.java:
query:String 类型,无默认值,语义为 “GraphQL query”;variables:Map 类型,默认null,语义为 “GraphQL variables”;timeout:Long 类型,无默认值,语义为超时周期;valueCover:Boolean 类型,默认false,语义为 “value cover”。
connect_timeout_ms 与 socket_timeout_ms 的默认值(12000/60000)来自 HTTP 客户端的参数构建逻辑(见 connector-http-base 中的 HttpParameter 构建过程),连接器启动时会统一组装进 HttpParameter。
工作原理:从配置到请求的完整链路
1. 参数校验与组装
在 GraphQLSinkParameter.java 的构造函数中完成以下关键步骤:
- 构建
HttpParameter,并读取query配置; - 调用
GraphQLUtil.validateSinkOperation(query)校验操作类型; - 调用
GraphQLUtil.validateUrlProtocol(url, false)校验 URL 协议前缀; - 将
variables与query组装为 JSON body:若无variables配置则填充"{}"; - 强制设置 HTTP 方法为
POST; - 若配置了
timeout,将其写入 HTTP 参数表中。
2. 操作类型校验(仅允许 mutation)
操作类型校验由 GraphQLUtil.java 完成。核心逻辑是使用 graphql-java 的 Parser 解析 query 文本,提取首个 OperationDefinition 的操作类型:
Document document = new Parser().parseDocument(query);
OperationDefinition.Operation operationType =
document.getDefinitionsOfType(OperationDefinition.class).stream()
.findFirst()
.map(OperationDefinition::getOperation)
.orElse(null);
validateSinkOperation 只放行 MUTATION,若解析结果为 QUERY、SUBSCRIPTION 或其他类型,则抛出 GraphQLConnectorException,错误码为 GRAPHQL_SINK_PARAMETER_ERROR,提示 “GraphQL Sink unsupported operation type”。
URL 协议校验则要求必须以 http:// 或 https:// 开头,否则抛出 PROTOCOL_ERROR。
3. 逐行写入与变量合并
写入逻辑位于 GraphQLSinkWriter.java,它继承自 HTTP Sink 的 HttpSinkWriter,并重写了 write 方法。对每条 SeaTunnelRow:
- 从 HTTP body 中取出
query与variables模板; - 遍历行类型的所有字段,将字段名与字段值放入
variables模板:- 若
valueCover == true且模板中已存在同名 key,则跳过(保留配置值); - 否则以行字段值覆盖/写入同名变量;
- 若
- 组装
{"query": ..., "variables": ...}请求体(使用 Gson 序列化); - 通过
HttpClientProvider执行 HTTP POST; - 响应码等于
200(HttpResponse.STATUS_OK)视为成功,否则记录错误日志;请求异常时抛出CommonError.jsonOperationError。
这也印证了文档中的说明:Sink 对每条输入行发送一次 mutation 请求。因此,当上游包含多张表时,必须保证同一条 mutation 及其变量名能处理所有路由到该 Sink 的表。
4. 重试与指数退避
retry、retry_backoff_multiplier_ms、retry_backoff_max_ms 三个参数用于吸收瞬时 HTTP 故障。其中退避倍率默认 100ms、退避上限默认 10000ms,这两个默认常量定义在 HttpCommonOptions.java 中。重试仅在 HTTP 请求抛出 IOException 时触发,采用指数退避策略(每次重试间隔按倍率递增,且不超过上限)。
任务示例
以下示例均来自官方文档,可直接在 SeaTunnel 的 HOCON 配置文件中使用。
示例一:通过 GraphQL Mutation 写入行数据(批处理)
env {
parallelism = 1
job.mode = "BATCH"
}
source {
FakeSource {
plugin_output = "fake"
schema = {
fields {
id = int
val_bool = boolean
val_int8 = tinyint
val_int16 = smallint
val_int32 = int
val_int64 = bigint
val_float = float
val_double = double
val_decimal = "decimal(16, 1)"
val_string = string
val_unixtime_micros = timestamp
}
}
rows = [
{
kind = INSERT
fields = [1, true, 1, 2, 3, 4, 4.3, 5.3, 6.3, "NEW", "2020-02-02T02:02:02"]
}
]
}
}
sink {
GraphQL {
plugin_input = "fake"
url = "http://graphql:8080/v1/graphql"
query = """
mutation MyMutation(
$id: Int!
$val_bool: Boolean!
$val_int8: smallint!
$val_int16: smallint!
$val_int32: Int!
$val_int64: bigint!
$val_float: Float!
$val_double: Float!
$val_decimal: numeric!
$val_string: String!
$val_unixtime_micros: timestamp!
) {
insert_sink(objects: {
id: $id,
val_bool: $val_bool,
val_int8: $val_int8,
val_int16: $val_int16,
val_int32: $val_int32,
val_int64: $val_int64,
val_float: $val_float,
val_double: $val_double,
val_decimal: $val_decimal,
val_string: $val_string,
val_unixtime_micros: $val_unixtime_micros
}) {
affected_rows
}
}
"""
}
}
要点解析:
- 上游
schema中的字段名(id、val_bool等)必须与 mutation 中声明的变量名一致,Sink 才会将行字段填充到variables; - mutation 变量类型需与上游字段类型匹配(如
tinyint/smallint映射为 GraphQL 标量smallint、decimal(16,1)映射为numeric、timestamp映射为timestamp); - 示例中的
url指向 Hasura 风格 GraphQL 端点(/v1/graphql),实际使用时替换为你的目标服务地址; - 本例未显式配置
variables,Sink 会将其初始化为空 Map,行字段全部按同名写入。
示例二:保留已配置的变量值(valueCover = true)
sink {
GraphQL {
plugin_input = "fake"
url = "http://graphql:8080/v1/graphql"
valueCover = true
variables = {
val_bool = true
}
query = """
mutation MyMutation($id: Int!, $val_bool: Boolean!) {
insert_sink(objects: {id: $id, val_bool: $val_bool}) {
affected_rows
}
}
"""
}
}
要点解析:当 valueCover = true 时,即使上游行中带有 val_bool 字段,Sink 也会保留 variables 中配置的 val_bool = true,而不会用行数据覆盖。对应源码中 GraphQLSinkWriter.java 的 if (valueCover && vars.contains(fieldName)) { continue; } 分支。反之,当 valueCover = false(默认)时,行字段值会替换同名的 variables 值。
示例三:流式 Mutation 写入(流处理 + 重试退避)
env {
parallelism = 2
job.mode = "STREAMING"
checkpoint.interval = 30000
}
source {
FakeSource {
plugin_output = "events"
schema = {
fields {
id = int
val_string = string
}
}
rows = [
{ kind = INSERT, fields = [1, "first"] }
{ kind = INSERT, fields = [2, "second"] }
]
}
}
sink {
GraphQL {
plugin_input = "events"
url = "http://graphql:8080/v1/graphql"
headers = {
Authorization = "Bearer ${secret}"
}
query = """
mutation MyMutation($id: Int!, $val_string: String!) {
insert_event(objects: {id: $id, val_string: $val_string}) {
affected_rows
}
}
"""
retry = 5
retry_backoff_multiplier_ms = 200
retry_backoff_max_ms = 5000
}
}
要点解析:
job.mode = "STREAMING"下 Sink 持续运行,对每条行发送一次 mutation;headers中的Authorization用于携带认证信息,这里使用了${secret}占位符,实际值由环境变量/参数注入(该占位符替换能力自 2.3.11 版本引入,见下文变更日志);retry = 5表示最多重试 5 次;retry_backoff_multiplier_ms = 200表示退避间隔以 200ms 为基数递增;retry_backoff_max_ms = 5000表示退避间隔封顶 5000ms。通过指数退避可有效吸收服务端的瞬时故障。
示例四:写入多个上游表(多表写入)
source {
FakeSource {
plugin_output = "fake"
tables_configs = [
{
schema = {
table = "graphql_sink_1"
fields {
id = int
val_bool = boolean
val_string = string
}
}
rows = [
{
kind = INSERT
fields = [1, true, "NEW"]
}
]
},
{
schema = {
table = "graphql_sink_2"
fields {
id = int
val_bool = boolean
val_string = string
}
}
rows = [
{
kind = INSERT
fields = [2, true, "READY"]
}
]
}
]
}
}
sink {
GraphQL {
plugin_input = "fake"
url = "http://graphql:8080/v1/graphql"
query = """
mutation MyMutation($id: Int!, $val_bool: Boolean!, $val_string: String!) {
insert_sink(objects: {id: $id, val_bool: $val_bool, val_string: $val_string}) {
affected_rows
}
}
"""
}
}
要点解析:上游 FakeSource 通过 tables_configs 定义两张表 graphql_sink_1 与 graphql_sink_2,二者字段结构一致,因此可以共用同一条 mutation。Sink 端只需一个 GraphQL 配置即可接收两张表的所有行。multi_table_sink_replica 参数仅影响多表运行时的 Sink 副本数量,不会为不同表选择不同的 mutation——所有行仍使用同一条 mutation 写入。
注意事项
使用 GraphQL Sink 时需要留意以下约束:
- 操作类型限制:Sink 会校验
query必须是 GraphQLmutation;query与subscription类型都会在启动阶段被拒绝; - URL 协议:Sink 模式仅接受
http://或https://前缀的端点; - 字段名匹配:上游行字段名应与 mutation 使用的变量名保持一致,否则变量无法被正确填充;
- valueCover 语义:若
variables已包含某个 key 且valueCover = true,则保留配置值;valueCover = false(默认)时行字段值覆盖同名变量; - 逐行请求:Sink 对每条输入行发送一次 mutation 请求,无批处理合并;高吞吐场景下需关注目标 GraphQL 服务的承载能力;
- 多表约束:上游含多张表时,需确保同一条 mutation 及变量名能覆盖所有路由到该 Sink 的表;
multi_table_sink_replica只改变多表 Sink 运行时副本数,不改变 mutation 选择; - 重试边界:
retry仅在请求抛出IOException时触发,非 2xx 响应不会自动重试,只会记录错误日志。
版本演进(Changelog)
| Change | Commit | Version |
|---|---|---|
[Feature][connector-http] 参数支持占位符替换(#9184) |
8617014edc | 2.3.11 |
[Feature][Connector-V2] 支持 GraphQL Connector(#8557、#9021) |
9eec2520c0 | 2.3.11 |
即 GraphQL Connector 自 2.3.11 版本引入,同一版本还带来了 HTTP 参数占位符替换能力(即示例三中 ${secret} 的用法来源)。
延伸阅读
- 连接器通用选项:Sink Common Options
- 连接器能力特性说明:connector-v2-features
- GraphQL Source 使用参考(同模块的读取端能力):connector-graphql 源码
- HTTP 基础连接器(GraphQL 复用了其 HTTP 客户端与重试能力):connector-http-base