sql: GA load data logical mode and add experimental physical mode (#1…

…3708) * doc * doc * change * change * doc * polished wording * Update sql-statements/sql-statement-load-data.md * Apply suggestions from code review * Update sql-statement-load-data.md * Update sql-statement-load-data.md * Update error-codes.md * change * Update sql-statements/sql-statement-load-data.md Co-authored-by: xixirangrang <[email protected]> * Update sql-statements/sql-statement-load-data.md Co-authored-by: xixirangrang <[email protected]> * Update sql-statements/sql-statement-load-data.md Co-authored-by: Frank945946 <[email protected]> * Update sql-statements/sql-statement-load-data.md Co-authored-by: Frank945946 <[email protected]> * Update sql-statements/sql-statement-load-data.md Co-authored-by: xixirangrang <[email protected]> * move order * Update sql-statements/sql-statement-load-data.md Co-authored-by: lance6716 <[email protected]> * Update sql-statements/sql-statement-load-data.md Co-authored-by: lance6716 <[email protected]> * Apply suggestions from code review Co-authored-by: Frank945946 <[email protected]> * fix comments * Update sql-statements/sql-statement-load-data.md * Update sql-statements/sql-statement-load-data.md * Update error-codes.md Co-authored-by: Aolin <[email protected]> * Update sql-statements/sql-statement-load-data.md Co-authored-by: Aolin <[email protected]> * Update sql-statements/sql-statement-load-data.md Co-authored-by: Aolin <[email protected]> * Update sql-statements/sql-statement-load-data.md Co-authored-by: Aolin <[email protected]> * Update sql-statements/sql-statement-load-data.md Co-authored-by: Aolin <[email protected]> * Update sql-statements/sql-statement-load-data.md Co-authored-by: Aolin <[email protected]> * Update sql-statements/sql-statement-load-data.md Co-authored-by: Aolin <[email protected]> * Update sql-statements/sql-statement-load-data.md Co-authored-by: Aolin <[email protected]> * Update sql-statements/sql-statement-load-data.md Co-authored-by: Aolin <[email protected]> * Update sql-statements/sql-statement-load-data.md Co-authored-by: Aolin <[email protected]> * Update sql-statements/sql-statement-load-data.md Co-authored-by: Aolin <[email protected]> * Update sql-statements/sql-statement-load-data.md Co-authored-by: Aolin <[email protected]> * Update sql-statements/sql-statement-load-data.md Co-authored-by: Aolin <[email protected]> * Update sql-statement-load-data.md * Update sql-statement-load-data.md * Update sql-statement-load-data.md * Update sql-statements/sql-statement-load-data.md * Update sql-statement-load-data.md * Update sql-statement-load-data.md --------- Co-authored-by: xixirangrang <[email protected]> Co-authored-by: xixirangrang <[email protected]> Co-authored-by: Frank945946 <[email protected]> Co-authored-by: lance6716 <[email protected]> Co-authored-by: Aolin <[email protected]>
pingcap · Apr 23, 2023 · a2d3300 · a2d3300
1 parent 47f9b66
commit a2d3300
Show file tree

Hide file tree

Showing 5 changed files with 81 additions and 23 deletions.
diff --git a/error-codes.md b/error-codes.md
@@ -351,7 +351,11 @@ TiDB 兼容 MySQL 的错误码，在大多数情况下，返回和 MySQL 一样
 
 * Error Number: 8172
 
-    指定 `LOCAL` 的 `LOAD DATA` 不能在后台运行，只有使用 S3/GCS 路径的 `LOAD DATA` 可以在后台运行。请参考 [`LOAD DATA`](/sql-statements/sql-statement-load-data.md) 更改 SQL 语句。
+    指定 `LOCAL` 时，不能指定特定的选项，比如 `DETACHED` 和 `import_mode='PHYSICAL'`。请参考 [`LOAD DATA`](/sql-statements/sql-statement-load-data.md) 更改 SQL 语句。
+
+* Error Number: 8173
+
+    执行 Physical Import 时，TiDB 会对当前环境进行检查，比如检查下游表是否为空等。请根据提示进行处理。
 
 * Error Number: 8200
 
