You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@seatunnel.apache.org by li...@apache.org on 2026/07/30 06:21:52 UTC
(seatunnel) branch dev updated: [Docs] Add second-priority FAQ guidance (#11590)
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 74754b6f17 [Docs] Add second-priority FAQ guidance (#11590)
74754b6f17 is described below
commit 74754b6f17ee77787c23bfd249d88c30ef3dc147
Author: danielnadean <gi...@gmail.com>
AuthorDate: Thu Jul 30 14:21:46 2026 +0800
[Docs] Add second-priority FAQ guidance (#11590)
Co-authored-by: davidzollo <da...@gmail.com>
---
docs/en/connectors/connector-faq.md | 4 ++
docs/en/connectors/file-object-storage-faq.md | 75 ++++++++++++++++++++
docs/en/connectors/type-schema-faq.md | 69 +++++++++++++++++++
docs/en/developer/connector-runtime-boundaries.md | 62 +++++++++++++++++
docs/en/transforms/transform-faq.md | 84 +++++++++++++++++++++++
docs/sidebars.js | 4 ++
docs/zh/connectors/connector-faq.md | 4 ++
docs/zh/connectors/file-object-storage-faq.md | 68 ++++++++++++++++++
docs/zh/connectors/type-schema-faq.md | 59 ++++++++++++++++
docs/zh/developer/connector-runtime-boundaries.md | 57 +++++++++++++++
docs/zh/transforms/transform-faq.md | 80 +++++++++++++++++++++
11 files changed, 566 insertions(+)
diff --git a/docs/en/connectors/connector-faq.md b/docs/en/connectors/connector-faq.md
index 6626404542..8fe14a028f 100644
--- a/docs/en/connectors/connector-faq.md
+++ b/docs/en/connectors/connector-faq.md
@@ -62,6 +62,10 @@ Change Data Capture connectors read real-time change events (INSERT / UPDATE / D
## Tips for Finding Answers
1. **Connector-specific issues** → go directly to the connector's page and scroll to its **FAQ** section.
+2. **Type and schema questions** (e.g., JSON schema, Debezium schema, Oracle CLOB, MySQL TINYINT, ORC/Parquet mapping) → see [Type and Schema FAQ](./type-schema-faq.md).
+3. **File and object storage questions** (e.g., MinIO/S3, small files, save modes, multi-table file paths) → see [File and Object Storage FAQ](./file-object-storage-faq.md).
+4. **Cross-connector topics** (e.g., "does SeaTunnel support CDC?", "what is `schema_save_mode`?") → see the [General FAQ](../faq.md).
+5. **Still stuck?** → search the [GitHub Issues](https://github.com/apache/seatunnel/issues) or reach out via the [mailing list](https://lists.apache.org/list.html?dev@seatunnel.apache.org).
2. **Cross-connector sink write topics** (e.g., "`generate_sink_sql` vs `query`", "`schema_save_mode`", "`data_save_mode`", or `enable_upsert`) → see [Sink Write Modes and Save Modes](./common-options/sink-write-modes.md).
3. **Other cross-connector topics** (e.g., "does SeaTunnel support CDC?") → see the [General FAQ](../faq.md).
4. **Still stuck?** → search the [GitHub Issues](https://github.com/apache/seatunnel/issues) or reach out via the [mailing list](https://lists.apache.org/list.html?dev@seatunnel.apache.org).
diff --git a/docs/en/connectors/file-object-storage-faq.md b/docs/en/connectors/file-object-storage-faq.md
new file mode 100644
index 0000000000..cf1adb21bb
--- /dev/null
+++ b/docs/en/connectors/file-object-storage-faq.md
@@ -0,0 +1,75 @@
+# File and Object Storage FAQ
+
+This page answers common questions for file connectors such as LocalFile, HDFS, S3, OSS, OBS, COS,
+FTP, and SFTP.
+
+## Can I use S3File with MinIO or another S3-compatible service?
+
+Use `S3File` when the target is compatible with the Hadoop S3A filesystem. Configure the S3A
+endpoint with `fs.s3a.endpoint`, choose the credentials provider with
+`fs.s3a.aws.credentials.provider`, and add provider-specific Hadoop settings under
+`hadoop_s3_properties` when required.
+
+If your target is a native cloud object store with its own connector, such as OSS, OBS, or COS, use
+the corresponding connector page for the exact options and dependencies.
+
+## Why does one file sink task produce multiple files?
+
+File sink output count is controlled by task parallelism and file rolling options:
+
+- `batch_size` controls the row count for each split file.
+- `single_file_mode = true` makes each parallelism task output one file and disables `batch_size`
+ rolling for that task.
+- `single_file_mode` does not mean "one global file for the entire job" when parallelism is greater
+ than one.
+- Custom file names can use `file_name_expression` with `${now}` and `${uuid}` when
+ `custom_filename = true`.
+
+If you need exactly one final file, run the sink with `parallelism = 1` or compact/merge files
+downstream after the SeaTunnel job finishes.
+
+## How do save modes work for file sinks?
+
+File sinks commonly expose `schema_save_mode` and `data_save_mode`.
+
+- `schema_save_mode` controls how the target path or table schema is prepared before the job starts.
+- `data_save_mode` controls how existing data files in the target path are handled before writing.
+
+For exact supported values and defaults, use the sink page for your connector. File-system behavior
+also depends on whether the connector supports transactions and whether the target object store has
+the same rename/commit semantics as HDFS.
+
+## How do I write multiple source tables to files?
+
+Use a multi-table-capable source and a file sink that supports multiple table write. In object
+storage paths, table metadata placeholders such as `${database_name}`, `${schema_name}`, and
+`${table_name}` can route tables to different directories when upstream table metadata exists.
+
+Example path pattern:
+
+```hocon
+sink {
+ S3File {
+ plugin_input = "cdc"
+ path = "/warehouse/${database_name}/${table_name}/"
+ file_format_type = "orc"
+ }
+}
+```
+
+If the upstream source does not provide table metadata, these placeholders cannot be resolved. Add
+table routing upstream, split the job by table, or use a transform/source configuration that
+preserves table identity.
+
+## Can one job load many text files into many Oracle tables?
+
+Yes when each input can be associated with the intended table and compatible schema. The most
+maintainable choices are:
+
+- one job per target table when schemas differ;
+- one multi-table job when the source preserves table identity and the JDBC sink can route by table;
+- a staging-table pattern when raw files need parsing, validation, or enrichment before loading
+ Oracle.
+
+When each file has a different schema, separate jobs are usually clearer because each job can declare
+the exact source schema, transform rules, and sink table options.
diff --git a/docs/en/connectors/type-schema-faq.md b/docs/en/connectors/type-schema-faq.md
new file mode 100644
index 0000000000..cbe6cdfd52
--- /dev/null
+++ b/docs/en/connectors/type-schema-faq.md
@@ -0,0 +1,69 @@
+# Type and Schema FAQ
+
+This page answers cross-connector questions about SeaTunnel schemas, source type mapping, and format
+parsing. Connector-specific type tables remain the authority for exact mappings.
+
+## Where should I check the exact type mapping?
+
+Start from the source connector page and the sink connector page:
+
+- Source connector pages describe how external database types become SeaTunnel logical types.
+- File sink pages describe how SeaTunnel logical types are written to formats such as ORC and
+ Parquet.
+- Format pages describe CDC envelope formats such as Debezium JSON, Canal JSON, Maxwell JSON, and
+ OGG JSON.
+
+For example, the MySQL JDBC source maps `BIT(1)` and `TINYINT(1)` to `BOOLEAN` by default, while
+`TINYINT` maps to `BYTE`. The MySQL source also provides `int_type_narrowing` when you need to
+control the `TINYINT(1)` narrowing behavior.
+
+## Why does a schema-less JSON or Kafka job fail in a downstream transform or sink?
+
+Transforms and many sinks work with SeaTunnel row fields, not with an untyped JSON blob. If the
+source should expose JSON object members as columns, configure the source `schema` or use a format
+that requires schema.
+
+Common patterns:
+
+- Kafka `format = json`: configure `schema` when downstream transforms or sinks need named columns.
+- Kafka `format = debezium_json`: configure both `schema` and `debezium_record_include_schema`.
+- Kafka `format = text`: keep the whole message as a text field and use `JsonPath` if you need to
+ extract fields later.
+- HTTP `format = json`: configure `schema`; use `content_field` or `json_field` when only a nested
+ fragment should become the row.
+
+If a configuration example from another system uses an option such as `num_as_string`, do not copy
+that option into SeaTunnel unless the SeaTunnel connector page documents it. In SeaTunnel, choose
+the intended field type in `schema`, then cast or reshape fields with Transform when needed.
+
+## How should I handle Oracle CLOB, NCLOB, and binary values?
+
+The Oracle JDBC source maps `CLOB` and `NCLOB` to SeaTunnel `STRING`, and binary Oracle types such
+as `BLOB`, `RAW`, and `LONG RAW` to `BYTES`. The generic JDBC source also has
+`handle_blob_as_string` for Oracle BLOB values when they should be exposed as strings before writing
+to a downstream system.
+
+If a downstream database rejects a value because the text contains a NUL byte or another unsupported
+character, treat it as a target-system constraint. Clean or replace that value before the sink writes
+it, for example with SQL Transform or a custom Transform.
+
+## Why does MySQL TINYINT look different after writing ORC or Parquet?
+
+There are two mappings in the path:
+
+1. MySQL or JDBC source type -> SeaTunnel logical type.
+2. SeaTunnel logical type -> file-format type.
+
+For S3/HDFS/OBS file sinks, ORC maps SeaTunnel `TINYINT` to ORC `BYTE`; Parquet maps SeaTunnel
+`TINYINT` to Parquet `INT_8`. If the downstream reader such as Trino shows a different display type,
+check both the SeaTunnel file sink type table and the reader's own ORC/Parquet type interpretation.
+
+## Should I put all casts in the source query or in Transform?
+
+Use the source query when the cast is specific to the source database and you want the database to
+perform it. Use Transform when the cast is part of the SeaTunnel pipeline contract and should stay
+visible between source and sink.
+
+For CDC jobs, avoid SQL expressions that remove primary key or schema metadata unless you have
+confirmed that the downstream sink no longer needs that metadata for upsert, delete, auto-create, or
+schema evolution behavior.
diff --git a/docs/en/developer/connector-runtime-boundaries.md b/docs/en/developer/connector-runtime-boundaries.md
new file mode 100644
index 0000000000..0eacd8351b
--- /dev/null
+++ b/docs/en/developer/connector-runtime-boundaries.md
@@ -0,0 +1,62 @@
+# Connector Runtime Boundaries
+
+This page explains how connector runtime APIs, option rules, catalogs, and metadata providers fit
+together. It is intended for developers building connectors or integrating SeaTunnel with external
+metadata systems.
+
+## Connector Source/Sink SPI is the runtime data path
+
+`TableSourceFactory` and `TableSinkFactory` create the runtime source and sink objects that read and
+write data. Runtime connector code is responsible for:
+
+- creating the source or sink instance;
+- validating and reading connector options;
+- producing or consuming `SeaTunnelRow` records;
+- preserving schema, primary key, table path, and row kind metadata when the connector supports
+ them.
+
+Do not put connector-specific read/write behavior into engine, core, or metadata provider code.
+
+## OptionRule is a configuration contract
+
+Every connector factory exposes `optionRule()`. SeaTunnel uses it to validate user configuration and
+to let Web UI or plugin-discovery code understand which options are required or optional.
+
+`OptionRule` should describe the connector's configuration surface. It is not a place to open
+network connections, discover remote schemas, or perform runtime side effects.
+
+When you add or change user-facing options:
+
+- define them as `Option` values;
+- include defaults only when the connector really has a stable default;
+- keep existing option names backward compatible;
+- update both English and Chinese docs.
+
+## CatalogFactory is for catalog operations
+
+`CatalogFactory` creates a `Catalog` for metadata operations such as listing databases, listing
+tables, and reading table schemas. A connector may provide both runtime source/sink factories and a
+catalog factory, but they are separate contracts.
+
+Use catalog code when the operation is about metadata. Use source/sink runtime code when the
+operation reads or writes records.
+
+## MetadataProvider is for external datasource resolution
+
+`MetadataProvider` is a separate SPI for external metadata services. It resolves a
+`metadata_datasource_id` or external table id into connector configuration or table schema.
+
+The provider acts before connector creation. It should map external metadata to SeaTunnel config; it
+should not replace the connector source/sink implementation and should not contain connector runtime
+read/write logic.
+
+## Practical boundary checks before submitting a connector PR
+
+- Does the connector factory expose all user-facing options through `OptionRule`?
+- Are option names, defaults, and docs consistent?
+- If the connector supports catalog operations, is the catalog implementation registered through
+ `CatalogFactory` instead of hidden in source/sink runtime code?
+- If external metadata is used, does `MetadataProvider` only resolve config/schema and leave runtime
+ reading/writing to the connector?
+- Do source, sink, catalog, SPI registration, plugin mapping, docs, and tests cover the same feature
+ scope?
diff --git a/docs/en/transforms/transform-faq.md b/docs/en/transforms/transform-faq.md
new file mode 100644
index 0000000000..885d200d39
--- /dev/null
+++ b/docs/en/transforms/transform-faq.md
@@ -0,0 +1,84 @@
+# Transform FAQ
+
+This page answers common transform configuration questions that span several transform plugins.
+For full option tables, use the linked plugin pages as the source of truth.
+
+## Which transform should I use for field changes?
+
+| Goal | Recommended transform | Notes |
+|---|---|---|
+| Rename, reorder, or drop fields | [`FieldMapper`](./field-mapper.md) | Maps input field names to output field names. Fields not listed in `field_mapper` are removed from the output schema. |
+| Rename fields only | [`FieldRename`](./field-rename.md) | Use when the field set and order should otherwise stay the same. |
+| Copy one field into another field | [`Copy`](./copy.md) | Keeps the source field and adds or overwrites the destination field, depending on the configuration. |
+| Compute a new field from an expression | [`Sql`](./sql.md) | Use `SELECT` expressions and SQL functions such as `UUID()`. |
+| Extract fields from JSON stored in one column | [`JsonPath`](./jsonpath.md) | The source row must contain a STRING/BYTES field that holds the JSON payload. |
+
+The transform output schema is passed to the downstream sink. It does not by itself create or alter
+the target system schema unless the sink supports the required save mode or schema evolution feature.
+
+## Can SQL Transform generate a UUID?
+
+Yes. SQL Transform supports the `UUID()` function:
+
+```hocon
+transform {
+ Sql {
+ plugin_input = "source_table"
+ plugin_output = "with_uuid"
+ query = "select UUID() as id, name, age from source_table"
+ }
+}
+```
+
+See [`SQL Functions`](./sql-functions.md#uuid) for the function reference.
+
+## Why does my SQL Transform fail after an HTTP or Kafka source?
+
+SQL Transform queries a SeaTunnel row schema. The source must therefore output named fields that the
+SQL query can reference.
+
+- `Http` with `format = json` should define `schema` so the response becomes named columns.
+- `Http` with `format = text` outputs a text payload column; use `JsonPath` first if you need to
+ extract nested JSON fields before SQL.
+- `Kafka` with `format = text` outputs the message value as a text field, while `format = NATIVE`
+ exposes Kafka metadata such as `key`, `value`, `partition`, and `timestamp`.
+- `Kafka` with `format = debezium_json` must define the table `schema` and
+ `debezium_record_include_schema` according to the Debezium message envelope.
+
+When a source emits multiple upstream tables, use [`Multi-Table Transform`](./transform-multi-table.md)
+options such as `table_match_regex` or `table_transform` to scope the transform to the intended
+table.
+
+## Can SQL Transform join two CDC tables?
+
+No. SQL Transform is for transforming the rows it receives from one input table stream. It does not
+provide a stateful streaming join between two CDC tables or two different sources.
+
+For supported multi-table patterns and alternatives, see
+[`Multi-Table Transform Capability Boundary`](./multi-table-transform-and-join-boundary.md).
+
+## How should I use date variables such as month partitions?
+
+SeaTunnel job variables use `${name}` syntax and are passed by `-i name=value`,
+`--variable name=value`, or environment variables. For example:
+
+```hocon
+source {
+ LocalFile {
+ path = "/data/orders/${biz_month}/"
+ }
+}
+```
+
+Then submit with:
+
+```bash
+sh bin/seatunnel.sh --config job.conf -e local -i biz_month=2026-07
+```
+
+Expressions such as `$[yyyy-MM]` are scheduler expressions, not SeaTunnel job-variable syntax. If
+your scheduler supports that syntax, render it in the scheduler first and pass the rendered value
+to SeaTunnel as `${biz_month}`.
+
+File sinks have an additional filename feature: when `custom_filename = true`, `file_name_expression`
+can use `${now}` and `${uuid}`, and `filename_time_format` controls the `${now}` format.
diff --git a/docs/sidebars.js b/docs/sidebars.js
index e28811444f..c6d5e422f7 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -153,6 +153,8 @@ const sidebars = {
]
},
"connectors/cdc-production-cookbook",
+ "connectors/type-schema-faq",
+ "connectors/file-object-storage-faq",
{
"type": "category",
"label": "Scenario Recipes",
@@ -192,6 +194,7 @@ const sidebars = {
]
},
"transforms/recipes",
+ "transforms/transform-faq",
"transforms/calcite",
"transforms/calcite-udf",
"transforms/copy",
@@ -388,6 +391,7 @@ const sidebars = {
"developer/coding-guide",
"developer/test-coding-guide",
"developer/how-to-create-your-connector",
+ "developer/connector-runtime-boundaries",
"developer/source-connector-development",
"developer/sink-connector-development",
"developer/contribute-plugin",
diff --git a/docs/zh/connectors/connector-faq.md b/docs/zh/connectors/connector-faq.md
index d8089e9186..3a0de3eef0 100644
--- a/docs/zh/connectors/connector-faq.md
+++ b/docs/zh/connectors/connector-faq.md
@@ -60,6 +60,10 @@ CDC(Change Data Capture)连接器从数据库事务日志中读取实时变
## 查找答案的技巧
1. **连接器相关问题** → 直接进入对应连接器页面,滚动到 **FAQ** 章节。
+2. **类型与 Schema 问题**(例如 JSON schema、Debezium schema、Oracle CLOB、MySQL TINYINT、ORC/Parquet 映射)→ 参阅[类型与 Schema 常见问题](./type-schema-faq.md)。
+3. **文件与对象存储问题**(例如 MinIO/S3、小文件、save mode、多表文件路径)→ 参阅[文件与对象存储常见问题](./file-object-storage-faq.md)。
+4. **跨连接器主题**(例如「SeaTunnel 是否支持 CDC?」「`schema_save_mode` 是什么?」)→ 参阅[通用常见问题](../faq.md)。
+5. **仍未解决?** → 在 [GitHub Issues](https://github.com/apache/seatunnel/issues) 中搜索,或通过[邮件列表](https://lists.apache.org/list.html?dev@seatunnel.apache.org)联系社区。
2. **跨 Sink 写入主题**(例如「`generate_sink_sql` 和 `query` 怎么选?」「`schema_save_mode` 是什么?」「`data_save_mode` 是否支持?」「`enable_upsert` 什么时候生效?」)→ 参阅 [Sink 写入模式与 Save Mode](./common-options/sink-write-modes.md)。
3. **其他跨连接器主题**(例如「SeaTunnel 是否支持 CDC?」)→ 参阅[通用常见问题](../faq.md)。
4. **仍未解决?** → 在 [GitHub Issues](https://github.com/apache/seatunnel/issues) 中搜索,或通过[邮件列表](https://lists.apache.org/list.html?dev@seatunnel.apache.org)联系社区。
diff --git a/docs/zh/connectors/file-object-storage-faq.md b/docs/zh/connectors/file-object-storage-faq.md
new file mode 100644
index 0000000000..29be740a3a
--- /dev/null
+++ b/docs/zh/connectors/file-object-storage-faq.md
@@ -0,0 +1,68 @@
+# 文件与对象存储常见问题
+
+本页回答 LocalFile、HDFS、S3、OSS、OBS、COS、FTP、SFTP 等文件连接器的常见问题。
+
+## S3File 可以连接 MinIO 或其他 S3 兼容服务吗?
+
+当目标服务兼容 Hadoop S3A 文件系统时,可以使用 `S3File`。通过 `fs.s3a.endpoint` 配置 S3A
+endpoint,通过 `fs.s3a.aws.credentials.provider` 选择凭据 provider;如果服务还有特殊 Hadoop
+参数要求,可放在 `hadoop_s3_properties` 中。
+
+如果目标是有独立连接器的云对象存储,例如 OSS、OBS、COS,请以对应连接器页面中的参数和依赖
+说明为准。
+
+## 为什么一个文件 Sink 任务会产生多个文件?
+
+文件 Sink 的输出文件数量由任务并行度和文件滚动参数共同决定:
+
+- `batch_size` 控制每个切分文件的行数。
+- `single_file_mode = true` 表示每个并行 task 输出一个文件,并且该 task 不再按 `batch_size`
+ 滚动。
+- 当并行度大于 1 时,`single_file_mode` 不表示“整个作业只输出一个全局文件”。
+- 当 `custom_filename = true` 时,自定义文件名可以在 `file_name_expression` 中使用 `${now}`
+ 和 `${uuid}`。
+
+如果必须得到一个最终文件,请把该 Sink 的 `parallelism` 设为 1,或在 SeaTunnel 作业结束后由
+下游流程做文件合并/压缩。
+
+## 文件 Sink 的 save mode 如何理解?
+
+文件 Sink 通常提供 `schema_save_mode` 和 `data_save_mode`。
+
+- `schema_save_mode` 控制作业启动前如何准备目标路径或表 schema。
+- `data_save_mode` 控制作业写入前如何处理目标路径中已有的数据文件。
+
+精确取值和默认值请以具体 Sink 页面为准。文件系统行为还取决于连接器是否启用事务,以及目标
+对象存储是否具备与 HDFS 相同的 rename/commit 语义。
+
+## 如何把多张源表写到文件?
+
+使用支持多表输出的 Source,并接支持多表写入的文件 Sink。对象存储路径中可以使用
+`${database_name}`、`${schema_name}`、`${table_name}` 等表元信息占位符,把不同表路由到不同
+目录,前提是上游确实提供了这些表元信息。
+
+示例路径:
+
+```hocon
+sink {
+ S3File {
+ plugin_input = "cdc"
+ path = "/warehouse/${database_name}/${table_name}/"
+ file_format_type = "orc"
+ }
+}
+```
+
+如果上游 Source 没有提供表元信息,这些占位符无法解析。此时可以在上游增加表路由、按表拆分
+作业,或使用能保留表身份的 source/transform 配置。
+
+## 一个作业可以把多个 txt 文件写入多张 Oracle 表吗?
+
+可以,但前提是每个输入文件能明确对应目标表,并且 schema 兼容。更易维护的选择通常是:
+
+- 各表 schema 不同时,每张目标表一个作业;
+- Source 能保留表身份、JDBC Sink 能按表路由时,使用一个多表作业;
+- 原始文件需要解析、校验或补充字段时,先写入 staging 表,再进入 Oracle 目标表。
+
+当每个文件的 schema 都不同,按表拆分作业通常更清晰,因为每个作业都能声明精确的 source
+schema、transform 规则和 sink 表选项。
diff --git a/docs/zh/connectors/type-schema-faq.md b/docs/zh/connectors/type-schema-faq.md
new file mode 100644
index 0000000000..b8da674223
--- /dev/null
+++ b/docs/zh/connectors/type-schema-faq.md
@@ -0,0 +1,59 @@
+# 类型与 Schema 常见问题
+
+本页回答跨连接器的 SeaTunnel schema、源端类型映射、format 解析问题。精确类型映射仍以具体
+Source 和 Sink 页面中的类型表为准。
+
+## 精确类型映射应该看哪里?
+
+先看 Source 连接器页面和 Sink 连接器页面:
+
+- Source 连接器页面说明外部数据库类型如何映射为 SeaTunnel 逻辑类型。
+- 文件 Sink 页面说明 SeaTunnel 逻辑类型如何写入 ORC、Parquet 等文件格式。
+- Format 页面说明 Debezium JSON、Canal JSON、Maxwell JSON、OGG JSON 等 CDC envelope 格式。
+
+例如,MySQL JDBC Source 默认把 `BIT(1)` 和 `TINYINT(1)` 映射为 `BOOLEAN`,把 `TINYINT`
+映射为 `BYTE`。MySQL Source 还提供 `int_type_narrowing`,用于控制 `TINYINT(1)` 的收窄行为。
+
+## 没有 schema 的 JSON 或 Kafka 作业,为什么下游 Transform/Sink 会失败?
+
+Transform 和很多 Sink 处理的是 SeaTunnel 行字段,而不是无类型 JSON 文本。如果希望把 JSON
+对象成员作为列使用,需要配置 Source `schema`,或选择要求 schema 的 format。
+
+常见模式:
+
+- Kafka `format = json`:当下游需要命名列时配置 `schema`。
+- Kafka `format = debezium_json`:同时配置 `schema` 和 `debezium_record_include_schema`。
+- Kafka `format = text`:先把整条消息保留为文本字段,后续需要字段时再用 `JsonPath` 抽取。
+- HTTP `format = json`:配置 `schema`;如果只需要嵌套片段,用 `content_field` 或 `json_field`。
+
+如果其他系统的配置示例里出现 `num_as_string` 这类参数,除非 SeaTunnel 对应连接器页面明确
+记录该参数,否则不要直接搬到 SeaTunnel。SeaTunnel 中应通过 `schema` 选择目标字段类型,再用
+Transform 做必要的类型转换或字段重塑。
+
+## Oracle CLOB、NCLOB 和二进制值应该如何处理?
+
+Oracle JDBC Source 将 `CLOB`、`NCLOB` 映射为 SeaTunnel `STRING`,将 `BLOB`、`RAW`、
+`LONG RAW` 等二进制类型映射为 `BYTES`。通用 JDBC Source 还提供 `handle_blob_as_string`,
+用于在写入下游系统前把 Oracle BLOB 暴露为字符串。
+
+如果下游数据库因为文本中包含 NUL 字节或其他不支持字符而拒绝写入,应把它视为目标系统约束。
+请在 Sink 写入前清洗或替换该值,例如使用 SQL Transform 或自定义 Transform。
+
+## MySQL TINYINT 写入 ORC/Parquet 后为什么看起来不一样?
+
+链路中实际有两段映射:
+
+1. MySQL 或 JDBC Source 类型 -> SeaTunnel 逻辑类型。
+2. SeaTunnel 逻辑类型 -> 文件格式类型。
+
+对于 S3/HDFS/OBS 文件 Sink,ORC 会把 SeaTunnel `TINYINT` 写为 ORC `BYTE`;Parquet 会把
+SeaTunnel `TINYINT` 写为 Parquet `INT_8`。如果 Trino 等下游读取器展示了不同类型,请同时
+核对 SeaTunnel 文件 Sink 类型表和该读取器自身对 ORC/Parquet 类型的解释。
+
+## 类型转换应该写在 Source query 里,还是写在 Transform 里?
+
+如果转换强依赖源数据库语义,并且希望由数据库执行,放在 Source query 中。如果转换属于
+SeaTunnel 管道契约,希望在 Source 和 Sink 之间保持可见,放在 Transform 中更清晰。
+
+对于 CDC 作业,避免使用会丢失主键或 schema 元信息的 SQL 表达式,除非你已经确认下游 Sink
+不再依赖这些信息来做 upsert、delete、自动建表或 schema evolution。
diff --git a/docs/zh/developer/connector-runtime-boundaries.md b/docs/zh/developer/connector-runtime-boundaries.md
new file mode 100644
index 0000000000..cc46f12b92
--- /dev/null
+++ b/docs/zh/developer/connector-runtime-boundaries.md
@@ -0,0 +1,57 @@
+# 连接器运行时边界
+
+本页说明 connector runtime API、option rule、catalog 和 metadata provider 之间的边界。适用于
+开发连接器,或把 SeaTunnel 接入外部元数据系统的开发者。
+
+## Connector Source/Sink SPI 是运行时数据通路
+
+`TableSourceFactory` 和 `TableSinkFactory` 负责创建真正读写数据的 runtime Source/Sink 对象。
+连接器运行时代码负责:
+
+- 创建 Source 或 Sink 实例;
+- 校验并读取连接器参数;
+- 生产或消费 `SeaTunnelRow`;
+- 在连接器支持时保留 schema、主键、表路径、row kind 等元信息。
+
+不要把某个连接器特有的读写逻辑放进 engine、core 或 metadata provider 代码中。
+
+## OptionRule 是配置契约
+
+每个连接器 factory 都会暴露 `optionRule()`。SeaTunnel 使用它校验用户配置,也让 Web UI 或
+plugin discovery 代码知道哪些参数必填、哪些参数可选。
+
+`OptionRule` 应描述连接器的配置表面。它不应该打开网络连接、发现远端 schema,也不应该执行
+运行时副作用。
+
+新增或修改用户可见参数时:
+
+- 使用 `Option` 定义参数;
+- 只有在连接器确实有稳定默认值时才设置 default;
+- 保持既有 option 名称向后兼容;
+- 同步更新英文和中文文档。
+
+## CatalogFactory 用于 catalog 元数据操作
+
+`CatalogFactory` 创建 `Catalog`,用于列出 database、列出 table、读取 table schema 等元数据
+操作。一个连接器可以同时提供 runtime source/sink factory 和 catalog factory,但它们是不同
+契约。
+
+当操作对象是元数据时,使用 catalog 代码;当操作对象是数据记录读写时,使用 source/sink
+runtime 代码。
+
+## MetadataProvider 用于外部 datasource 解析
+
+`MetadataProvider` 是面向外部元数据服务的独立 SPI。它把 `metadata_datasource_id` 或外部表 ID
+解析为 SeaTunnel 连接器配置或 table schema。
+
+Provider 在连接器创建之前工作。它应该负责把外部元数据映射为 SeaTunnel config;不应该替代
+connector source/sink 实现,也不应该包含连接器运行时读写逻辑。
+
+## 提交连接器 PR 前的实用边界检查
+
+- 连接器 factory 是否通过 `OptionRule` 暴露了全部用户可见参数?
+- option 名称、默认值和文档是否一致?
+- 如果连接器支持 catalog 操作,是否通过 `CatalogFactory` 注册,而不是隐藏在 source/sink
+ runtime 代码里?
+- 如果使用外部元数据,`MetadataProvider` 是否只解析 config/schema,把运行时读写留给连接器?
+- source、sink、catalog、SPI 注册、plugin mapping、文档和测试覆盖的是不是同一个功能范围?
diff --git a/docs/zh/transforms/transform-faq.md b/docs/zh/transforms/transform-faq.md
new file mode 100644
index 0000000000..a9c0032dba
--- /dev/null
+++ b/docs/zh/transforms/transform-faq.md
@@ -0,0 +1,80 @@
+# Transform 常见问题
+
+本页回答跨多个 Transform 插件的常见配置问题。完整参数表仍以各插件页面为准。
+
+## 字段调整应该选哪个 Transform?
+
+| 目标 | 推荐 Transform | 说明 |
+|---|---|---|
+| 字段重命名、重排或删除 | [`FieldMapper`](./field-mapper.md) | 把输入字段名映射为输出字段名;未写入 `field_mapper` 的字段不会进入输出 schema。 |
+| 只重命名字段 | [`FieldRename`](./field-rename.md) | 适用于字段集合和顺序基本不变,只改字段名的场景。 |
+| 把一个字段复制到另一个字段 | [`Copy`](./copy.md) | 保留源字段,并按配置新增或覆盖目标字段。 |
+| 通过表达式计算新字段 | [`Sql`](./sql.md) | 使用 `SELECT` 表达式和 SQL 函数,例如 `UUID()`。 |
+| 从单列 JSON 中抽取字段 | [`JsonPath`](./jsonpath.md) | 上游行里需要有一个 STRING/BYTES 字段保存 JSON 原文。 |
+
+Transform 的输出 schema 会传给下游 Sink。Transform 本身不会自动在目标端建表或改表;是否能创建
+或演进目标 schema,取决于下游 Sink 是否支持对应的 save mode 或 schema evolution 能力。
+
+## SQL Transform 可以生成 UUID 吗?
+
+可以。SQL Transform 支持 `UUID()` 函数:
+
+```hocon
+transform {
+ Sql {
+ plugin_input = "source_table"
+ plugin_output = "with_uuid"
+ query = "select UUID() as id, name, age from source_table"
+ }
+}
+```
+
+函数说明请参考 [`SQL Functions`](./sql-functions.md#uuid)。
+
+## HTTP 或 Kafka Source 后面的 SQL Transform 为什么会失败?
+
+SQL Transform 查询的是 SeaTunnel 行 schema,因此 Source 必须输出 SQL 能引用的命名字段。
+
+- `Http` 使用 `format = json` 时,建议配置 `schema`,让响应体解析成命名列。
+- `Http` 使用 `format = text` 时,输出的是文本载荷列;如果要从嵌套 JSON 中取字段,先用
+ `JsonPath` 抽取后再接 SQL。
+- `Kafka` 使用 `format = text` 时,输出 message value 文本字段;使用 `format = NATIVE`
+ 时会暴露 `key`、`value`、`partition`、`timestamp` 等 Kafka 元数据。
+- `Kafka` 使用 `format = debezium_json` 时,需要根据 Debezium 消息 envelope 配置表
+ `schema` 和 `debezium_record_include_schema`。
+
+当 Source 输出多张上游表时,请使用 [`Multi-Table Transform`](./transform-multi-table.md) 的
+`table_match_regex` 或 `table_transform` 等选项限定 Transform 作用的表。
+
+## SQL Transform 可以 JOIN 两张 CDC 表吗?
+
+不可以。SQL Transform 用于转换它接收到的单表行流,不提供两张 CDC 表之间、或两个不同 Source
+之间的有状态流式 JOIN。
+
+多表能力边界和替代方案请参考
+[`多表 Transform 能力边界`](./multi-table-transform-and-join-boundary.md)。
+
+## 月份分区这类日期变量应该怎么写?
+
+SeaTunnel 作业变量使用 `${name}` 语法,通过 `-i name=value`、`--variable name=value` 或
+环境变量传入。例如:
+
+```hocon
+source {
+ LocalFile {
+ path = "/data/orders/${biz_month}/"
+ }
+}
+```
+
+提交时传入:
+
+```bash
+sh bin/seatunnel.sh --config job.conf -e local -i biz_month=2026-07
+```
+
+`$[yyyy-MM]` 这类表达式通常是调度系统表达式,不是 SeaTunnel 作业变量语法。如果你的调度器
+支持这种写法,应先由调度器渲染成具体值,再以 `${biz_month}` 的变量值传给 SeaTunnel。
+
+文件 Sink 还有一个额外的文件名能力:当 `custom_filename = true` 时,`file_name_expression`
+可以使用 `${now}` 和 `${uuid}`,其中 `${now}` 的格式由 `filename_time_format` 控制。