This is an automated email from the ASF dual-hosted git repository.
zhangshenghang 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 2c54825f4e [Docs][Connector-V2] Improve Typesense connector docs
(#11259)
2c54825f4e is described below
commit 2c54825f4ee6e4369a1cd588ac11c2eb944a4e8a
Author: Daniel Carter <[email protected]>
AuthorDate: Fri Jul 3 08:13:32 2026 +0800
[Docs][Connector-V2] Improve Typesense connector docs (#11259)
Co-authored-by: DanielCarter-stack
<[email protected]>
Co-authored-by: Shenghang <[email protected]>
---
docs/en/connectors/sink/Typesense.md | 111 +++++++++++++++++++++++++------
docs/en/connectors/source/Typesense.md | 80 +++++++++++++++--------
docs/zh/connectors/sink/Typesense.md | 115 ++++++++++++++++++++++++++-------
docs/zh/connectors/source/Typesense.md | 84 +++++++++++++++---------
4 files changed, 292 insertions(+), 98 deletions(-)
diff --git a/docs/en/connectors/sink/Typesense.md
b/docs/en/connectors/sink/Typesense.md
index 0b514c0c3b..96ac7396e3 100644
--- a/docs/en/connectors/sink/Typesense.md
+++ b/docs/en/connectors/sink/Typesense.md
@@ -4,12 +4,15 @@ import ChangeLog from '../changelog/connector-typesense.md';
## Description
-Outputs data to `Typesense`.
+Writes SeaTunnel rows to a Typesense collection. The connector can create the
target collection
+when needed, clear existing documents before writing, and generate document
`id` values from one
+or more primary key fields.
## Key Features
- [ ] [Exactly Once](../../introduction/concepts/connector-v2-features.md)
- [x] [CDC](../../introduction/concepts/connector-v2-features.md)
+- [x] [Multiple Table
Sink](../../introduction/concepts/connector-v2-features.md)
- [ ] [timer flush](../../introduction/concepts/connector-v2-features.md)
## Options
@@ -22,7 +25,7 @@ Outputs data to `Typesense`.
| data_save_mode | string | Yes | APPEND_DATA |
| primary_keys | array | No | |
| key_delimiter | string | No | `_` |
-| api_key | string | No | |
+| api_key | string | Yes | - |
| max_retry_count | int | No | 3 |
| max_batch_size | int | No | 10 |
| common-options | | No | - |
@@ -37,23 +40,24 @@ The name of the collection to write to, e.g., "seatunnel".
### primary_keys [array]
-Primary key fields used to generate the document `id`.
+Primary key fields used to generate the document `id`. When more than one
field is configured,
+the connector joins their values with `key_delimiter`.
### key_delimiter [string]
Sets the delimiter for composite keys (default is `_`).
-### api_key [config]
+### api_key [string]
The `api_key` for secure access to Typesense.
### max_retry_count [int]
-The maximum number of retry attempts for batch requests.
+The maximum number of retry attempts for one batch request.
### max_batch_size [int]
-The maximum size of document batches.
+The maximum number of documents sent in one batch.
### common options
@@ -73,24 +77,93 @@ Choose how to handle existing data on the target side
before starting the synchr
- `APPEND_DATA`: Retains both the database structure and the data.
- `ERROR_WHEN_DATA_EXISTS`: Throws an error if data exists.
-## Example
+## Task Example
-Simple example:
+### Write Documents With Primary Keys
```bash
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
+source {
+ FakeSource {
+ row.num = 5
+ plugin_output = "typesense_test_table"
+ schema {
+ fields {
+ company_name = string
+ num = long
+ id = string
+ num_employees = int
+ flag = boolean
+ }
+ }
+ }
+}
+
sink {
- Typesense {
- plugin_input = "typesense_test_table"
- hosts = ["localhost:8108"]
- collection = "typesense_to_typesense_sink_with_query"
- max_retry_count = 3
- max_batch_size = 10
- api_key = "xyz"
- primary_keys = ["num_employees","id"]
- key_delimiter = "="
- schema_save_mode = "CREATE_SCHEMA_WHEN_NOT_EXIST"
- data_save_mode = "APPEND_DATA"
+ Typesense {
+ plugin_input = "typesense_test_table"
+ hosts = ["localhost:8108"]
+ collection = "typesense_test_collection"
+ api_key = "xyz"
+ primary_keys = ["num_employees", "num"]
+ key_delimiter = "="
+ max_retry_count = 3
+ max_batch_size = 10
+ schema_save_mode = "CREATE_SCHEMA_WHEN_NOT_EXIST"
+ data_save_mode = "APPEND_DATA"
+ }
+}
+```
+
+### Read From Typesense And Write To Another Collection
+
+```bash
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
+source {
+ Typesense {
+ hosts = ["localhost:8108"]
+ collection = "typesense_source_collection"
+ api_key = "xyz"
+ query = "q=*&filter_by=c_row.c_int:>10"
+ plugin_output = "typesense_test_table"
+ schema = {
+ fields {
+ company_name_list = array<string>
+ company_name = string
+ num_employees = long
+ country = string
+ id = string
+ c_row = {
+ c_int = int
+ c_string = string
+ c_array_int = array<int>
+ }
+ }
}
+ }
+}
+
+sink {
+ Typesense {
+ plugin_input = "typesense_test_table"
+ hosts = ["localhost:8108"]
+ collection = "typesense_sink_collection"
+ api_key = "xyz"
+ primary_keys = ["num_employees", "id"]
+ key_delimiter = "="
+ max_retry_count = 3
+ max_batch_size = 10
+ schema_save_mode = "CREATE_SCHEMA_WHEN_NOT_EXIST"
+ data_save_mode = "APPEND_DATA"
+ }
}
```
diff --git a/docs/en/connectors/source/Typesense.md
b/docs/en/connectors/source/Typesense.md
index 4ee1ff637e..715838f5c5 100644
--- a/docs/en/connectors/source/Typesense.md
+++ b/docs/en/connectors/source/Typesense.md
@@ -6,7 +6,8 @@ import ChangeLog from '../changelog/connector-typesense.md';
## Description
-Reads data from Typesense.
+Reads documents from a Typesense collection. The source supports bounded batch
reads and can pass
+Typesense search parameters through `query`.
## Key Features
@@ -24,27 +25,40 @@ Reads data from Typesense.
| hosts | array | yes | - |
| collection | string | yes | - |
| schema | config | yes | - |
-| api_key | string | no | - |
+| api_key | string | yes | - |
+| protocol | string | no | http |
| query | string | no | - |
| batch_size | int | no | 100 |
+| common-options | | no | - |
### hosts [array]
-The access address of Typesense, for example: `["typesense-01:8108"]`.
+The access address of Typesense. Use the `host:port` format, for example:
+`["typesense-01:8108"]`. Multiple hosts are supported.
### collection [string]
-The name of the collection to write to, for example: `"seatunnel"`.
+The name of the Typesense collection to read from, for example: `"companies"`.
### schema [config]
The columns to be read from Typesense. For more information, please refer to
the
[guide](../../introduction/concepts/schema-feature.md#how-to-declare-type-supported).
-### api_key [config]
+### api_key [string]
The `api_key` for Typesense security authentication.
-### batch_size
+### protocol [string]
+
+The protocol used to connect to Typesense. The default value is `http`. Use
`https` for
+Typesense Cloud or other TLS-enabled endpoints.
+
+### query [string]
+
+Typesense search parameters, for example `q=*&filter_by=num_employees:>9000`.
If it is not set,
+the source reads all documents returned by the default search.
+
+### batch_size [int]
The number of records to query per batch when reading data.
@@ -52,33 +66,45 @@ The number of records to query per batch when reading data.
For common parameters of Source plugins, please refer to [Source Common
Options](../common-options/source-common-options.md).
-## Example
+## Task Example
+
+### Read Documents With A Filter
```bash
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
source {
- Typesense {
- hosts = ["localhost:8108"]
- collection = "companies"
- api_key = "xyz"
- query = "q=*&filter_by=num_employees:>9000"
- schema = {
- fields {
- company_name_list = array<string>
- company_name = string
- num_employees = long
- country = string
- id = string
- c_row = {
- c_int = int
- c_string = string
- c_array_int = array<int>
- }
- }
- }
+ Typesense {
+ hosts = ["localhost:8108"]
+ collection = "companies"
+ api_key = "xyz"
+ query = "q=*&filter_by=num_employees:>9000"
+ batch_size = 100
+ schema = {
+ fields {
+ company_name_list = array<string>
+ company_name = string
+ num_employees = long
+ country = string
+ id = string
+ c_row = {
+ c_int = int
+ c_string = string
+ c_array_int = array<int>
+ }
+ }
}
+ }
+}
+
+sink {
+ Console {}
}
```
## Changelog
-<ChangeLog />
\ No newline at end of file
+<ChangeLog />
diff --git a/docs/zh/connectors/sink/Typesense.md
b/docs/zh/connectors/sink/Typesense.md
index d6384dd917..3902b6922a 100644
--- a/docs/zh/connectors/sink/Typesense.md
+++ b/docs/zh/connectors/sink/Typesense.md
@@ -4,12 +4,14 @@ import ChangeLog from '../changelog/connector-typesense.md';
## 描述
-输出数据到 `Typesense`
+将 SeaTunnel 数据写入 Typesense collection。该 connector 可以按配置创建目标 collection、
+写入前清理已有文档，也可以用一个或多个主键字段生成 Typesense 文档 `id`。
## 主要特性
- [ ] [精确一次](../../introduction/concepts/connector-v2-features.md)
- [x] [cdc](../../introduction/concepts/connector-v2-features.md)
+- [x] [支持多表写入](../../introduction/concepts/connector-v2-features.md)
- [ ] [timer flush](../../introduction/concepts/connector-v2-features.md)
## 选项
@@ -22,38 +24,38 @@ import ChangeLog from '../changelog/connector-typesense.md';
| data_save_mode | string | 是 | APPEND_DATA |
| primary_keys | array | 否 | |
| key_delimiter | string | 否 | `_` |
-| api_key | string | 否 | |
+| api_key | string | 是 | - |
| max_retry_count | int | 否 | 3 |
| max_batch_size | int | 否 | 10 |
| common-options | | 否 | - |
### hosts [array]
-Typesense的访问地址，格式为 `host:port`，例如：["typesense-01:8108"]
+Typesense 的访问地址，格式为 `host:port`，例如：`["typesense-01:8108"]`。
### collection [string]
-要写入的集合名，例如：“seatunnel”
+要写入的 collection 名，例如：`seatunnel`。
### primary_keys [array]
-主键字段用于生成文档 `id`。
+主键字段用于生成文档 `id`。配置多个字段时，connector 会用 `key_delimiter` 拼接这些字段值。
### key_delimiter [string]
设定复合键的分隔符（默认为 `_`）。
-### api_key [config]
+### api_key [string]
-typesense 安全认证的 api_key。
+Typesense 安全认证的 `api_key`。
### max_retry_count [int]
-批次批量请求最大尝试大小
+单个批量请求的最大重试次数。
### max_batch_size [int]
-批次批量文档最大大小
+每批最多写入的文档数量。
### common options
@@ -75,24 +77,93 @@ Sink 插件常用参数，请参考 [Sink 常用选项](../common-options/sink-c
`APPEND_DATA`：保留数据库结构，保留数据<br/>
`ERROR_WHEN_DATA_EXISTS`：当有数据时抛出错误<br/>
-## 示例
+## 任务示例
-简单示例
+### 使用主键写入文档
```bash
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
+source {
+ FakeSource {
+ row.num = 5
+ plugin_output = "typesense_test_table"
+ schema {
+ fields {
+ company_name = string
+ num = long
+ id = string
+ num_employees = int
+ flag = boolean
+ }
+ }
+ }
+}
+
sink {
- Typesense {
- plugin_input = "typesense_test_table"
- hosts = ["localhost:8108"]
- collection = "typesense_to_typesense_sink_with_query"
- max_retry_count = 3
- max_batch_size = 10
- api_key = "xyz"
- primary_keys = ["num_employees","id"]
- key_delimiter = "="
- schema_save_mode = "CREATE_SCHEMA_WHEN_NOT_EXIST"
- data_save_mode = "APPEND_DATA"
+ Typesense {
+ plugin_input = "typesense_test_table"
+ hosts = ["localhost:8108"]
+ collection = "typesense_test_collection"
+ api_key = "xyz"
+ primary_keys = ["num_employees", "num"]
+ key_delimiter = "="
+ max_retry_count = 3
+ max_batch_size = 10
+ schema_save_mode = "CREATE_SCHEMA_WHEN_NOT_EXIST"
+ data_save_mode = "APPEND_DATA"
+ }
+}
+```
+
+### 从 Typesense 读取并写入另一个 collection
+
+```bash
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
+source {
+ Typesense {
+ hosts = ["localhost:8108"]
+ collection = "typesense_source_collection"
+ api_key = "xyz"
+ query = "q=*&filter_by=c_row.c_int:>10"
+ plugin_output = "typesense_test_table"
+ schema = {
+ fields {
+ company_name_list = array<string>
+ company_name = string
+ num_employees = long
+ country = string
+ id = string
+ c_row = {
+ c_int = int
+ c_string = string
+ c_array_int = array<int>
+ }
}
+ }
+ }
+}
+
+sink {
+ Typesense {
+ plugin_input = "typesense_test_table"
+ hosts = ["localhost:8108"]
+ collection = "typesense_sink_collection"
+ api_key = "xyz"
+ primary_keys = ["num_employees", "id"]
+ key_delimiter = "="
+ max_retry_count = 3
+ max_batch_size = 10
+ schema_save_mode = "CREATE_SCHEMA_WHEN_NOT_EXIST"
+ data_save_mode = "APPEND_DATA"
+ }
}
```
diff --git a/docs/zh/connectors/source/Typesense.md
b/docs/zh/connectors/source/Typesense.md
index 5ba5a1222e..40937446ce 100644
--- a/docs/zh/connectors/source/Typesense.md
+++ b/docs/zh/connectors/source/Typesense.md
@@ -6,9 +6,10 @@ import ChangeLog from '../changelog/connector-typesense.md';
## 描述
-从 Typesense 读取数据。
+从 Typesense collection 读取文档。该 source 支持有界批读取，也可以通过 `query` 传入
+Typesense 查询参数。
-## 主要功能
+## 主要特性
- [x] [批处理](../../introduction/concepts/connector-v2-features.md)
- [ ] [流处理](../../introduction/concepts/connector-v2-features.md)
@@ -24,61 +25,84 @@ import ChangeLog from '../changelog/connector-typesense.md';
| hosts | array | 是 | - |
| collection | string | 是 | - |
| schema | config | 是 | - |
-| api_key | string | 否 | - |
+| api_key | string | 是 | - |
+| protocol | string | 否 | http |
| query | string | 否 | - |
| batch_size | int | 否 | 100 |
+| common-options | | 否 | - |
### hosts [array]
-Typesense的访问地址，格式为 `host:port`，例如：["typesense-01:8108"]
+Typesense 的访问地址，格式为 `host:port`，例如：`["typesense-01:8108"]`。支持配置多个地址。
### collection [string]
-要写入的集合名，例如：“seatunnel”
+要读取的 Typesense collection 名，例如：`companies`。
### schema [config]
typesense
需要读取的列。有关更多信息，请参阅：[guide](../../introduction/concepts/schema-feature.md#how-to-declare-type-supported)。
-### api_key [config]
+### api_key [string]
-typesense 安全认证的 api_key。
+Typesense 安全认证的 `api_key`。
-### batch_size
+### protocol [string]
-读取数据时，每批次查询数量
+连接 Typesense 使用的协议，默认是 `http`。如果使用 Typesense Cloud 或启用了 TLS 的服务，
+请设置为 `https`。
+
+### query [string]
+
+Typesense 查询参数，例如 `q=*&filter_by=num_employees:>9000`。不配置时读取默认查询返回的文档。
+
+### batch_size [int]
+
+读取数据时每批查询的文档数量。
### 常用选项
Source 插件常用参数，具体请参考 [Source 常用选项](../common-options/source-common-options.md)
-## 示例
+## 任务示例
+
+### 带过滤条件读取文档
```bash
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
source {
- Typesense {
- hosts = ["localhost:8108"]
- collection = "companies"
- api_key = "xyz"
- query = "q=*&filter_by=num_employees:>9000"
- schema = {
- fields {
- company_name_list = array<string>
- company_name = string
- num_employees = long
- country = string
- id = string
- c_row = {
- c_int = int
- c_string = string
- c_array_int = array<int>
- }
- }
- }
+ Typesense {
+ hosts = ["localhost:8108"]
+ collection = "companies"
+ api_key = "xyz"
+ query = "q=*&filter_by=num_employees:>9000"
+ batch_size = 100
+ schema = {
+ fields {
+ company_name_list = array<string>
+ company_name = string
+ num_employees = long
+ country = string
+ id = string
+ c_row = {
+ c_int = int
+ c_string = string
+ c_array_int = array<int>
+ }
+ }
}
+ }
+}
+
+sink {
+ Console {}
}
```
## 变更日志
-<ChangeLog />
\ No newline at end of file
+<ChangeLog />