@@ -412,7 +416,7 @@ TiDB 兼容 MySQL 的错误码，在大多数情况下，返回和 MySQL 一样
 * Error Number: 8250
 
     完整的报错信息如下：
-    
+
     `ERROR 8250 (HY000) : Resource control feature is disabled. Run "SET GLOBAL tidb_enable_resource_control='on'" to enable the feature`
 
     资源控制的功能没有打开时，使用资源管控 (Resource Control) 相关功能会返回该错误。你可以开启全局变量 [`tidb_enable_resource_control`](/system-variables.md#tidb_enable_resource_control-从-v660-版本开始引入) 启用资源管控。
@@ -424,7 +428,7 @@ TiDB 兼容 MySQL 的错误码，在大多数情况下，返回和 MySQL 一样
 * Error Number: 8252
 
     完整的报错信息如下：
-    
+
     `ERROR 8252 (HY000) : Exceeded resource group quota limitation`
 
     在尝试消耗超过资源组的限制时返回该错误。一般出现该错误，是由于单次事务太大或者并发太多导致，需调整事务大小或减少客户端并发数。

diff --git a/sql-statements/sql-statement-load-data.md b/sql-statements/sql-statement-load-data.md
@@ -8,15 +8,22 @@ aliases: ['/docs-cn/dev/sql-statements/sql-statement-load-data/','/docs-cn/dev/r
 
 `LOAD DATA` 语句用于将数据批量加载到 TiDB 表中。
 
-在 v7.0.0 版本集成 TiDB Lightning 的逻辑导入模式，使 `LOAD DATA` 语句更加强大，包括：
+从 v7.0.0 开始，`LOAD DATA` 集成 TiDB Lightning 的逻辑导入模式 (Logical Import Mode)，使 `LOAD DATA` 语句更加强大，包括：
 
 - 支持从 S3、GCS 导入数据
 - 支持导入 Parquet 格式的数据
-- 新增参数 `FORMAT`、`FIELDS DEFINED NULL BY`、`With batch_size=<number>,detached`
+- 新增参数 `FORMAT`、`FIELDS DEFINED NULL BY` 和 `WITH batch_size=<number>,detached`
+
+从 v7.1.0 开始，`LOAD DATA` 支持以下特性：
+
+- 支持导入压缩的 `DELIMITED DATA` 和 `SQL FILE` 数据文件
+- 逻辑导入支持并发导入
+- 支持通过 `CharsetOpt` 来指定数据文件的编码格式
+- `LOAD DATA` 集成 TiDB Lightning 的物理导入模式 (Physical Import Mode)。该模式不经过 SQL 接口，而是直接将数据以键值对的形式插入 TiKV 节点，是一种高效且快速的导入模式。
 
 > **警告：**
 >
-> 新增的能力和参数为实验特性，不建议在生产环境中使用。
+> v7.1.0 新增的并发导入和物理导入模式为实验特性，不建议在生产环境中使用。
 
 ## 语法图
 
@@ -29,6 +36,9 @@ LocalOpt ::= ('LOCAL')?
 FormatOpt ::=
     ('FORMAT' ('DELIMITED DATA' | 'SQL FILE' | 'PARQUET'))?
 
+DuplicateOpt ::=
+    ('IGNORE' | 'REPLACE')?
+
 Fields ::=
     ('TERMINATED' 'BY' stringLit
     | ('OPTIONALLY')? 'ENCLOSED' 'BY' stringLit
@@ -39,7 +49,11 @@ LoadDataOptionListOpt ::=
     ('WITH' (LoadDataOption (',' LoadDataOption)*))?
 
 LoadDataOption ::=
-    detached | batch_size '=' numberLiteral
+    import_mode '=' ('LOGICAL' | 'PHYSICAL')
+    | thread '=' numberLiteral
+    | batch_size '=' numberLiteral
+    | max_write_speed '=' stringLit
+    | detached
 ```
 
 ## 参数说明
@@ -64,6 +78,28 @@ LoadDataOption ::=
 
 你可以通过 `FORMAT` 参数来指定数据文件的格式。如果不指定该参数，需要使用的格式为 `DELIMITED DATA`，该格式即 MySQL `LOAD DATA` 支持的数据格式。
 
+数据格式 `DELIMITED DATA` 和 `SQL FILE` 支持压缩文件。`LOAD DATA` 会根据文件名称的后缀来自动决定压缩格式。目前支持的压缩格式如下：
+
+| 文件后缀 | 压缩格式 | 示例 |
+|:---|:---|:---|
+| `.gz` 或 `.gzip`  | gzip 压缩格式   | `tbl.0001.csv.gz`     |
+| `.zstd` 或 `.zst` | zstd 压缩格式   | `tbl.0001.csv.zstd`   |
+| `.snappy`      | snappy 压缩格式 | `tbl.0001.csv.snappy` |
+
+### `DuplicateOpt`
+
+该参数与 MySQL 行为一致，具体请参考 [MySQL LOAD DATA 文档](https://dev.mysql.com/doc/refman/8.0/en/load-data.html#load-data-error-handling)。
+
+该参数只适用于逻辑导入模式，对物理导入模式不生效。
+
+### `CharsetOpt`
+
+当数据格式是 `DELIMITED DATA` 时，可以通过 `CharsetOpt` 指定数据文件的编码格式。目前支持下列编码格式：`ascii`、`latin1`、`binary`、`utf8`、`utf8mb4` 和 `gbk`。
+
+```sql
+LOAD DATA INFILE 's3://<bucket-name>/path/to/data/foo.csv' INTO TABLE load_charset.latin1 CHARACTER SET latin1
+```
+
 ### `Fields`、`Lines`、`Ignore Lines`
 
 只有数据格式是 `DELIMITED DATA` 时，才能指定 `Fields`、`Lines`、`Ignore Lines` 等语句。
@@ -104,16 +140,41 @@ LINES TERMINATED BY '\n' STARTING BY ''
 
 你可以通过 `IGNORE <number> LINES` 参数来忽略文件开始的 `<number>` 行。例如，可以使用 `IGNORE 1 LINES` 来忽略文件的第一行。
 
-### `WITH detached`
+### `WITH import_mode = ('LOGICAL' | 'PHYSICAL')`
 
-如果你指定了 S3/GCS 路径（且未指定 `LOCAL` 参数），可以通过 `WITH detached` 来让 `LOAD DATA` 任务在后台运行。此时 `LOAD DATA` 会返回 job ID。
+可以通过 `import_mode = ('LOGICAL' | 'PHYSICAL')` 来指定数据导入的模式，默认值为 `LOGICAL`，即逻辑导入。从 v7.1.0 开始，`LOAD DATA` 集成 TiDB Lightning 的物理导入模式，可通过 `WITH import_mode = 'PHYSICAL'` 开启。
 
-可以通过 [`SHOW LOAD DATA`](/sql-statements/sql-statement-show-load-data.md) 查看创建的 job，也可以使用 [`CANCEL LOAD DATA` 和 `DROP LOAD DATA`](/sql-statements/sql-statement-operate-load-data-job.md) 取消或删除创建的 job。
+物理导入模式只能在非 `LOCAL` 模式下使用，采用单线程执行。目前物理导入尚未接入[冲突监测](/tidb-lightning/tidb-lightning-physical-import-mode-usage.md#冲突数据检测)，因此遇到数据主键或唯一键冲突时会报 checksum 不一致错误。建议在导入前检查数据文件是否存在键值冲突。其他的限制和必要条件，请参考 [TiDB Lightning Physical Import Mode 简介](/tidb-lightning/tidb-lightning-physical-import-mode.md)。
+
+物理导入模式下，`LOAD DATA` 将本地排序后的数据写入 TiDB [`temp-dir`](/tidb-configuration-file.md#temp-dir-从-v630-版本开始引入) 子目录中。子目录命名规则为 `import-<tidb-port>/<job-id>`。
+
+物理导入模式目前尚未接入[磁盘资源配额](/tidb-lightning/tidb-lightning-physical-import-mode-usage.md#磁盘资源配额-从-v620-版本开始引入)。请确保对应磁盘有足够的空间，具体可参考[必要条件及限制](/tidb-lightning/tidb-lightning-physical-import-mode.md#必要条件及限制)中存储空间的部分。
+
+### `WITH thread=<number>`
+
+目前该参数仅对逻辑导入生效。
+
+可以通过 `WITH thread=<number>` 指定数据导入的并发度。默认值与 `FORMAT` 有关：
+
+- 当 `FORMAT` 为 `PARQUET` 时，默认值为 CPU 核数的 75%。
+- 对于其他 `FORMAT`，默认值为 CPU 的逻辑核数。
 
 ### `WITH batch_size=<number>`
 
 可以通过 `WITH batch_size=<number>` 来指定批量写入 TiDB 时的行数，默认值为 `1000`。如果不希望分批写入，可以指定为 `0`。
 
+### `WITH max_write_speed = stringLit`
+
+在使用物理导入模式时，可以通过该参数指定写入单个 TiKV 的速率限制。默认值为 `0`，表示无限制。
+
+该参数支持 [go-units](https://pkg.go.dev/github.com/docker/go-units#example-RAMInBytes) 格式。例如，`WITH max_write_speed = '1MB'` 表示写入单个 TiKV 的最大速率为 `1MB/s`。
+
+### `WITH detached`
+
+如果你指定了 S3/GCS 路径（且未指定 `LOCAL` 参数），可以通过 `WITH detached` 让 `LOAD DATA` 任务在后台运行。此时 `LOAD DATA` 会返回任务的 ID。
+
+你可以执行 [`SHOW LOAD DATA`](/sql-statements/sql-statement-show-load-data.md) 查看创建的任务，也可以使用 [`CANCEL LOAD DATA` 和 `DROP LOAD DATA`](/sql-statements/sql-statement-operate-load-data-job.md) 取消或删除创建的任务。
+
 ## 示例
 
 后台运行 job，执行后会输出对应的 job id：

diff --git a/sql-statements/sql-statement-operate-load-data-job.md b/sql-statements/sql-statement-operate-load-data-job.md
@@ -9,10 +9,6 @@ summary: TiDB 数据库中 CANCEL LOAD DATA 和 DROP LOAD DATA 的使用概况
 
 `DROP LOAD DATA` 语句用于删除系统中创建的 LOAD DATA 任务。
 
-> **警告：**
->
-> 当前该功能为实验特性，不建议在生产环境中使用。
-
 ## 语法图
 
 ```ebnf+diagram

diff --git a/sql-statements/sql-statement-show-load-data.md b/sql-statements/sql-statement-show-load-data.md
@@ -7,10 +7,6 @@ summary: TiDB 数据库中 SHOW LOAD DATA 的使用概况。
 
 `SHOW LOAD DATA` 语句用于显示系统中创建的 LOAD DATA 任务。该语句只能显示由当前用户创建的任务。
 
-> **警告：**
->
-> 当前该功能为实验特性，不建议在生产环境中使用。
-
 ## 语法图
 
 ```ebnf+diagram
@@ -36,7 +32,7 @@ ShowLoadDataJobStmt ::=
 | Job_State        | 表示任务当前所处的阶段，对于 `logical` 模式的任务，只有 `loading` 这一个阶段                                      |
 | Job_Status       | 表示当前任务的状态。有以下几种状态：`pending` 表示任务已创建但还未开始运行；`running` 表示运行中；`canceled` 表示已经取消的任务；`failed` 表示任务失败并退出；`finished` 表示任务已完成。                 |
 | Source_File_Size | 源文件大小                                                   |
-| Loaded_File_Size | 已经读到并写入目标表的数据量大小                               |
+| Imported_Rows | 已经读到并写入目标表的数据行数                               |
 | Result_Code      | 任务状态为 `finished` 时，其值为 `0`。任务状态为 `failed` 时，其值为对应的错误码。    |
 | Result_Message   | 如果导入成功，则返回摘要信息。如果导入失败，则返回错误信息。                  |
 
@@ -48,9 +44,9 @@ SHOW LOAD DATA JOBS;
 
 ```
 +--------+----------------------------+----------------------------+---------------------+---------------------------+--------------------+-------------+------------+-----------+------------+------------------+------------------+-------------+----------------+
-| Job_ID | Create_Time                | Start_Time                 | End_Time            | Data_Source               | Target_Table       | Import_Mode | Created_By | Job_State | Job_Status | Source_File_Size | Loaded_File_Size | Result_Code | Result_Message |
+| Job_ID | Create_Time                | Start_Time                 | End_Time            | Data_Source               | Target_Table       | Import_Mode | Created_By | Job_State | Job_Status | Source_File_Size | Imported_Rows | Result_Code | Result_Message |
 +--------+----------------------------+----------------------------+---------------------+---------------------------+-------------------+-------------+------------+-----------+------------+------------------+------------------+-------------+----------------+
-|      1 | 2023-03-16 22:29:12.990576 | 2023-03-16 22:29:12.991951 | 0000-00-00 00:00:00 | s3://bucket-name/test.csv | `my_db`.`my_table` | logical     | root@%     | loading   | running    | 52.43MB          | 43.58MB          |             |                |
+|      1 | 2023-03-16 22:29:12.990576 | 2023-03-16 22:29:12.991951 | 0000-00-00 00:00:00 | s3://bucket-name/test.csv | `my_db`.`my_table` | logical     | root@%     | loading   | running    | 52.43MB          | 323339          |             |                |
 +--------+----------------------------+----------------------------+---------------------+---------------------------+--------------------+-------------+------------+-----------+------------+------------------+------------------+-------------+----------------+
 1 row in set (0.01 sec)
 ```
@@ -61,9 +57,9 @@ SHOW LOAD DATA JOB 1;
 
 ```
 +--------+----------------------------+----------------------------+---------------------+---------------------------+--------------------+-------------+------------+-----------+------------+------------------+------------------+-------------+----------------+
-| Job_ID | Create_Time                | Start_Time                 | End_Time            | Data_Source               | Target_Table       | Import_Mode | Created_By | Job_State | Job_Status | Source_File_Size | Loaded_File_Size | Result_Code | Result_Message |
+| Job_ID | Create_Time                | Start_Time                 | End_Time            | Data_Source               | Target_Table       | Import_Mode | Created_By | Job_State | Job_Status | Source_File_Size | Imported_Rows | Result_Code | Result_Message |
 +--------+----------------------------+----------------------------+---------------------+---------------------------+-------------------+-------------+------------+-----------+------------+------------------+------------------+-------------+----------------+
-|      1 | 2023-03-16 22:29:12.990576 | 2023-03-16 22:29:12.991951 | 0000-00-00 00:00:00 | s3://bucket-name/test.csv | `my_db`.`my_table` | logical     | root@%     | loading   | running    | 52.43MB          | 43.58MB          |             |                |
+|      1 | 2023-03-16 22:29:12.990576 | 2023-03-16 22:29:12.991951 | 0000-00-00 00:00:00 | s3://bucket-name/test.csv | `my_db`.`my_table` | logical     | root@%     | loading   | running    | 52.43MB          | 323339          |             |                |
 +--------+----------------------------+----------------------------+---------------------+---------------------------+--------------------+-------------+------------+-----------+------------+------------------+------------------+-------------+----------------+
 1 row in set (0.01 sec)
 ```

diff --git a/tidb-configuration-file.md b/tidb-configuration-file.md
@@ -46,6 +46,7 @@ TiDB 配置文件比命令行参数支持更多的选项。你可以在 [config/
 
 + TiDB 用于存放临时数据的路径。如果一个功能需要使用 TiDB 节点的本地存储，TiDB 将把对应数据临时存放在这个目录下。
 + 在创建索引的过程中，如果开启了[创建索引加速](/system-variables.md#tidb_ddl_enable_fast_reorg-从-v630-版本开始引入)，那么新创建索引需要回填的数据会被先存放在 TiDB 本地临时存储路径，然后批量导入到 TiKV，从而提升索引创建速度。
++ 在使用 [`LOAD DATA`](/sql-statements/sql-statement-load-data.md) 的物理导入模式时，排序后的数据会被先存放在 TiDB 本地临时存储路径，然后批量导入到 TiKV。
 + 默认值："/tmp/tidb"
 
 ### `oom-use-tmp-storage`