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 150b7468a2 [Docs][Connector-V2] Improve Cassandra connector docs
(#11266)
150b7468a2 is described below
commit 150b7468a21a3ed14121d2aefad8f3e889db2a5a
Author: Daniel Carter <[email protected]>
AuthorDate: Fri Jul 3 08:17:00 2026 +0800
[Docs][Connector-V2] Improve Cassandra connector docs (#11266)
Co-authored-by: DanielCarter-stack
<[email protected]>
Co-authored-by: Shenghang <[email protected]>
---
docs/en/connectors/sink/Cassandra.md | 95 +++++++++++++++++++++-------
docs/en/connectors/source/Cassandra.md | 110 +++++++++++++++++++++++++++------
docs/zh/connectors/sink/Cassandra.md | 93 +++++++++++++++++++++-------
docs/zh/connectors/source/Cassandra.md | 104 ++++++++++++++++++++++++++-----
4 files changed, 319 insertions(+), 83 deletions(-)
diff --git a/docs/en/connectors/sink/Cassandra.md
b/docs/en/connectors/sink/Cassandra.md
index 58dc0e5348..d32d41c508 100644
--- a/docs/en/connectors/sink/Cassandra.md
+++ b/docs/en/connectors/sink/Cassandra.md
@@ -6,7 +6,11 @@ import ChangeLog from '../changelog/connector-cassandra.md';
## Description
-Write data to Apache Cassandra.
+Write data to Apache Cassandra in batch mode.
+
+The sink writes rows to an existing Cassandra table. If `fields` is not
configured, the connector
+uses all columns from the target Cassandra table schema. If `fields` is
configured, only those
+columns are written, and every configured field must exist in the target table.
## Key features
@@ -14,19 +18,19 @@ Write data to Apache Cassandra.
## Options
-| name | type | required | default value |
-|-------------------|---------|----------|---------------|
-| host | String | Yes | - |
-| keyspace | String | Yes | - |
-| table | String | Yes | - |
-| username | String | No | - |
-| password | String | No | - |
-| datacenter | String | No | datacenter1 |
-| consistency_level | String | No | LOCAL_ONE |
-| fields | Array | No | - |
-| batch_size | int | No | 5000 |
-| batch_type | String | No | UNLOGGED |
-| async_write | boolean | No | true |
+| Name | Type | Required | Default | Description |
+|-------------------|---------|----------|-------------|-------------|
+| host | String | Yes | - | Cassandra cluster
address. Use `host:port`, and separate multiple hosts with commas. |
+| keyspace | String | Yes | - | Cassandra keyspace
used by the session. |
+| table | String | Yes | - | Target Cassandra
table name. |
+| username | String | No | - | Cassandra username.
Configure it together with `password`. |
+| password | String | No | - | Cassandra password.
Configure it together with `username`. |
+| datacenter | String | No | datacenter1 | Local datacenter name
used by the Cassandra Java driver. |
+| consistency_level | String | No | LOCAL_ONE | Write consistency
level, such as `LOCAL_ONE`, `ONE`, `QUORUM`, or `LOCAL_QUORUM`. |
+| fields | Array | No | - | Target columns to
write. If not set, all target table columns are used. |
+| batch_size | int | No | 5000 | Maximum number of
rows buffered before one flush. |
+| batch_type | String | No | UNLOGGED | Cassandra batch type.
Supported driver values include `LOGGED`, `UNLOGGED`, and `COUNTER`. |
+| async_write | boolean | No | true | Whether to execute
writes asynchronously. |
### host [string]
@@ -59,8 +63,11 @@ The `Cassandra` write consistency level, default is
`LOCAL_ONE`.
### fields [array]
-The data field that needs to be output to `Cassandra` , if not configured, it
will be automatically adapted
-according to the sink table `schema`.
+The data fields that need to be written to `Cassandra`. If this option is not
configured, the
+connector reads the target table schema and writes all columns from that table.
+
+When this option is configured, the field names must exist in the target
Cassandra table and must
+also exist in the upstream SeaTunnel row.
### batch_size [number]
@@ -69,7 +76,7 @@ default is `5000`.
### batch_type [String]
-The `Cassandra` batch processing mode, default is `UNLOGGER`.
+The `Cassandra` batch processing mode, default is `UNLOGGED`.
### async_write [boolean]
@@ -77,15 +84,55 @@ Whether `cassandra` writes in asynchronous mode, default is
`true`.
## Examples
+### Write to Cassandra
+
+```hocon
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
+source {
+ Cassandra {
+ host = "localhost:9042"
+ username = "cassandra"
+ password = "cassandra"
+ datacenter = "datacenter1"
+ keyspace = "test"
+ cql = "select * from source_table"
+ plugin_output = "source_table"
+ }
+}
+
+sink {
+ Cassandra {
+ host = "localhost:9042"
+ username = "cassandra"
+ password = "cassandra"
+ datacenter = "datacenter1"
+ keyspace = "test"
+ table = "sink_table"
+ async_write = true
+ }
+}
+```
+
+### Write Selected Fields
+
```hocon
sink {
- Cassandra {
- host = "localhost:9042"
- username = "cassandra"
- password = "cassandra"
- datacenter = "datacenter1"
- keyspace = "test"
- }
+ Cassandra {
+ host = "localhost:9042"
+ username = "cassandra"
+ password = "cassandra"
+ datacenter = "datacenter1"
+ keyspace = "test"
+ table = "sink_table"
+ fields = ["id", "c_int", "c_text"]
+ batch_size = 1000
+ batch_type = "UNLOGGED"
+ async_write = true
+ }
}
```
diff --git a/docs/en/connectors/source/Cassandra.md
b/docs/en/connectors/source/Cassandra.md
index b45f502c0f..8fbb432cbd 100644
--- a/docs/en/connectors/source/Cassandra.md
+++ b/docs/en/connectors/source/Cassandra.md
@@ -6,7 +6,15 @@ import ChangeLog from '../changelog/connector-cassandra.md';
## Description
-Read data from Apache Cassandra.
+Read data from Apache Cassandra in batch mode.
+
+The Cassandra source supports two read modes:
+
+- Single-table read with `cql`.
+- Multi-table read with `tables_configs`, where each entry contains one `cql`.
+
+The source gets column names and data types from the result set returned by
the configured CQL, so
+the CQL should return the columns that downstream steps need.
## Key features
@@ -17,18 +25,42 @@ Read data from Apache Cassandra.
- [ ] [parallelism](../../introduction/concepts/connector-v2-features.md)
- [ ] [support user-defined
split](../../introduction/concepts/connector-v2-features.md)
+## Data Type Mapping
+
+| Cassandra Data Type | SeaTunnel Data Type |
+|---------------------|---------------------|
+| ascii | STRING |
+| varchar/text | STRING |
+| varint | STRING |
+| uuid/timeuuid | STRING |
+| inet | STRING |
+| tinyint | BYTE |
+| smallint | SHORT |
+| int | INT |
+| bigint/counter | LONG |
+| float | FLOAT |
+| double/decimal | DOUBLE |
+| boolean | BOOLEAN |
+| time | TIME |
+| date | DATE |
+| timestamp | TIMESTAMP |
+| blob | ARRAY\<BYTE\> |
+| list | ARRAY |
+| set | ARRAY |
+| map | MAP |
+
## Options
-| name | type | required | default value |
-|-------------------|--------------------|----------|---------------|
-| host | String | Yes | - |
-| keyspace | String | Yes | - |
-| cql | String | No * | - |
-| tables_configs | List\<Map\> | No * | - |
-| username | String | No | - |
-| password | String | No | - |
-| datacenter | String | No | datacenter1 |
-| consistency_level | String | No | LOCAL_ONE |
+| Name | Type | Required | Default | Description |
+|-------------------|------------|----------|-------------|-------------|
+| host | String | Yes | - | Cassandra cluster
address. Use `host:port`, and separate multiple hosts with commas. |
+| keyspace | String | Yes | - | Cassandra keyspace
used by the session. |
+| cql | String | No * | - | CQL used to read
one table. |
+| tables_configs | List\<Map\> | No * | - | Multi-table read
configuration. Each item must contain one `cql`. |
+| username | String | No | - | Cassandra
username. Configure it together with `password`. |
+| password | String | No | - | Cassandra
password. Configure it together with `username`. |
+| datacenter | String | No | datacenter1 | Local datacenter
name used by the Cassandra Java driver. |
+| consistency_level | String | No | LOCAL_ONE | Read consistency
level, such as `LOCAL_ONE`, `ONE`, `QUORUM`, or `LOCAL_QUORUM`. |
> \* Exactly one of `cql` or `tables_configs` must be provided.
@@ -43,13 +75,20 @@ The `Cassandra` keyspace.
### cql [String]
-The query CQL used to read data from Cassandra. Use this for single-table
reads.
-Mutually exclusive with `tables_configs`.
+The query CQL used to read data from Cassandra. Use this for single-table
reads. It is mutually
+exclusive with `tables_configs`.
+
+The connector uses the CQL result metadata to build the output schema. In
normal cases, use a query
+that returns real table columns, for example `select * from source_table` or
+`select id, name from source_table`.
### tables_configs [List\<Map\>]
Multi-table read configuration. Each entry must contain a `cql` field with the
query for that table.
-Mutually exclusive with `cql`.
+It is mutually exclusive with root-level `cql`.
+
+Do not configure the same source table more than once in `tables_configs`; the
connector checks for
+duplicate table names during startup.
Example entry:
@@ -75,11 +114,26 @@ The `Cassandra` datacenter, default is `datacenter1`.
The `Cassandra` read consistency level, default is `LOCAL_ONE`.
+## Notes
+
+- `username` and `password` are a pair. Configure both when authentication is
enabled; omit both
+ when the cluster does not require authentication.
+- `datacenter` must match the Cassandra cluster local datacenter name. The
default is
+ `datacenter1`, which is also the common Testcontainers default.
+- `cql` and `tables_configs` are mutually exclusive. Use `cql` for one result
table and
+ `tables_configs` when one source should read multiple Cassandra tables.
+- The source is a batch source. It reads the current query result and then
finishes.
+
## Examples
-### Single-table mode
+### Single-table read
```hocon
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
source {
Cassandra {
host = "localhost:9042"
@@ -91,11 +145,20 @@ source {
plugin_output = "source_table"
}
}
+
+sink {
+ Console {}
+}
```
-### Multi-table mode
+### Multi-table read
```hocon
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
source {
Cassandra {
host = "localhost:9042"
@@ -105,14 +168,25 @@ source {
keyspace = "test"
tables_configs = [
{
- cql = "SELECT id, name FROM test.table1"
+ cql = "select id, c_int from mt_source_a"
},
{
- cql = "SELECT id, value FROM test.table2"
+ cql = "select id, c_int from mt_source_b"
}
]
}
}
+
+sink {
+ Cassandra {
+ host = "localhost:9042"
+ username = "cassandra"
+ password = "cassandra"
+ datacenter = "datacenter1"
+ keyspace = "test"
+ table = "mt_sink_table"
+ }
+}
```
## Changelog
diff --git a/docs/zh/connectors/sink/Cassandra.md
b/docs/zh/connectors/sink/Cassandra.md
index 00e8b5e2d9..006acc1958 100644
--- a/docs/zh/connectors/sink/Cassandra.md
+++ b/docs/zh/connectors/sink/Cassandra.md
@@ -6,7 +6,10 @@ import ChangeLog from '../changelog/connector-cassandra.md';
## 描述
-将数据写入 Apache Cassandra.
+以批处理方式将数据写入 Apache Cassandra。
+
+sink 会把数据写入已经存在的 Cassandra 表。如果不配置 `fields`，连接器会使用目标 Cassandra 表里的全部字段。
+如果配置了 `fields`，则只写这些字段，并且每个字段都必须存在于目标表中。
## 关键特性
@@ -14,19 +17,19 @@ import ChangeLog from '../changelog/connector-cassandra.md';
## 选项
-| 名称 | 类型 | 必需 | 默认值 |
-|-------------------|---------|----|---------------|
-| host | String | 是 | - |
-| keyspace | String | 是 | - |
-| table | String | 是 | - |
-| username | String | 否 | - |
-| password | String | 否 | - |
-| datacenter | String | 否 | datacenter1 |
-| consistency_level | String | 否 | LOCAL_ONE |
-| fields | Array | 否 | - |
-| batch_size | int | 否 | 5000 |
-| batch_type | String | 否 | UNLOGGED |
-| async_write | boolean | 否 | true |
+| 名称 | 类型 | 是否必填 | 默认值 | 描述 |
+|-------------------|---------|----------|-------------|------|
+| host | String | 是 | - | Cassandra 集群地址，格式是
`host:port`，多个地址用逗号分隔。 |
+| keyspace | String | 是 | - | Cassandra 会话使用的
keyspace。 |
+| table | String | 是 | - | 目标 Cassandra 表名。 |
+| username | String | 否 | - | Cassandra 用户名，需要和
`password` 一起配置。 |
+| password | String | 否 | - | Cassandra 密码，需要和
`username` 一起配置。 |
+| datacenter | String | 否 | datacenter1 | Cassandra Java Driver
使用的本地数据中心名称。 |
+| consistency_level | String | 否 | LOCAL_ONE | 写入一致性级别，例如
`LOCAL_ONE`、`ONE`、`QUORUM`、`LOCAL_QUORUM`。 |
+| fields | Array | 否 | - |
要写入的目标字段。不配置时写入目标表的全部字段。 |
+| batch_size | int | 否 | 5000 | 每次 flush 前最多缓存的行数。 |
+| batch_type | String | 否 | UNLOGGED | Cassandra batch
类型，常用值包括 `LOGGED`、`UNLOGGED`、`COUNTER`。 |
+| async_write | boolean | 否 | true | 是否异步执行写入。 |
### host [string]
@@ -59,7 +62,9 @@ import ChangeLog from '../changelog/connector-cassandra.md';
### fields [array]
-需要输出到 `Cassandra` 的数据字段, 如果未配置, 如果未配置，它将自动适应 sink 表 `schema`.
+需要写入到 `Cassandra` 的字段。如果不配置，连接器会读取目标表结构，并写入目标表中的全部字段。
+
+如果配置了该选项，字段名必须存在于目标 Cassandra 表中，也必须存在于上游 SeaTunnel 数据中。
### batch_size [number]
@@ -68,7 +73,7 @@ import ChangeLog from '../changelog/connector-cassandra.md';
### batch_type [String]
-`Cassandra` 批处理模式, 默认值 `UNLOGGER`.
+`Cassandra` 批处理模式, 默认值 `UNLOGGED`.
### async_write [boolean]
@@ -76,18 +81,58 @@ import ChangeLog from '../changelog/connector-cassandra.md';
## 示例
+### 写入 Cassandra
+
+```hocon
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
+source {
+ Cassandra {
+ host = "localhost:9042"
+ username = "cassandra"
+ password = "cassandra"
+ datacenter = "datacenter1"
+ keyspace = "test"
+ cql = "select * from source_table"
+ plugin_output = "source_table"
+ }
+}
+
+sink {
+ Cassandra {
+ host = "localhost:9042"
+ username = "cassandra"
+ password = "cassandra"
+ datacenter = "datacenter1"
+ keyspace = "test"
+ table = "sink_table"
+ async_write = true
+ }
+}
+```
+
+### 写入指定字段
+
```hocon
sink {
- Cassandra {
- host = "localhost:9042"
- username = "cassandra"
- password = "cassandra"
- datacenter = "datacenter1"
- keyspace = "test"
- }
+ Cassandra {
+ host = "localhost:9042"
+ username = "cassandra"
+ password = "cassandra"
+ datacenter = "datacenter1"
+ keyspace = "test"
+ table = "sink_table"
+ fields = ["id", "c_int", "c_text"]
+ batch_size = 1000
+ batch_type = "UNLOGGED"
+ async_write = true
+ }
}
```
## 变更日志
-<ChangeLog />
\ No newline at end of file
+<ChangeLog />
diff --git a/docs/zh/connectors/source/Cassandra.md
b/docs/zh/connectors/source/Cassandra.md
index 17a3d36a92..889d465e09 100644
--- a/docs/zh/connectors/source/Cassandra.md
+++ b/docs/zh/connectors/source/Cassandra.md
@@ -6,7 +6,14 @@ import ChangeLog from '../changelog/connector-cassandra.md';
## 描述
-从 Apache Cassandra 读取数据.
+以批处理方式从 Apache Cassandra 读取数据。
+
+Cassandra source 支持两种读取方式：
+
+- 使用 `cql` 读取单张表。
+- 使用 `tables_configs` 读取多张表，每个条目里配置一个 `cql`。
+
+连接器会根据 CQL 返回结果里的列名和数据类型生成下游数据结构，所以 CQL 应该返回下游真正需要的列。
## 关键特性
@@ -17,18 +24,42 @@ import ChangeLog from '../changelog/connector-cassandra.md';
- [ ] [并行度](../../introduction/concepts/connector-v2-features.md)
- [ ] [支持用户自定义分片](../../introduction/concepts/connector-v2-features.md)
+## 数据类型映射
+
+| Cassandra 数据类型 | SeaTunnel 数据类型 |
+|-------------------|--------------------|
+| ascii | STRING |
+| varchar/text | STRING |
+| varint | STRING |
+| uuid/timeuuid | STRING |
+| inet | STRING |
+| tinyint | BYTE |
+| smallint | SHORT |
+| int | INT |
+| bigint/counter | LONG |
+| float | FLOAT |
+| double/decimal | DOUBLE |
+| boolean | BOOLEAN |
+| time | TIME |
+| date | DATE |
+| timestamp | TIMESTAMP |
+| blob | ARRAY\<BYTE\> |
+| list | ARRAY |
+| set | ARRAY |
+| map | MAP |
+
## 选项
-| 名称 | 类型 | 必需 | 默认值 |
-|-------------------|-------------|------|---------------|
-| host | String | 是 | - |
-| keyspace | String | 是 | - |
-| cql | String | 否 * | - |
-| tables_configs | List\<Map\> | 否 * | - |
-| username | String | 否 | - |
-| password | String | 否 | - |
-| datacenter | String | 否 | datacenter1 |
-| consistency_level | String | 否 | LOCAL_ONE |
+| 名称 | 类型 | 是否必填 | 默认值 | 描述 |
+|-------------------|------------|----------|-------------|------|
+| host | String | 是 | - | Cassandra 集群地址，格式是
`host:port`，多个地址用逗号分隔。 |
+| keyspace | String | 是 | - | Cassandra 会话使用的
keyspace。 |
+| cql | String | 否 * | - | 读取单张表时使用的 CQL。 |
+| tables_configs | List\<Map\> | 否 * | - | 多表读取配置，每个条目必须包含一个
`cql`。 |
+| username | String | 否 | - | Cassandra 用户名，需要和
`password` 一起配置。 |
+| password | String | 否 | - | Cassandra 密码，需要和
`username` 一起配置。 |
+| datacenter | String | 否 | datacenter1 | Cassandra Java
Driver 使用的本地数据中心名称。 |
+| consistency_level | String | 否 | LOCAL_ONE | 读取一致性级别，例如
`LOCAL_ONE`、`ONE`、`QUORUM`、`LOCAL_QUORUM`。 |
> \* `cql` 与 `tables_configs` 二选一，必须提供其中之一。
@@ -43,11 +74,16 @@ import ChangeLog from '../changelog/connector-cassandra.md';
### cql [String]
-查询 CQL，用于通过 Cassandra 会话读取单张表的数据。与 `tables_configs` 互斥。
+查询 CQL，用于读取单张表的数据。它和 `tables_configs` 互斥。
+
+连接器会使用 CQL 返回结果里的元数据来生成输出结构。通常建议写成能返回真实表字段的查询，例如
+`select * from source_table` 或 `select id, name from source_table`。
### tables_configs [List\<Map\>]
-多表读取配置，每个条目必须包含 `cql` 字段。与 `cql` 互斥。
+多表读取配置，每个条目必须包含 `cql` 字段。它和根层级的 `cql` 互斥。
+
+不要在 `tables_configs` 中重复配置同一张源表，连接器启动时会检查重复表名。
示例条目：
@@ -73,11 +109,25 @@ import ChangeLog from
'../changelog/connector-cassandra.md';
`Cassandra` 的读取一致性级别, 默认为 `LOCAL_ONE`.
+## 注意事项
+
+- `username` 和 `password` 是一组配置。集群开启认证时两个都要配；未开启认证时两个都可以不配。
+- `datacenter` 必须和 Cassandra 集群的本地数据中心名称一致。默认值是 `datacenter1`，这也是常见
+ Testcontainers 环境里的默认值。
+- `cql` 和 `tables_configs` 互斥。读取一个结果表时用 `cql`，需要让一个 source 读取多张 Cassandra 表时用
+ `tables_configs`。
+- 这是批处理 source。它读取当前查询结果后就会结束。
+
## 示例
-### 单表模式
+### 单表读取
```hocon
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
source {
Cassandra {
host = "localhost:9042"
@@ -89,11 +139,20 @@ source {
plugin_output = "source_table"
}
}
+
+sink {
+ Console {}
+}
```
-### 多表模式
+### 多表读取
```hocon
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
source {
Cassandra {
host = "localhost:9042"
@@ -103,14 +162,25 @@ source {
keyspace = "test"
tables_configs = [
{
- cql = "SELECT id, name FROM test.table1"
+ cql = "select id, c_int from mt_source_a"
},
{
- cql = "SELECT id, value FROM test.table2"
+ cql = "select id, c_int from mt_source_b"
}
]
}
}
+
+sink {
+ Cassandra {
+ host = "localhost:9042"
+ username = "cassandra"
+ password = "cassandra"
+ datacenter = "datacenter1"
+ keyspace = "test"
+ table = "mt_sink_table"
+ }
+}
```
## 变更日志
