From 22b50064e0604c4ff2e334a63a127b40ffef0adc Mon Sep 17 00:00:00 2001 From: Airton Lastori <6343615+alastori@users.noreply.github.com> Date: Tue, 11 Aug 2026 01:22:51 -0400 Subject: [PATCH 1/4] docs: document IMPORT INTO format detection --- sql-statements/sql-statement-import-into.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-import-into.md b/sql-statements/sql-statement-import-into.md index 86040ff8d6b11..587fabce2fe4f 100644 --- a/sql-statements/sql-statement-import-into.md +++ b/sql-statements/sql-statement-import-into.md @@ -132,7 +132,11 @@ In the `fileLocation` parameter, you can specify a single file, or use the `*` a ### Format -The `IMPORT INTO` statement supports three data file formats: `CSV`, `SQL`, and `PARQUET`. If not specified, the default format is `CSV`. +The `IMPORT INTO` statement supports three data file formats: `CSV`, `SQL`, and `PARQUET`. When you specify the `FORMAT` clause, TiDB uses that format regardless of the file extension. If you omit `FORMAT`, TiDB automatically detects the format from the `.csv`, `.sql`, or `.parquet` file extension. Detection is case-insensitive. For compressed files, TiDB ignores the `.gz`, `.gzip`, `.zstd`, `.zst`, or `.snappy` compression suffix before detecting the data file format. If the remaining file name has no extension or an unrecognized extension, TiDB treats the file as `CSV`. + +> **Note:** +> +> For wildcard paths, make sure that all matched files use the same data file format. TiDB determines one format for the import job and applies it to every matched file. Files that do not use that format can cause the import to fail. Use separate `IMPORT INTO` statements for different formats. ### WithOptions From 3f6999373ecdc9cd5a2b3f567926deea8be34c5f Mon Sep 17 00:00:00 2001 From: Airton Lastori <6343615+alastori@users.noreply.github.com> Date: Tue, 11 Aug 2026 01:51:53 -0400 Subject: [PATCH 2/4] docs: qualify format detection by platform and version --- sql-statements/sql-statement-import-into.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-import-into.md b/sql-statements/sql-statement-import-into.md index 587fabce2fe4f..6336ee88837f1 100644 --- a/sql-statements/sql-statement-import-into.md +++ b/sql-statements/sql-statement-import-into.md @@ -132,7 +132,21 @@ In the `fileLocation` parameter, you can specify a single file, or use the `*` a ### Format -The `IMPORT INTO` statement supports three data file formats: `CSV`, `SQL`, and `PARQUET`. When you specify the `FORMAT` clause, TiDB uses that format regardless of the file extension. If you omit `FORMAT`, TiDB automatically detects the format from the `.csv`, `.sql`, or `.parquet` file extension. Detection is case-insensitive. For compressed files, TiDB ignores the `.gz`, `.gzip`, `.zstd`, `.zst`, or `.snappy` compression suffix before detecting the data file format. If the remaining file name has no extension or an unrecognized extension, TiDB treats the file as `CSV`. +The `IMPORT INTO` statement supports three data file formats: `CSV`, `SQL`, and `PARQUET`. When you specify the `FORMAT` clause, TiDB uses that format regardless of the file extension. + + + +Starting from v8.5.7, if you omit `FORMAT`, TiDB automatically detects the format from the `.csv`, `.sql`, or `.parquet` file extension. Detection is case-insensitive. For compressed files, TiDB ignores the `.gz`, `.gzip`, `.zstd`, `.zst`, or `.snappy` compression suffix before detecting the data file format. If the remaining file name has no extension or an unrecognized extension, TiDB treats the file as `CSV`. + +In v8.5.6 and earlier versions, TiDB treats the file as `CSV` when you omit `FORMAT`. + + + + + +If you omit `FORMAT`, TiDB automatically detects the format from the `.csv`, `.sql`, or `.parquet` file extension. Detection is case-insensitive. For compressed files, TiDB ignores the `.gz`, `.gzip`, `.zstd`, `.zst`, or `.snappy` compression suffix before detecting the data file format. If the remaining file name has no extension or an unrecognized extension, TiDB treats the file as `CSV`. + + > **Note:** > From 944e270a111e0cf5567d72adf502eb06dd021485 Mon Sep 17 00:00:00 2001 From: Airton Lastori <6343615+alastori@users.noreply.github.com> Date: Fri, 14 Aug 2026 01:42:09 -0400 Subject: [PATCH 3/4] docs: clarify IMPORT INTO format selection --- sql-statements/sql-statement-import-into.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/sql-statements/sql-statement-import-into.md b/sql-statements/sql-statement-import-into.md index 6336ee88837f1..f1eb5058db866 100644 --- a/sql-statements/sql-statement-import-into.md +++ b/sql-statements/sql-statement-import-into.md @@ -115,7 +115,7 @@ It specifies the storage location of the data file, which can be an Amazon S3 or - Amazon S3 or GCS URI path: for URI configuration details, see [URI Formats of External Storage Services](/external-storage-uri.md). -- TiDB local file path: it must be an absolute path, and the file extension must be `.csv`, `.sql`, or `.parquet`. Make sure that the files corresponding to this path are stored on the TiDB node connected by the current user, and the user has the `FILE` privilege. +- TiDB local file path: it must be an absolute path, and its final suffix must be `.csv`, `.sql`, `.parquet`, `.gz`, `.gzip`, `.zstd`, `.zst`, or `.snappy` (case-insensitive). Make sure that the files corresponding to this path are stored on the TiDB node connected by the current user, and the user has the `FILE` privilege. > **Note:** > @@ -138,8 +138,12 @@ The `IMPORT INTO` statement supports three data file formats: `CSV`, `SQL`, and Starting from v8.5.7, if you omit `FORMAT`, TiDB automatically detects the format from the `.csv`, `.sql`, or `.parquet` file extension. Detection is case-insensitive. For compressed files, TiDB ignores the `.gz`, `.gzip`, `.zstd`, `.zst`, or `.snappy` compression suffix before detecting the data file format. If the remaining file name has no extension or an unrecognized extension, TiDB treats the file as `CSV`. +For a TiDB local file path, the final suffix validation described above runs before format detection. A local path without a supported final suffix is rejected instead of falling back to `CSV`. + In v8.5.6 and earlier versions, TiDB treats the file as `CSV` when you omit `FORMAT`. +After upgrading to v8.5.7 or later, if an existing import relies on CSV parsing for a file whose name indicates another supported format, specify `FORMAT 'CSV'` to preserve the earlier behavior. + @@ -150,7 +154,7 @@ If you omit `FORMAT`, TiDB automatically detects the format from the `.csv`, `.s > **Note:** > -> For wildcard paths, make sure that all matched files use the same data file format. TiDB determines one format for the import job and applies it to every matched file. Files that do not use that format can cause the import to fail. Use separate `IMPORT INTO` statements for different formats. +> For wildcard paths, when `FORMAT` is omitted, TiDB detects the format from an arbitrary matched file and applies that format to every matched file. Make sure that all matched files use the same data file format. If any matched file uses another format, the import can fail during parsing. Use separate `IMPORT INTO` statements for different formats. ### WithOptions From 5bf118e969835e7e0375ada8bac5d1c657f132ac Mon Sep 17 00:00:00 2001 From: Airton Lastori <6343615+alastori@users.noreply.github.com> Date: Fri, 14 Aug 2026 01:53:57 -0400 Subject: [PATCH 4/4] docs: clarify FORMAT local path validation --- sql-statements/sql-statement-import-into.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-import-into.md b/sql-statements/sql-statement-import-into.md index f1eb5058db866..0f46bac3b5272 100644 --- a/sql-statements/sql-statement-import-into.md +++ b/sql-statements/sql-statement-import-into.md @@ -132,7 +132,7 @@ In the `fileLocation` parameter, you can specify a single file, or use the `*` a ### Format -The `IMPORT INTO` statement supports three data file formats: `CSV`, `SQL`, and `PARQUET`. When you specify the `FORMAT` clause, TiDB uses that format regardless of the file extension. +The `IMPORT INTO` statement supports three data file formats: `CSV`, `SQL`, and `PARQUET`. When you specify the `FORMAT` clause, TiDB uses that format for parsing instead of detecting it from the file extension. For TiDB local file paths, the final suffix validation described above still applies.