Skip to content

IMPORT INTO: update document for SHOW IMPORT #21610

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
joechenrh wants to merge 12 commits into
base: master
Choose a base branch
from
Open

IMPORT INTO: update document for SHOW IMPORT #21610

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
e781ad2
update document
joechenrh Aug 15, 2025
978c792
docs: update SHOW IMPORT syntax
joechenrh May 22, 2026
1c4cbd1
docs: refine SHOW IMPORT examples
joechenrh May 22, 2026
9248b55
docs: rename import group example
joechenrh May 22, 2026
af8657a
docs: clarify SHOW IMPORT JOBS filters
joechenrh May 22, 2026
9970993
docs: restore SHOW IMPORT JOB examples
joechenrh May 22, 2026
e3d312e
docs: address import review wording
joechenrh May 22, 2026
8ac1977
docs: remove unfinished SHOW RAW IMPORT syntax
joechenrh May 22, 2026
2188a5b
docs: clarify LIKE filtering in SHOW IMPORT JOBS
joechenrh May 25, 2026
074cbb1
Apply suggestions from code review
joechenrh May 26, 2026
caac9a6
sql-statement-import-into: add GROUP_KEY example in the Example section
joechenrh May 26, 2026
54a5a83
sql-statement-import-into: clarify GROUP_KEY is optional and does not…
joechenrh May 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions TOC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion privilege-management.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 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.

Expand Down
3 changes: 2 additions & 1 deletion sql-statements/sql-statement-cancel-import-job.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
14 changes: 13 additions & 1 deletion sql-statements/sql-statement-import-into.md
View file
Open in desktop
Copy link
Copy Markdown
Collaborator

@qiancai qiancai May 25, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because there is a dedicated doc for SHOW IMPORT GROUPS, adding a simple example of this new GROUP_KEY option in the Example section of this doc would be more friendly to our users.

image

For example:

Import a CSV file with a specific group key

IMPORT INTO mytable
FROM 's3://bucket/data.csv'
WITH GROUP_KEY='user_group';

Copy link
Copy Markdown
Contributor Author

@joechenrh joechenrh May 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good idea, done in joechenrh@caac9a6 .

Added an Assign a group key to the import job example under the IMPORT INTO ... FROM FILE Examples section, with a link over to SHOW IMPORT GROUPS so users can jump to the dedicated doc for monitoring grouped jobs. 👍

Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,7 @@ The supported options are described as follows:

| Option name | Supported data sources and formats | Description |
|:---|:---|:---|
| `GROUP_KEY='<string>'` | 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='<string>'` | 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='<string>'` | CSV | Specifies the field separator. The default separator is `,`. |
| `FIELDS_ENCLOSED_BY='<char>'` | CSV | Specifies the field delimiter. The default delimiter is `"`. |
Expand Down Expand Up @@ -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.

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 <job-id>`](/sql-statements/sql-statement-cancel-import-job.md).

Expand All @@ -258,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:
Expand Down Expand Up @@ -363,4 +374,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)
1 change: 1 addition & 0 deletions sql-statements/sql-statement-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
77 changes: 77 additions & 0 deletions sql-statements/sql-statement-show-import-group.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
---
title: SHOW IMPORT GROUP
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.

## 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 <group-key>`: 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 GROUP` 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 creation 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 |
+--------------+------------+---------+---------+-----------+--------+-----------+----------------------------+----------------------------+
| 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 |
+--------------+------------+---------+---------+-----------+--------+-----------+----------------------------+----------------------------+
2 rows in set (0.01 sec)
```

```sql
SHOW IMPORT GROUP "import_group_1";
```

```
+--------------+------------+---------+---------+-----------+--------+-----------+----------------------------+----------------------------+
| Group_Key | Total_Jobs | Pending | Running | Completed | Failed | Cancelled | First_Job_Create_Time | Last_Job_Update_Time |
+--------------+------------+---------+---------+-----------+--------+-----------+----------------------------+----------------------------+
| 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)
```

