From 18afd37bc6cbfca3f3fc392f85a8de66c5edb5b0 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 b753d9243eb7272ac1a5b6c9ec318c14d145382c 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 f8ba31168d7f0f41f3ef2960aeab8384005b3fbf 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 4de1d6e393dba3397c6818d7b7581a292376fcf6 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 b9e1679f230b6a301bb0f7ae2013f9b7ab8fb6c8 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 6823bb0b5027a16c1f2107e3bd6ce13c15f0c16b 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 09e4e7f15a60baf8d4dafc9182ff5c717a500ab8 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 722b39496b7a12b3511fca27569c538eaee104b4 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 47cc83a1e11deff0e8fd8191b1fc465f2fdd9c42 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 250d1890aecb9337425b1803f630a3a9331d174a 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 7521a93c6ff4b5184cb54a8cfab5e54f73a6f898 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 ff3c547bf97befc78bff3898d733ecc7d6afb425 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 85b65677fd3bfdeb466fefc000074b5a16684d65 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 228ffdf787bf7b7222fdea1c9e46dfece4589457 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 0eda3dfc07093868404d2a5169f73572d1b06581 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 e540032418e9bb50759fbb8f655a2d8d0830f069 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.