From e781ad2f38919c78dd42a6012c30fb25bf1978b1 Mon Sep 17 00:00:00 2001 From: Ruihao Chen Date: Fri, 15 Aug 2025 14:37:43 +0800 Subject: [PATCH 01/14] 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 From 978c792906891f6a817802c7410098df05f581e0 Mon Sep 17 00:00:00 2001 From: Ruihao Chen Date: Fri, 22 May 2026 02:15:18 -0400 Subject: [PATCH 02/14] docs: update SHOW IMPORT syntax --- sql-statements/sql-statement-import-into.md | 3 +- .../sql-statement-show-import-group.md | 5 ++- .../sql-statement-show-import-job.md | 43 ++++++++++++++----- 3 files changed, 37 insertions(+), 14 deletions(-) diff --git a/sql-statements/sql-statement-import-into.md b/sql-statements/sql-statement-import-into.md index 7ec582d0354f5..e8f8afefd9f62 100644 --- a/sql-statements/sql-statement-import-into.md +++ b/sql-statements/sql-statement-import-into.md @@ -243,7 +243,7 @@ IMPORT INTO t FROM '/path/to/small.csv' WITH DETACHED; 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. +Besides, you can use [`SHOW IMPORT GROUP`](/sql-statements/sql-statement-show-import-group.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). @@ -366,4 +366,5 @@ This statement is a TiDB extension to MySQL syntax. * [`ADMIN CHECKSUM TABLE`](/sql-statements/sql-statement-admin-checksum-table.md) * [`CANCEL IMPORT JOB`](/sql-statements/sql-statement-cancel-import-job.md) * [`SHOW IMPORT JOB(s)`](/sql-statements/sql-statement-show-import-job.md) +* [`SHOW IMPORT GROUP`](/sql-statements/sql-statement-show-import-group.md) * [TiDB Distributed eXecution Framework (DXF)](/tidb-distributed-execution-framework.md) diff --git a/sql-statements/sql-statement-show-import-group.md b/sql-statements/sql-statement-show-import-group.md index a3292e3e7f754..eb65120dfd3ab 100644 --- a/sql-statements/sql-statement-show-import-group.md +++ b/sql-statements/sql-statement-show-import-group.md @@ -3,7 +3,7 @@ title: SHOW IMPORT GROUP summary: An overview of the usage of SHOW IMPORT GROUP in TiDB. --- -# SHOW IMPORT +# SHOW IMPORT GROUP 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. @@ -22,7 +22,7 @@ ShowImportGroupStmt ::= 'SHOW' 'IMPORT' 'GROUP' GroupKey ``` -The output fields of the `SHOW IMPORT` statement are described as follows: +The output fields of the `SHOW IMPORT GROUP` statement are described as follows: | Column | Description | |------------------|-------------------------| @@ -73,4 +73,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) * [`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 a44051aeae8ef..bc41e7ffc5541 100644 --- a/sql-statements/sql-statement-show-import-job.md +++ b/sql-statements/sql-statement-show-import-job.md @@ -1,32 +1,40 @@ --- -title: SHOW IMPORT -summary: An overview of the usage of SHOW IMPORT in TiDB. +title: SHOW IMPORT JOB +summary: An overview of the usage of SHOW IMPORT JOB in TiDB. --- -# SHOW IMPORT +# SHOW IMPORT JOB -The `SHOW IMPORT` statement is used to show the IMPORT jobs created in TiDB. This statement can only show jobs created by the current user. +The `SHOW IMPORT JOB` statement is used to show the IMPORT jobs created in TiDB. This statement can only show jobs created by the current user. ## Required privileges -- `SHOW IMPORT JOBS`: if a user has the `SUPER` privilege, this statement shows all import jobs in TiDB. Otherwise, this statement only shows jobs created by the current user. -- `SHOW IMPORT JOB `: only the creator of an import job or users with the `SUPER` privilege can use this statement to view a specific job. +- `SHOW [RAW] IMPORT JOBS`: if a user has the `SUPER` privilege, this statement shows all import jobs in TiDB. Otherwise, this statement only shows jobs created by the current user. +- `SHOW [RAW] IMPORT JOB `: only the creator of an import job or users with the `SUPER` privilege can use this statement to view a specific job. ## Synopsis ```ebnf+diagram ShowImportJobsStmt ::= - 'SHOW' 'IMPORT' 'JOBS' + 'SHOW' RawOpt? 'IMPORT' 'JOBS' ShowLikeOrWhereOpt? ShowImportJobStmt ::= - 'SHOW' 'IMPORT' 'JOB' JobID + 'SHOW' RawOpt? 'IMPORT' 'JOB' JobID + +RawOpt ::= + 'RAW' + +ShowLikeOrWhereOpt ::= + 'LIKE' SimpleExpr +| 'WHERE' Expression ``` -The output fields of the `SHOW IMPORT` statement are described as follows: +The output fields of the `SHOW IMPORT JOB` statement are described as follows: | Column | Description | |------------------|-------------------------| | Job_ID | The ID of the task | +| Group_Key | The group key of the task | | Data_Source | Information about the data source | | Target_Table | The name of the target table | | Phase | The current phase of the job, including `importing`, `validating`, and `add-index` | @@ -38,8 +46,7 @@ The output fields of the `SHOW IMPORT` statement are described as follows: | Start_Time | The time when the task is started | | 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 | +| Last_Update_Time | The time when the task is last updated | | 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 | @@ -76,6 +83,20 @@ SHOW IMPORT JOB 2; 1 row in set (0.07 sec) ``` +You can also add the `RAW` keyword before `IMPORT`: + +```sql +SHOW RAW IMPORT JOBS; +``` + +```sql +SHOW RAW IMPORT JOBS WHERE Group_Key = 'user_group'; +``` + +```sql +SHOW RAW IMPORT JOB 2; +``` + ## MySQL compatibility This statement is a TiDB extension to MySQL syntax. From 1c4cbd1bef236cd8888483b8f1ec39c476e6c118 Mon Sep 17 00:00:00 2001 From: Ruihao Chen Date: Fri, 22 May 2026 02:16:57 -0400 Subject: [PATCH 03/14] docs: refine SHOW IMPORT examples --- .../sql-statement-show-import-job.md | 24 +++++++------------ 1 file changed, 8 insertions(+), 16 deletions(-) diff --git a/sql-statements/sql-statement-show-import-job.md b/sql-statements/sql-statement-show-import-job.md index bc41e7ffc5541..5d7c79eb0362c 100644 --- a/sql-statements/sql-statement-show-import-job.md +++ b/sql-statements/sql-statement-show-import-job.md @@ -56,31 +56,22 @@ The output fields of the `SHOW IMPORT JOB` statement are described as follows: ## Example +Show all import jobs that the current user can view: + ```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 | 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) -``` +Show a specific import job by job ID: ```sql 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 | 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) +Filter import jobs by output fields: + +```sql +SHOW IMPORT JOBS WHERE Group_Key = 'user_group'; ``` You can also add the `RAW` keyword before `IMPORT`: @@ -104,4 +95,5 @@ This statement is a TiDB extension to MySQL syntax. ## See also * [`IMPORT INTO`](/sql-statements/sql-statement-import-into.md) +* [`SHOW IMPORT GROUP`](/sql-statements/sql-statement-show-import-group.md) * [`CANCEL IMPORT JOB`](/sql-statements/sql-statement-cancel-import-job.md) From 9248b55a8b2a1ac1c314a113b53271931d88f874 Mon Sep 17 00:00:00 2001 From: Ruihao Chen Date: Fri, 22 May 2026 02:20:42 -0400 Subject: [PATCH 04/14] docs: rename import group example --- sql-statements/sql-statement-show-import-group.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sql-statements/sql-statement-show-import-group.md b/sql-statements/sql-statement-show-import-group.md index eb65120dfd3ab..b10ec9ad06185 100644 --- a/sql-statements/sql-statement-show-import-group.md +++ b/sql-statements/sql-statement-show-import-group.md @@ -46,7 +46,7 @@ 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 | +| import_group_1 | 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 | +--------------+------------+---------+---------+-----------+--------+-----------+----------------------------+----------------------------+ @@ -54,14 +54,14 @@ SHOW IMPORT GROUPS; ``` ```sql -SHOW IMPORT GROUP "system_group"; +SHOW IMPORT GROUP "import_group_1"; ``` ``` +--------------+------------+---------+---------+-----------+--------+-----------+----------------------------+----------------------------+ | 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 | +| import_group_1 | 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) ``` From af8657a6aa8d67b7cacf57b7062f1a8e8d68da9d Mon Sep 17 00:00:00 2001 From: Ruihao Chen Date: Fri, 22 May 2026 02:22:55 -0400 Subject: [PATCH 05/14] docs: clarify SHOW IMPORT JOBS filters --- sql-statements/sql-statement-show-import-job.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/sql-statements/sql-statement-show-import-job.md b/sql-statements/sql-statement-show-import-job.md index 5d7c79eb0362c..e293bfc1d7ebf 100644 --- a/sql-statements/sql-statement-show-import-job.md +++ b/sql-statements/sql-statement-show-import-job.md @@ -37,6 +37,7 @@ The output fields of the `SHOW IMPORT JOB` statement are described as follows: | Group_Key | The group key of the task | | Data_Source | Information about the data source | | Target_Table | The name of the target table | +| Table_ID | The ID of the target table | | Phase | The current phase of the job, including `importing`, `validating`, and `add-index` | | Status | The current status of the job, including `pending` (means created but not started yet), `running`, `canceled`, `failed`, and `finished` | | Source_File_Size | The size of the source file | @@ -54,6 +55,12 @@ The output fields of the `SHOW IMPORT JOB` statement are described as follows: | Cur_Step_Speed | The current data processing speed | | Cur_Step_ETA | The estimated time remaining for the current step to complete | +## Filtering import jobs + +Only `SHOW [RAW] IMPORT JOBS` supports filtering import jobs with a `WHERE` clause. `SHOW [RAW] IMPORT JOB ` does not support a `WHERE` clause. + +The `WHERE` clause can reference the output fields of `SHOW IMPORT JOBS`, including `Job_ID`, `Group_Key`, `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`, and `Cur_Step_ETA`. + ## Example Show all import jobs that the current user can view: From 997099360b1541e48b672f08bb54d49029355c37 Mon Sep 17 00:00:00 2001 From: Ruihao Chen Date: Fri, 22 May 2026 02:24:26 -0400 Subject: [PATCH 06/14] docs: restore SHOW IMPORT JOB examples --- sql-statements/sql-statement-show-import-job.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/sql-statements/sql-statement-show-import-job.md b/sql-statements/sql-statement-show-import-job.md index e293bfc1d7ebf..d5079343a17f1 100644 --- a/sql-statements/sql-statement-show-import-job.md +++ b/sql-statements/sql-statement-show-import-job.md @@ -75,6 +75,12 @@ Show a specific import job by job ID: SHOW IMPORT JOB 2; ``` +The output is as follows: + +| Job_ID | Group_Key | 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 | import_group_1 | /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 | + Filter import jobs by output fields: ```sql @@ -95,6 +101,8 @@ SHOW RAW IMPORT JOBS WHERE Group_Key = 'user_group'; SHOW RAW IMPORT JOB 2; ``` +`SHOW RAW IMPORT JOB ` returns the same output fields as `SHOW IMPORT JOB `. + ## MySQL compatibility This statement is a TiDB extension to MySQL syntax. From e3d312ee82548b14577b58f7cd1dc2ceb934c3f9 Mon Sep 17 00:00:00 2001 From: Ruihao Chen Date: Fri, 22 May 2026 02:28:30 -0400 Subject: [PATCH 07/14] docs: address import review wording --- sql-statements/sql-statement-import-into.md | 2 +- sql-statements/sql-statement-show-import-group.md | 2 +- sql-statements/sql-statement-show-import-job.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/sql-statements/sql-statement-import-into.md b/sql-statements/sql-statement-import-into.md index e8f8afefd9f62..3e1ee88c2524e 100644 --- a/sql-statements/sql-statement-import-into.md +++ b/sql-statements/sql-statement-import-into.md @@ -243,7 +243,7 @@ IMPORT INTO t FROM '/path/to/small.csv' WITH DETACHED; 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-group.md) to view the overall progress of the jobs in the group. +You can also use [`SHOW IMPORT GROUP(s)`](/sql-statements/sql-statement-show-import-group.md) to view the overall progress of jobs in the same 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-show-import-group.md b/sql-statements/sql-statement-show-import-group.md index b10ec9ad06185..e6e7b5ba60e18 100644 --- a/sql-statements/sql-statement-show-import-group.md +++ b/sql-statements/sql-statement-show-import-group.md @@ -5,7 +5,7 @@ summary: An overview of the usage of SHOW IMPORT GROUP in TiDB. # SHOW IMPORT GROUP -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. +The `SHOW IMPORT GROUP` statement is used to show the groups of `IMPORT` jobs created in TiDB. By default, `SHOW IMPORT GROUPS` shows groups created by the current user. To view all import groups, you need the `SUPER` privilege. ## Required privileges diff --git a/sql-statements/sql-statement-show-import-job.md b/sql-statements/sql-statement-show-import-job.md index d5079343a17f1..51bd0b20f5418 100644 --- a/sql-statements/sql-statement-show-import-job.md +++ b/sql-statements/sql-statement-show-import-job.md @@ -5,7 +5,7 @@ summary: An overview of the usage of SHOW IMPORT JOB in TiDB. # SHOW IMPORT JOB -The `SHOW IMPORT JOB` statement is used to show the IMPORT jobs created in TiDB. This statement can only show jobs created by the current user. +The `SHOW IMPORT JOB` statement is used to show `IMPORT` jobs created in TiDB. By default, `SHOW IMPORT JOBS` shows jobs created by the current user. To view all import jobs, you need the `SUPER` privilege. ## Required privileges From 8ac1977c59341f0637e737720aca15713baf2621 Mon Sep 17 00:00:00 2001 From: Ruihao Chen Date: Fri, 22 May 2026 05:02:21 -0400 Subject: [PATCH 08/14] docs: remove unfinished SHOW RAW IMPORT syntax --- .../sql-statement-show-import-job.md | 29 ++++--------------- 1 file changed, 5 insertions(+), 24 deletions(-) diff --git a/sql-statements/sql-statement-show-import-job.md b/sql-statements/sql-statement-show-import-job.md index 51bd0b20f5418..f79031747e6a8 100644 --- a/sql-statements/sql-statement-show-import-job.md +++ b/sql-statements/sql-statement-show-import-job.md @@ -9,20 +9,17 @@ The `SHOW IMPORT JOB` statement is used to show `IMPORT` jobs created in TiDB. B ## Required privileges -- `SHOW [RAW] IMPORT JOBS`: if a user has the `SUPER` privilege, this statement shows all import jobs in TiDB. Otherwise, this statement only shows jobs created by the current user. -- `SHOW [RAW] IMPORT JOB `: only the creator of an import job or users with the `SUPER` privilege can use this statement to view a specific job. +- `SHOW IMPORT JOBS`: if a user has the `SUPER` privilege, this statement shows all import jobs in TiDB. Otherwise, this statement only shows jobs created by the current user. +- `SHOW IMPORT JOB `: only the creator of an import job or users with the `SUPER` privilege can use this statement to view a specific job. ## Synopsis ```ebnf+diagram ShowImportJobsStmt ::= - 'SHOW' RawOpt? 'IMPORT' 'JOBS' ShowLikeOrWhereOpt? + 'SHOW' 'IMPORT' 'JOBS' ShowLikeOrWhereOpt? ShowImportJobStmt ::= - 'SHOW' RawOpt? 'IMPORT' 'JOB' JobID - -RawOpt ::= - 'RAW' + 'SHOW' 'IMPORT' 'JOB' JobID ShowLikeOrWhereOpt ::= 'LIKE' SimpleExpr @@ -57,7 +54,7 @@ The output fields of the `SHOW IMPORT JOB` statement are described as follows: ## Filtering import jobs -Only `SHOW [RAW] IMPORT JOBS` supports filtering import jobs with a `WHERE` clause. `SHOW [RAW] IMPORT JOB ` does not support a `WHERE` clause. +Only `SHOW IMPORT JOBS` supports filtering import jobs with a `WHERE` clause. `SHOW IMPORT JOB ` does not support a `WHERE` clause. The `WHERE` clause can reference the output fields of `SHOW IMPORT JOBS`, including `Job_ID`, `Group_Key`, `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`, and `Cur_Step_ETA`. @@ -87,22 +84,6 @@ Filter import jobs by output fields: SHOW IMPORT JOBS WHERE Group_Key = 'user_group'; ``` -You can also add the `RAW` keyword before `IMPORT`: - -```sql -SHOW RAW IMPORT JOBS; -``` - -```sql -SHOW RAW IMPORT JOBS WHERE Group_Key = 'user_group'; -``` - -```sql -SHOW RAW IMPORT JOB 2; -``` - -`SHOW RAW IMPORT JOB ` returns the same output fields as `SHOW IMPORT JOB `. - ## MySQL compatibility This statement is a TiDB extension to MySQL syntax. From 2188a5b38470899e55ef4f762236051c0b44886e Mon Sep 17 00:00:00 2001 From: Ruihao Chen Date: Mon, 25 May 2026 03:54:30 -0400 Subject: [PATCH 09/14] docs: clarify LIKE filtering in SHOW IMPORT JOBS Co-Authored-By: Claude Opus 4.7 (1M context) --- sql-statements/sql-statement-show-import-job.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-show-import-job.md b/sql-statements/sql-statement-show-import-job.md index f79031747e6a8..7930c5041345d 100644 --- a/sql-statements/sql-statement-show-import-job.md +++ b/sql-statements/sql-statement-show-import-job.md @@ -54,10 +54,12 @@ The output fields of the `SHOW IMPORT JOB` statement are described as follows: ## Filtering import jobs -Only `SHOW IMPORT JOBS` supports filtering import jobs with a `WHERE` clause. `SHOW IMPORT JOB ` does not support a `WHERE` clause. +Only `SHOW IMPORT JOBS` supports filtering import jobs with a `WHERE` or `LIKE` clause. `SHOW IMPORT JOB ` does not support these clauses. The `WHERE` clause can reference the output fields of `SHOW IMPORT JOBS`, including `Job_ID`, `Group_Key`, `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`, and `Cur_Step_ETA`. +The `LIKE` clause matches its pattern only against the first column `Job_ID` (compared as a string). For example, `SHOW IMPORT JOBS LIKE '%1'` returns the jobs whose `Job_ID` ends with `1`. + ## Example Show all import jobs that the current user can view: From 074cbb114af3c79857f64b97b0d02c5bb813ce1d Mon Sep 17 00:00:00 2001 From: Ruihao Chen Date: Tue, 26 May 2026 10:01:28 +0800 Subject: [PATCH 10/14] Apply suggestions from code review Co-authored-by: Grace Cai --- privilege-management.md | 2 +- sql-statements/sql-statement-import-into.md | 2 +- sql-statements/sql-statement-show-import-group.md | 2 +- sql-statements/sql-statement-show-import-job.md | 6 +++--- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/privilege-management.md b/privilege-management.md index 5ac4882b7556c..cd5154f021905 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` 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 IMPORT JOB` and `SHOW IMPORT GROUP` require the `SUPER` privilege to show import jobs and import groups belonging to other users. Otherwise, these statements only show jobs and groups 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-import-into.md b/sql-statements/sql-statement-import-into.md index 3e1ee88c2524e..e98169396fda9 100644 --- a/sql-statements/sql-statement-import-into.md +++ b/sql-statements/sql-statement-import-into.md @@ -141,7 +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. | +| `GROUP_KEY=''` | All file formats | Specifies the group key for the job. TiDB groups import jobs with the same group key, allowing you to monitor related jobs collectively using [`SHOW IMPORT GROUPS`](/sql-statements/sql-statement-show-import-group.md). 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 does not belong to any group and does 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 `"`. | diff --git a/sql-statements/sql-statement-show-import-group.md b/sql-statements/sql-statement-show-import-group.md index e6e7b5ba60e18..f8d4834f6b853 100644 --- a/sql-statements/sql-statement-show-import-group.md +++ b/sql-statements/sql-statement-show-import-group.md @@ -33,7 +33,7 @@ The output fields of the `SHOW IMPORT GROUP` statement are described as follows: | 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 | +| First_Job_Create_Time | The earliest creation time of the jobs in this group | | Last_Job_Update_Time | The latest update time of the jobs in this group | ## Example diff --git a/sql-statements/sql-statement-show-import-job.md b/sql-statements/sql-statement-show-import-job.md index 7930c5041345d..60da0b01ec5dd 100644 --- a/sql-statements/sql-statement-show-import-job.md +++ b/sql-statements/sql-statement-show-import-job.md @@ -30,8 +30,8 @@ The output fields of the `SHOW IMPORT JOB` statement are described as follows: | Column | Description | |------------------|-------------------------| -| Job_ID | The ID of the task | -| Group_Key | The group key of the task | +| Job_ID | The ID of the job | +| Group_Key | The group key of the job | | Data_Source | Information about the data source | | Target_Table | The name of the target table | | Table_ID | The ID of the target table | @@ -44,7 +44,7 @@ The output fields of the `SHOW IMPORT JOB` statement are described as follows: | Start_Time | The time when the task is started | | End_Time | The time when the task is ended | | Created_By | The name of the database user who creates the task | -| Last_Update_Time | The time when the task is last updated | +| Last_Update_Time | The time when the job was last updated | | 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 | From caac9a6be567af672e12f098738db3303b6e1887 Mon Sep 17 00:00:00 2001 From: Ruihao Chen Date: Tue, 26 May 2026 10:09:20 +0800 Subject: [PATCH 11/14] sql-statement-import-into: add GROUP_KEY example in the Example section --- sql-statements/sql-statement-import-into.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-import-into.md b/sql-statements/sql-statement-import-into.md index e98169396fda9..cc23ce6729800 100644 --- a/sql-statements/sql-statement-import-into.md +++ b/sql-statements/sql-statement-import-into.md @@ -141,7 +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. TiDB groups import jobs with the same group key, allowing you to monitor related jobs collectively using [`SHOW IMPORT GROUPS`](/sql-statements/sql-statement-show-import-group.md). 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 does not belong to any group and does not appear in `SHOW IMPORT GROUPS` results. | +| `GROUP_KEY=''` | All file formats | Specifies the group key for the job. TiDB groups import jobs with the same group key, allowing you to monitor related jobs collectively using [`SHOW IMPORT GROUPS`](/sql-statements/sql-statement-show-import-group.md). 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 does not belong to any group and does 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 `"`. | @@ -261,6 +261,14 @@ IMPORT INTO t FROM '/path/to/file.csv' WITH skip_rows=1; IMPORT INTO t FROM '/path/to/file.csv' WITH DETACHED; ``` +#### Assign a group key to the import job + +To group related import jobs so that you can monitor them together using [`SHOW IMPORT GROUPS`](/sql-statements/sql-statement-show-import-group.md), specify the `GROUP_KEY` option: + +```sql +IMPORT INTO t FROM '/path/to/file.csv' WITH GROUP_KEY='user_group'; +``` + #### Skip importing a specific field in your data file Assume that your data file is in the CSV format and its content is as follows: From 54a5a83cf2a8322a2129a20045ec37288a87656d Mon Sep 17 00:00:00 2001 From: Ruihao Chen Date: Tue, 26 May 2026 10:15:09 +0800 Subject: [PATCH 12/14] sql-statement-import-into: clarify GROUP_KEY is optional and does not affect the import --- 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 cc23ce6729800..56ef7d98b5fdf 100644 --- a/sql-statements/sql-statement-import-into.md +++ b/sql-statements/sql-statement-import-into.md @@ -141,7 +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. TiDB groups import jobs with the same group key, allowing you to monitor related jobs collectively using [`SHOW IMPORT GROUPS`](/sql-statements/sql-statement-show-import-group.md). 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 does not belong to any group and does not appear in `SHOW IMPORT GROUPS` results. | +| `GROUP_KEY=''` | All file formats | Specifies an optional group key for the job. The group key does not affect the import itself; TiDB groups import jobs with the same group key so that you can monitor related jobs collectively using [`SHOW IMPORT GROUPS`](/sql-statements/sql-statement-show-import-group.md). 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 does not belong to any group and does 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 `"`. | From afa772d691d45a2ddc5d78f7bfddcc8f37a7fdb7 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Thu, 4 Jun 2026 10:23:06 +0800 Subject: [PATCH 13/14] editorial changes Co-Authored-By: Grace Cai --- sql-statements/sql-statement-import-into.md | 4 ++-- sql-statements/sql-statement-show-import-job.md | 17 +++++++++++------ 2 files changed, 13 insertions(+), 8 deletions(-) diff --git a/sql-statements/sql-statement-import-into.md b/sql-statements/sql-statement-import-into.md index 56ef7d98b5fdf..3d5ce6295e94b 100644 --- a/sql-statements/sql-statement-import-into.md +++ b/sql-statements/sql-statement-import-into.md @@ -141,7 +141,7 @@ The supported options are described as follows: | Option name | Supported data sources and formats | Description | |:---|:---|:---| -| `GROUP_KEY=''` | All file formats | Specifies an optional group key for the job. The group key does not affect the import itself; TiDB groups import jobs with the same group key so that you can monitor related jobs collectively using [`SHOW IMPORT GROUPS`](/sql-statements/sql-statement-show-import-group.md). 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 does not belong to any group and does not appear in `SHOW IMPORT GROUPS` results. | +| `GROUP_KEY=''` | All file formats | Specifies an optional group key for the job. The group key does not affect the import process itself. It enables you to monitor import jobs with the same group key collectively using [`SHOW IMPORT GROUPS`](/sql-statements/sql-statement-show-import-group.md). The group key can contain only alphanumeric characters, underscores (`_`), and hyphens (`-`), up to 256 characters. If no group key is specified, the job does not belong to any group and does 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 `"`. | @@ -263,7 +263,7 @@ IMPORT INTO t FROM '/path/to/file.csv' WITH DETACHED; #### Assign a group key to the import job -To group related import jobs so that you can monitor them together using [`SHOW IMPORT GROUPS`](/sql-statements/sql-statement-show-import-group.md), specify the `GROUP_KEY` option: +To monitor related import jobs collectively using [`SHOW IMPORT GROUPS`](/sql-statements/sql-statement-show-import-group.md), assign them the same group key with the `GROUP_KEY` option: ```sql IMPORT INTO t FROM '/path/to/file.csv' WITH GROUP_KEY='user_group'; diff --git a/sql-statements/sql-statement-show-import-job.md b/sql-statements/sql-statement-show-import-job.md index 60da0b01ec5dd..5e6b1cfa238d9 100644 --- a/sql-statements/sql-statement-show-import-job.md +++ b/sql-statements/sql-statement-show-import-job.md @@ -5,11 +5,16 @@ summary: An overview of the usage of SHOW IMPORT JOB in TiDB. # SHOW IMPORT JOB -The `SHOW IMPORT JOB` statement is used to show `IMPORT` jobs created in TiDB. By default, `SHOW IMPORT JOBS` shows jobs created by the current user. To view all import jobs, you need the `SUPER` privilege. +The `SHOW IMPORT JOB` statement is used to show `IMPORT` jobs created in TiDB. + +It supports the following two forms: + +- `SHOW IMPORT JOBS` +- `SHOW IMPORT JOB ` ## Required privileges -- `SHOW IMPORT JOBS`: if a user has the `SUPER` privilege, this statement shows all import jobs in TiDB. Otherwise, this statement only shows jobs created by the current user. +- `SHOW IMPORT JOBS`: by default, this statement only shows jobs created by the current user. To view all import jobs, you need the `SUPER` privilege. - `SHOW IMPORT JOB `: only the creator of an import job or users with the `SUPER` privilege can use this statement to view a specific job. ## Synopsis @@ -30,8 +35,8 @@ The output fields of the `SHOW IMPORT JOB` statement are described as follows: | Column | Description | |------------------|-------------------------| -| Job_ID | The ID of the job | -| Group_Key | The group key of the job | +| Job_ID | The ID of the job | +| Group_Key | The group key of the job | | Data_Source | Information about the data source | | Target_Table | The name of the target table | | Table_ID | The ID of the target table | @@ -44,7 +49,7 @@ The output fields of the `SHOW IMPORT JOB` statement are described as follows: | Start_Time | The time when the task is started | | End_Time | The time when the task is ended | | Created_By | The name of the database user who creates the task | -| Last_Update_Time | The time when the job was last updated | +| Last_Update_Time | The time when the job was last updated | | 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 | @@ -52,7 +57,7 @@ The output fields of the `SHOW IMPORT JOB` statement are described as follows: | Cur_Step_Speed | The current data processing speed | | Cur_Step_ETA | The estimated time remaining for the current step to complete | -## Filtering import jobs +## Filter import jobs Only `SHOW IMPORT JOBS` supports filtering import jobs with a `WHERE` or `LIKE` clause. `SHOW IMPORT JOB ` does not support these clauses. From e7dc9fe651c966fa092345c8172e78979992a4fa Mon Sep 17 00:00:00 2001 From: qiancai Date: Thu, 4 Jun 2026 11:07:01 +0800 Subject: [PATCH 14/14] Update sql-statement-show-import-group.md Co-Authored-By: Grace Cai --- sql-statements/sql-statement-show-import-group.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/sql-statements/sql-statement-show-import-group.md b/sql-statements/sql-statement-show-import-group.md index f8d4834f6b853..9a1a320b016c9 100644 --- a/sql-statements/sql-statement-show-import-group.md +++ b/sql-statements/sql-statement-show-import-group.md @@ -5,11 +5,18 @@ summary: An overview of the usage of SHOW IMPORT GROUP in TiDB. # SHOW IMPORT GROUP -The `SHOW IMPORT GROUP` statement is used to show the groups of `IMPORT` jobs created in TiDB. By default, `SHOW IMPORT GROUPS` shows groups created by the current user. To view all import groups, you need the `SUPER` privilege. +The `SHOW IMPORT GROUP` statement is used to show the groups of `IMPORT` jobs created in TiDB. + +It supports the following two forms: + +- `SHOW IMPORT GROUPS` +- `SHOW IMPORT GROUP ` + +In `SHOW IMPORT GROUP `, `` is the key specified in the `GROUP_KEY` option when creating an import job. For more information, see [`IMPORT INTO`](/sql-statements/sql-statement-import-into.md). ## 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 GROUPS`: by default, this statement only shows groups created by the current user. To view all import groups, you need the `SUPER` privilege. - `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 @@ -33,7 +40,7 @@ The output fields of the `SHOW IMPORT GROUP` statement are described as follows: | 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 creation time of the jobs in this group | +| First_Job_Create_Time | The earliest creation time of the jobs in this group | | Last_Job_Update_Time | The latest update time of the jobs in this group | ## Example