From 8121e1c9eae9e2dbe6e14009cae07f31f1607dd3 Mon Sep 17 00:00:00 2001 From: tangenta Date: Fri, 22 Nov 2024 15:43:11 +0800 Subject: [PATCH 01/16] docs: add documentation for ADMIN ALTER DDL JOBS command --- .../sql-statement-admin-alter-ddl.md | 82 +++++++++++++++++++ .../sql-statement-admin-show-ddl.md | 56 +++++++------ 2 files changed, 114 insertions(+), 24 deletions(-) create mode 100644 sql-statements/sql-statement-admin-alter-ddl.md diff --git a/sql-statements/sql-statement-admin-alter-ddl.md b/sql-statements/sql-statement-admin-alter-ddl.md new file mode 100644 index 0000000000000..d77f5e699ea62 --- /dev/null +++ b/sql-statements/sql-statement-admin-alter-ddl.md @@ -0,0 +1,82 @@ +--- +title: ADMIN ALTER DDL JOBS +summary: An overview of the usage of ADMIN ALTER DDL JOBS for the TiDB database. +--- + +# ADMIN ALTER DDL JOBS + +`ADMIN ALTER DDL JOBS` can be used to change the parameter of a running DDL job. For example: + +```sql +ADMIN ALTER DDL JOBS 101 THREAD = 8; +``` + +`101` indicates the ID of the DDL job, which can be obtained by querying [`ADMIN SHOW DDL JOBS`](/sql-statements/sql-statement-admin-show-ddl.md) to obtain it. `THREAD` indicates the concurrency of the DDL job, whose initial value is set by the system variable [`tidb_ddl_reorg_worker_cnt`](/system-variables.md#tidb_ddl_reorg_worker_cnt). + +DDL job types that currently support `ADMIN ALTER DDL JOBS` include `ADD INDEX`, `MODIFY COLUMN`, and `REORGANIZE PARTITION`. For other DDL job types, executing `ADMIN ALTER DDL JOBS` reports an `unsupported DDL operation` error. + +Currently, only the parameters of a single DDL job can be modified in a `ADMIN ALTER DDL JOBS`, not the parameters of multiple IDs at the same time. + +The following are the supported parameters for different DDL jobs and their corresponding system variables: + +- `ADD INDEX`: + - `THREAD`: Concurrency. The initial value is set by `tidb_ddl_reorg_worker_cnt`. + - `BATCH_SIZE`: Batch size. The initial value is set by [`tidb_ddl_reorg_batch_size`](/system-variables.md#tidb_ddl_reorg_batch_size). + - `MAX_WRITE_SPEED`: Maximum bandwidth limit for importing index records into each TiKV. The initial value is set by [`tidb_ddl_reorg_max_write_speed`](/system-variables.md#tidb_ddl_reorg_max_write_speed). + +- `MODIFY COLUMN`: + - `THREAD`: Concurrency. The initial value is set by `tidb_ddl_reorg_worker_cnt`. + - `BATCH_SIZE`: Batch size. The initial value is set by [`tidb_ddl_reorg_batch_size`](/system-variables.md#tidb_ddl_reorg_batch_size). + +- `REORGANIZE PARTITION`: + - `THREAD`: Concurrency. The initial value is set by `tidb_ddl_reorg_worker_cnt`. + - `BATCH_SIZE`: Batch size. The initial value is set by [`tidb_ddl_reorg_batch_size`](/system-variables.md#tidb_ddl_reorg_batch_size). + +The value range of the parameter is consistent with that of the system variable. + +`ADMIN ALTER DDL JOBS` takes effect only for running DDL jobs. If the DDL job does not exist or has ended, execution of this statement results in a `ddl job is not running` error. + +The following are examples of this statement: + +```sql +ADMIN ALTER DDL JOBS 101 THREAD = 8; +ADMIN ALTER DDL JOBS 101 BATCH_SIZE = 256; +ADMIN ALTER DDL JOBS 101 MAX_WRITE_SPEED = '200MiB'; +ADMIN ALTER DDL JOBS 101 THREAD = 8, BATCH_SIZE = 256; +``` + +To view the current parameter values for a particular DDL job, you can execute `ADMIN SHOW DDL JOBS` and the results are displayed in the `COMMENTS` column: + +```sql +mysql> admin show ddl jobs 1; ++--------+---------+------------+-----------+--------------+-----------+----------+-----------+----------------------------+----------------------------+----------------------------+--------+-----------------------+ +| JOB_ID | DB_NAME | TABLE_NAME | JOB_TYPE | SCHEMA_STATE | SCHEMA_ID | TABLE_ID | ROW_COUNT | CREATE_TIME | START_TIME | END_TIME | STATE | COMMENTS | ++--------+---------+------------+-----------+--------------+-----------+----------+-----------+----------------------------+----------------------------+----------------------------+--------+-----------------------+ +| 124 | test | t | add index | public | 2 | 122 | 3 | 2024-11-15 11:17:06.213000 | 2024-11-15 11:17:06.213000 | 2024-11-15 11:17:08.363000 | synced | ingest, DXF, thread=8 | ++--------+---------+------------+-----------+--------------+-----------+----------+-----------+----------------------------+----------------------------+----------------------------+--------+-----------------------+ +1 row in set (0.01 sec) +``` + +## Synopsis + +```ebnf+diagram +AdminPauseDDLStmt ::= + 'ADMIN' 'ALTER' 'DDL' 'JOBS' Int64Num AlterJobOptionList + +AlterJobOptionList ::= + AlterJobOption ( ',' AlterJobOption )* + +AlterJobOption ::= + identifier "=" SignedLiteral +``` + +## MySQL compatibility + +`ADMIN ALTER DDL JOBS` statement is a TiDB extension to MySQL syntax. + +## See also + +* [`ADMIN SHOW DDL [JOBS|QUERIES]`](/sql-statements/sql-statement-admin-show-ddl.md) +* [`ADMIN CANCEL DDL`](/sql-statements/sql-statement-admin-cancel-ddl.md) +* [`ADMIN PAUSE DDL`](/sql-statements/sql-statement-admin-pause-ddl.md) +* [`ADMIN RESUME DDL`](/sql-statements/sql-statement-admin-resume-ddl.md) diff --git a/sql-statements/sql-statement-admin-show-ddl.md b/sql-statements/sql-statement-admin-show-ddl.md index ca63cd5d3b792..92d0db2ffa864 100644 --- a/sql-statements/sql-statement-admin-show-ddl.md +++ b/sql-statements/sql-statement-admin-show-ddl.md @@ -55,7 +55,7 @@ OWNER_ADDRESS: 0.0.0.0:4000 ### `ADMIN SHOW DDL JOBS` -The `ADMIN SHOW DDL JOBS` statement is used to view all the results in the current DDL job queue, including running and queuing tasks, as well as the latest ten results in the completed DDL job queue. The returned result fields are described as follows: +The `ADMIN SHOW DDL JOBS` statement is used to view all the results in the current DDL job queue, including running and queuing tasks, as well as the recent results in the completed DDL job queue. The returned result fields are described as follows: @@ -66,9 +66,7 @@ The `ADMIN SHOW DDL JOBS` statement is used to view all the results in the curre - `create schema`: for [`CREATE SCHEMA`](/sql-statements/sql-statement-create-database.md) operations. - `create table`: for [`CREATE TABLE`](/sql-statements/sql-statement-create-table.md) operations. - `create view`: for [`CREATE VIEW`](/sql-statements/sql-statement-create-view.md) operations. - - `ingest`: ingestion with accelerated index backfilling as configured by [`tidb_ddl_enable_fast_reorg`](/system-variables.md#tidb_ddl_enable_fast_reorg-new-in-v630). - - `txn`: basic transactional backfilling. - - `add index /* txn-merge */`: transactional backfilling with a temporary index that gets merged with the original index when the backfilling is finished. + - `add index`: for [`ADD INDEX`](/sql-statements/sql-statement-add-index.md) operations. - `SCHEMA_STATE`: the current state of the schema object that the DDL operates on. If `JOB_TYPE` is `ADD INDEX`, it is the state of the index; if `JOB_TYPE` is `ADD COLUMN`, it is the state of the column; if `JOB_TYPE` is `CREATE TABLE`, it is the state of the table. Common states include the following: - `none`: indicates that it does not exist. Generally, after the `DROP` operation or after the `CREATE` operation fails and rolls back, it will become the `none` state. - `delete only`, `write only`, `delete reorganization`, `write reorganization`: these four states are intermediate states. For their specific meanings, see [How the Online DDL Asynchronous Change Works in TiDB](/ddl-introduction.md#how-the-online-ddl-asynchronous-change-works-in-tidb). As the intermediate state conversion is fast, these states are generally not visible during operation. Only when performing `ADD INDEX` operation can the `write reorganization` state be seen, indicating that index data is being added. @@ -91,6 +89,15 @@ The `ADMIN SHOW DDL JOBS` statement is used to view all the results in the curre - `pausing`: indicates that the operation is being paused. - `paused`: indicates that the operation has been paused. This state only appears when you use the [`ADMIN PAUSED DDL JOBS`](/sql-statements/sql-statement-admin-pause-ddl.md) command to pause the DDL job. You can use the [`ADMIN RESUME DDL JOBS`](/sql-statements/sql-statement-admin-resume-ddl.md) command to resume the DDL job. - `done`: indicates that the operation has been successfully executed on the TiDB owner node, but other TiDB nodes have not yet synchronized the changes performed by this DDL job. +- `COMMENTS`: contains other information for auxiliary diagnostic purposes. + - `ingest`: ingest task for accelerated adding index backfill configured via [`tidb_ddl_enable_fast_reorg`](/system-variables.md#tidb_ddl_enable_fast_reorg-new-in-v630)。 + - `txn`: basic transactional backfill. + - `txn-merge`: transactional backfilling with a temporary index that gets merged with the original index when the backfilling is finished. + - `DXF`: tasks executed with distributed frameworks configured via [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-new-in-v710). + - `service_scope`: the service scope of the TiDB node configured via [`tidb_service_scope`](/system-variables.md#tidb_service_scope-new-in-v740). + - `thread`: concurrency of backfill tasks. The initial value can be set with `tidb_ddl_reorg_worker_cnt`. It supports dynamic modification via `ADMIN ALTER DDL JOBS`. + - `batch_size`: batch size of backfill tasks. The initial value can be set with `tidb_ddl_reorg_batch_size`. It supports dynamic modification via `ADMIN ALTER DDL JOBS`. + - `max_write_speed`: flow control during ingest task import. The initial value can be set with `tidb_ddl_reorg_max_write_speed`. It supports dynamic modification via `ADMIN ALTER DDL JOBS`. @@ -126,31 +133,32 @@ ADMIN SHOW DDL JOBS; ``` ```sql -mysql> ADMIN SHOW DDL JOBS; -+--------+---------+--------------------+--------------+----------------------+-----------+----------+-----------+-----------------------------------------------------------------+---------+ -| JOB_ID | DB_NAME | TABLE_NAME | JOB_TYPE | SCHEMA_STATE | SCHEMA_ID | TABLE_ID | ROW_COUNT | CREATE_TIME | START_TIME | END_TIME | STATE | -+--------+---------+--------------------+--------------+----------------------+-----------+----------+-----------+---------------------+-------------------------------------------+---------+ -| 59 | test | t1 | add index | write reorganization | 1 | 55 | 88576 | 2020-08-17 07:51:58 | 2020-08-17 07:51:58 | NULL | running | -| 60 | test | t2 | add index | none | 1 | 57 | 0 | 2020-08-17 07:51:59 | 2020-08-17 07:51:59 | NULL | none | -| 58 | test | t2 | create table | public | 1 | 57 | 0 | 2020-08-17 07:41:28 | 2020-08-17 07:41:28 | 2020-08-17 07:41:28 | synced | -| 56 | test | t1 | create table | public | 1 | 55 | 0 | 2020-08-17 07:41:02 | 2020-08-17 07:41:02 | 2020-08-17 07:41:02 | synced | -| 54 | test | t1 | drop table | none | 1 | 50 | 0 | 2020-08-17 07:41:02 | 2020-08-17 07:41:02 | 2020-08-17 07:41:02 | synced | -| 53 | test | t1 | drop index | none | 1 | 50 | 0 | 2020-08-17 07:35:44 | 2020-08-17 07:35:44 | 2020-08-17 07:35:44 | synced | -| 52 | test | t1 | add index | public | 1 | 50 | 451010 | 2020-08-17 07:34:43 | 2020-08-17 07:34:43 | 2020-08-17 07:35:16 | synced | -| 51 | test | t1 | create table | public | 1 | 50 | 0 | 2020-08-17 07:34:02 | 2020-08-17 07:34:02 | 2020-08-17 07:34:02 | synced | -| 49 | test | t1 | drop table | none | 1 | 47 | 0 | 2020-08-17 07:34:02 | 2020-08-17 07:34:02 | 2020-08-17 07:34:02 | synced | -| 48 | test | t1 | create table | public | 1 | 47 | 0 | 2020-08-17 07:33:37 | 2020-08-17 07:33:37 | 2020-08-17 07:33:37 | synced | -| 46 | mysql | stats_extended | create table | public | 3 | 45 | 0 | 2020-08-17 06:42:38 | 2020-08-17 06:42:38 | 2020-08-17 06:42:38 | synced | -| 44 | mysql | opt_rule_blacklist | create table | public | 3 | 43 | 0 | 2020-08-17 06:42:38 | 2020-08-17 06:42:38 | 2020-08-17 06:42:38 | synced | -+--------+---------+--------------------+--------------+----------------------+-----------+----------+-----------+---------------------+---------------------+-------------------------------+ -12 rows in set (0.00 sec) ++--------+---------+------------+---------------------------------+----------------------+-----------+----------+-----------+----------------------------+----------------------------+----------------------------+----------+-------------+ +| JOB_ID | DB_NAME | TABLE_NAME | JOB_TYPE | SCHEMA_STATE | SCHEMA_ID | TABLE_ID | ROW_COUNT | CREATE_TIME | START_TIME | END_TIME | STATE | COMMENTS | ++--------+---------+------------+---------------------------------+----------------------+-----------+----------+-----------+----------------------------+----------------------------+----------------------------+----------+-------------+ +| 565 | test | sbtest1 | add index | write reorganization | 554 | 556 | 0 | 2024-11-22 12:39:25.475000 | 2024-11-22 12:39:25.524000 | NULL | running | ingest, DXF | +| 566 | test | sbtest1 | add index | none | 554 | 556 | 0 | 2024-11-22 12:39:26.425000 | NULL | NULL | queueing | | +| 564 | test | sbtest1 | alter table multi-schema change | none | 554 | 556 | 0 | 2024-11-22 12:39:02.925000 | 2024-11-22 12:39:02.925000 | 2024-11-22 12:39:03.275000 | synced | | +| 564 | test | sbtest1 | drop index /* subjob */ | none | 554 | 556 | 0 | 2024-11-22 12:39:02.925000 | 2024-11-22 12:39:02.925000 | 2024-11-22 12:39:03.275000 | done | | +| 564 | test | sbtest1 | drop index /* subjob */ | none | 554 | 556 | 0 | 2024-11-22 12:39:02.925000 | 2024-11-22 12:39:02.975000 | 2024-11-22 12:39:03.275000 | done | | +| 563 | test | sbtest1 | modify column | public | 554 | 556 | 0 | 2024-11-22 12:38:35.624000 | 2024-11-22 12:38:35.624000 | 2024-11-22 12:38:35.674000 | synced | | +| 562 | test | sbtest1 | add index | public | 554 | 556 | 1580334 | 2024-11-22 12:36:58.471000 | 2024-11-22 12:37:05.271000 | 2024-11-22 12:37:13.374000 | synced | ingest, DXF | +| 561 | test | sbtest1 | add index | public | 554 | 556 | 1580334 | 2024-11-22 12:36:57.771000 | 2024-11-22 12:36:57.771000 | 2024-11-22 12:37:04.671000 | synced | ingest, DXF | +| 560 | test | sbtest1 | add index | public | 554 | 556 | 1580334 | 2024-11-22 12:34:53.314000 | 2024-11-22 12:34:53.314000 | 2024-11-22 12:34:57.114000 | synced | ingest | +| 559 | test | sbtest1 | drop index | none | 554 | 556 | 0 | 2024-11-22 12:34:43.565000 | 2024-11-22 12:34:43.565000 | 2024-11-22 12:34:43.764000 | synced | | +| 558 | test | sbtest1 | add index | public | 554 | 556 | 1580334 | 2024-11-22 12:34:06.215000 | 2024-11-22 12:34:06.215000 | 2024-11-22 12:34:14.314000 | synced | ingest, DXF | +| 557 | test | sbtest1 | create table | public | 554 | 556 | 0 | 2024-11-22 12:32:09.515000 | 2024-11-22 12:32:09.915000 | 2024-11-22 12:32:10.015000 | synced | | +| 555 | test | | create schema | public | 554 | 0 | 0 | 2024-11-22 12:31:51.215000 | 2024-11-22 12:31:51.264000 | 2024-11-22 12:31:51.264000 | synced | | +| 553 | test | | drop schema | none | 2 | 0 | 0 | 2024-11-22 12:31:48.615000 | 2024-11-22 12:31:48.615000 | 2024-11-22 12:31:48.865000 | synced | | ++--------+---------+------------+---------------------------------+----------------------+-----------+----------+-----------+----------------------------+----------------------------+----------------------------+----------+-------------+ +14 rows in set (0.00 sec) ``` From the output above: -- Job 59 is currently in progress (`STATE` of `running`). The schema state is currently in `write reorganization`, but will switch to `public` once the task is completed to note that the change can be observed publicly by user sessions. The `end_time` column is also `NULL` indicating that the completion time for the job is currently not known. +- Job 565 is currently in progress (`STATE` of `running`). The schema state is currently in `write reorganization`, but will switch to `public` once the task is completed to note that the change can be observed publicly by user sessions. The `end_time` column is also `NULL` indicating that the completion time for the job is currently not known. -- Job 60 is an `add index` job, which is currently queued waiting for job 59 to complete. When job 59 completes, the `STATE` of job 60 will switch to `running`. +- Job 566 is an `add index` job, which is currently queued waiting for job 565 to complete. When job 565 completes, the `STATE` of job 60 will switch to `running`. - For destructive changes such as dropping an index or dropping a table, the `SCHEMA_STATE` will change to `none` when the job is complete. For additive changes, the `SCHEMA_STATE` will change to `public`. From a904fb6b20f1ac3a45134dc118eb44fb9c8d4d8e Mon Sep 17 00:00:00 2001 From: houfaxin Date: Fri, 22 Nov 2024 18:01:10 +0800 Subject: [PATCH 02/16] Update TOC.md --- TOC.md | 1 + 1 file changed, 1 insertion(+) diff --git a/TOC.md b/TOC.md index 438109b424bba..3e707f8f25fe6 100644 --- a/TOC.md +++ b/TOC.md @@ -730,6 +730,7 @@ - SQL Statements - [Overview](/sql-statements/sql-statement-overview.md) - [`ADMIN`](/sql-statements/sql-statement-admin.md) + - [`ADMIN ALTER DDL JOBS`](sql-statements/sql-statement-admin-alter-ddl.md) - [`ADMIN CANCEL DDL`](/sql-statements/sql-statement-admin-cancel-ddl.md) - [`ADMIN CHECKSUM TABLE`](/sql-statements/sql-statement-admin-checksum-table.md) - [`ADMIN CHECK [TABLE|INDEX]`](/sql-statements/sql-statement-admin-check-table-index.md) From 57e43c55952cb37c9b1f9becdfd8772027d0c7e9 Mon Sep 17 00:00:00 2001 From: houfaxin Date: Mon, 25 Nov 2024 10:38:32 +0800 Subject: [PATCH 03/16] Update sql-statement-admin-alter-ddl.md --- .../sql-statement-admin-alter-ddl.md | 25 ++++++++++--------- 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/sql-statements/sql-statement-admin-alter-ddl.md b/sql-statements/sql-statement-admin-alter-ddl.md index d77f5e699ea62..cb94e1350112d 100644 --- a/sql-statements/sql-statement-admin-alter-ddl.md +++ b/sql-statements/sql-statement-admin-alter-ddl.md @@ -1,6 +1,6 @@ --- title: ADMIN ALTER DDL JOBS -summary: An overview of the usage of ADMIN ALTER DDL JOBS for the TiDB database. +summary: An overview of the usage of `ADMIN ALTER DDL JOBS` for the TiDB database. --- # ADMIN ALTER DDL JOBS @@ -11,26 +11,27 @@ summary: An overview of the usage of ADMIN ALTER DDL JOBS for the TiDB database. ADMIN ALTER DDL JOBS 101 THREAD = 8; ``` -`101` indicates the ID of the DDL job, which can be obtained by querying [`ADMIN SHOW DDL JOBS`](/sql-statements/sql-statement-admin-show-ddl.md) to obtain it. `THREAD` indicates the concurrency of the DDL job, whose initial value is set by the system variable [`tidb_ddl_reorg_worker_cnt`](/system-variables.md#tidb_ddl_reorg_worker_cnt). +- `101`: indicates the ID of the DDL job. You can obtain the ID by executing [`ADMIN SHOW DDL JOBS`](/sql-statements/sql-statement-admin-show-ddl.md). +- `THREAD`: indicates the concurrency of the DDL job. You can configure the initial value of the thread by the system variable [`tidb_ddl_reorg_worker_cnt`](/system-variables.md#tidb_ddl_reorg_worker_cnt). -DDL job types that currently support `ADMIN ALTER DDL JOBS` include `ADD INDEX`, `MODIFY COLUMN`, and `REORGANIZE PARTITION`. For other DDL job types, executing `ADMIN ALTER DDL JOBS` reports an `unsupported DDL operation` error. +The following DDL job types support `ADMIN ALTER DDL JOBS`: `ADD INDEX`, `MODIFY COLUMN`, and `REORGANIZE PARTITION`. For other DDL job types, executing `ADMIN ALTER DDL JOBS` reports an error `unsupported DDL operation`. -Currently, only the parameters of a single DDL job can be modified in a `ADMIN ALTER DDL JOBS`, not the parameters of multiple IDs at the same time. +Currently, you can only modiy the parameters of a single DDL job by executing `ADMIN ALTER DDL JOBS`. Modifying the parameters of multiple IDs at the same time is not supported. The following are the supported parameters for different DDL jobs and their corresponding system variables: - `ADD INDEX`: - - `THREAD`: Concurrency. The initial value is set by `tidb_ddl_reorg_worker_cnt`. - - `BATCH_SIZE`: Batch size. The initial value is set by [`tidb_ddl_reorg_batch_size`](/system-variables.md#tidb_ddl_reorg_batch_size). - - `MAX_WRITE_SPEED`: Maximum bandwidth limit for importing index records into each TiKV. The initial value is set by [`tidb_ddl_reorg_max_write_speed`](/system-variables.md#tidb_ddl_reorg_max_write_speed). + - `THREAD`: the concurrency of the DDL job. The initial value is set by `tidb_ddl_reorg_worker_cnt`. + - `BATCH_SIZE`: the batch size. The initial value is set by [`tidb_ddl_reorg_batch_size`](/system-variables.md#tidb_ddl_reorg_batch_size). + - `MAX_WRITE_SPEED`: the maximum bandwidth limit for importing index records into each TiKV. The initial value is set by [`tidb_ddl_reorg_max_write_speed`](/system-variables.md#tidb_ddl_reorg_max_write_speed). - `MODIFY COLUMN`: - - `THREAD`: Concurrency. The initial value is set by `tidb_ddl_reorg_worker_cnt`. - - `BATCH_SIZE`: Batch size. The initial value is set by [`tidb_ddl_reorg_batch_size`](/system-variables.md#tidb_ddl_reorg_batch_size). + - `THREAD`: the concurrency of the DDL job. The initial value is set by `tidb_ddl_reorg_worker_cnt`. + - `BATCH_SIZE`: the batch size. The initial value is set by `tidb_ddl_reorg_batch_size`. - `REORGANIZE PARTITION`: - - `THREAD`: Concurrency. The initial value is set by `tidb_ddl_reorg_worker_cnt`. - - `BATCH_SIZE`: Batch size. The initial value is set by [`tidb_ddl_reorg_batch_size`](/system-variables.md#tidb_ddl_reorg_batch_size). + - `THREAD`: the concurrency of the DDL job. The initial value is set by `tidb_ddl_reorg_worker_cnt`. + - `BATCH_SIZE`: the batch size. The initial value is set by `tidb_ddl_reorg_batch_size`. The value range of the parameter is consistent with that of the system variable. @@ -48,7 +49,7 @@ ADMIN ALTER DDL JOBS 101 THREAD = 8, BATCH_SIZE = 256; To view the current parameter values for a particular DDL job, you can execute `ADMIN SHOW DDL JOBS` and the results are displayed in the `COMMENTS` column: ```sql -mysql> admin show ddl jobs 1; +mysql> ADMIN SHOW DDL JOBS 1; +--------+---------+------------+-----------+--------------+-----------+----------+-----------+----------------------------+----------------------------+----------------------------+--------+-----------------------+ | JOB_ID | DB_NAME | TABLE_NAME | JOB_TYPE | SCHEMA_STATE | SCHEMA_ID | TABLE_ID | ROW_COUNT | CREATE_TIME | START_TIME | END_TIME | STATE | COMMENTS | +--------+---------+------------+-----------+--------------+-----------+----------+-----------+----------------------------+----------------------------+----------------------------+--------+-----------------------+ From 93f5c1f93e3d4c4d616ec1e1e275eb5e6736e9e3 Mon Sep 17 00:00:00 2001 From: tangenta Date: Mon, 25 Nov 2024 13:43:47 +0800 Subject: [PATCH 04/16] Update sql-statements/sql-statement-admin-show-ddl.md Co-authored-by: xixirangrang --- sql-statements/sql-statement-admin-show-ddl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-admin-show-ddl.md b/sql-statements/sql-statement-admin-show-ddl.md index 92d0db2ffa864..b906c2bd8092c 100644 --- a/sql-statements/sql-statement-admin-show-ddl.md +++ b/sql-statements/sql-statement-admin-show-ddl.md @@ -158,7 +158,7 @@ From the output above: - Job 565 is currently in progress (`STATE` of `running`). The schema state is currently in `write reorganization`, but will switch to `public` once the task is completed to note that the change can be observed publicly by user sessions. The `end_time` column is also `NULL` indicating that the completion time for the job is currently not known. -- Job 566 is an `add index` job, which is currently queued waiting for job 565 to complete. When job 565 completes, the `STATE` of job 60 will switch to `running`. +- The `STATE` for `job_id` 566 is shown as `queueing`, indicating that it is queuing. When job 565 completes and job 566 begins execution, the `STATE` for job 566 will change to `running`. - For destructive changes such as dropping an index or dropping a table, the `SCHEMA_STATE` will change to `none` when the job is complete. For additive changes, the `SCHEMA_STATE` will change to `public`. From 9fe9caae1b74c8ef2f141e005469160a3c6510d0 Mon Sep 17 00:00:00 2001 From: tangenta Date: Mon, 25 Nov 2024 13:43:54 +0800 Subject: [PATCH 05/16] Update sql-statements/sql-statement-admin-show-ddl.md Co-authored-by: xixirangrang --- sql-statements/sql-statement-admin-show-ddl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-admin-show-ddl.md b/sql-statements/sql-statement-admin-show-ddl.md index b906c2bd8092c..7352634240c1c 100644 --- a/sql-statements/sql-statement-admin-show-ddl.md +++ b/sql-statements/sql-statement-admin-show-ddl.md @@ -95,7 +95,7 @@ The `ADMIN SHOW DDL JOBS` statement is used to view all the results in the curre - `txn-merge`: transactional backfilling with a temporary index that gets merged with the original index when the backfilling is finished. - `DXF`: tasks executed with distributed frameworks configured via [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-new-in-v710). - `service_scope`: the service scope of the TiDB node configured via [`tidb_service_scope`](/system-variables.md#tidb_service_scope-new-in-v740). - - `thread`: concurrency of backfill tasks. The initial value can be set with `tidb_ddl_reorg_worker_cnt`. It supports dynamic modification via `ADMIN ALTER DDL JOBS`. + - `thread`: concurrency of backfill tasks. The initial value can be set with `tidb_ddl_reorg_worker_cnt`. It supports dynamic modification via [`ADMIN ALTER DDL JOBS`](sql-statements/sql-statement-admin-alter-ddl.md). - `batch_size`: batch size of backfill tasks. The initial value can be set with `tidb_ddl_reorg_batch_size`. It supports dynamic modification via `ADMIN ALTER DDL JOBS`. - `max_write_speed`: flow control during ingest task import. The initial value can be set with `tidb_ddl_reorg_max_write_speed`. It supports dynamic modification via `ADMIN ALTER DDL JOBS`. From c3e14a23a5e978e19d13bb1d29441251e14ec40c Mon Sep 17 00:00:00 2001 From: tangenta Date: Mon, 25 Nov 2024 14:12:33 +0800 Subject: [PATCH 06/16] Update sql-statements/sql-statement-admin-alter-ddl.md --- sql-statements/sql-statement-admin-alter-ddl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-admin-alter-ddl.md b/sql-statements/sql-statement-admin-alter-ddl.md index cb94e1350112d..b9bac02a928ec 100644 --- a/sql-statements/sql-statement-admin-alter-ddl.md +++ b/sql-statements/sql-statement-admin-alter-ddl.md @@ -61,7 +61,7 @@ mysql> ADMIN SHOW DDL JOBS 1; ## Synopsis ```ebnf+diagram -AdminPauseDDLStmt ::= +AdminAlterDDLStmt ::= 'ADMIN' 'ALTER' 'DDL' 'JOBS' Int64Num AlterJobOptionList AlterJobOptionList ::= From 18e0cb8d2a92246a2aa4cf03c709c4d7e01b62bd Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Thu, 28 Nov 2024 21:59:11 +0800 Subject: [PATCH 07/16] Apply suggestions from code review --- TOC.md | 2 +- sql-statements/sql-statement-admin-show-ddl.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/TOC.md b/TOC.md index 3e707f8f25fe6..976ee4b5b1ed8 100644 --- a/TOC.md +++ b/TOC.md @@ -730,7 +730,7 @@ - SQL Statements - [Overview](/sql-statements/sql-statement-overview.md) - [`ADMIN`](/sql-statements/sql-statement-admin.md) - - [`ADMIN ALTER DDL JOBS`](sql-statements/sql-statement-admin-alter-ddl.md) + - [`ADMIN ALTER DDL JOBS`](/sql-statements/sql-statement-admin-alter-ddl.md) - [`ADMIN CANCEL DDL`](/sql-statements/sql-statement-admin-cancel-ddl.md) - [`ADMIN CHECKSUM TABLE`](/sql-statements/sql-statement-admin-checksum-table.md) - [`ADMIN CHECK [TABLE|INDEX]`](/sql-statements/sql-statement-admin-check-table-index.md) diff --git a/sql-statements/sql-statement-admin-show-ddl.md b/sql-statements/sql-statement-admin-show-ddl.md index 7352634240c1c..04873218d26fc 100644 --- a/sql-statements/sql-statement-admin-show-ddl.md +++ b/sql-statements/sql-statement-admin-show-ddl.md @@ -95,7 +95,7 @@ The `ADMIN SHOW DDL JOBS` statement is used to view all the results in the curre - `txn-merge`: transactional backfilling with a temporary index that gets merged with the original index when the backfilling is finished. - `DXF`: tasks executed with distributed frameworks configured via [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-new-in-v710). - `service_scope`: the service scope of the TiDB node configured via [`tidb_service_scope`](/system-variables.md#tidb_service_scope-new-in-v740). - - `thread`: concurrency of backfill tasks. The initial value can be set with `tidb_ddl_reorg_worker_cnt`. It supports dynamic modification via [`ADMIN ALTER DDL JOBS`](sql-statements/sql-statement-admin-alter-ddl.md). + - `thread`: concurrency of backfill tasks. The initial value can be set with `tidb_ddl_reorg_worker_cnt`. It supports dynamic modification via [`ADMIN ALTER DDL JOBS`](/sql-statements/sql-statement-admin-alter-ddl.md). - `batch_size`: batch size of backfill tasks. The initial value can be set with `tidb_ddl_reorg_batch_size`. It supports dynamic modification via `ADMIN ALTER DDL JOBS`. - `max_write_speed`: flow control during ingest task import. The initial value can be set with `tidb_ddl_reorg_max_write_speed`. It supports dynamic modification via `ADMIN ALTER DDL JOBS`. From 40167027d9ba62746f62f453af5f80d70a5388e9 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Thu, 28 Nov 2024 22:05:08 +0800 Subject: [PATCH 08/16] Update sql-statements/sql-statement-admin-alter-ddl.md --- sql-statements/sql-statement-admin-alter-ddl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-admin-alter-ddl.md b/sql-statements/sql-statement-admin-alter-ddl.md index b9bac02a928ec..16b8b236b9491 100644 --- a/sql-statements/sql-statement-admin-alter-ddl.md +++ b/sql-statements/sql-statement-admin-alter-ddl.md @@ -23,7 +23,7 @@ The following are the supported parameters for different DDL jobs and their corr - `ADD INDEX`: - `THREAD`: the concurrency of the DDL job. The initial value is set by `tidb_ddl_reorg_worker_cnt`. - `BATCH_SIZE`: the batch size. The initial value is set by [`tidb_ddl_reorg_batch_size`](/system-variables.md#tidb_ddl_reorg_batch_size). - - `MAX_WRITE_SPEED`: the maximum bandwidth limit for importing index records into each TiKV. The initial value is set by [`tidb_ddl_reorg_max_write_speed`](/system-variables.md#tidb_ddl_reorg_max_write_speed). + - `MAX_WRITE_SPEED`: the maximum bandwidth limit for importing index records into each TiKV. The initial value is set by [`tidb_ddl_reorg_max_write_speed`](/system-variables.md#tidb_ddl_reorg_max_write_speed-new-in-v850). - `MODIFY COLUMN`: - `THREAD`: the concurrency of the DDL job. The initial value is set by `tidb_ddl_reorg_worker_cnt`. From 0ee58fd3509ece6ccb07958a5face277f80e4a1e Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Fri, 29 Nov 2024 10:22:33 +0800 Subject: [PATCH 09/16] Apply suggestions from code review --- sql-statements/sql-statement-admin-alter-ddl.md | 2 +- sql-statements/sql-statement-admin-show-ddl.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/sql-statements/sql-statement-admin-alter-ddl.md b/sql-statements/sql-statement-admin-alter-ddl.md index 16b8b236b9491..ec15e2006dead 100644 --- a/sql-statements/sql-statement-admin-alter-ddl.md +++ b/sql-statements/sql-statement-admin-alter-ddl.md @@ -46,7 +46,7 @@ ADMIN ALTER DDL JOBS 101 MAX_WRITE_SPEED = '200MiB'; ADMIN ALTER DDL JOBS 101 THREAD = 8, BATCH_SIZE = 256; ``` -To view the current parameter values for a particular DDL job, you can execute `ADMIN SHOW DDL JOBS` and the results are displayed in the `COMMENTS` column: +To view the current parameter values for a specific DDL job, you can execute `ADMIN SHOW DDL JOBS` and the results are displayed in the `COMMENTS` column: ```sql mysql> ADMIN SHOW DDL JOBS 1; diff --git a/sql-statements/sql-statement-admin-show-ddl.md b/sql-statements/sql-statement-admin-show-ddl.md index 04873218d26fc..f541ebd360475 100644 --- a/sql-statements/sql-statement-admin-show-ddl.md +++ b/sql-statements/sql-statement-admin-show-ddl.md @@ -90,10 +90,10 @@ The `ADMIN SHOW DDL JOBS` statement is used to view all the results in the curre - `paused`: indicates that the operation has been paused. This state only appears when you use the [`ADMIN PAUSED DDL JOBS`](/sql-statements/sql-statement-admin-pause-ddl.md) command to pause the DDL job. You can use the [`ADMIN RESUME DDL JOBS`](/sql-statements/sql-statement-admin-resume-ddl.md) command to resume the DDL job. - `done`: indicates that the operation has been successfully executed on the TiDB owner node, but other TiDB nodes have not yet synchronized the changes performed by this DDL job. - `COMMENTS`: contains other information for auxiliary diagnostic purposes. - - `ingest`: ingest task for accelerated adding index backfill configured via [`tidb_ddl_enable_fast_reorg`](/system-variables.md#tidb_ddl_enable_fast_reorg-new-in-v630)。 + - `ingest`: ingest tasks for accelerated adding index backfill configured via [`tidb_ddl_enable_fast_reorg`](/system-variables.md#tidb_ddl_enable_fast_reorg-new-in-v630)。 - `txn`: basic transactional backfill. - `txn-merge`: transactional backfilling with a temporary index that gets merged with the original index when the backfilling is finished. - - `DXF`: tasks executed with distributed frameworks configured via [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-new-in-v710). + - `DXF`: tasks executed with Distributed eXecution Framework (DXF) configured via [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-new-in-v710). - `service_scope`: the service scope of the TiDB node configured via [`tidb_service_scope`](/system-variables.md#tidb_service_scope-new-in-v740). - `thread`: concurrency of backfill tasks. The initial value can be set with `tidb_ddl_reorg_worker_cnt`. It supports dynamic modification via [`ADMIN ALTER DDL JOBS`](/sql-statements/sql-statement-admin-alter-ddl.md). - `batch_size`: batch size of backfill tasks. The initial value can be set with `tidb_ddl_reorg_batch_size`. It supports dynamic modification via `ADMIN ALTER DDL JOBS`. From 50c98b376848aae913aa61ed1120736dfd9489c8 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Mon, 2 Dec 2024 10:04:17 +0800 Subject: [PATCH 10/16] Apply suggestions from code review --- sql-statements/sql-statement-admin-alter-ddl.md | 4 ++-- sql-statements/sql-statement-admin-show-ddl.md | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/sql-statements/sql-statement-admin-alter-ddl.md b/sql-statements/sql-statement-admin-alter-ddl.md index ec15e2006dead..ea0fa11fa8e33 100644 --- a/sql-statements/sql-statement-admin-alter-ddl.md +++ b/sql-statements/sql-statement-admin-alter-ddl.md @@ -22,8 +22,8 @@ The following are the supported parameters for different DDL jobs and their corr - `ADD INDEX`: - `THREAD`: the concurrency of the DDL job. The initial value is set by `tidb_ddl_reorg_worker_cnt`. - - `BATCH_SIZE`: the batch size. The initial value is set by [`tidb_ddl_reorg_batch_size`](/system-variables.md#tidb_ddl_reorg_batch_size). - - `MAX_WRITE_SPEED`: the maximum bandwidth limit for importing index records into each TiKV. The initial value is set by [`tidb_ddl_reorg_max_write_speed`](/system-variables.md#tidb_ddl_reorg_max_write_speed-new-in-v850). + - `BATCH_SIZE`: the batch size. You can set the initial value by [`tidb_ddl_reorg_batch_size`](/system-variables.md#tidb_ddl_reorg_batch_size). + - `MAX_WRITE_SPEED`: the maximum bandwidth limit for importing index records into each TiKV. The initial value is set by [`tidb_ddl_reorg_max_write_speed`](/system-variables.md#tidb_ddl_reorg_max_write_speed-new-in-v850). Currently this parameter only works for jobs with `ADD INDEX` submitted and running after disabling [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-new-in-v710). - `MODIFY COLUMN`: - `THREAD`: the concurrency of the DDL job. The initial value is set by `tidb_ddl_reorg_worker_cnt`. diff --git a/sql-statements/sql-statement-admin-show-ddl.md b/sql-statements/sql-statement-admin-show-ddl.md index f541ebd360475..ba7c3a2b1aba9 100644 --- a/sql-statements/sql-statement-admin-show-ddl.md +++ b/sql-statements/sql-statement-admin-show-ddl.md @@ -91,12 +91,12 @@ The `ADMIN SHOW DDL JOBS` statement is used to view all the results in the curre - `done`: indicates that the operation has been successfully executed on the TiDB owner node, but other TiDB nodes have not yet synchronized the changes performed by this DDL job. - `COMMENTS`: contains other information for auxiliary diagnostic purposes. - `ingest`: ingest tasks for accelerated adding index backfill configured via [`tidb_ddl_enable_fast_reorg`](/system-variables.md#tidb_ddl_enable_fast_reorg-new-in-v630)。 - - `txn`: basic transactional backfill. + - `txn`: transaction-based index backfill after [`tidb_ddl_enable_fast_reorg`](/system-variables.md#tidb_ddl_enable_fast_reorg-new-in-v630) is disabled. - `txn-merge`: transactional backfilling with a temporary index that gets merged with the original index when the backfilling is finished. - `DXF`: tasks executed with Distributed eXecution Framework (DXF) configured via [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-new-in-v710). - `service_scope`: the service scope of the TiDB node configured via [`tidb_service_scope`](/system-variables.md#tidb_service_scope-new-in-v740). - - `thread`: concurrency of backfill tasks. The initial value can be set with `tidb_ddl_reorg_worker_cnt`. It supports dynamic modification via [`ADMIN ALTER DDL JOBS`](/sql-statements/sql-statement-admin-alter-ddl.md). - - `batch_size`: batch size of backfill tasks. The initial value can be set with `tidb_ddl_reorg_batch_size`. It supports dynamic modification via `ADMIN ALTER DDL JOBS`. + - `thread`: concurrency of backfill tasks. You can set the initial value by `tidb_ddl_reorg_worker_cnt`. It supports dynamic modification via [`ADMIN ALTER DDL JOBS`](/sql-statements/sql-statement-admin-alter-ddl.md). + - `batch_size`: batch size of backfill tasks. You can set the initial value by `tidb_ddl_reorg_batch_size`. It supports dynamic modification via `ADMIN ALTER DDL JOBS`. - `max_write_speed`: flow control during ingest task import. The initial value can be set with `tidb_ddl_reorg_max_write_speed`. It supports dynamic modification via `ADMIN ALTER DDL JOBS`. From d9185130641fb1533ce13083bd0d387f888c5b0d Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Mon, 2 Dec 2024 10:47:01 +0800 Subject: [PATCH 11/16] Apply suggestions from code review --- sql-statements/sql-statement-admin-alter-ddl.md | 3 ++- sql-statements/sql-statement-admin-show-ddl.md | 4 ++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/sql-statements/sql-statement-admin-alter-ddl.md b/sql-statements/sql-statement-admin-alter-ddl.md index ea0fa11fa8e33..00422dd15ca69 100644 --- a/sql-statements/sql-statement-admin-alter-ddl.md +++ b/sql-statements/sql-statement-admin-alter-ddl.md @@ -23,7 +23,8 @@ The following are the supported parameters for different DDL jobs and their corr - `ADD INDEX`: - `THREAD`: the concurrency of the DDL job. The initial value is set by `tidb_ddl_reorg_worker_cnt`. - `BATCH_SIZE`: the batch size. You can set the initial value by [`tidb_ddl_reorg_batch_size`](/system-variables.md#tidb_ddl_reorg_batch_size). - - `MAX_WRITE_SPEED`: the maximum bandwidth limit for importing index records into each TiKV. The initial value is set by [`tidb_ddl_reorg_max_write_speed`](/system-variables.md#tidb_ddl_reorg_max_write_speed-new-in-v850). Currently this parameter only works for jobs with `ADD INDEX` submitted and running after disabling [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-new-in-v710). + - `MAX_WRITE_SPEED`: the maximum bandwidth limit for importing index records into each TiKV. The initial value is set by [`tidb_ddl_reorg_max_write_speed`](/system-variables.md#tidb_ddl_reorg_max_write_speed-new-in-v850). + Currently this parameter only works for jobs with `ADD INDEX` submitted and running after disabling [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-new-in-v710). - `MODIFY COLUMN`: - `THREAD`: the concurrency of the DDL job. The initial value is set by `tidb_ddl_reorg_worker_cnt`. diff --git a/sql-statements/sql-statement-admin-show-ddl.md b/sql-statements/sql-statement-admin-show-ddl.md index ba7c3a2b1aba9..d8109d88a3671 100644 --- a/sql-statements/sql-statement-admin-show-ddl.md +++ b/sql-statements/sql-statement-admin-show-ddl.md @@ -55,7 +55,7 @@ OWNER_ADDRESS: 0.0.0.0:4000 ### `ADMIN SHOW DDL JOBS` -The `ADMIN SHOW DDL JOBS` statement is used to view all the results in the current DDL job queue, including running and queuing tasks, as well as the recent results in the completed DDL job queue. The returned result fields are described as follows: +The `ADMIN SHOW DDL JOBS` statement is used to view the 10 jobs in the current DDL job queue, including running and pending jobs (if any), and the last 10 jobs in the executed DDL job queue (if any). The returned result fields are described as follows: @@ -156,7 +156,7 @@ ADMIN SHOW DDL JOBS; From the output above: -- Job 565 is currently in progress (`STATE` of `running`). The schema state is currently in `write reorganization`, but will switch to `public` once the task is completed to note that the change can be observed publicly by user sessions. The `end_time` column is also `NULL` indicating that the completion time for the job is currently not known. +- Job 565 is currently in progress (`STATE` of `running`). The schema state is currently in `write reorganization`, but will switch to `public` once the job is completed to note that the change can be observed publicly by user sessions. The `end_time` column is also `NULL` indicating that the completion time for the job is currently not known. - The `STATE` for `job_id` 566 is shown as `queueing`, indicating that it is queuing. When job 565 completes and job 566 begins execution, the `STATE` for job 566 will change to `running`. From f818ce931faa8fca735e2390956312037a8a8a93 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Mon, 2 Dec 2024 10:48:45 +0800 Subject: [PATCH 12/16] Apply suggestions from code review --- sql-statements/sql-statement-admin-alter-ddl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-admin-alter-ddl.md b/sql-statements/sql-statement-admin-alter-ddl.md index 00422dd15ca69..b375190986bdd 100644 --- a/sql-statements/sql-statement-admin-alter-ddl.md +++ b/sql-statements/sql-statement-admin-alter-ddl.md @@ -24,7 +24,7 @@ The following are the supported parameters for different DDL jobs and their corr - `THREAD`: the concurrency of the DDL job. The initial value is set by `tidb_ddl_reorg_worker_cnt`. - `BATCH_SIZE`: the batch size. You can set the initial value by [`tidb_ddl_reorg_batch_size`](/system-variables.md#tidb_ddl_reorg_batch_size). - `MAX_WRITE_SPEED`: the maximum bandwidth limit for importing index records into each TiKV. The initial value is set by [`tidb_ddl_reorg_max_write_speed`](/system-variables.md#tidb_ddl_reorg_max_write_speed-new-in-v850). - Currently this parameter only works for jobs with `ADD INDEX` submitted and running after disabling [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-new-in-v710). + Currently these parameters only work for jobs with `ADD INDEX` submitted and running after [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-new-in-v710) is disabled. - `MODIFY COLUMN`: - `THREAD`: the concurrency of the DDL job. The initial value is set by `tidb_ddl_reorg_worker_cnt`. From 74a93fc254d9087bd0dbc2ffcc244e9bcd1293ed Mon Sep 17 00:00:00 2001 From: lilin90 Date: Mon, 2 Dec 2024 12:04:00 +0800 Subject: [PATCH 13/16] Update format --- sql-statements/sql-statement-admin-alter-ddl.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/sql-statements/sql-statement-admin-alter-ddl.md b/sql-statements/sql-statement-admin-alter-ddl.md index b375190986bdd..57059eec1ded6 100644 --- a/sql-statements/sql-statement-admin-alter-ddl.md +++ b/sql-statements/sql-statement-admin-alter-ddl.md @@ -11,7 +11,7 @@ summary: An overview of the usage of `ADMIN ALTER DDL JOBS` for the TiDB databas ADMIN ALTER DDL JOBS 101 THREAD = 8; ``` -- `101`: indicates the ID of the DDL job. You can obtain the ID by executing [`ADMIN SHOW DDL JOBS`](/sql-statements/sql-statement-admin-show-ddl.md). +- `101`: indicates the ID of the DDL job. You can obtain the ID by executing [`ADMIN SHOW DDL JOBS`](/sql-statements/sql-statement-admin-show-ddl.md). - `THREAD`: indicates the concurrency of the DDL job. You can configure the initial value of the thread by the system variable [`tidb_ddl_reorg_worker_cnt`](/system-variables.md#tidb_ddl_reorg_worker_cnt). The following DDL job types support `ADMIN ALTER DDL JOBS`: `ADD INDEX`, `MODIFY COLUMN`, and `REORGANIZE PARTITION`. For other DDL job types, executing `ADMIN ALTER DDL JOBS` reports an error `unsupported DDL operation`. @@ -23,8 +23,8 @@ The following are the supported parameters for different DDL jobs and their corr - `ADD INDEX`: - `THREAD`: the concurrency of the DDL job. The initial value is set by `tidb_ddl_reorg_worker_cnt`. - `BATCH_SIZE`: the batch size. You can set the initial value by [`tidb_ddl_reorg_batch_size`](/system-variables.md#tidb_ddl_reorg_batch_size). - - `MAX_WRITE_SPEED`: the maximum bandwidth limit for importing index records into each TiKV. The initial value is set by [`tidb_ddl_reorg_max_write_speed`](/system-variables.md#tidb_ddl_reorg_max_write_speed-new-in-v850). - Currently these parameters only work for jobs with `ADD INDEX` submitted and running after [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-new-in-v710) is disabled. + - `MAX_WRITE_SPEED`: the maximum bandwidth limit for importing index records into each TiKV. The initial value is set by [`tidb_ddl_reorg_max_write_speed`](/system-variables.md#tidb_ddl_reorg_max_write_speed-new-in-v850). + Currently these parameters only work for jobs with `ADD INDEX` submitted and running after [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-new-in-v710) is disabled. - `MODIFY COLUMN`: - `THREAD`: the concurrency of the DDL job. The initial value is set by `tidb_ddl_reorg_worker_cnt`. @@ -50,7 +50,10 @@ ADMIN ALTER DDL JOBS 101 THREAD = 8, BATCH_SIZE = 256; To view the current parameter values for a specific DDL job, you can execute `ADMIN SHOW DDL JOBS` and the results are displayed in the `COMMENTS` column: ```sql -mysql> ADMIN SHOW DDL JOBS 1; +ADMIN SHOW DDL JOBS 1; +``` + +``` +--------+---------+------------+-----------+--------------+-----------+----------+-----------+----------------------------+----------------------------+----------------------------+--------+-----------------------+ | JOB_ID | DB_NAME | TABLE_NAME | JOB_TYPE | SCHEMA_STATE | SCHEMA_ID | TABLE_ID | ROW_COUNT | CREATE_TIME | START_TIME | END_TIME | STATE | COMMENTS | +--------+---------+------------+-----------+--------------+-----------+----------+-----------+----------------------------+----------------------------+----------------------------+--------+-----------------------+ From 25a504a45409ff74dcfb5c9a0670fee295ed1c54 Mon Sep 17 00:00:00 2001 From: Lilian Lee Date: Mon, 2 Dec 2024 13:59:57 +0800 Subject: [PATCH 14/16] Apply suggestions from code review --- sql-statements/sql-statement-admin-alter-ddl.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sql-statements/sql-statement-admin-alter-ddl.md b/sql-statements/sql-statement-admin-alter-ddl.md index 57059eec1ded6..a401a9221ce25 100644 --- a/sql-statements/sql-statement-admin-alter-ddl.md +++ b/sql-statements/sql-statement-admin-alter-ddl.md @@ -5,7 +5,7 @@ summary: An overview of the usage of `ADMIN ALTER DDL JOBS` for the TiDB databas # ADMIN ALTER DDL JOBS -`ADMIN ALTER DDL JOBS` can be used to change the parameter of a running DDL job. For example: +The `ADMIN ALTER DDL JOBS` statement allows you to modify the parameter of a single running DDL job. For example: ```sql ADMIN ALTER DDL JOBS 101 THREAD = 8; @@ -77,7 +77,7 @@ AlterJobOption ::= ## MySQL compatibility -`ADMIN ALTER DDL JOBS` statement is a TiDB extension to MySQL syntax. +This statement is a TiDB extension to MySQL syntax. ## See also From b447d0850d00a4d78aa5f04117693674119319ca Mon Sep 17 00:00:00 2001 From: lilin90 Date: Mon, 2 Dec 2024 14:24:44 +0800 Subject: [PATCH 15/16] Refine wording and format --- .../sql-statement-admin-alter-ddl.md | 19 ++++++++++--------- .../sql-statement-admin-show-ddl.md | 16 ++++++++-------- 2 files changed, 18 insertions(+), 17 deletions(-) diff --git a/sql-statements/sql-statement-admin-alter-ddl.md b/sql-statements/sql-statement-admin-alter-ddl.md index a401a9221ce25..47a34092b9c63 100644 --- a/sql-statements/sql-statement-admin-alter-ddl.md +++ b/sql-statements/sql-statement-admin-alter-ddl.md @@ -12,19 +12,20 @@ ADMIN ALTER DDL JOBS 101 THREAD = 8; ``` - `101`: indicates the ID of the DDL job. You can obtain the ID by executing [`ADMIN SHOW DDL JOBS`](/sql-statements/sql-statement-admin-show-ddl.md). -- `THREAD`: indicates the concurrency of the DDL job. You can configure the initial value of the thread by the system variable [`tidb_ddl_reorg_worker_cnt`](/system-variables.md#tidb_ddl_reorg_worker_cnt). +- `THREAD`: indicates the concurrency of the DDL job. You can configure its initial value using the system variable [`tidb_ddl_reorg_worker_cnt`](/system-variables.md#tidb_ddl_reorg_worker_cnt). -The following DDL job types support `ADMIN ALTER DDL JOBS`: `ADD INDEX`, `MODIFY COLUMN`, and `REORGANIZE PARTITION`. For other DDL job types, executing `ADMIN ALTER DDL JOBS` reports an error `unsupported DDL operation`. +Currently, the DDL job types supported by the `ADMIN ALTER DDL JOBS` statement include `ADD INDEX`, `MODIFY COLUMN`, and `REORGANIZE PARTITION`. For other DDL job types, executing `ADMIN ALTER DDL JOBS` returns the `unsupported DDL operation` error. -Currently, you can only modiy the parameters of a single DDL job by executing `ADMIN ALTER DDL JOBS`. Modifying the parameters of multiple IDs at the same time is not supported. +Currently, you can only modify the parameters of a single DDL job by executing `ADMIN ALTER DDL JOBS`. Modifying the parameters of multiple DDL job IDs at the same time is not supported. The following are the supported parameters for different DDL jobs and their corresponding system variables: - `ADD INDEX`: - `THREAD`: the concurrency of the DDL job. The initial value is set by `tidb_ddl_reorg_worker_cnt`. - - `BATCH_SIZE`: the batch size. You can set the initial value by [`tidb_ddl_reorg_batch_size`](/system-variables.md#tidb_ddl_reorg_batch_size). + - `BATCH_SIZE`: the batch size. The initial value is set by [`tidb_ddl_reorg_batch_size`](/system-variables.md#tidb_ddl_reorg_batch_size). - `MAX_WRITE_SPEED`: the maximum bandwidth limit for importing index records into each TiKV. The initial value is set by [`tidb_ddl_reorg_max_write_speed`](/system-variables.md#tidb_ddl_reorg_max_write_speed-new-in-v850). - Currently these parameters only work for jobs with `ADD INDEX` submitted and running after [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-new-in-v710) is disabled. + + Currently, the preceding parameters only work for `ADD INDEX` jobs that are submitted and running after [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-new-in-v710) is disabled. - `MODIFY COLUMN`: - `THREAD`: the concurrency of the DDL job. The initial value is set by `tidb_ddl_reorg_worker_cnt`. @@ -34,11 +35,11 @@ The following are the supported parameters for different DDL jobs and their corr - `THREAD`: the concurrency of the DDL job. The initial value is set by `tidb_ddl_reorg_worker_cnt`. - `BATCH_SIZE`: the batch size. The initial value is set by `tidb_ddl_reorg_batch_size`. -The value range of the parameter is consistent with that of the system variable. +The value ranges of the preceding parameters are consistent with those of the corresponding system variables. -`ADMIN ALTER DDL JOBS` takes effect only for running DDL jobs. If the DDL job does not exist or has ended, execution of this statement results in a `ddl job is not running` error. +`ADMIN ALTER DDL JOBS` takes effect only on running DDL jobs. If the DDL job does not exist or has already completed, executing this statement returns the `ddl job is not running` error. -The following are examples of this statement: +The following are some examples of this statement: ```sql ADMIN ALTER DDL JOBS 101 THREAD = 8; @@ -47,7 +48,7 @@ ADMIN ALTER DDL JOBS 101 MAX_WRITE_SPEED = '200MiB'; ADMIN ALTER DDL JOBS 101 THREAD = 8, BATCH_SIZE = 256; ``` -To view the current parameter values for a specific DDL job, you can execute `ADMIN SHOW DDL JOBS` and the results are displayed in the `COMMENTS` column: +To view the current parameter values for a specific DDL job, you can execute `ADMIN SHOW DDL JOBS`. The results are displayed in the `COMMENTS` column: ```sql ADMIN SHOW DDL JOBS 1; diff --git a/sql-statements/sql-statement-admin-show-ddl.md b/sql-statements/sql-statement-admin-show-ddl.md index d8109d88a3671..ff8498697bad3 100644 --- a/sql-statements/sql-statement-admin-show-ddl.md +++ b/sql-statements/sql-statement-admin-show-ddl.md @@ -12,9 +12,9 @@ The `ADMIN SHOW DDL [JOBS|JOB QUERIES]` statement shows information about runnin ```ebnf+diagram AdminShowDDLStmt ::= 'ADMIN' 'SHOW' 'DDL' - ( - 'JOBS' Int64Num? WhereClauseOptional - | 'JOB' 'QUERIES' NumList + ( + 'JOBS' Int64Num? WhereClauseOptional + | 'JOB' 'QUERIES' NumList | 'JOB' 'QUERIES' 'LIMIT' m ( ('OFFSET' | ',') n )? )? @@ -47,9 +47,9 @@ ADMIN SHOW DDL\G; SCHEMA_VER: 26 OWNER_ID: 2d1982af-fa63-43ad-a3d5-73710683cc63 OWNER_ADDRESS: 0.0.0.0:4000 - RUNNING_JOBS: + RUNNING_JOBS: SELF_ID: 2d1982af-fa63-43ad-a3d5-73710683cc63 - QUERY: + QUERY: 1 row in set (0.00 sec) ``` @@ -89,14 +89,14 @@ The `ADMIN SHOW DDL JOBS` statement is used to view the 10 jobs in the current D - `pausing`: indicates that the operation is being paused. - `paused`: indicates that the operation has been paused. This state only appears when you use the [`ADMIN PAUSED DDL JOBS`](/sql-statements/sql-statement-admin-pause-ddl.md) command to pause the DDL job. You can use the [`ADMIN RESUME DDL JOBS`](/sql-statements/sql-statement-admin-resume-ddl.md) command to resume the DDL job. - `done`: indicates that the operation has been successfully executed on the TiDB owner node, but other TiDB nodes have not yet synchronized the changes performed by this DDL job. -- `COMMENTS`: contains other information for auxiliary diagnostic purposes. +- `COMMENTS`: contains additional information for diagnostic purposes. - `ingest`: ingest tasks for accelerated adding index backfill configured via [`tidb_ddl_enable_fast_reorg`](/system-variables.md#tidb_ddl_enable_fast_reorg-new-in-v630)。 - `txn`: transaction-based index backfill after [`tidb_ddl_enable_fast_reorg`](/system-variables.md#tidb_ddl_enable_fast_reorg-new-in-v630) is disabled. - `txn-merge`: transactional backfilling with a temporary index that gets merged with the original index when the backfilling is finished. - `DXF`: tasks executed with Distributed eXecution Framework (DXF) configured via [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-new-in-v710). - `service_scope`: the service scope of the TiDB node configured via [`tidb_service_scope`](/system-variables.md#tidb_service_scope-new-in-v740). - - `thread`: concurrency of backfill tasks. You can set the initial value by `tidb_ddl_reorg_worker_cnt`. It supports dynamic modification via [`ADMIN ALTER DDL JOBS`](/sql-statements/sql-statement-admin-alter-ddl.md). - - `batch_size`: batch size of backfill tasks. You can set the initial value by `tidb_ddl_reorg_batch_size`. It supports dynamic modification via `ADMIN ALTER DDL JOBS`. + - `thread`: the concurrency of backfill tasks. You can set the initial value by `tidb_ddl_reorg_worker_cnt`. It supports dynamic modification via [`ADMIN ALTER DDL JOBS`](/sql-statements/sql-statement-admin-alter-ddl.md). + - `batch_size`: the batch size of backfill tasks. You can set the initial value by `tidb_ddl_reorg_batch_size`. It supports dynamic modification via `ADMIN ALTER DDL JOBS`. - `max_write_speed`: flow control during ingest task import. The initial value can be set with `tidb_ddl_reorg_max_write_speed`. It supports dynamic modification via `ADMIN ALTER DDL JOBS`. From 97b1c30f38e51ad9a1a5fc034b1de5ae67678994 Mon Sep 17 00:00:00 2001 From: lilin90 Date: Mon, 2 Dec 2024 14:25:45 +0800 Subject: [PATCH 16/16] Update wording --- sql-statements/sql-statement-admin-alter-ddl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-admin-alter-ddl.md b/sql-statements/sql-statement-admin-alter-ddl.md index 47a34092b9c63..e7cc26dd7fff8 100644 --- a/sql-statements/sql-statement-admin-alter-ddl.md +++ b/sql-statements/sql-statement-admin-alter-ddl.md @@ -14,7 +14,7 @@ ADMIN ALTER DDL JOBS 101 THREAD = 8; - `101`: indicates the ID of the DDL job. You can obtain the ID by executing [`ADMIN SHOW DDL JOBS`](/sql-statements/sql-statement-admin-show-ddl.md). - `THREAD`: indicates the concurrency of the DDL job. You can configure its initial value using the system variable [`tidb_ddl_reorg_worker_cnt`](/system-variables.md#tidb_ddl_reorg_worker_cnt). -Currently, the DDL job types supported by the `ADMIN ALTER DDL JOBS` statement include `ADD INDEX`, `MODIFY COLUMN`, and `REORGANIZE PARTITION`. For other DDL job types, executing `ADMIN ALTER DDL JOBS` returns the `unsupported DDL operation` error. +The DDL job types supported by the `ADMIN ALTER DDL JOBS` statement include `ADD INDEX`, `MODIFY COLUMN`, and `REORGANIZE PARTITION`. For other DDL job types, executing `ADMIN ALTER DDL JOBS` returns the `unsupported DDL operation` error. Currently, you can only modify the parameters of a single DDL job by executing `ADMIN ALTER DDL JOBS`. Modifying the parameters of multiple DDL job IDs at the same time is not supported.