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-11606-fb47236179b271bf279f3777734c0e3b3e9287db in repository https://gitbox.apache.org/repos/asf/seatunnel.git
commit f6bfc4e07c5d319563946ecb40a18eec162d9efa Author: lifeng <[email protected]> AuthorDate: Thu Oct 29 09:57:40 2026 +0000 [Docs][Connector-V2] Clarify LocalFile CSV header semantics (#11606) Signed-off-by: lifeng <[email protected]> --- docs/en/connectors/source/LocalFile.md | 24 ++++++------------------ docs/zh/connectors/source/LocalFile.md | 24 ++++++------------------ 2 files changed, 12 insertions(+), 36 deletions(-) diff --git a/docs/en/connectors/source/LocalFile.md b/docs/en/connectors/source/LocalFile.md index 7f98eb8618..e98f7cc586 100644 --- a/docs/en/connectors/source/LocalFile.md +++ b/docs/en/connectors/source/LocalFile.md @@ -68,7 +68,7 @@ For bounded Zeta jobs, restore resumes pending file splits after readers registe | datetime_format | string | no | yyyy-MM-dd HH:mm:ss | | time_format | string | no | HH:mm:ss | | skip_header_row_number | long | no | 0 | -| schema | config | no | - | +| schema | config | conditionally yes | - | | sheet_name | string | no | - | | excel_engine | string | no | POI | | excel_use_header_line | boolean | no | false | @@ -161,23 +161,11 @@ connector will generate data as the following: |------|-------------|---------| | 200 | get success | true | -If you assign file type to `parquet` `orc`, schema option not required, connector can find the schema of upstream data automatically. +If you assign file type to `parquet` or `orc`, the schema option is not required because the connector can read the schema from the file metadata. -If you assign file type to `text` `csv`, you can choose to specify the schema information or not. +If you assign file type to `json`, `excel`, or `xml`, you must specify the schema because these formats do not provide the field types required by SeaTunnel. -For example, upstream data is the following: - -```text - -tyrantlucifer#26#male - -``` - -If you do not assign data schema connector will treat the upstream data as the following: - -| content | -|-----------------------| -| tyrantlucifer#26#male | +For `text` and `csv`, the schema is optional. Without a schema, the connector reads each input line into a single `content` field of type string; `read_columns` is not supported in this mode. Configure a schema when you need typed fields or column mapping. If you assign data schema, you should also assign the option `field_delimiter` too except CSV file type @@ -335,7 +323,7 @@ preamble, leave the value at `0`. ### schema [config] -Only need to be configured when the file_format_type are text, json, excel, xml or csv ( Or other format we can't read the schema from metadata). +Required when `file_format_type` is `json`, `excel`, or `xml`. Optional for `text` and `csv`; when omitted, each input line is read into a single `content` field of type string and `read_columns` is not supported. #### fields [Config] @@ -401,7 +389,7 @@ For security reasons (XXE hardening), XML files (`file_format_type = xml`) conta ### csv_use_header_line [boolean] -Whether to use the header line to parse the file, only used when the file_format is `csv` and the file contains the header line that match RFC 4180 +When enabled, the connector consumes the first RFC 4180 CSV record as the header and maps its column names to the fields in the configured `schema`. This option does not infer the schema or field types. Do not also use `skip_header_row_number` to skip the same header row. ### file_filter_pattern [string] diff --git a/docs/zh/connectors/source/LocalFile.md b/docs/zh/connectors/source/LocalFile.md index bc69c073cb..c721289c8c 100644 --- a/docs/zh/connectors/source/LocalFile.md +++ b/docs/zh/connectors/source/LocalFile.md @@ -68,7 +68,7 @@ import ChangeLog from '../changelog/connector-file-local.md'; | datetime_format | string | 否 | yyyy-MM-dd HH:mm:ss | | time_format | string | 否 | HH:mm:ss | | skip_header_row_number | long | 否 | 0 | -| schema | config | 否 | - | +| schema | config | 视情况而定 | - | | sheet_name | string | 否 | - | | excel_engine | string | 否 | POI | | excel_use_header_line | boolean | 否 | false | @@ -161,23 +161,11 @@ schema { |------|-------------|---------| | 200 | get success | true | -如果您将文件类型指定为 `parquet` `orc`，则不需要 schema 选项，连接器可以自动找到上游数据的 schema。 +如果您将文件类型指定为 `parquet` 或 `orc`，则不需要 schema 选项，因为连接器可以从文件元数据中读取 schema。 -如果您将文件类型指定为 `text` `csv`，您可以选择指定或不指定 schema 信息。 +如果您将文件类型指定为 `json`、`excel` 或 `xml`，则必须指定 schema，因为这些格式不提供 SeaTunnel 所需的字段类型。 -例如，上游数据如下： - -```text - -tyrantlucifer#26#male - -``` - -如果您不指定数据 schema，连接器将把上游数据视为如下： - -| content | -|-----------------------| -| tyrantlucifer#26#male | +对于 `text` 和 `csv`，schema 是可选的。未配置 schema 时，连接器会将每个输入行读取为一个 string 类型的 `content` 字段；此模式不支持 `read_columns`。如果需要有类型的字段或列映射，请配置 schema。 如果您指定数据 schema，除了 CSV 文件类型外，您还应该指定选项 `field_delimiter` @@ -334,7 +322,7 @@ PDF 特有的解析行为如下： ### schema [config] -仅在 file_format_type 为 text、json、excel、xml 或 csv（或其他我们无法从元数据读取 schema 的格式）时需要配置。 +当 `file_format_type` 为 `json`、`excel` 或 `xml` 时必须配置。对于 `text` 和 `csv`，schema 是可选的；未配置时，每个输入行会被读取为一个 string 类型的 `content` 字段，并且不支持 `read_columns`。 #### fields [Config] @@ -400,7 +388,7 @@ POI 引擎允许读取的最大 Excel 文件大小，单位为字节。默认值 ### csv_use_header_line [boolean] -是否使用标题行解析文件，仅在 file_format 为 `csv` 且文件包含符合 RFC 4180 的标题行时使用 +启用后，连接器会将第一个符合 RFC 4180 的 CSV 记录作为标题行，并按列名映射到已配置 `schema` 中的字段。此选项不会推断 schema 或字段类型。不要再使用 `skip_header_row_number` 跳过同一个标题行。 ### file_filter_pattern [string]
