This is an automated email from the ASF dual-hosted git repository. github-merge-queue[bot] pushed a commit to branch gh-readonly-queue/dev/pr-13019-c367c4c8cce611ffd0939fcdf725c1315a455c6e in repository https://gitbox.apache.org/repos/asf/seatunnel.git
commit c6185fb3c3263f6b20fd974d653098181d4b4344 Author: Jast <[email protected]> AuthorDate: Thu Oct 29 10:04:23 2026 +0000 [Docs] Fix missing sections in Chinese docs to align with English documentation (#13019) Co-authored-by: zhangshenghang <[email protected]> --- docs/zh/architecture/api-design/catalog-table.md | 10 ++ .../architecture/api-design/sink-architecture.md | 17 ++ .../architecture/api-design/translation-layer.md | 13 ++ docs/zh/architecture/features/multi-table.md | 54 ++++++ docs/zh/connectors/sink/Prometheus.md | 98 +++++++++++ docs/zh/connectors/sink/SensorsData.md | 60 +++++++ docs/zh/connectors/sink/StarRocks.md | 181 +++++++++++++++++++++ docs/zh/connectors/source/InfluxDB.md | 64 ++++++++ docs/zh/connectors/source/Intercom.md | 10 ++ docs/zh/connectors/source/Typeform.md | 15 +- docs/zh/introduction/concepts/config.md | 6 +- 11 files changed, 523 insertions(+), 5 deletions(-) diff --git a/docs/zh/architecture/api-design/catalog-table.md b/docs/zh/architecture/api-design/catalog-table.md index 5319040e34..f0c9fb0a31 100644 --- a/docs/zh/architecture/api-design/catalog-table.md +++ b/docs/zh/architecture/api-design/catalog-table.md @@ -379,3 +379,13 @@ sink { - [sink 目标端架构](sink-architecture.md) - [模式演化](../../introduction/configuration/schema-evolution.md) - [模式特性](../../introduction/concepts/schema-feature.md) + +## 11. 参考资料 + +### 关键源码文件 + +- [CatalogTable.java](../../../../seatunnel-api/src/main/java/org/apache/seatunnel/api/table/catalog/CatalogTable.java) +- [TableSchema.java](../../../../seatunnel-api/src/main/java/org/apache/seatunnel/api/table/catalog/TableSchema.java) +- [Column.java](../../../../seatunnel-api/src/main/java/org/apache/seatunnel/api/table/catalog/Column.java) +- [SeaTunnelDataType.java](../../../../seatunnel-api/src/main/java/org/apache/seatunnel/api/table/type/SeaTunnelDataType.java) +- [SchemaChangeEvent.java](../../../../seatunnel-api/src/main/java/org/apache/seatunnel/api/table/schema/event/SchemaChangeEvent.java) diff --git a/docs/zh/architecture/api-design/sink-architecture.md b/docs/zh/architecture/api-design/sink-architecture.md index b879609d77..2474e72a85 100644 --- a/docs/zh/architecture/api-design/sink-architecture.md +++ b/docs/zh/architecture/api-design/sink-architecture.md @@ -154,6 +154,10 @@ sequenceDiagram Note over Committer: commit 失败由框架重试\n必须保证幂等 ``` +## 3. 关键实现 + +### 3.1 SinkWriter 接口 + **核心职责**： - `write(element)`：接收上游记录并写入外部系统的“临时/事务内”区域（避免对外可见） - `prepareCommit(checkpointId)`：在 checkpoint 边界生成提交信息（commitInfo），要求“无副作用”（不让数据对外可见） @@ -209,6 +213,19 @@ sequenceDiagram - `combine`： Sink 总所有 writer 产生的文件/分区元数据，形成一次表级提交所需的“全量变更集” - `commit`：对外部 metastore/表事务执行一次全局原子提交；失败后需要可重试且不重复（幂等） +### 3.4 代码参考 + +**API 接口**： +- [SeaTunnelSink.java](../../../../seatunnel-api/src/main/java/org/apache/seatunnel/api/sink/SeaTunnelSink.java) +- [SinkWriter.java](../../../../seatunnel-api/src/main/java/org/apache/seatunnel/api/sink/SinkWriter.java) +- [SinkCommitter.java](../../../../seatunnel-api/src/main/java/org/apache/seatunnel/api/sink/SinkCommitter.java) +- [SinkAggregatedCommitter.java](../../../../seatunnel-api/src/main/java/org/apache/seatunnel/api/sink/SinkAggregatedCommitter.java) + +**示例实现**： +- JDBC Sink：`seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/sink/` +- Kafka Sink：`seatunnel-connectors-v2/connector-kafka/src/main/java/org/apache/seatunnel/connectors/seatunnel/kafka/sink/` +- File Sink：`seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/sink/` + ## 4. 设计考量 ### 4.1 设计权衡 diff --git a/docs/zh/architecture/api-design/translation-layer.md b/docs/zh/architecture/api-design/translation-layer.md index 7db68c39b6..db11a265d7 100644 --- a/docs/zh/architecture/api-design/translation-layer.md +++ b/docs/zh/architecture/api-design/translation-layer.md @@ -254,3 +254,16 @@ SeaTunnel 侧使用统一抽象类型；转换层根据引擎能力与用户配 - [数据 Source 架构](../api-design/source-architecture.md) - [目标端 Sink 架构](../api-design/sink-architecture.md) - [设计理念](../design-philosophy.md) + +## 10. 参考资料 + +### 关键源码文件 + +- Flink 转换层：`seatunnel-translation/seatunnel-translation-flink/` +- Spark 转换层：`seatunnel-translation/seatunnel-translation-spark/` +- 基础接口：`seatunnel-api/src/main/java/org/apache/seatunnel/api/` + +### 延伸阅读 + +- [Apache Flink Source API](https://nightlies.apache.org/flink/flink-docs-stable/docs/dev/datastream/sources/) +- [Apache Spark Data Source V2](https://spark.apache.org/docs/latest/sql-data-sources.html) diff --git a/docs/zh/architecture/features/multi-table.md b/docs/zh/architecture/features/multi-table.md index 30bdce1313..c0bb7ca407 100644 --- a/docs/zh/architecture/features/multi-table.md +++ b/docs/zh/architecture/features/multi-table.md @@ -453,6 +453,60 @@ env { 该配置不处理共享故障，例如 source 连接中断、checkpoint 协调失败、插件加载失败或 OOM；这类异常仍会导致整个作业失败。 +## 11. 限制与注意事项 + +### 11.1 当前限制 + +**并行度共享**： +- 所有表共享同一并行度 +- 无法为每张表单独设置并行度 + +**副本数固定**： +- 所有表使用相同的副本数 +- 高吞吐表和低吞吐表被同等对待 + +**内存开销**： +- 每个写入器维护独立的缓冲区 +- 100 张表 × 4 个副本 = 内存中 400 个写入器 + +### 11.2 应对方法 + +**高吞吐表**： +```hocon +# 方案一：为热点表拆分独立作业 +job-1 { source { table-name = "orders" } } # 独立作业 + +job-2 { source { table-name = "user_.*|product_.*" } } # 其余表 +``` + +**内存优化**： +```hocon +# 减小每个写入器的缓冲区 +sink { + JDBC { + batch-size = 500 # 更小的批次 + } +} +``` + +## 12. 后续增强 + +### 12.1 动态副本 + +当前的 `multi_table_sink_replica` 参数不支持按表覆盖副本数（它对所有表生效）。如果需要按表设置副本数， +还需要额外的 connector/框架能力支持。 + +### 12.2 自适应副本 + +```java +// 根据吞吐量自动调整副本数 +if (table.getWriteRate() > threshold) { + increaseReplicas(table); +} else if (table.getWriteRate() < lowThreshold) { + decreaseReplicas(table); +} +``` + ## 13. 相关资源 - [CatalogTable 和元数据](../api-design/catalog-table.md) diff --git a/docs/zh/connectors/sink/Prometheus.md b/docs/zh/connectors/sink/Prometheus.md index b57be92e0d..10e1efe70e 100644 --- a/docs/zh/connectors/sink/Prometheus.md +++ b/docs/zh/connectors/sink/Prometheus.md @@ -157,6 +157,104 @@ sink { } ``` +## 流式 Remote Write 与批量刷新 + +下面的示例以流式模式从 Kafka 读取数据并写入 Prometheus remote write 端点。Sink 会先缓冲最多 +`batch_size` 行数据再发起 HTTP 写入，同时引擎级的 `sink.flush.interval`（仅 Zeta 支持）每 10 秒 +强制刷新一次缓冲区，即使上游数据流处于空闲状态，指标样本也会持续发送。 + +```hocon +env { + parallelism = 2 + job.mode = "STREAMING" + checkpoint.interval = 30000 + sink.flush.interval = 10000 +} + +source { + Kafka { + plugin_output = "metrics_topic" + bootstrap.servers = "kafka:9092" + topic = "metrics" + format = "json" + schema = { + fields { + c_map = "map<string, string>" + c_double = double + c_timestamp = bigint + } + } + } +} + +sink { + Prometheus { + plugin_input = "metrics_topic" + url = "http://prometheus:9090/api/v1/write"; + key_label = "c_map" + key_value = "c_double" + key_timestamp = "c_timestamp" + batch_size = 2048 + retry = 5 + retry_backoff_multiplier_ms = 200 + retry_backoff_max_ms = 10000 + } +} +``` + +## 多表 Remote Write + +当同一个作业从多张上游表读取数据并写入同一个 Prometheus remote write 端点时，可以通过 +`multi_table_sink_replica` 控制每张表分配多少个写入任务。表都比较小时使用默认值 `1` 即可； +只有当某张表需要比其他表更高的并行度时才需要调大该值。 + +```hocon +env { + parallelism = 2 + job.mode = "BATCH" +} + +source { + FakeSource { + plugin_output = "fake_app_a" + schema = { + fields { + c_map = "map<string, string>" + c_double = double + c_timestamp = timestamp + } + } + rows = [ + { kind = INSERT, fields = [{"__name__" : "app_a_metric"}, 1.0, CURRENT_TIMESTAMP] } + ] + } + FakeSource { + plugin_output = "fake_app_b" + schema = { + fields { + c_map = "map<string, string>" + c_double = double + c_timestamp = timestamp + } + } + rows = [ + { kind = INSERT, fields = [{"__name__" : "app_b_metric"}, 2.0, CURRENT_TIMESTAMP] } + ] + } +} + +sink { + Prometheus { + plugin_input = ["fake_app_a", "fake_app_b"] + url = "http://prometheus:9090/api/v1/write"; + key_label = "c_map" + key_value = "c_double" + key_timestamp = "c_timestamp" + multi_table_sink_replica = 2 + } +} +``` + ## 变更日志 <ChangeLog /> diff --git a/docs/zh/connectors/sink/SensorsData.md b/docs/zh/connectors/sink/SensorsData.md index ad2e035880..113503a4d9 100644 --- a/docs/zh/connectors/sink/SensorsData.md +++ b/docs/zh/connectors/sink/SensorsData.md @@ -278,6 +278,66 @@ sink { } ``` +### 用户明细（Detail 记录） + +用户明细记录（`record_type = "details"`）会为 SensorsData 用户附加一条按记录维度的标识。 +`detail_id_column` 提供明细键，`distinct_id_column` 和 `identity_fields` 用于标识所属用户。 + +```hocon +sink { + SensorsData { + consumer = console + server_url = "http://10.129.27.43:8106/sa?project=sditest"; + time_free = true + + record_type = details + schema = fund_manager + distinct_id_column = c_id + detail_id_column = c_id + identity_fields = [ + { target = "$identity_distinct_id", source = c_id } + ] + property_fields = [ + { target = c_id, source = c_id, type = STRING } + { target = fund_amount, source = c_int, type = INT } + { target = "$is_valid", source = c_boolean, type = BOOLEAN } + ] + } +} +``` + +### 多身份与动态事件名称 + +下面的示例直接从数据行本身构造事件名称（`event_name = "${c_event}"`），并一次性映射多个身份 +（`$identity_login_id`、`$identity_distinct_id`）。转换失败的记录会通过 `skip_error_record = true` 跳过。 + +```hocon +sink { + SensorsData { + consumer = console + server_url = "http://10.1.136.63:8106/sa?project=default"; + time_free = true + + record_type = events + schema = events + event_name = "${c_event}" + time_column = c_date + distinct_id_column = c_bigint + identity_fields = [ + { source = c_bigint, target = "$identity_login_id" } + { source = c_bigint, target = "$identity_distinct_id" } + ] + property_fields = [ + { target = c_tinyint, source = c_tinyint, type = INT } + { target = c_bigint, source = c_bigint, type = BIGINT } + { target = c_int, source = c_int, type = INT } + { target = c_boolean, source = c_boolean, type = BOOLEAN } + ] + skip_error_record = true + } +} +``` + ### 控制台输出（用于测试） ```hocon diff --git a/docs/zh/connectors/sink/StarRocks.md b/docs/zh/connectors/sink/StarRocks.md index 24e1e36b2e..ae0303daa9 100644 --- a/docs/zh/connectors/sink/StarRocks.md +++ b/docs/zh/connectors/sink/StarRocks.md @@ -377,6 +377,187 @@ sink { } ``` +### CDC 与 Schema 变更 + +下面的示例演示 MySQL-CDC 以 `schema-changes.enabled = true` 的方式写入 StarRocks，这样上游 MySQL 的 DDL 变更 +（新增列、类型加宽等）会同步应用到目标 StarRocks 主键表上。 + +```hocon +env { + job.mode = "STREAMING" + checkpoint.interval = 2000 +} + +source { + MySQL-CDC { + username = "st_user_source" + password = "mysqlpw" + table-names = ["shop.products", "shop.orders", "shop.customers"] + url = "jdbc:mysql://mysql_cdc_e2e:3306/shop" + + schema-changes.enabled = true + } +} + +sink { + StarRocks { + nodeUrls = ["starrocks_cdc_e2e:8040"] + base-url = "jdbc:mysql://starrocks_cdc_e2e:9030/shop" + username = "root" + password = "" + database = "shop" + table = "${table_name}" + max_retries = 3 + enable_upsert_delete = true + schema_save_mode = "RECREATE_SCHEMA" + data_save_mode = "DROP_DATA" + save_mode_create_template = """ + CREATE TABLE IF NOT EXISTS shop.`${table_name}` ( + ${rowtype_primary_key}, + ${rowtype_fields} + ) ENGINE=OLAP + PRIMARY KEY (${rowtype_primary_key}) + DISTRIBUTED BY HASH (${rowtype_primary_key}) + PROPERTIES ( + "replication_num" = "1", + "in_memory" = "false", + "enable_persistent_index" = "true", + "replicated_storage" = "true", + "compression" = "LZ4" + ) + """ + } +} +``` + +### MySQL-CDC 与定时刷新 + +下面的示例在流式作业中配置了 `sink.flush.interval`，使 StarRocks Sink 每隔 500 ms 刷新一次缓冲区， +不再受 `batch_max_rows` 和 `batch_max_bytes` 的限制。 + +```hocon +env { + parallelism = 1 + job.mode = "STREAMING" + checkpoint.interval = 300000 + sink.flush.interval = 500 +} + +source { + MySQL-CDC { + server-id = 5670 + username = "st_user_source" + password = "mysqlpw" + table-names = ["shop.products"] + url = "jdbc:mysql://mysql_starrocks_timer_flush_e2e:3306/shop" + } +} + +sink { + StarRocks { + nodeUrls = ["starrocks_timer_flush_e2e:8030"] + base-url = "jdbc:mysql://starrocks_timer_flush_e2e:9030/timer_flush" + username = root + password = "" + database = "timer_flush" + table = "starrocks_timer_flush" + labelPrefix = "timer-flush-" + batch_max_rows = 100000 + batch_max_bytes = 104857600 + schema_save_mode = "IGNORE" + data_save_mode = "APPEND_DATA" + starrocks.config = { + format = "JSON" + } + } +} +``` + +### 多表 + +#### 示例1 + +```hocon +env { + parallelism = 1 + job.mode = "STREAMING" + checkpoint.interval = 5000 +} + +source { + Mysql-CDC { + base-url = "jdbc:mysql://127.0.0.1:3306/seatunnel" + username = "root" + password = "******" + + table-names = ["seatunnel.role","seatunnel.user","galileo.Bucket"] + } +} + +transform { +} + +sink { + StarRocks { + nodeUrls = ["e2e_starRocksdb:8030"] + base-url = "jdbc:mysql://e2e_starRocksdb:9030/" + username = root + password = "" + database = "${database_name}_test" + table = "${table_name}_test" + ... + + // 支持 upsert/delete 事件同步（enable_upsert_delete=true），仅支持 PrimaryKey 模型。 + enable_upsert_delete = true + } +} +``` + +#### 示例2 + +```hocon +env { + parallelism = 1 + job.mode = "BATCH" +} + +source { + Jdbc { + driver = oracle.jdbc.driver.OracleDriver + url = "jdbc:oracle:thin:@localhost:1521/XE" + user = testUser + password = testPassword + + table_list = [ + { + table_path = "TESTSCHEMA.TABLE_1" + }, + { + table_path = "TESTSCHEMA.TABLE_2" + } + ] + } +} + +transform { +} + +sink { + StarRocks { + nodeUrls = ["e2e_starRocksdb:8030"] + base-url = "jdbc:mysql://e2e_starRocksdb:9030/" + username = root + password = "" + database = "${schema_name}_test" + table = "${table_name}_test" + ... + + // 支持 upsert/delete 事件同步（enable_upsert_delete=true），仅支持 PrimaryKey 模型。 + enable_upsert_delete = true + } +} +``` + ## 常见问题 ### StarRocks Sink 支持自动建表吗？ diff --git a/docs/zh/connectors/source/InfluxDB.md b/docs/zh/connectors/source/InfluxDB.md index b4f35f3568..0f78b41273 100644 --- a/docs/zh/connectors/source/InfluxDB.md +++ b/docs/zh/connectors/source/InfluxDB.md @@ -159,6 +159,19 @@ split 2: select * from test where ($split_column >= 6 and $split_column < 11) an > 提示：确保 `upper_bound - lower_bound` 能被 `partition_num` 整除，否则查询结果会重叠。 +### where [string] + +:::caution 保留参数 + +当前的切分逻辑会直接从 `sql` 参数中读取小写的 `where` 关键字。设置 `where` 参数对生成的切分查询 +没有任何效果——请把过滤条件直接写进 `sql` 中，例如 `select * from test where age > 0`。切分解析器 +对 `where` 关键字区分大小写。 + +该参数保留在参数列表中，只是因为校验规则（`InfluxDBSourceFactory.optionRule()`）为了向后兼容仍然 +引用了它；运行时的切分查询生成器不会读取该参数。 + +::: + ### epoch [string] InfluxDB 返回的时间精度。可选值：`H`、`m`、`s`、`MS`、`u`、`n`，默认值为 `n`。 @@ -319,6 +332,57 @@ sink { } ``` +### 有界读取与并行切分 + +InfluxDB Source 的读取范围由 `sql` 的结果决定。如果需要把它接入流式 Sink 且不丢数据，可以设置一个 +有限的 `partition_num`，让 SeaTunnel 通过检查点记录每个切分的读取位置。 + +```hocon +env { + parallelism = 2 + job.mode = "BATCH" + checkpoint.interval = 10000 +} + +source { + InfluxDB { + url = "http://influxdb-host:8086"; + sql = "select label, c_string, c_double, c_bigint, c_float, c_int, c_smallint, c_boolean from source" + database = "test" + lower_bound = 0 + upper_bound = 99 + partition_num = 4 + split_column = "c_int" + query_timeout_sec = 10 + connect_timeout_ms = 20000 + schema { + fields { + label = STRING + c_string = STRING + c_double = DOUBLE + c_bigint = BIGINT + c_float = FLOAT + c_int = INT + c_smallint = SMALLINT + c_boolean = BOOLEAN + time = BIGINT + } + } + } +} + +sink { + InfluxDB { + url = "http://influxdb-host:8086"; + database = "test" + measurement = "sink" + key_time = "time" + key_tags = ["label"] + batch_size = 1024 + } +} +``` + ## 变更日志 <ChangeLog /> diff --git a/docs/zh/connectors/source/Intercom.md b/docs/zh/connectors/source/Intercom.md index 8bbd122aac..3e4bbc53be 100644 --- a/docs/zh/connectors/source/Intercom.md +++ b/docs/zh/connectors/source/Intercom.md @@ -29,6 +29,16 @@ import ChangeLog from '../changelog/connector-http-intercom.md'; | retry_backoff_multiplier_ms | Int | 否 | `100` | 退避倍数（毫秒）。 | | retry_backoff_max_ms | Int | 否 | `10000` | 最大退避时间（毫秒）。 | +### api_key +只会通过 `Authorization: Bearer <token>` 请求头发送。连接器不会在日志中输出请求头或配置，也不会 +持久化任何状态，因此该令牌不会进入检查点。引擎在打印作业配置时是否对 `api_key` 做脱敏处理， +不在本连接器的控制范围内。 + +### retry +HTTP 429 和 5xx 的最大重试次数（基础 HTTP 客户端中还包括 IOException）。退避时间从 +`retry_backoff_multiplier_ms` 开始翻倍，直到 `retry_backoff_max_ms`。不会遵循 `Retry-After` 响应头。 +Intercom 的默认限流为每个应用每分钟 10,000 次调用（每个工作区 25,000 次），按 10 秒窗口执行限制。 + ## 输出列 `id`、`role`、`email`、`name`、`phone`、`external_id`（均为 STRING，后三者可为 null）， diff --git a/docs/zh/connectors/source/Typeform.md b/docs/zh/connectors/source/Typeform.md index 0d060b5d65..bc6afcf6f6 100644 --- a/docs/zh/connectors/source/Typeform.md +++ b/docs/zh/connectors/source/Typeform.md @@ -33,8 +33,19 @@ import ChangeLog from '../changelog/connector-http-typeform.md'; | retry_backoff_multiplier_ms | Int | 否 | `100` | 退避倍数（毫秒）。 | | retry_backoff_max_ms | Int | 否 | `10000` | 最大退避时间（毫秒）。 | -令牌只放在 `Authorization: Bearer <token>` 请求头中，不会出现在查询参数、日志或作业状态里。 -Typeform 每个账号每秒允许 2 个请求，因此连接器会让请求间隔至少 500 毫秒。 +### api_key +只会通过 `Authorization: Bearer <token>` 请求头发送，绝不会出现在查询参数中。连接器不会在日志中 +输出请求头或配置，也不会持久化任何状态，因此该令牌不会进入检查点。引擎在打印作业配置时是否对 +`api_key` 做脱敏处理，不在本连接器的控制范围内。 + +### since / until / response_type +这三个参数会原样传给 Typeform。对于已完成的回复，Typeform 按 `submitted_at` 过滤 `since` 和 `until`； +对于其他回复类型则使用不同的时间戳（参见 Typeform 的 API 参考）。 + +### retry +请求之间的间隔至少 500 毫秒，因为 Typeform 每个账号每秒只允许 2 个请求。HTTP 429 和 5xx 会进行重试， +退避时间从 `retry_backoff_multiplier_ms` 开始翻倍，直到 `retry_backoff_max_ms`。不会遵循 `Retry-After` +响应头。 ## 输出列 diff --git a/docs/zh/introduction/concepts/config.md b/docs/zh/introduction/concepts/config.md index 52ffb947f3..6befacb32f 100644 --- a/docs/zh/introduction/concepts/config.md +++ b/docs/zh/introduction/concepts/config.md @@ -206,7 +206,7 @@ sql = """ select * from "table" """ 在配置文件中，我们可以定义一些变量并在运行时替换它们。但请注意，目前仅支持 HOCON 格式的文件。 -变量使用方法： +### 变量使用方法： - `${varName}`，如果变量未传值，则抛出异常。 - `${varName:default}`，如果变量未传值，则使用默认值。如果设置默认值则变量需要写在双引号中。 - `${varName:}`，如果变量未传值，则使用空字符串。 @@ -220,7 +220,7 @@ export varName="value with space" 如果您在配置文件中设置了没有默认值的变量，但在执行过程中未传递该变量，则会保留该变量值，系统不会抛出异常。但请您需要确保其他流程能够正确解析该变量值。例如，ElasticSearch的索引需要支持`${xxx}`这样的格式来动态指定索引。若其他流程不支持，程序可能无法正常运行。 -具体样例： +### 示例： ```hocon env { job.mode = "BATCH" @@ -321,7 +321,7 @@ sink { ``` -一些注意事项: +### 注意事项: - 为了避免非预期的数据同步错误，`-i` 传参不能出现重复的key。 - 如果值包含逗号，需要用`\"`包裹起来，如 `-i read_cols=\"id,name\"`，但list和map类型不需要用`\"`包裹，如`-i include_fields=[id,name]`。 - 如果值包含特殊字符，如`(`，请使用`'`引号将其括起来。
