This is an automated email from the ASF dual-hosted git repository.
davidzollo 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 3c0dd79fbb [Docs][Connector-V2] Improve Tablestore connector docs
(#11379)
3c0dd79fbb is described below
commit 3c0dd79fbb556ef6f248925163c6dc48d3865aff
Author: Daniel Carter <[email protected]>
AuthorDate: Fri Jul 10 16:05:21 2026 +0800
[Docs][Connector-V2] Improve Tablestore connector docs (#11379)
Co-authored-by: DanielCarter-stack
<[email protected]>
---
docs/en/connectors/sink/Tablestore.md | 119 +++++++++++++++++++-----------
docs/en/connectors/source/Tablestore.md | 125 ++++++++++++++++----------------
docs/zh/connectors/sink/Tablestore.md | 124 +++++++++++++++++++------------
docs/zh/connectors/source/Tablestore.md | 125 ++++++++++++++++----------------
4 files changed, 279 insertions(+), 214 deletions(-)
diff --git a/docs/en/connectors/sink/Tablestore.md
b/docs/en/connectors/sink/Tablestore.md
index bf01ccdf5c..a5a17744db 100644
--- a/docs/en/connectors/sink/Tablestore.md
+++ b/docs/en/connectors/sink/Tablestore.md
@@ -6,66 +6,99 @@ import ChangeLog from '../changelog/connector-tablestore.md';
## Description
-Write data to `Tablestore`
+Write SeaTunnel rows to Alibaba Cloud Tablestore.
## Key features
- [ ] [exactly-once](../../introduction/concepts/connector-v2-features.md)
+- [ ] [cdc](../../introduction/concepts/connector-v2-features.md)
+- [ ] [support multiple table
write](../../introduction/concepts/connector-v2-features.md)
+- [ ] [timer flush](../../introduction/concepts/connector-v2-features.md)
## Options
-| name | type | required | default value |
-|-------------------|--------|----------|---------------|
-| end_point | string | yes | - |
-| instance_name | string | yes | - |
-| access_key_id | string | yes | - |
-| access_key_secret | string | yes | - |
-| table | string | yes | - |
-| primary_keys | array | yes | - |
-| batch_size | string | no | 25 |
-| common-options | config | no | - |
+| name | type | required | default value | description
|
+|-------------------|--------|----------|---------------|--------------------------------------------------|
+| end_point | string | yes | - | Tablestore endpoint.
|
+| instance_name | string | yes | - | Tablestore instance
name. |
+| access_key_id | string | yes | - | AccessKey ID used to
access Tablestore. |
+| access_key_secret | string | yes | - | AccessKey secret
used to access Tablestore. |
+| table | string | yes | - | Target Tablestore
table name. |
+| primary_keys | array | yes | - | Primary key field
names in the target table. |
+| schema | config | yes | - | Input schema.
Primary key fields must also exist in `schema.fields`. |
+| batch_size | int | no | 25 | Maximum number of
rows written in one batch. |
+| common-options | config | no | - | Sink common options.
|
-### end_point [string]
+## Usage notes
-endPoint to write to Tablestore.
+- `primary_keys` can contain one or more primary key fields. These fields are
written as Tablestore primary key columns; all other schema fields are written
as normal attribute columns.
+- The sink writes rows with Tablestore `RowPutChange` and
`RowExistenceExpectation.IGNORE`. It does not delete rows when upstream sends
`DELETE` row kinds.
+- `batch_size` controls when buffered rows are flushed. The writer also
flushes remaining rows when the job closes.
+- Keep `access_key_id` and `access_key_secret` out of committed job files.
Prefer runtime variable substitution or a secret manager supported by your
deployment environment.
-### instanceName [string]
-
-The instanceName of Tablestore.
-
-### access_key_id [string]
-
-The access id of Tablestore.
-
-### access_key_secret [string]
-
-The access secret of Tablestore.
-
-### table [string]
-
-The table of Tablestore.
-
-### primaryKeys [array]
-
-The primaryKeys of Tablestore.
-
-### common options [ config ]
+### common options [config]
Sink plugin common parameters, please refer to [Sink Common
Options](../common-options/sink-common-options.md) for details.
## Example
-```bash
-Tablestore {
- end_point = "xxxx"
- instance_name = "xxxx"
- access_key_id = "xxxx"
- access_key_secret = "xxxx"
- table = "sink"
- primary_keys = ["pk_1","pk_2","pk_3","pk_4"]
+```hocon
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
+source {
+ FakeSource {
+ row.num = 2
+ schema = {
+ fields {
+ order_id = string
+ user_id = string
+ amount = double
+ }
+ }
+ rows = [
+ {
+ fields = ["order-1", "user-1", 99.5]
+ },
+ {
+ fields = ["order-2", "user-2", 20.0]
+ }
+ ]
}
+}
+
+sink {
+ Tablestore {
+ end_point = "https://<instance>.<region>.ots.aliyuncs.com"
+ instance_name = "<instance-name>"
+ access_key_id = "${ACCESS_KEY_ID}"
+ access_key_secret = "${ACCESS_KEY_SECRET}"
+ table = "orders"
+ primary_keys = ["order_id"]
+ batch_size = 25
+ schema = {
+ fields {
+ order_id = string
+ user_id = string
+ amount = double
+ }
+ }
+ }
+}
```
+## Type mapping
+
+| SeaTunnel type | Tablestore attribute column type |
Tablestore primary key type |
+|----------------------------------------|----------------------------------|-----------------------------|
+| `INT`, `TINYINT`, `SMALLINT`, `BIGINT` | `INTEGER` |
`INTEGER` |
+| `FLOAT`, `DOUBLE`, `DECIMAL` | `DOUBLE` |
`STRING` |
+| `STRING`, `DATE`, `TIME`, `TIMESTAMP` | `STRING` |
`STRING` |
+| `BOOLEAN` | `BOOLEAN` |
`STRING` |
+| `BYTES` | `BINARY` |
`BINARY` |
+
## Changelog
-<ChangeLog />
\ No newline at end of file
+<ChangeLog />
diff --git a/docs/en/connectors/source/Tablestore.md
b/docs/en/connectors/source/Tablestore.md
index ebd7beb8e9..69395aead1 100644
--- a/docs/en/connectors/source/Tablestore.md
+++ b/docs/en/connectors/source/Tablestore.md
@@ -6,102 +6,101 @@ import ChangeLog from
'../changelog/connector-tablestore.md';
## Description
-Read data from Alicloud Tablestore，support full and CDC.
-
+Read full and incremental data from Alibaba Cloud Tablestore. The source uses
Tablestore Tunnel in `BaseAndStream` mode, so it can read existing data first
and then consume later changes.
## Key features
-- [ ] [batch](../../introduction/concepts/connector-v2-features.md)
-- [X] [stream](../../introduction/concepts/connector-v2-features.md)
+- [x] [batch](../../introduction/concepts/connector-v2-features.md)
+- [x] [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)
+- [x] [cdc](../../introduction/concepts/connector-v2-features.md)
+- [x] [column projection](../../introduction/concepts/connector-v2-features.md)
+- [x] [parallelism](../../introduction/concepts/connector-v2-features.md)
- [ ] [support user-defined
split](../../introduction/concepts/connector-v2-features.md)
## Options
-| name | type | required | default value |
-|-----------------------|--------|----------|---------------|
-| end_point | string | yes | - |
-| instance_name | string | yes | - |
-| access_key_id | string | yes | - |
-| access_key_secret | string | yes | - |
-| table | string | yes | - |
-| primary_keys | array | yes | - |
-| schema | config | yes | - |
-
-
-### end_point [string]
-
-The endpoint of Tablestore.
-
-### instance_name [string]
-
-The intance name of Tablestore.
-
-### access_key_id [string]
-
-The access id of Tablestore.
+| name | type | required | default value | description
|
+|-------------------|--------|----------|---------------|-----------------------------------------------------------------------------|
+| end_point | string | yes | - | Tablestore endpoint,
for example `https://<instance>.<region>.ots.aliyuncs.com`. |
+| instance_name | string | yes | - | Tablestore instance
name. |
+| access_key_id | string | yes | - | AccessKey ID used to
access Tablestore. |
+| access_key_secret | string | yes | - | AccessKey secret
used to access Tablestore. |
+| table | string | yes | - | Tablestore table
name. Multiple tables can be separated by commas. |
+| primary_keys | array | yes | - | Primary key names.
For multiple source tables, configure one primary key name for each table in
the same order as `table`. |
+| schema | config | yes | - | Output schema. For
details, see [Schema Feature](../../introduction/concepts/schema-feature.md). |
-### access_key_secret [string]
-
-The access secret of Tablestore.
-
-### table [string]
-
-The table name of Tablestore.
-
-### primary_keys [array]
-
-The primarky key of table,just add a unique primary key.
-
-### schema [Config]
-The structure of the data, including field names and field types. For more
details, please refer to [Schema
Feature](../../introduction/concepts/schema-feature.md).
+## Usage notes
+- `job.mode = "BATCH"` reads bounded data. `job.mode = "STREAMING"` keeps
consuming incremental records after the existing data is read.
+- When `table` contains multiple table names, `primary_keys` must contain the
same number of entries. For example, `table = "orders,users"` can use
`primary_keys = ["id", "id"]` when both tables use `id` as the primary key
field.
+- Multi-table reads use one `schema` block for the source, so the listed
tables should have compatible output fields.
+- The source emits `INSERT`, `UPDATE_AFTER`, and `DELETE` row kinds according
to Tablestore stream records.
+- Keep `access_key_id` and `access_key_secret` out of committed job files.
Prefer runtime variable substitution or a secret manager supported by your
deployment environment.
## Example
-```bash
+```hocon
env {
parallelism = 1
job.mode = "STREAMING"
}
source {
- # This is a example source plugin **only for test and demonstrate the
feature source plugin**
Tablestore {
- end_point = "https://****.cn-zhangjiakou.tablestore.aliyuncs.com";
- instance_name = "****"
- access_key_id="***************2Ag5"
- access_key_secret="***********2Dok"
- table="test"
- primary_keys=["id"]
- schema={
- fields {
- id = string
- name = string
- }
+ end_point = "https://<instance>.<region>.ots.aliyuncs.com"
+ instance_name = "<instance-name>"
+ access_key_id = "${ACCESS_KEY_ID}"
+ access_key_secret = "${ACCESS_KEY_SECRET}"
+ table = "orders"
+ primary_keys = ["order_id"]
+ schema = {
+ fields {
+ order_id = string
+ user_id = string
+ amount = double
+ updated_at = string
+ }
}
}
}
-
sink {
- MongoDB{
- uri = "mongodb://localhost:27017"
- database = "test"
- collection = "test"
- primary-key = ["id"]
+ Console {}
+}
+```
+
+### Multiple table example
+
+```hocon
+env {
+ parallelism = 2
+ job.mode = "STREAMING"
+}
+
+source {
+ Tablestore {
+ end_point = "https://<instance>.<region>.ots.aliyuncs.com"
+ instance_name = "<instance-name>"
+ access_key_id = "${ACCESS_KEY_ID}"
+ access_key_secret = "${ACCESS_KEY_SECRET}"
+ table = "orders,users"
+ primary_keys = ["id", "id"]
schema = {
fields {
id = string
- name = string
+ value = string
+ updated_at = string
}
}
}
}
+
+sink {
+ Console {}
+}
```
## Changelog
-<ChangeLog />
\ No newline at end of file
+<ChangeLog />
diff --git a/docs/zh/connectors/sink/Tablestore.md
b/docs/zh/connectors/sink/Tablestore.md
index 4753407876..1c921672e8 100644
--- a/docs/zh/connectors/sink/Tablestore.md
+++ b/docs/zh/connectors/sink/Tablestore.md
@@ -2,71 +2,103 @@ import ChangeLog from '../changelog/connector-tablestore.md';
# Tablestore
-> Tablestore 数据接收器
+> Tablestore Sink 连接器
## 描述
-用于将数据写入 Tablestore
+将 SeaTunnel 数据写入阿里云 Tablestore。
## 主要特性
-- [ ] [exactly-once](../../introduction/concepts/connector-v2-features.md)
-- [ ] [timer flush](../../introduction/concepts/connector-v2-features.md)
+- [ ] [精确一次](../../introduction/concepts/connector-v2-features.md)
+- [ ] [cdc](../../introduction/concepts/connector-v2-features.md)
+- [ ] [支持多表写入](../../introduction/concepts/connector-v2-features.md)
+- [ ] [定时刷新](../../introduction/concepts/connector-v2-features.md)
## 选项
-| 名称 | 类型 | 是否必填 | 默认值 |
-|-------------------|--------|----------|---------------|
-| end_point | string | 是 | - |
-| instance_name | string | 是 | - |
-| access_key_id | string | 是 | - |
-| access_key_secret | string | 是 | - |
-| table | string | 是 | - |
-| primary_keys | array | 是 | - |
-| batch_size | string | 否 | 25 |
-| common-options | config | 否 | - |
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+|-------------------|--------|----------|--------|------|
+| end_point | string | 是 | - | Tablestore 访问地址。 |
+| instance_name | string | 是 | - | Tablestore 实例名称。 |
+| access_key_id | string | 是 | - | 访问 Tablestore 使用的 AccessKey
ID。 |
+| access_key_secret | string | 是 | - | 访问 Tablestore 使用的 AccessKey
Secret。 |
+| table | string | 是 | - | 目标 Tablestore 表名。 |
+| primary_keys | array | 是 | - | 目标表的主键字段名。 |
+| schema | config | 是 | - | 输入数据结构。主键字段也必须包含在
`schema.fields` 中。 |
+| batch_size | int | 否 | 25 | 单次批量写入的最大数据条数。 |
+| common-options | config | 否 | - | Sink 通用选项。 |
-### end_point [string]
+## 使用说明
-endPoint 用于写入Tablestore。
+- `primary_keys` 可以包含一个或多个主键字段。这些字段会写为 Tablestore 主键列，其余字段会写为普通属性列。
+- Sink 使用 Tablestore `RowPutChange` 写入，并使用
`RowExistenceExpectation.IGNORE`。当上游发送 `DELETE` 类型数据时，当前 Sink 不会删除 Tablestore
中的行。
+- `batch_size` 控制缓存多少行后刷新；任务关闭时，写入器也会刷新剩余数据。
+- 不建议把 `access_key_id` 和 `access_key_secret`
直接写入会提交到代码仓库的任务文件中，建议使用运行时变量替换或部署环境支持的密钥管理方式。
-### instanceName [string]
+### common options [config]
-Tablestore 的实例名称。
-
-### access_key_id [string]
-
-Tablestore 访问的id。
-
-### access_key_secret [string]
-
-Tablestore 访问的密钥。
-
-### table [string]
-
-Tablestore的表。
-
-### primaryKeys [array]
-
-Tablestore 的主键。
-
-### common 选项 [ config ]
-
-Sink插件常用参数，请参考[Sink common
Options](../common-options/sink-common-options.md)了解详细信息。
+Sink 插件通用参数，请参考 [Sink Common
Options](../common-options/sink-common-options.md)。
## 示例
-```bash
-Tablestore {
- end_point = "xxxx"
- instance_name = "xxxx"
- access_key_id = "xxxx"
- access_key_secret = "xxxx"
- table = "sink"
- primary_keys = ["pk_1","pk_2","pk_3","pk_4"]
+```hocon
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
+source {
+ FakeSource {
+ row.num = 2
+ schema = {
+ fields {
+ order_id = string
+ user_id = string
+ amount = double
+ }
+ }
+ rows = [
+ {
+ fields = ["order-1", "user-1", 99.5]
+ },
+ {
+ fields = ["order-2", "user-2", 20.0]
+ }
+ ]
}
+}
+
+sink {
+ Tablestore {
+ end_point = "https://<instance>.<region>.ots.aliyuncs.com"
+ instance_name = "<instance-name>"
+ access_key_id = "${ACCESS_KEY_ID}"
+ access_key_secret = "${ACCESS_KEY_SECRET}"
+ table = "orders"
+ primary_keys = ["order_id"]
+ batch_size = 25
+ schema = {
+ fields {
+ order_id = string
+ user_id = string
+ amount = double
+ }
+ }
+ }
+}
```
+## 类型映射
+
+| SeaTunnel 类型 | Tablestore 普通属性列类型 | Tablestore 主键列类型
|
+|----------------------------------------|---------------------------|-----------------------|
+| `INT`, `TINYINT`, `SMALLINT`, `BIGINT` | `INTEGER` |
`INTEGER` |
+| `FLOAT`, `DOUBLE`, `DECIMAL` | `DOUBLE` |
`STRING` |
+| `STRING`, `DATE`, `TIME`, `TIMESTAMP` | `STRING` |
`STRING` |
+| `BOOLEAN` | `BOOLEAN` |
`STRING` |
+| `BYTES` | `BINARY` |
`BINARY` |
+
## 变更日志
<ChangeLog />
diff --git a/docs/zh/connectors/source/Tablestore.md
b/docs/zh/connectors/source/Tablestore.md
index cd384c9882..12c28d39fb 100644
--- a/docs/zh/connectors/source/Tablestore.md
+++ b/docs/zh/connectors/source/Tablestore.md
@@ -6,100 +6,101 @@ import ChangeLog from
'../changelog/connector-tablestore.md';
## 描述
-从阿里云 Tablestore 读取数据，支持全量和 CDC。
+从阿里云 Tablestore 读取全量和增量数据。该连接器使用 Tablestore Tunnel 的 `BaseAndStream`
模式，先读取已有数据，再继续消费后续变更。
-## 关键特性
+## 主要特性
-- [ ] [批](../../introduction/concepts/connector-v2-features.md)
-- [X] [流](../../introduction/concepts/connector-v2-features.md)
+- [x] [批](../../introduction/concepts/connector-v2-features.md)
+- [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)
-- [ ] [支持用户自定义split](../../introduction/concepts/connector-v2-features.md)
+- [x] [cdc](../../introduction/concepts/connector-v2-features.md)
+- [x] [列投影](../../introduction/concepts/connector-v2-features.md)
+- [x] [并行度](../../introduction/concepts/connector-v2-features.md)
+- [ ] [支持用户自定义切片](../../introduction/concepts/connector-v2-features.md)
## 选项
-| 参数名 | 类型 | 必须 | 默认值 | 描述
|
-|-------------------|--------|----|-----|---------------------------------------------------------------------------|
-| end_point | string | 是 | - | Tablestore 的端点
|
-| instance_name | string | 是 | - | Tablestore 的实例名称
|
-| access_key_id | string | 是 | - | Tablestore 的访问 ID
|
-| access_key_secret | string | 是 | - | Tablestore 的访问密钥
|
-| table | string | 是 | - | Tablestore 的表名
|
-| primary_keys | array | 是 | - | 表的主键，只需添加一个唯一的主键
|
-| schema | config | 是 | - | 数据的结构。更多详情请参考 [Schema
特性](../../introduction/concepts/schema-feature.md)。 |
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+|-------------------|--------|----------|--------|------|
+| end_point | string | 是 | - | Tablestore 访问地址，例如
`https://<instance>.<region>.ots.aliyuncs.com`。 |
+| instance_name | string | 是 | - | Tablestore 实例名称。 |
+| access_key_id | string | 是 | - | 访问 Tablestore 使用的 AccessKey
ID。 |
+| access_key_secret | string | 是 | - | 访问 Tablestore 使用的 AccessKey
Secret。 |
+| table | string | 是 | - | Tablestore
表名。读取多张表时，用英文逗号分隔。 |
+| primary_keys | array | 是 | - | 主键名。读取多张表时，需要按 `table`
的顺序为每张表配置一个主键名。 |
+| schema | config | 是 | - | 输出数据结构。更多详情请参考 [Schema
特性](../../introduction/concepts/schema-feature.md)。 |
-### end_point [string]
+## 使用说明
-Tablestore 的端点。
-
-### instance_name [string]
-
-Tablestore 的实例名称。
-
-### access_key_id [string]
-
-Tablestore 的访问 ID。
-
-### access_key_secret [string]
-
-Tablestore 的访问密钥。
-
-### table [string]
-
-Tablestore 的表名。
-
-### primary_keys [array]
-
-表的主键，只需添加一个唯一的主键。
-
-### schema [Config]
-
-数据的结构。更多详情请参考 [Schema 特性](../../introduction/concepts/schema-feature.md)。
+- `job.mode = "BATCH"` 会读取有界数据；`job.mode = "STREAMING"` 会在读取已有数据后继续消费增量记录。
+- 当 `table` 配置多张表时，`primary_keys` 的数量必须和表数量一致。例如 `table = "orders,users"`
且两张表都使用 `id` 作为主键字段时，可以配置 `primary_keys = ["id", "id"]`。
+- 多表读取共用一个 `schema` 配置，因此这些表的输出字段需要保持兼容。
+- 源连接器会根据 Tablestore 的变更记录输出 `INSERT`、`UPDATE_AFTER` 和 `DELETE` 类型的数据。
+- 不建议把 `access_key_id` 和 `access_key_secret`
直接写入会提交到代码仓库的任务文件中，建议使用运行时变量替换或部署环境支持的密钥管理方式。
## 示例
-```bash
+```hocon
env {
parallelism = 1
job.mode = "STREAMING"
}
source {
- # 这是一个示例源插件 **仅用于测试和演示源插件功能**
Tablestore {
- end_point = "https://****.cn-zhangjiakou.tablestore.aliyuncs.com";
- instance_name = "****"
- access_key_id="***************2Ag5"
- access_key_secret="***********2Dok"
- table="test"
- primary_keys=["id"]
- schema={
- fields {
- id = string
- name = string
- }
+ end_point = "https://<instance>.<region>.ots.aliyuncs.com"
+ instance_name = "<instance-name>"
+ access_key_id = "${ACCESS_KEY_ID}"
+ access_key_secret = "${ACCESS_KEY_SECRET}"
+ table = "orders"
+ primary_keys = ["order_id"]
+ schema = {
+ fields {
+ order_id = string
+ user_id = string
+ amount = double
+ updated_at = string
+ }
}
}
}
sink {
- MongoDB{
- uri = "mongodb://localhost:27017"
- database = "test"
- collection = "test"
- primary-key = ["id"]
+ Console {}
+}
+```
+
+### 多表示例
+
+```hocon
+env {
+ parallelism = 2
+ job.mode = "STREAMING"
+}
+
+source {
+ Tablestore {
+ end_point = "https://<instance>.<region>.ots.aliyuncs.com"
+ instance_name = "<instance-name>"
+ access_key_id = "${ACCESS_KEY_ID}"
+ access_key_secret = "${ACCESS_KEY_SECRET}"
+ table = "orders,users"
+ primary_keys = ["id", "id"]
schema = {
fields {
id = string
- name = string
+ value = string
+ updated_at = string
}
}
}
}
+
+sink {
+ Console {}
+}
```
## 变更日志
<ChangeLog />
-
