From e781ad2f38919c78dd42a6012c30fb25bf1978b1 Mon Sep 17 00:00:00 2001 From: Ruihao Chen Date: Fri, 15 Aug 2025 14:37:43 +0800 Subject: [PATCH] update document Signed-off-by: Ruihao Chen --- TOC.md | 1 + privilege-management.md | 2 +- .../sql-statement-cancel-import-job.md | 3 +- sql-statements/sql-statement-import-into.md | 5 +- sql-statements/sql-statement-overview.md | 1 + .../sql-statement-show-import-group.md | 76 +++++++++++++++++++ .../sql-statement-show-import-job.md | 36 +++++---- 7 files changed, 107 insertions(+), 17 deletions(-) create mode 100644 sql-statements/sql-statement-show-import-group.md diff --git a/TOC.md b/TOC.md index 0bb0cbe9fa244..b77f98657347f 100644 --- a/TOC.md +++ b/TOC.md @@ -898,6 +898,7 @@ - [`SHOW FIELDS FROM`](/sql-statements/sql-statement-show-fields-from.md) - [`SHOW GRANTS`](/sql-statements/sql-statement-show-grants.md) - [`SHOW IMPORT JOB`](/sql-statements/sql-statement-show-import-job.md) + - [`SHOW IMPORT GROUP`](/sql-statements/sql-statement-show-import-group.md) - [`SHOW INDEXES`](/sql-statements/sql-statement-show-indexes.md) - [`SHOW MASTER STATUS`](/sql-statements/sql-statement-show-master-status.md) - [`SHOW PLACEMENT`](/sql-statements/sql-statement-show-placement.md) diff --git a/privilege-management.md b/privilege-management.md index c0b1bb3df426c..5ac4882b7556c 100644 --- a/privilege-management.md +++ b/privilege-management.md @@ -430,7 +430,7 @@ Requires the `INSERT` and `SELECT` privileges for the table. `SHOW PROCESSLIST` requires the `PROCESS` privilege to show connections belonging to other users. -`SHOW IMPORT JOB` requires the `SUPER` privilege to show connections belonging to other users. Otherwise, it only shows jobs created by the current user. +`SHOW IMPORT JOB` and `SHOW IMPORT GROUP` require the `SUPER` privilege to show connections belonging to other users. Otherwise, it only shows jobs created by the current user. `SHOW STATS_LOCKED` requires the `SELECT` privilege to the `mysql.stats_table_locked` table. diff --git a/sql-statements/sql-statement-cancel-import-job.md b/sql-statements/sql-statement-cancel-import-job.md index d4b911d846384..9f388bf5f352b 100644 --- a/sql-statements/sql-statement-cancel-import-job.md +++ b/sql-statements/sql-statement-cancel-import-job.md @@ -39,4 +39,5 @@ This statement is a TiDB extension to MySQL syntax. ## See also * [`IMPORT INTO`](/sql-statements/sql-statement-import-into.md) -* [`SHOW IMPORT JOB`](/sql-statements/sql-statement-show-import-job.md) +* [`SHOW IMPORT JOB(s)`](/sql-statements/sql-statement-show-import-job.md) +* [`SHOW IMPORT GROUP(s)`](/sql-statements/sql-statement-show-import-group.md) diff --git a/sql-statements/sql-statement-import-into.md b/sql-statements/sql-statement-import-into.md index 7793534234871..7ec582d0354f5 100644 --- a/sql-statements/sql-statement-import-into.md +++ b/sql-statements/sql-statement-import-into.md @@ -141,6 +141,7 @@ The supported options are described as follows: | Option name | Supported data sources and formats | Description | |:---|:---|:---| +| `GROUP_KEY=''` | All file formats | Specifies the group key for the job. The key can contain only alphanumeric characters, underscores (_), or hyphens (-), and can be up to 256 characters long. If no group key is set, the job will not belong to any group and will not appear in `SHOW IMPORT GROUPS` results. | | `CHARACTER_SET=''` | CSV | Specifies the character set of the data file. The default character set is `utf8mb4`. The supported character sets include `binary`, `utf8`, `utf8mb4`, `gb18030`, `gbk`, `latin1`, and `ascii`. | | `FIELDS_TERMINATED_BY=''` | CSV | Specifies the field separator. The default separator is `,`. | | `FIELDS_ENCLOSED_BY=''` | CSV | Specifies the field delimiter. The default delimiter is `"`. | @@ -240,7 +241,9 @@ IMPORT INTO t FROM '/path/to/small.csv' WITH DETACHED; ### View and manage import jobs -For an import job with the `DETACHED` mode enabled, you can use [`SHOW IMPORT`](/sql-statements/sql-statement-show-import-job.md) to view its current job progress. +For an import job with the `DETACHED` mode enabled, you can use [`SHOW IMPORT JOB`](/sql-statements/sql-statement-show-import-job.md) to view its current job progress. + +Besides, you can use [`SHOW IMPORT GROUP`](/sql-statements/sql-statement-show-import-job.md) to view the overall progress of the jobs in the group. After an import job is started, you can cancel it using [`CANCEL IMPORT JOB `](/sql-statements/sql-statement-cancel-import-job.md). diff --git a/sql-statements/sql-statement-overview.md b/sql-statements/sql-statement-overview.md index c76059777c72d..1f6f0e4a6758a 100644 --- a/sql-statements/sql-statement-overview.md +++ b/sql-statements/sql-statement-overview.md @@ -131,6 +131,7 @@ TiDB uses SQL statements that aim to follow ISO/IEC SQL standards, with extensio | [`IMPORT INTO`](/sql-statements/sql-statement-import-into.md) | Imports data into a table via the [Physical Import Mode](https://docs.pingcap.com/tidb/stable/tidb-lightning-physical-import-mode) of TiDB Lightning. | | [`LOAD DATA`](/sql-statements/sql-statement-load-data.md) | Loads data into a table from Amazon S3 or Google Cloud Storage. | | [`SHOW IMPORT JOB`](/sql-statements/sql-statement-show-import-job.md) | Shows the status of an import job. | +| [`SHOW IMPORT GROUP`](/sql-statements/sql-statement-show-import-group.md) | Shows the status of a group of import jobs. | ## Backup & restore diff --git a/sql-statements/sql-statement-show-import-group.md b/sql-statements/sql-statement-show-import-group.md new file mode 100644 index 0000000000000..a3292e3e7f754 --- /dev/null +++ b/sql-statements/sql-statement-show-import-group.md @@ -0,0 +1,76 @@ +--- +title: SHOW IMPORT GROUP +summary: An overview of the usage of SHOW IMPORT GROUP in TiDB. +--- + +# SHOW IMPORT + +The `SHOW IMPORT GROUP` statement is used to show the groups of IMPORT jobs created in TiDB. This statement can only show jobs created by the current user. + +## Required privileges + +- `SHOW IMPORT GROUPS`: if a user has the `SUPER` privilege, this statement shows all import groups in TiDB. Otherwise, this statement only shows groups created by the current user. +- `SHOW IMPORT GROUP `: only the creator of an import group or users with the `SUPER` privilege can use this statement to view a specific import group. + +## Synopsis + +```ebnf+diagram +ShowImportGroupsStmt ::= + 'SHOW' 'IMPORT' 'GROUPS' + +ShowImportGroupStmt ::= + 'SHOW' 'IMPORT' 'GROUP' GroupKey +``` + +The output fields of the `SHOW IMPORT` statement are described as follows: + +| Column | Description | +|------------------|-------------------------| +| Group_Key | The key of the group | +| Total_Jobs | Total number of jobs in this group | +| Pending | Number of pending jobs in this group | +| Running | Number of running jobs in this group | +| Completed | Number of completed jobs in this group | +| Failed | Number of failed jobs in this group | +| Cancelled | Number of cancelled jobs in this group | +| First_Job_Create_Time | The earliest create time of the jobs in this group | +| Last_Job_Update_Time | The latest update time of the jobs in this group | + +## Example + +```sql +SHOW IMPORT GROUPS; +``` + +``` ++--------------+------------+---------+---------+-----------+--------+-----------+----------------------------+----------------------------+ +| Group_Key | Total_Jobs | Pending | Running | Completed | Failed | Cancelled | First_Job_Create_Time | Last_Job_Update_Time | ++--------------+------------+---------+---------+-----------+--------+-----------+----------------------------+----------------------------+ +| system_group | 1 | 0 | 1 | 0 | 0 | 0 | 2025-08-07 01:36:18.479055 | 2025-08-07 01:36:18.479055 | ++--------------+------------+---------+---------+-----------+--------+-----------+----------------------------+----------------------------+ +| user_group | 1 | 1 | 0 | 0 | 0 | 0 | 2025-08-07 01:37:26.162268 | NULL | ++--------------+------------+---------+---------+-----------+--------+-----------+----------------------------+----------------------------+ +2 rows in set (0.01 sec) +``` + +```sql +SHOW IMPORT GROUP "system_group"; +``` + +``` ++--------------+------------+---------+---------+-----------+--------+-----------+----------------------------+----------------------------+ +| Group_Key | Total_Jobs | Pending | Running | Completed | Failed | Cancelled | First_Job_Create_Time | Last_Job_Update_Time | ++--------------+------------+---------+---------+-----------+--------+-----------+----------------------------+----------------------------+ +| system_group | 1 | 0 | 1 | 0 | 0 | 0 | 2025-08-07 01:36:18.479055 | 2025-08-07 01:36:18.479055 | ++--------------+------------+---------+---------+-----------+--------+-----------+----------------------------+----------------------------+ +1 row in set (0.01 sec) +``` + +## MySQL compatibility + +This statement is a TiDB extension to MySQL syntax. + +## See also + +* [`IMPORT INTO`](/sql-statements/sql-statement-import-into.md) +* [`CANCEL IMPORT JOB`](/sql-statements/sql-statement-cancel-import-job.md) diff --git a/sql-statements/sql-statement-show-import-job.md b/sql-statements/sql-statement-show-import-job.md index 396f60558a137..a44051aeae8ef 100644 --- a/sql-statements/sql-statement-show-import-job.md +++ b/sql-statements/sql-statement-show-import-job.md @@ -39,6 +39,14 @@ The output fields of the `SHOW IMPORT` statement are described as follows: | End_Time | The time when the task is ended | | Created_By | The name of the database user who creates the task | +| Last_Update_Time (NEW) | The total size of the data to be processed in the current step | +| Cur_Step | The specific sequential processing step of this job | +| Cur_Step_Processed_Size | The amount of data that has been processed within the current step | +| Cur_Step_Total_Size | The total size of the data to be processed in the current step | +| Cur_Step_Progress_Pct | The estimated completion percentage of the current step | +| Cur_Step_Speed | The current data processing speed | +| Cur_Step_ETA | The estimated time remaining for the current step to complete | + ## Example ```sql @@ -46,26 +54,26 @@ 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 | -+--------+-------------------+--------------+----------+-------+----------+------------------+---------------+----------------+----------------------------+----------------------------+----------------------------+------------+ -| 1 | /path/to/file.csv | `test`.`foo` | 116 | | finished | 11GB | 950000 | | 2023-06-26 11:23:59.281257 | 2023-06-26 11:23:59.484932 | 2023-06-26 13:04:30.622952 | root@% | -| 2 | /path/to/file.csv | `test`.`bar` | 130 | | finished | 1.194TB | 49995000 | | 2023-06-26 15:42:45.079237 | 2023-06-26 15:42:45.388108 | 2023-06-26 17:29:43.023568 | root@% | -+--------+-------------------+--------------+----------+-------+----------+------------------+---------------+----------------+----------------------------+----------------------------+----------------------------+------------+ -1 row in set (0.01 sec) ++--------+-------------------+--------------+----------+----------------+----------+------------------+---------------+----------------+----------------------------+----------------------------+----------------------------+------------+---------------------+--------------+-------------------------+---------------------+-----------------------+----------------+--------------+ +| 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 | Last_Update_Time | Cur_Step | Cur_Step_Processed_Size | Cur_Step_Total_Size | Cur_Step_Progress_Pct | Cur_Step_Speed | Cur_Step_ETA | ++--------+-------------------+--------------+----------+----------------+----------+------------------+---------------+----------------+----------------------------+----------------------------+----------------------------+------------+---------------------+--------------+-------------------------+---------------------+-----------------------+----------------+--------------+ +| 1 | /path/to/file.csv | `test`.`foo` | 116 | | finished | 11GB | 950000 | | 2023-06-26 11:23:59.281257 | 2023-06-26 11:23:59.484932 | 2023-06-26 13:04:30.622952 | root@% | 0000-00-00 00:00:00 | NULL | NULL | NULL | NULL | NULL | NULL | +| 2 | /path/to/file.csv | `test`.`bar` | 118 | global-sorting | running | 277.5GiB | 0 | | 2025-07-09 10:40:18.580706 | 2025-07-09 10:40:19.092528 | NULL | root@% | 2025-07-09 10:47:15 | encode | 4.55GB | 298GB | 1 | 10.96MB/s | 07:26:03 | +--------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+----------+----------------+---------+------------------+---------------+----------------+----------------------------+----------------------------+----------+------------+---------------------+----------+-------------------------+---------------------+----------- ++--------+-------------------+--------------+----------+----------------+----------+------------------+---------------+----------------+----------------------------+----------------------------+----------------------------+------------+---------------------+--------------+-------------------------+---------------------+-----------------------+----------------+--------------+ +2 rows in set (0.01 sec) ``` ```sql -SHOW IMPORT JOB 60001; +SHOW IMPORT JOB 2; ``` ``` -+--------+--------------------+--------------+----------+-------+---------+------------------+---------------+----------------+----------------------------+------------+----------+------------+ -| 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 | -+--------+--------------------+--------------+----------+-------+---------+------------------+---------------+----------------+----------------------------+------------+----------+------------+ -| 60001 | /path/to/small.csv | `test`.`t` | 361 | | pending | 16B | NULL | | 2023-06-08 15:59:37.047703 | NULL | NULL | root@% | -+--------+--------------------+--------------+----------+-------+---------+------------------+---------------+----------------+----------------------------+------------+----------+------------+ -1 row in set (0.01 sec) ++--------+-------------------+--------------+----------+----------------+----------+------------------+---------------+----------------+----------------------------+----------------------------+----------------------------+------------+---------------------+--------------+-------------------------+---------------------+-----------------------+----------------+--------------+ +| 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 | Last_Update_Time | Cur_Step | Cur_Step_Processed_Size | Cur_Step_Total_Size | Cur_Step_Progress_Pct | Cur_Step_Speed | Cur_Step_ETA | ++--------+-------------------+--------------+----------+----------------+----------+------------------+---------------+----------------+----------------------------+----------------------------+----------------------------+------------+---------------------+--------------+-------------------------+---------------------+-----------------------+----------------+--------------+ +| 2 | /path/to/file.csv | `test`.`bar` | 118 | global-sorting | running | 277.5GiB | 0 | | 2025-07-09 10:40:18.580706 | 2025-07-09 10:40:19.092528 | NULL | root@% | 2025-07-09 10:47:15 | encode | 4.55GB | 298GB | 1 | 10.96MB/s | 07:26:03 | +--------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+----------+----------------+---------+------------------+---------------+----------------+----------------------------+----------------------------+----------+------------+---------------------+----------+-------------------------+---------------------+----------- ++--------+-------------------+--------------+----------+----------------+----------+------------------+---------------+----------------+----------------------------+----------------------------+----------------------------+------------+---------------------+--------------+-------------------------+---------------------+-----------------------+----------------+--------------+ +1 row in set (0.07 sec) ``` ## MySQL compatibility