Skip to content

Commit b352434

Browse files
qiancaiqiancai
authored
editorial changes
Co-authored-by: Grace Cai <qqzczy@126.com>
1 parent 54a5a83 commit b352434

2 files changed

Lines changed: 106 additions & 96 deletions

File tree

‎sql-statements/sql-statement-import-into.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,7 @@ The supported options are described as follows:
141141

142142
| Option name | Supported data sources and formats | Description |
143143
|:---|:---|:---|
144-
| `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. |
144+
| `GROUP_KEY='<string>'` | 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. |
145145
| `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`. |
146146
| `FIELDS_TERMINATED_BY='<string>'` | CSV | Specifies the field separator. The default separator is `,`. |
147147
| `FIELDS_ENCLOSED_BY='<char>'` | CSV | Specifies the field delimiter. The default delimiter is `"`. |
@@ -263,7 +263,7 @@ IMPORT INTO t FROM '/path/to/file.csv' WITH DETACHED;
263263

264264
#### Assign a group key to the import job
265265

266-
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:
266+
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:
267267

268268
```sql
269269
IMPORT INTO t FROM '/path/to/file.csv' WITH GROUP_KEY='user_group';

‎sql-statements/sql-statement-show-import-job.md‎

Lines changed: 104 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -1,97 +1,107 @@
1-
---
2-
title: SHOW IMPORT JOB
3-
summary: An overview of the usage of SHOW IMPORT JOB in TiDB.
4-
---
5-
6-
# SHOW IMPORT JOB
7-
8-
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.
9-
10-
## Required privileges
11-
12-
- `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.
13-
- `SHOW IMPORT JOB <job-id>`: only the creator of an import job or users with the `SUPER` privilege can use this statement to view a specific job.
14-
15-
## Synopsis
16-
17-
```ebnf+diagram
18-
ShowImportJobsStmt ::=
19-
'SHOW' 'IMPORT' 'JOBS' ShowLikeOrWhereOpt?
20-
21-
ShowImportJobStmt ::=
22-
'SHOW' 'IMPORT' 'JOB' JobID
23-
24-
ShowLikeOrWhereOpt ::=
25-
'LIKE' SimpleExpr
26-
| 'WHERE' Expression
27-
```
28-
29-
The output fields of the `SHOW IMPORT JOB` statement are described as follows:
30-
31-
| Column | Description |
32-
|------------------|-------------------------|
1+
---
2+
title: SHOW IMPORT JOB
3+
summary: An overview of the usage of SHOW IMPORT JOB in TiDB.
4+
---
5+
6+
# SHOW IMPORT JOB
7+
8+
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.
9+
10+
## Required privileges
11+
12+
- `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.
13+
The `SHOW IMPORT JOB` statement is used to show `IMPORT` jobs created in TiDB.
14+
15+
It supports the following two forms:
16+
17+
- `SHOW IMPORT JOBS`
18+
- `SHOW IMPORT JOB <job-id>`
19+
20+
## Required privileges
21+
22+
- `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.
23+
- `SHOW IMPORT JOB <job-id>`: only the creator of an import job or users with the `SUPER` privilege can use this statement to view a specific job.
24+
25+
## Synopsis
26+
27+
```ebnf+diagram
28+
ShowImportJobsStmt ::=
29+
'SHOW' 'IMPORT' 'JOBS' ShowLikeOrWhereOpt?
30+
31+
ShowImportJobStmt ::=
32+
'SHOW' 'IMPORT' 'JOB' JobID
33+
34+
ShowLikeOrWhereOpt ::=
35+
'LIKE' SimpleExpr
36+
| 'WHERE' Expression
37+
```
38+
39+
The output fields of the `SHOW IMPORT JOB` statement are described as follows:
40+
41+
| Column | Description |
42+
|------------------|-------------------------|
3343
| Job_ID | The ID of the job |
3444
| Group_Key | The group key of the job |
35-
| Data_Source | Information about the data source |
36-
| Target_Table | The name of the target table |
37-
| Table_ID | The ID of the target table |
38-
| Phase | The current phase of the job, including `importing`, `validating`, and `add-index` |
39-
| Status | The current status of the job, including `pending` (means created but not started yet), `running`, `canceled`, `failed`, and `finished` |
40-
| Source_File_Size | The size of the source file |
41-
| Imported_Rows | The number of data rows that have been read and written to the target table |
42-
| Result_Message | If the import fails, this field returns the error message. Otherwise, it is empty.|
43-
| Create_Time | The time when the task is created |
44-
| Start_Time | The time when the task is started |
45-
| End_Time | The time when the task is ended |
46-
| Created_By | The name of the database user who creates the task |
45+
| Data_Source | Information about the data source |
46+
| Target_Table | The name of the target table |
47+
| Table_ID | The ID of the target table |
48+
| Phase | The current phase of the job, including `importing`, `validating`, and `add-index` |
49+
| Status | The current status of the job, including `pending` (means created but not started yet), `running`, `canceled`, `failed`, and `finished` |
50+
| Source_File_Size | The size of the source file |
51+
| Imported_Rows | The number of data rows that have been read and written to the target table |
52+
| Result_Message | If the import fails, this field returns the error message. Otherwise, it is empty.|
53+
| Create_Time | The time when the task is created |
54+
| Start_Time | The time when the task is started |
55+
| End_Time | The time when the task is ended |
56+
| Created_By | The name of the database user who creates the task |
4757
| Last_Update_Time | The time when the job was last updated |
48-
| Cur_Step | The specific sequential processing step of this job |
49-
| Cur_Step_Processed_Size | The amount of data that has been processed within the current step |
50-
| Cur_Step_Total_Size | The total size of the data to be processed in the current step |
51-
| Cur_Step_Progress_Pct | The estimated completion percentage of the current step |
52-
| Cur_Step_Speed | The current data processing speed |
53-
| Cur_Step_ETA | The estimated time remaining for the current step to complete |
54-
55-
## Filtering import jobs
56-
57-
Only `SHOW IMPORT JOBS` supports filtering import jobs with a `WHERE` or `LIKE` clause. `SHOW IMPORT JOB <job-id>` does not support these clauses.
58-
59-
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`.
60-
61-
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`.
62-
63-
## Example
64-
65-
Show all import jobs that the current user can view:
66-
67-
```sql
68-
SHOW IMPORT JOBS;
69-
```
70-
71-
Show a specific import job by job ID:
72-
73-
```sql
74-
SHOW IMPORT JOB 2;
75-
```
76-
77-
The output is as follows:
78-
79-
| 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 |
80-
|--------|-----------|-------------|--------------|----------|-------|--------|------------------|---------------|----------------|-------------|------------|----------|------------|------------------|----------|-------------------------|---------------------|-----------------------|----------------|--------------|
81-
| 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 |
82-
83-
Filter import jobs by output fields:
84-
85-
```sql
86-
SHOW IMPORT JOBS WHERE Group_Key = 'user_group';
87-
```
88-
89-
## MySQL compatibility
90-
91-
This statement is a TiDB extension to MySQL syntax.
92-
93-
## See also
94-
95-
* [`IMPORT INTO`](/sql-statements/sql-statement-import-into.md)
96-
* [`SHOW IMPORT GROUP`](/sql-statements/sql-statement-show-import-group.md)
97-
* [`CANCEL IMPORT JOB`](/sql-statements/sql-statement-cancel-import-job.md)
58+
| Cur_Step | The specific sequential processing step of this job |
59+
| Cur_Step_Processed_Size | The amount of data that has been processed within the current step |
60+
| Cur_Step_Total_Size | The total size of the data to be processed in the current step |
61+
| Cur_Step_Progress_Pct | The estimated completion percentage of the current step |
62+
| Cur_Step_Speed | The current data processing speed |
63+
| Cur_Step_ETA | The estimated time remaining for the current step to complete |
64+
65+
## Filter import jobs
66+
67+
Only `SHOW IMPORT JOBS` supports filtering import jobs with a `WHERE` or `LIKE` clause. `SHOW IMPORT JOB <job-id>` does not support these clauses.
68+
69+
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`.
70+
71+
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`.
72+
73+
## Example
74+
75+
Show all import jobs that the current user can view:
76+
77+
```sql
78+
SHOW IMPORT JOBS;
79+
```
80+
81+
Show a specific import job by job ID:
82+
83+
```sql
84+
SHOW IMPORT JOB 2;
85+
```
86+
87+
The output is as follows:
88+
89+
| 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 |
90+
|--------|-----------|-------------|--------------|----------|-------|--------|------------------|---------------|----------------|-------------|------------|----------|------------|------------------|----------|-------------------------|---------------------|-----------------------|----------------|--------------|
91+
| 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 |
92+
93+
Filter import jobs by output fields:
94+
95+
```sql
96+
SHOW IMPORT JOBS WHERE Group_Key = 'user_group';
97+
```
98+
99+
## MySQL compatibility
100+
101+
This statement is a TiDB extension to MySQL syntax.
102+
103+
## See also
104+
105+
* [`IMPORT INTO`](/sql-statements/sql-statement-import-into.md)
106+
* [`SHOW IMPORT GROUP`](/sql-statements/sql-statement-show-import-group.md)
107+
* [`CANCEL IMPORT JOB`](/sql-statements/sql-statement-cancel-import-job.md)

0 commit comments

Comments
 (0)