This is an automated email from the ASF dual-hosted git repository. nielifeng pushed a commit to branch codex/docs-localfile-csv-header-9948 in repository https://gitbox.apache.org/repos/asf/seatunnel.git
commit 7e2007c70d68e45979d60206c29ebde25b230a72 Author: lifeng <[email protected]> AuthorDate: Fri Jul 31 16:13:41 2026 +0800 [Docs][Connector-V2] Clarify LocalFile CSV header semantics Signed-off-by: lifeng <[email protected]> --- docs/en/connectors/source/LocalFile.md | 24 +++++------------------- docs/zh/connectors/source/LocalFile.md | 24 +++++------------------- 2 files changed, 10 insertions(+), 38 deletions(-) diff --git a/docs/en/connectors/source/LocalFile.md b/docs/en/connectors/source/LocalFile.md index 63d7fec912..1155382ca1 100644 --- a/docs/en/connectors/source/LocalFile.md +++ b/docs/en/connectors/source/LocalFile.md @@ -63,7 +63,7 @@ If you use SeaTunnel Engine, It automatically integrated the hadoop jar when you | 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 | | xml_row_tag | string | no | - | @@ -154,23 +154,9 @@ 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. - -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 | +If you assign file type to `text`, `json`, `excel`, `csv`, or `xml`, you must specify the schema because these formats do not provide the field types required by SeaTunnel. If you assign data schema, you should also assign the option `field_delimiter` too except CSV file type @@ -308,7 +294,7 @@ then SeaTunnel will skip the first 2 lines from source files ### 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 `text`, `json`, `excel`, `xml`, or `csv` (or another format whose schema cannot be read from metadata). #### fields [Config] @@ -354,7 +340,7 @@ Specifies Whether to process data using the tag attribute format. ### 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 ded499c9b8..01cd26a2bb 100644 --- a/docs/zh/connectors/source/LocalFile.md +++ b/docs/zh/connectors/source/LocalFile.md @@ -63,7 +63,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 | | xml_row_tag | string | 否 | - | @@ -154,23 +154,9 @@ schema { |------|-------------|---------| | 200 | get success | true | -如果您将文件类型指定为 `parquet` `orc`，则不需要 schema 选项，连接器可以自动找到上游数据的 schema。 +如果您将文件类型指定为 `parquet` 或 `orc`，则不需要 schema 选项，因为连接器可以从文件元数据中读取 schema。 -如果您将文件类型指定为 `text` `csv`，您可以选择指定或不指定 schema 信息。 - -例如，上游数据如下： - -```text - -tyrantlucifer#26#male - -``` - -如果您不指定数据 schema，连接器将把上游数据视为如下： - -| content | -|-----------------------| -| tyrantlucifer#26#male | +如果您将文件类型指定为 `text`、`json`、`excel`、`csv` 或 `xml`，则必须指定 schema，因为这些格式不提供 SeaTunnel 所需的字段类型。 如果您指定数据 schema，除了 CSV 文件类型外，您还应该指定选项 `field_delimiter` @@ -308,7 +294,7 @@ PDF 特有的解析行为如下： ### schema [config] -仅在 file_format_type 为 text、json、excel、xml 或 csv（或其他我们无法从元数据读取 schema 的格式）时需要配置。 +当 `file_format_type` 为 `text`、`json`、`excel`、`xml` 或 `csv`（或其他无法从元数据读取 schema 的格式）时必须配置。 #### fields [Config] @@ -354,7 +340,7 @@ PDF 特有的解析行为如下： ### csv_use_header_line [boolean] -是否使用标题行解析文件，仅在 file_format 为 `csv` 且文件包含符合 RFC 4180 的标题行时使用 +启用后，连接器会将第一个符合 RFC 4180 的 CSV 记录作为标题行，并按列名映射到已配置 `schema` 中的字段。此选项不会推断 schema 或字段类型。不要再使用 `skip_header_row_number` 跳过同一个标题行。 ### file_filter_pattern [string]
