This is an automated email from the ASF dual-hosted git repository.
github-merge-queue[bot] pushed a commit to branch dev
in repository https://gitbox.apache.org/repos/asf/seatunnel.git
The following commit(s) were added to refs/heads/dev by this push:
new f72a75f1aa [Docs] Fix missing, misplaced and divergent connector
documentation verified against source code (#12621)
f72a75f1aa is described below
commit f72a75f1aa120cae0cb7b08d135297950e08132f
Author: Jast <[email protected]>
AuthorDate: Sun Oct 18 14:02:33 2026 +0000
[Docs] Fix missing, misplaced and divergent connector documentation
verified against source code (#12621)
Co-authored-by: jast <[email protected]>
Co-authored-by: Claude Code <[email protected]>
Co-authored-by: multica-agent <[email protected]>
---
docs/en/connector-v2/source/Http-Linear.md | 35 ------
.../connectors/changelog/connector-http-linear.md | 7 ++
.../common-options/sink-common-options.md | 10 ++
docs/en/connectors/source/FakeSource.md | 25 +----
docs/en/connectors/source/Http-Linear.md | 125 +++++++++++++++++++++
.../connectors/changelog/connector-http-linear.md | 7 ++
.../common-options/sink-common-options.md | 7 --
docs/zh/connectors/source/FakeSource.md | 24 +---
docs/zh/connectors/source/Http-Linear.md | 125 +++++++++++++++++++++
9 files changed, 286 insertions(+), 79 deletions(-)
diff --git a/docs/en/connector-v2/source/Http-Linear.md
b/docs/en/connector-v2/source/Http-Linear.md
deleted file mode 100644
index 4d6b240b2d..0000000000
--- a/docs/en/connector-v2/source/Http-Linear.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# Http-Linear
-
-> Http-Linear source connector
-
-## Description
-
-Read data from the Linear API via HTTP.
-
-## Key Features
-
-- [x] batch
-- [ ] stream
-- [ ] exactly-once
-
-## Options
-
-| Name | Type | Required | Default Value | Description |
-| --- | --- | --- | --- | --- |
-| url | String | Yes | - | Linear API Endpoint URL |
-| api_key | String | Yes | - | Linear API Key for Authentication |
-| plugin_output | String | No | - | The result table name when generating data
|
-
-## Example
-
-```hocon
-source {
- Http-Linear {
- url = "https://api.linear.app/graphql";
- api_key = "your_linear_api_key"
- method = "POST"
- body = "{\"query\": \"{ issues { nodes { id title } } }\"}"
- plugin_output = "linear_data"
- }
-}
-```
\ No newline at end of file
diff --git a/docs/en/connectors/changelog/connector-http-linear.md
b/docs/en/connectors/changelog/connector-http-linear.md
new file mode 100644
index 0000000000..4de4886215
--- /dev/null
+++ b/docs/en/connectors/changelog/connector-http-linear.md
@@ -0,0 +1,7 @@
+<details><summary> Change Log </summary>
+
+| Change | Commit | Version |
+| --- | --- | --- |
+|[Feature][Connector-V2] Add Linear HTTP source
connector|[https://github.com/apache/seatunnel/commit/56cfbca0fb](https://github.com/apache/seatunnel/commit/56cfbca0fb)|Next|
+
+</details>
diff --git a/docs/en/connectors/common-options/sink-common-options.md
b/docs/en/connectors/common-options/sink-common-options.md
index 295524f28a..d86b8cb742 100644
--- a/docs/en/connectors/common-options/sink-common-options.md
+++ b/docs/en/connectors/common-options/sink-common-options.md
@@ -20,6 +20,16 @@ The old configuration name `source_table_name` is
deprecated, please migrate to
| plugin_input | String | No | - | When `plugin_input` is not
specified, the current plug-in processes the data set `dataset` output by the
previous plugin in the configuration file <br/> When `plugin_input` is
specified, the current plug-in is processing the data set corresponding to this
parameter. |
| metadata_datasource_id | String | No | - | The data source ID
for retrieving connection configuration from Metadata Center. When specified,
the connector will fetch connection details (e.g., URL, username, password)
from the external metadata service instead of using direct configuration. See
[Metadata SPI](../../introduction/concepts/metadata-spi.md) for more
information. |
+### plugin_input [string]
+
+When `plugin_input` is not specified, the current plug-in processes the data
set `dataset` output by the previous plugin in the configuration file.
+
+When `plugin_input` is specified, the current plug-in is processing the data
set corresponding to this parameter.
+
+### metadata_datasource_id [string]
+
+The data source ID for retrieving connection configuration from Metadata
Center. When specified, the connector will fetch connection details (e.g., URL,
username, password) from the external metadata service instead of using direct
configuration. See [Metadata SPI](../../introduction/concepts/metadata-spi.md)
for more information.
+
# Important note
When the job configuration `plugin_input` you must set the `plugin_output`
parameter
diff --git a/docs/en/connectors/source/FakeSource.md
b/docs/en/connectors/source/FakeSource.md
index 399aeee7ae..f7e04724c3 100644
--- a/docs/en/connectors/source/FakeSource.md
+++ b/docs/en/connectors/source/FakeSource.md
@@ -67,6 +67,12 @@ FakeSource is a virtual source that generates rows from a
user-defined schema. I
| double.min | double | No | 0 |
The min value of double data that connector generated
|
| double.max | double | No | 0x1.fffffffffffffP+1023 |
The max value of double data that connector generated
|
| double.template | list | No | - |
The template list of double type that connector generated, if user configured
it, connector will randomly select an item from the template list
|
+| date.year.template | list | No | - |
The template list of year of date like `yyyy`, if user configured it, connector
will randomly select an item from the template list |
+| date.month.template | list | No | - |
The template list of month of date like `MM`, if user configured it, connector
will randomly select an item from the template list |
+| date.day.template | list | No | - |
The template list of day of date like `dd`, if user configured it, connector
will randomly select an item from the template list |
+| time.hour.template | list | No | - |
The template list of hour of time like `HH`, if user configured it, connector
will randomly select an item from the template list |
+| time.minute.template | list | No | - |
The template list of minute of time like `mm`, if user configured it, connector
will randomly select an item from the template list |
+| time.second.template | list | No | - |
The template list of second of time like `ss`, if user configured it, connector
will randomly select an item from the template list |
| vector.dimension | int | No | 4 |
Dimension of the generated vector, excluding binary vectors
|
| binary.vector.dimension | int | No | 8 |
Dimension of the generated binary vector
|
| vector.float.min | float | No | 0 |
The min value of float data in vector that connector generated
|
@@ -387,25 +393,6 @@ rows = [
]
```
-### Options `table-names` Case
-
-```hocon
-
-source {
- # This is a example source plugin **only for test and demonstrate the
feature source plugin**
- FakeSource {
- table-names = ["test.table1", "test.table2", "test.table3"]
- parallelism = 1
- schema = {
- fields {
- name = "string"
- age = "int"
- }
- }
- }
-}
-```
-
### Options `defaultValue` Case
Custom data can be generated by `row` and `columns`. For the time type, obtain
the current time by
diff --git a/docs/en/connectors/source/Http-Linear.md
b/docs/en/connectors/source/Http-Linear.md
new file mode 100644
index 0000000000..612c87d8e7
--- /dev/null
+++ b/docs/en/connectors/source/Http-Linear.md
@@ -0,0 +1,125 @@
+import ChangeLog from '../changelog/connector-http-linear.md';
+
+# Linear
+
+> Linear source connector
+
+## Description
+
+The Linear source connector reads data from the [Linear](https://linear.app/)
GraphQL API. It is based on the HTTP source connector and sends the configured
`api_key` as the `Authorization` request header, as required by the Linear API.
+
+## Key Features
+
+- [x] [batch](../../introduction/concepts/connector-v2-features.md)
+- [ ] [stream](../../introduction/concepts/connector-v2-features.md)
+- [ ] [exactly-once](../../introduction/concepts/connector-v2-features.md)
+- [ ] [column projection](../../introduction/concepts/connector-v2-features.md)
+- [ ] [parallelism](../../introduction/concepts/connector-v2-features.md)
+- [ ] [support user-defined
split](../../introduction/concepts/connector-v2-features.md)
+
+## Source Options
+
+| Name | Type | Required | Default | Description |
+|-----------------------------|---------|----------|---------|-------------|
+| url | String | Yes | - | Linear API
endpoint URL, usually `https://api.linear.app/graphql`. |
+| api_key | String | Yes | - | Linear API key.
The connector sends it verbatim as the `Authorization` request header value; no
`Bearer ` prefix is added, so OAuth access tokens must be configured as
`api_key = "Bearer <token>"`. |
+| method | String | No | get | HTTP request
method. Supported values are `GET` and `POST`. |
+| headers | Map | No | - | Extra HTTP
headers. Any `Authorization` entry here is always replaced by the value of
`api_key`. |
+| params | Map | No | - | Query
parameters sent with the request. |
+| body | String | No | - | HTTP request
body. Usually used with `method = "POST"` to send a GraphQL query. |
+| format | String | No | text | Response
format. Use `json` when reading the GraphQL response into a SeaTunnel schema;
use `text` to return the raw response as `content`. The shared HTTP option also
accepts `binary`, but `binary` is not supported by the `Linear` source and
`binary_chunk_size` has no effect here. |
+| schema | Config | No | - | Output schema.
Required when `format = "json"`. |
+| schema.fields | Config | No | - | Field names and
SeaTunnel data types used to parse the JSON response. |
+| content_field | String | No | - | JSONPath used
to select a nested part of the response before parsing it with `schema`, for
example `$.data.issues.nodes.*`. |
+| json_field | Config | No | - | Field-level
JSONPath mapping. Use it with `schema` when output fields come from different
JSON paths. |
+| retry | Int | No | - | Maximum retry
times when the HTTP request fails with an `IOException`. |
+| retry_backoff_multiplier_ms | Int | No | 100 | Retry backoff
multiplier in milliseconds. Takes effect only when `retry` is configured. |
+| retry_backoff_max_ms | Int | No | 10000 | Maximum retry
backoff in milliseconds. Takes effect only when `retry` is configured. |
+| enable_multi_lines | Boolean | No | false | When `true`,
multiple JSON objects separated by newlines in the response body are treated as
separate records. |
+| keep_params_as_form | Boolean | No | false | When `true`,
request parameters are sent as form-encoded body parameters instead of URL
query parameters. |
+| connect_timeout_ms | Int | No | 12000 | HTTP connection
timeout in milliseconds. |
+| socket_timeout_ms | Int | No | 60000 | HTTP socket
timeout in milliseconds. |
+| json_filed_missed_return_null | Boolean | No | false | Return null
when a configured JSON field is missing. |
+| common-options | Config | No | - | Source plugin
common parameters. See [Source Common
Options](../common-options/source-common-options.md). |
+
+:::tip
+
+`api_key` is a sensitive credential. Unlike options such as `password` or
`access_key`, `api_key` is not masked in parsed-config logs and is not
encrypted or decrypted by default. To protect the value, add `api_key` to
`env.shade.options` and encrypt it with the configured `shade.identifier`. See
[Config Encryption and
Decryption](../../introduction/configuration/config-encryption-decryption.md).
+
+:::
+
+## Usage Notes
+
+- The plugin name in the job configuration is `Linear`.
+- Set `format = "json"` and configure `schema` when you want typed SeaTunnel
rows.
+- Use `content_field` to unwrap the GraphQL envelope, for example
`$.data.issues.nodes.*`, before parsing with `schema`.
+- Use `json_field` only when each output field needs its own JSONPath
expression.
+- Pagination is not supported by this connector. Each job reads only what a
single request returns; the HTTP `pageing` block and its options have no effect
here.
+- `api_key` is sent verbatim as the `Authorization` header value and always
overrides any `Authorization` entry in `headers`. Put only other custom headers
in `headers`.
+
+## Task Examples
+
+### Read Issues
+
+```hocon
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
+source {
+ Linear {
+ url = "https://api.linear.app/graphql";
+ api_key = "<your_linear_api_key>"
+ method = "POST"
+ body = "{\"query\": \"{ issues { nodes { id title } } }\"}"
+ format = "json"
+ content_field = "$.data.issues.nodes.*"
+ schema = {
+ fields {
+ id = string
+ title = string
+ }
+ }
+ plugin_output = "linear_data"
+ }
+}
+
+sink {
+ Console {
+ }
+}
+```
+
+### Extract Fields With JSONPath
+
+```hocon
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
+source {
+ Linear {
+ url = "https://api.linear.app/graphql";
+ api_key = "<your_linear_api_key>"
+ method = "POST"
+ body = "{\"query\": \"{ issues { nodes { id title } } }\"}"
+ format = "json"
+ json_field = {
+ id = "$.data.issues.nodes[*].id"
+ title = "$.data.issues.nodes[*].title"
+ }
+ schema = {
+ fields {
+ id = string
+ title = string
+ }
+ }
+ }
+}
+```
+
+## Changelog
+
+<ChangeLog />
diff --git a/docs/zh/connectors/changelog/connector-http-linear.md
b/docs/zh/connectors/changelog/connector-http-linear.md
new file mode 100644
index 0000000000..4de4886215
--- /dev/null
+++ b/docs/zh/connectors/changelog/connector-http-linear.md
@@ -0,0 +1,7 @@
+<details><summary> Change Log </summary>
+
+| Change | Commit | Version |
+| --- | --- | --- |
+|[Feature][Connector-V2] Add Linear HTTP source
connector|[https://github.com/apache/seatunnel/commit/56cfbca0fb](https://github.com/apache/seatunnel/commit/56cfbca0fb)|Next|
+
+</details>
diff --git a/docs/zh/connectors/common-options/sink-common-options.md
b/docs/zh/connectors/common-options/sink-common-options.md
index 4c9223ed8f..af97fd29b2 100644
--- a/docs/zh/connectors/common-options/sink-common-options.md
+++ b/docs/zh/connectors/common-options/sink-common-options.md
@@ -18,7 +18,6 @@ sidebar_position: 4
| 名称 | 类型 | 是否需要 | 默认值 |
|--------------|--------|------|-----|
| plugin_input | string | 否 | - |
-| parallelism | int | 否 | - |
| metadata_datasource_id | string | 否 | - |
### metadata_datasource_id [string]
@@ -31,12 +30,6 @@ sidebar_position: 4
当指定了 `plugin_input` 时，当前插件正在处理该参数对应的数据集
-### parallelism [int]
-
-当没有指定`parallelism`时，默认使用 env 中的 `parallelism`。
-
-当指定 `parallelism` 时，它将覆盖 env 中的 `parallelism`。
-
## Examples
```bash
diff --git a/docs/zh/connectors/source/FakeSource.md
b/docs/zh/connectors/source/FakeSource.md
index cb03571f08..b42efef880 100644
--- a/docs/zh/connectors/source/FakeSource.md
+++ b/docs/zh/connectors/source/FakeSource.md
@@ -67,6 +67,12 @@ FakeSource 是一个虚拟数据源，它根据用户定义的 schema 数据结
| double.min | double | 否 | 0 |
连接器生成的 double 数据的最小值
|
| double.max | double | 否 | 0x1.fffffffffffffP+1023 |
连接器生成的 double 数据的最大值
|
| double.template | list | 否 | - |
连接器生成的 double 类型的模板列表，如果用户配置了此选项，连接器将从模板列表中随机选择一个项
|
+| date.year.template | list | 否 | - |
日期年份的模板列表（如 `yyyy`），如果用户配置了此选项，连接器将从模板列表中随机选择一个项
|
+| date.month.template | list | 否 | - |
日期月份的模板列表（如 `MM`），如果用户配置了此选项，连接器将从模板列表中随机选择一个项
|
+| date.day.template | list | 否 | - |
日期天数的模板列表（如 `dd`），如果用户配置了此选项，连接器将从模板列表中随机选择一个项
|
+| time.hour.template | list | 否 | - |
时间小时的模板列表（如 `HH`），如果用户配置了此选项，连接器将从模板列表中随机选择一个项
|
+| time.minute.template | list | 否 | - |
时间分钟的模板列表（如 `mm`），如果用户配置了此选项，连接器将从模板列表中随机选择一个项
|
+| time.second.template | list | 否 | - |
时间秒数的模板列表（如 `ss`），如果用户配置了此选项，连接器将从模板列表中随机选择一个项
|
| vector.dimension | int | 否 | 4 |
生成的向量的维度，不包括二进制向量
|
| binary.vector.dimension | int | 否 | 8 |
生成的二进制向量的维度
|
| vector.float.min | float | 否 | 0 |
连接器生成的向量中 float 数据的最小值
|
@@ -388,24 +394,6 @@ rows = [
]
```
-### `table-names` 选项示例
-
-```hocon
-source {
- # 这是一个示例源插件，**仅用于测试和演示源插件功能**
- FakeSource {
- table-names = ["test.table1", "test.table2", "test.table3"]
- parallelism = 1
- schema = {
- fields {
- name = "string"
- age = "int"
- }
- }
- }
-}
-```
-
### `defaultValue` 选项示例
可以通过 `row` 和 `columns` 生成自定义数据。对于时间类型，可以通过
`CURRENT_TIMESTAMP`、`CURRENT_TIME`、`CURRENT_DATE` 获取当前时间。
diff --git a/docs/zh/connectors/source/Http-Linear.md
b/docs/zh/connectors/source/Http-Linear.md
new file mode 100644
index 0000000000..cc093dc37c
--- /dev/null
+++ b/docs/zh/connectors/source/Http-Linear.md
@@ -0,0 +1,125 @@
+import ChangeLog from '../changelog/connector-http-linear.md';
+
+# Linear
+
+> Linear 源连接器
+
+## 描述
+
+Linear 源连接器用于读取 [Linear](https://linear.app/) GraphQL API 数据。它基于 HTTP
源连接器实现，并按 Linear API 的要求将配置的 `api_key` 作为 `Authorization` 请求头发送。
+
+## 主要特性
+
+- [x] [批处理](../../introduction/concepts/connector-v2-features.md)
+- [ ] [流处理](../../introduction/concepts/connector-v2-features.md)
+- [ ] [精确一次](../../introduction/concepts/connector-v2-features.md)
+- [ ] [列投影](../../introduction/concepts/connector-v2-features.md)
+- [ ] [并行度](../../introduction/concepts/connector-v2-features.md)
+- [ ] [支持用户自定义分片](../../introduction/concepts/connector-v2-features.md)
+
+## 源选项
+
+| 参数名 | 类型 | 必须 | 默认值 | 描述
|
+|------------------------------|---------|------|------------|----------------------------------------------------------------------------------------------|
+| url | String | 是 | - | Linear API
请求地址，通常为 `https://api.linear.app/graphql`。 |
+| api_key | String | 是 | - | Linear API
key。连接器会将其原样作为 `Authorization` 请求头的值发送，不会自动添加 `Bearer ` 前缀，因此 OAuth 访问令牌需要配置为
`api_key = "Bearer <token>"`。 |
+| method | String | 否 | get | HTTP 请求方法，支持
`GET` 和 `POST`。 |
+| headers | Map | 否 | - | 额外的 HTTP
请求头。此处任何 `Authorization` 条目都会被 `api_key` 的值覆盖。
|
+| params | Map | 否 | - | 请求附带的查询参数。
|
+| body | String | 否 | - | HTTP 请求体，通常与
`method = "POST"` 一起使用以发送 GraphQL 查询。 |
+| format | String | 否 | text | 响应格式，`json`
时需要配合 `schema`；`text` 时返回原始响应。共享的 HTTP 选项也接受 `binary`，但 `Linear` 源连接器不支持
`binary`，`binary_chunk_size` 在此处无效。 |
+| schema | Config | 否 | - | 输出数据结构，`format =
"json"` 时必填。 |
+| schema.fields | Config | 否 | - | 字段名与 SeaTunnel
数据类型，用于解析 JSON 响应。 |
+| content_field | String | 否 | - | 在 `schema`
解析之前先通过 JSONPath 抽取一段 JSON，例如 `$.data.issues.nodes.*`。 |
+| json_field | Config | 否 | - | 字段级 JSONPath
映射，与 `schema` 配合使用。 |
+| retry | Int | 否 | - | HTTP 请求抛出
`IOException` 时的最大重试次数。
|
+| retry_backoff_multiplier_ms | Int | 否 | 100 | 重试退避乘数（毫秒），仅在配置了
`retry` 时生效。 |
+| retry_backoff_max_ms | Int | 否 | 10000 |
最大重试退避时间（毫秒），仅在配置了 `retry` 时生效。 |
+| enable_multi_lines | Boolean | 否 | false | 为 `true`
时，响应体中以换行分隔的多个 JSON 对象会被当作独立记录。 |
+| keep_params_as_form | Boolean | 否 | false | 为 `true`
时，请求参数以表单编码放入请求体，而不是 URL 查询参数。 |
+| connect_timeout_ms | Int | 否 | 12000 | HTTP 连接超时（毫秒）。
|
+| socket_timeout_ms | Int | 否 | 60000 | HTTP socket
超时（毫秒）。
|
+| json_filed_missed_return_null | Boolean | 否 | false | 配置的 JSON
字段缺失时返回 null。
|
+| common-options | Config | 否 | - | Source 插件通用参数，详见
[Source Common Options](../common-options/source-common-options.md)。 |
+
+:::tip
+
+`api_key` 是敏感凭据。与 `password`、`access_key` 等选项不同，`api_key`
不会在解析后的配置日志中遮蔽，默认也不参与配置加密或解密。若需保护该值，请将 `api_key` 加入 `env.shade.options`，并使用配置的
`shade.identifier`
加密其值。参见[配置加密与解密](../../introduction/configuration/config-encryption-decryption.md)。
+
+:::
+
+## 使用说明
+
+- 作业配置中的插件名是 `Linear`。
+- 需要带类型的 SeaTunnel 数据行时，请设置 `format = "json"` 并配置 `schema`。
+- 响应带有 GraphQL 外层结构时，先用 `content_field`（例如 `$.data.issues.nodes.*`）解包，再交给
`schema` 解析。
+- 仅当每个输出字段需要独立的 JSONPath 时才使用 `json_field`。
+- 该连接器不支持分页，每个作业只读取单次请求返回的数据；HTTP 的 `pageing` 配置块及其选项在此无效。
+- `api_key` 会原样作为 `Authorization` 请求头的值发送，并始终覆盖 `headers` 中的任何 `Authorization`
条目，其余自定义请求头放在 `headers` 中即可。
+
+## 任务示例
+
+### 读取 Issues
+
+```hocon
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
+source {
+ Linear {
+ url = "https://api.linear.app/graphql";
+ api_key = "<your_linear_api_key>"
+ method = "POST"
+ body = "{\"query\": \"{ issues { nodes { id title } } }\"}"
+ format = "json"
+ content_field = "$.data.issues.nodes.*"
+ schema = {
+ fields {
+ id = string
+ title = string
+ }
+ }
+ plugin_output = "linear_data"
+ }
+}
+
+sink {
+ Console {
+ }
+}
+```
+
+### 使用 JSONPath 抽取字段
+
+```hocon
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
+source {
+ Linear {
+ url = "https://api.linear.app/graphql";
+ api_key = "<your_linear_api_key>"
+ method = "POST"
+ body = "{\"query\": \"{ issues { nodes { id title } } }\"}"
+ format = "json"
+ json_field = {
+ id = "$.data.issues.nodes[*].id"
+ title = "$.data.issues.nodes[*].title"
+ }
+ schema = {
+ fields {
+ id = string
+ title = string
+ }
+ }
+ }
+}
+```
+
+## 更新日志
+
+<ChangeLog />
