zhangshenghang opened a new pull request, #12476:
URL: https://github.com/apache/seatunnel/pull/12476
## Purpose of this PR
This PR fixes a batch of real documentation inaccuracies in the transform
plugin docs (English and Chinese), every one of them verified directly against
the source code in `seatunnel-transforms-v2`.
## Issues found and changes made
| # | Doc (en + zh) | Issue | Fix | Source evidence |
|---|---|---|---|---|
| 1 | `jsonpath.md` | `row_error_handle_way` documented only `FAIL`/`SKIP`,
but the option accepts a third value `ROUTE_TO_TABLE` | Documented
`ROUTE_TO_TABLE` including the `row_error_handle_way.error_table` routing
behavior and the warn-and-skip fallback when no error table is configured |
`TransformCommonOptions.java` (`singleChoice(..., FAIL, SKIP,
ROUTE_TO_TABLE)`); sibling `calcite.md` already documents it |
| 2 | `jsonpath.md` | The "Read Json Example" result table was missing the
`c1_map_array` column that both example configs produce | Added the
`c1_map_array` column to the result table | Example configs in the same section
define `dest_field = "c1_map_array"` |
| 3 | `copy.md` | Still-supported deprecated options
`src_field`/`dest_field` were undocumented, so legacy configs could not be
understood | Documented both as deprecated, including that `dest_field` is
mandatory when `src_field` is used and that they are mutually exclusive with
`fields` | `CopyTransformConfig.java` (`@Deprecated SRC_FIELD/DEST_FIELD`),
`CopyFieldTransformFactory.optionRule()` (`.exclusive(FIELDS, SRC_FIELD)`,
`RequireDestFieldValidator`) |
| 4 | `filter.md` | Legacy fallback key `fields` for `include_fields` was
undocumented | Added a note that `fields` is still accepted for backward
compatibility | `FilterFieldTransformConfig.java`
(`withFallbackKeys("fields")`) |
| 5 | `metadata.md` | `metadata_fields` documented as optional with default
"empty map", but the factory declares it required and non-empty — a user
following the doc gets a validation error | Changed required to `yes`, default
to `-`, and noted at least one entry is needed |
`MetadataTransformFactory.optionRule()` (`.required(METADATA_FIELDS,
Conditions.mapNotEmpty(...))`) |
| 6 | `data-validator.md` | Claimed `error_table` is "required when using
ROUTE_TO_TABLE mode", but the code does not enforce it — it logs a warning and
silently skips invalid rows instead | Reworded to describe the actual behavior
| `DataValidatorTransform.java` ("Error table not configured, skipping invalid
row") |
| 7 | `field-rename.md`, `table-rename.md` | `convert_case` labeled type
`string`, source declares it as an enum | Changed type to `enum` |
`FieldRenameConfig.java` / `TableRenameConfig.java`
(`.enumType(ConvertCase.class)`) |
| 8 | `table-filter.md` | `pattern_mode` labeled type `string`, source
declares it as an enum with default `INCLUDE` | Changed type to `enum` |
`TableFilterConfig.java` (`.enumType(PatternMode.class)`) |
| 9 | `table-merge.md` (en only) | A stray backtick line before the first
example's code fence rendered as a stray literal character | Removed the stray
backtick | — |
## Are English and Chinese docs both checked?
Yes. Every issue was fixed in both `docs/en/transforms/` and
`docs/zh/transforms/` except the stray backtick, which existed only in the
English `table-merge.md`. While checking, I also confirmed `python.md`
correctly lists only `FAIL`/`SKIP` because `PythonTransformConfig` deliberately
rejects other values, so it was left unchanged.
## Duplicate check of last 7 days
Before starting I reviewed all doc PRs created in the last 7 days by any
author, and in particular the four still-open doc-fix PRs from this account:
- #12459 (sink/source/Zeta engine docs)
- #12423 (DynamoDB/Maxcompute/StarRocks/MySQL-CDC/Paimon + transforms
embedding/field-mapper/filter-rowkind/llm/sql)
- #12409 (HTTP/IoTDB/Mem0 and zh sync docs)
- #12347 (file connectors/Doris/developer docs/faq)
None of them touches the 17 files in this PR, and none covers any of the
issues listed above (e.g. #12423 already fixed `llm.md`/`sql.md`, which this PR
deliberately does not touch). This PR targets a disjoint area: the remaining
transform docs (jsonpath, copy, filter, metadata, data-validator, field-rename,
table-rename, table-filter, table-merge).
## How the change was verified
- Every documented option name, type, default value, required/optional flag
and enum value was compared against the `Option` definitions and `optionRule()`
of the corresponding factory in `seatunnel-transforms-v2` (files cited in the
table above).
- Relative links in all 17 changed files were checked programmatically: all
resolve to existing files, 0 broken.
- Markdown table column consistency was checked programmatically on all
changed files: 0 mismatches.
- No external URLs were added, so `markdown-link-check` (CI dead-link job,
`continue-on-error`) is unaffected; it could not be run locally because the
sandbox has no npm network access — the equivalent relative-link check was run
with a local script instead.
- No Java code was changed, so `spotless:apply` / `mvnw verify` are not
applicable to this diff.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
