diff --git a/sql-statements/sql-statement-import-into.md b/sql-statements/sql-statement-import-into.md index 0de6d3cbb594..02a840b697cd 100644 --- a/sql-statements/sql-statement-import-into.md +++ b/sql-statements/sql-statement-import-into.md @@ -26,7 +26,7 @@ summary: TiDB 数据库中 IMPORT INTO 的使用概况。 - TiDB [临时目录](/tidb-configuration-file.md#temp-dir-从-v630-版本开始引入)至少需要有 90 GiB 的可用空间。建议预留大于等于所需导入数据的存储空间,以保证最佳导入性能。 - 一个导入任务只支持导入数据到一张目标表中。 - TiDB 集群升级期间不支持使用该语句。 -- 所需导入的数据不能存在主键或非空唯一索引冲突的记录,否则会导致任务失败。 +- 当未使用[全局排序](/tidb-global-sort.md)功能或 TiDB 版本低于 v8.5.5 时,请务必确保所需导入的数据不存在主键或非空唯一索引冲突的记录,因为此类冲突会导致导入任务失败。从 v8.5.5 起,当使用[全局排序](/tidb-global-sort.md)功能时,`IMPORT INTO` 将移除所有冲突行以自动解决冲突问题。 - 已知问题:在 TiDB 节点配置文件中的 PD 地址与当前集群 PD 拓扑不一致时(如曾经缩容过 PD,但没有对应更新 TiDB 配置文件或者更新该文件后未重启 TiDB 节点),执行 `IMPORT INTO` 会失败。 ### `IMPORT INTO ... FROM FILE` 使用限制 @@ -210,6 +210,53 @@ SET GLOBAL tidb_server_memory_limit='75%'; > - 如果源数据文件 KV range 重叠较少,开启全局排序后可能会降低导入性能,因为全局排序需要等所有子任务的数据本地排序后,再进行额外的全局排序操作,之后才进行导入。 > - 使用全局排序的导入任务完成后,存放在云存储里用于全局排序的文件会在后台线程中异步清理。 +#### 冲突解决 + +从 v8.5.5 起,当使用[全局排序](/tidb-global-sort.md)功能导入数据时,如果发生主键或唯一索引冲突,`IMPORT INTO` 将通过移除所有冲突行来自动解决冲突。 + +例如,在启用全局排序的情况下,如果将以下数据文件 `conflicts.csv` 导入到通过 `CREATE TABLE t(id INT PRIMARY KEY, v INT);` 语句创建的表: + +```csv +id,v +1,2 +1,3 +2,2 +3,3 +3,3 +4,4 +``` + +```sql +IMPORT INTO t FROM 's3://mybucket/conflicts.csv' WITH THREAD=8, SKIP_ROWS=1; +``` + +导入完成后,表 `t` 将只包含不存在冲突的数据行。 + +```sql +SHOW IMPORT JOBS; +``` + +``` ++--------+-----------------------------+--------------+----------+-------+----------+------------------+---------------+--------------------+----------------------------+----------------------------+----------------------------+------------+ +| Job_ID | Data_Source | Target_Table | Table_ID | Phase | Status | Source_File_Size | Imported_Rows | Result_Message | Create_Time | Start_Time | End_Time | Created_By | ++--------+-----------------------------+--------------+----------+-------+----------+------------------+---------------+--------------------+----------------------------+----------------------------+----------------------------+------------+ +| 30001 | s3://mybucket/conflicts.csv | `test`.`t` | 114 | | finished | 24B | 2 | 4 conflicted rows. | 2025-11-28 17:21:40.591023 | 2025-11-28 17:21:41.109977 | 2025-11-28 17:21:44.112506 | root@% | ++--------+-----------------------------+--------------+----------+-------+----------+------------------+---------------+--------------------+----------------------------+----------------------------+----------------------------+------------+ +``` + +```sql +SELECT * FROM t; ++----+------+ +| id | v | ++----+------+ +| 2 | 2 | +| 4 | 4 | ++----+------+ +2 rows in set (0.01 sec) +``` + +冲突行的详细信息存储在云存储 URI 中。更多信息,请参见[使用全局排序时冲突行的信息](#使用全局排序时冲突行的信息)。 + ### 输出内容 当 `IMPORT INTO ... FROM FILE` 导入完成,或者开启了 `DETACHED` 模式时,TiDB 会返回当前任务的信息。以下为一些示例,字段的含义描述请参考 [`SHOW IMPORT JOB(s)`](/sql-statements/sql-statement-show-import-job.md)。 @@ -236,6 +283,36 @@ IMPORT INTO t FROM '/path/to/small.csv' WITH DETACHED; +--------+--------------------+--------------+----------+-------+---------+------------------+---------------+----------------+----------------------------+------------+----------+------------+ ``` +#### 使用全局排序时冲突行的信息 + +从 v8.5.5 起,当使用[全局排序](/tidb-global-sort.md)功能导入数据时,如果发生主键或唯一索引冲突,你可以通过 [`SHOW IMPORT`](/sql-statements/sql-statement-show-import-job.md) 语句输出结果中的 `Result_Message` 列来查看冲突行的数量,示例如下: + +```sql +IMPORT INTO t FROM 's3://mybucket/conflicts.csv' WITH THREAD=8, SKIP_ROWS=1; +SHOW IMPORT JOBS; +``` + +``` ++--------+-----------------------------+--------------+----------+-------+----------+------------------+---------------+--------------------+----------------------------+----------------------------+----------------------------+------------+ +| Job_ID | Data_Source | Target_Table | Table_ID | Phase | Status | Source_File_Size | Imported_Rows | Result_Message | Create_Time | Start_Time | End_Time | Created_By | ++--------+-----------------------------+--------------+----------+-------+----------+------------------+---------------+--------------------+----------------------------+----------------------------+----------------------------+------------+ +| 30001 | s3://mybucket/conflicts.csv | `test`.`t` | 114 | | finished | 24B | 2 | 4 conflicted rows. | 2025-11-28 17:21:40.591023 | 2025-11-28 17:21:41.109977 | 2025-11-28 17:21:44.112506 | root@% | ++--------+-----------------------------+--------------+----------+-------+----------+------------------+---------------+--------------------+----------------------------+----------------------------+----------------------------+------------+ +``` + +你可以在云存储 URI 的 `conflicted-rows/` 文件夹中查看冲突行的详细信息。例如: + +``` +s3://mybucket/sorted-dir/conflicted-rows/1/1-28f0e03a-27c3-4283-a523-418859bb7a2c/data-1.txt +s3://mybucket/sorted-dir/conflicted-rows/1/1-298a387a-065c-4ea9-bc31-949e89ca186f/data-1.txt +s3://mybucket/sorted-dir/conflicted-rows/1/1-2e306ff5-40eb-4045-9992-2ccc04ab7bef/data-1.txt +s3://mybucket/sorted-dir/conflicted-rows/1/1-382d8886-f6e9-4c5e-891c-69d54694a175/data-1.txt +s3://mybucket/sorted-dir/conflicted-rows/1/1-3fd1b7e7-70d4-4734-a12f-ec4f70c3a9af/data-1.txt +s3://mybucket/sorted-dir/conflicted-rows/1/1-46320371-436f-46fa-a8ab-b0f2e2eecf75/data-1.txt +s3://mybucket/sorted-dir/conflicted-rows/1/1-631f1c02-4a25-4c8f-9e8d-6ae61a801f5c/data-1.txt +s3://mybucket/sorted-dir/conflicted-rows/1/1-68f84255-4965-4d9e-9add-934ba07b5ef1/data-1.txt +``` + ### 查看和控制导入任务 对于开启了 `DETACHED` 模式的任务,可通过 [`SHOW IMPORT`](/sql-statements/sql-statement-show-import-job.md) 来查看当前任务的执行进度。