SeaTunnel GraphQL Sink Connector 完全指南:基于 Mutation 的实时数据写入实践

原创2026-09-16 09:31:551,972 阅读
文章标签:数据集成ETL大数据数据同步变更数据捕获流处理批处理

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 的构造函数中完成以下关键步骤:

  1. 构建 HttpParameter,并读取 query 配置;
  2. 调用 GraphQLUtil.validateSinkOperation(query) 校验操作类型;
  3. 调用 GraphQLUtil.validateUrlProtocol(url, false) 校验 URL 协议前缀;
  4. 将 variables 与 query 组装为 JSON body:若无 variables 配置则填充 "{}";
  5. 强制设置 HTTP 方法为 POST;
  6. 若配置了 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:

  1. 从 HTTP body 中取出 query 与 variables 模板;
  2. 遍历行类型的所有字段,将字段名与字段值放入 variables 模板:
    • 若 valueCover == true 且模板中已存在同名 key,则跳过(保留配置值);
    • 否则以行字段值覆盖/写入同名变量;
  3. 组装 {"query": ..., "variables": ...} 请求体(使用 Gson 序列化);
  4. 通过 HttpClientProvider 执行 HTTP POST;
  5. 响应码等于 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 时需要留意以下约束:

  1. 操作类型限制:Sink 会校验 query 必须是 GraphQL mutation;query 与 subscription 类型都会在启动阶段被拒绝;
  2. URL 协议:Sink 模式仅接受 http:// 或 https:// 前缀的端点;
  3. 字段名匹配:上游行字段名应与 mutation 使用的变量名保持一致,否则变量无法被正确填充;
  4. valueCover 语义:若 variables 已包含某个 key 且 valueCover = true,则保留配置值;valueCover = false(默认)时行字段值覆盖同名变量;
  5. 逐行请求:Sink 对每条输入行发送一次 mutation 请求,无批处理合并;高吞吐场景下需关注目标 GraphQL 服务的承载能力;
  6. 多表约束:上游含多张表时,需确保同一条 mutation 及变量名能覆盖所有路由到该 Sink 的表;multi_table_sink_replica 只改变多表 Sink 运行时副本数,不改变 mutation 选择;
  7. 重试边界:retry 仅在请求抛出 IOException 时触发,非 2xx 响应不会自动重试,只会记录错误日志。

版本演进(Changelog)

根据 connector-graphql 变更日志:

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} 的用法来源)。

延伸阅读

登录后查看全文
seatunnel