## MySQL compatibility

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)
67 changes: 43 additions & 24 deletions sql-statements/sql-statement-show-import-job.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
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 `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

Expand All @@ -16,19 +16,25 @@

```ebnf+diagram
ShowImportJobsStmt ::=
'SHOW' 'IMPORT' 'JOBS'
'SHOW' 'IMPORT' 'JOBS' ShowLikeOrWhereOpt?

ShowImportJobStmt ::=
'SHOW' 'IMPORT' 'JOB' JobID

ShowLikeOrWhereOpt ::=
'LIKE' SimpleExpr
Comment thread
D3Hunter marked this conversation as resolved.
| '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 |
| 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 |
| 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 |
Expand All @@ -38,34 +44,46 @@
| 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 |
| 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 |

## Filtering import jobs

Only `SHOW IMPORT JOBS` supports filtering import jobs with a `WHERE` or `LIKE` clause. `SHOW IMPORT JOB <job-id>` 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:

```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 |
+--------+-------------------+--------------+----------+-------+----------+------------------+---------------+----------------+----------------------------+----------------------------+----------------------------+------------+
| 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)
```
Show a specific import job by job ID:

```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)
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 |
Copy link
Copy Markdown
Contributor

@D3Hunter D3Hunter May 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

classic kernel still the old way, we need to keep the old way, and put those new ones somewhere else for Premium
SHOW IMPORT GROUPS too

Copy link
Copy Markdown
Contributor Author

@joechenrh joechenrh May 25, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Classic kernel actually uses this same output format. There's no classic-vs-nextgen branching for SHOW IMPORT JOB(S) or SHOW IMPORT GROUP(S): the column schema is shared and used unconditionally, FillOneImportJobInfo fills the same columns, and neither fetchShowImportGroups nor the GROUP_KEY option is kernel-gated. These columns were added for all kernels back in pingcap/tidb#62283. On classic, Group_Key simply shows NULL when no group key was set.

Copy link
Copy Markdown
Contributor

@D3Hunter D3Hunter May 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I mean it's not in latest 8.5 release. but this PR is for master, it should be fine

|--------|-----------|-------------|--------------|----------|-------|--------|------------------|---------------|----------------|-------------|------------|----------|------------|------------------|----------|-------------------------|---------------------|-----------------------|----------------|--------------|
| 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 |

Check failure on line 81 in sql-statements/sql-statement-show-import-job.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[PingCAP.Units] Put a nonbreaking space between the number and the unit in '96MB'.

Raw Output:
{"message": "[PingCAP.Units] Put a nonbreaking space between the number and the unit in '96MB'.", "location": {"path": "sql-statements/sql-statement-show-import-job.md", "range": {"start": {"line": 81, "column": 239}}}, "severity": "ERROR"}

Check failure on line 81 in sql-statements/sql-statement-show-import-job.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[PingCAP.Units] Put a nonbreaking space between the number and the unit in '298GB'.

Raw Output:
{"message": "[PingCAP.Units] Put a nonbreaking space between the number and the unit in '298GB'.", "location": {"path": "sql-statements/sql-statement-show-import-job.md", "range": {"start": {"line": 81, "column": 224}}}, "severity": "ERROR"}

Check failure on line 81 in sql-statements/sql-statement-show-import-job.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[PingCAP.Units] Put a nonbreaking space between the number and the unit in '55GB'.

Raw Output:
{"message": "[PingCAP.Units] Put a nonbreaking space between the number and the unit in '55GB'.", "location": {"path": "sql-statements/sql-statement-show-import-job.md", "range": {"start": {"line": 81, "column": 217}}}, "severity": "ERROR"}

Check failure on line 81 in sql-statements/sql-statement-show-import-job.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[PingCAP.Units] Put a nonbreaking space between the number and the unit in '5GiB'.

Raw Output:
{"message": "[PingCAP.Units] Put a nonbreaking space between the number and the unit in '5GiB'.", "location": {"path": "sql-statements/sql-statement-show-import-job.md", "range": {"start": {"line": 81, "column": 96}}}, "severity": "ERROR"}

Filter import jobs by output fields:

```sql
SHOW IMPORT JOBS WHERE Group_Key = 'user_group';
```

## MySQL compatibility
Expand All @@ -75,4 +93,5 @@
## 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)
Loading