This is an automated email from the ASF dual-hosted git repository.
morningman pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new 588ba67368f [fix](kill) opt kill query doc (#2371)
588ba67368f is described below
commit 588ba67368f0e9391db970bc3e5edb788717c37a
Author: Mingyu Chen (Rayner) <[email protected]>
AuthorDate: Mon May 26 11:28:51 2025 +0800
[fix](kill) opt kill query doc (#2371)
## Versions
- [x] dev
- [x] 3.0
- [x] 2.1
- [ ] 2.0
## Languages
- [x] Chinese
- [x] English
## Docs Checklist
- [x] Checked by AI
- [ ] Test Cases Built
---
.../admin-manual/workload-management/kill-query.md | 154 ++++++++++++++------
.../admin-manual/workload-management/kill-query.md | 157 ++++++++++++++++-----
.../admin-manual/workload-management/kill-query.md | 157 ++++++++++++++++-----
.../admin-manual/workload-management/kill-query.md | 157 ++++++++++++++++-----
.../admin-manual/workload-management/kill-query.md | 154 ++++++++++++++------
.../admin-manual/workload-management/kill-query.md | 154 ++++++++++++++------
6 files changed, 696 insertions(+), 237 deletions(-)
diff --git a/docs/admin-manual/workload-management/kill-query.md
b/docs/admin-manual/workload-management/kill-query.md
index 24959b45f39..7b8701edffc 100644
--- a/docs/admin-manual/workload-management/kill-query.md
+++ b/docs/admin-manual/workload-management/kill-query.md
@@ -24,77 +24,151 @@ specific language governing permissions and limitations
under the License.
-->
-## Retrieve the List of Queries
+You can cancel currently executing operations or disconnect current connection
sessions using the `KILL` command. This document introduces related operations
and considerations.
-Syntax:
+## Getting Query Identifiers
+
+`KILL` requires a query identifier to cancel the corresponding query request.
Query identifiers include: Query ID, Connection ID, and Trace ID.
+
+You can obtain query identifiers through the following methods.
+### PROCESSLIST
+
+Through the `processlist` system table, you can get all current session
connections and query operations being executed in the connections. This
includes the Query ID and Connection ID.
```sql
-SHOW PROCESSLIST;
+mysql> SHOW PROCESSLIST;
++------------------+------+------+---------------------+---------------------+----------+------+---------+------+-------+-----------------------------------+------------------+---------------+--------------+
+| CurrentConnected | Id | User | Host | LoginTime |
Catalog | Db | Command | Time | State | QueryId |
Info | FE | CloudCluster |
++------------------+------+------+---------------------+---------------------+----------+------+---------+------+-------+-----------------------------------+------------------+---------------+--------------+
+| No | 2 | root | 172.20.32.136:54850 | 2025-05-11 10:41:52 |
internal | | Query | 6 | OK | 12ccf7f95c1c4d2c-b03fa9c652757c15 |
select sleep(20) | 172.20.32.152 | NULL |
+| Yes | 3 | root | 172.20.32.136:54862 | 2025-05-11 10:41:55 |
internal | | Query | 0 | OK | b710ed990d4144ee-8b15bb53002b7710 |
show processlist | 172.20.32.152 | NULL |
+| No | 1 | root | 172.20.32.136:47964 | 2025-05-11 10:41:54 |
internal | | Sleep | 11 | EOF | b60daa992bac4fe4-b29466aacce67d27 |
| 172.20.32.153 | NULL |
++------------------+------+------+---------------------+---------------------+----------+------+---------+------+-------+-----------------------------------+------------------+---------------+--------------+
```
-This command displays all current connections to the FE and the list of
queries being executed on each connection. For example:
+- `CurrentConnected`: `Yes` indicates the connection corresponding to the
current session.
+- `Id`: The unique identifier of the connection, i.e., Connection ID.
+- `QueryId`: The unique identifier of the Query. Displays the Query Id of the
most recently executed or currently executing SQL command.
-```sql
-SHOW PROCESSLIST;
-+------------------+------+------+--------------------+---------------------+----------+---------+---------+------+-------+-----------------------------------+---------------------------------------------------------------------------------------+
-| CurrentConnected | Id | User | Host | LoginTime |
Catalog | Db | Command | Time | State | QueryId
| Info
|
-+------------------+------+------+--------------------+---------------------+----------+---------+---------+------+-------+-----------------------------------+---------------------------------------------------------------------------------------+
-| Yes | 48 | root | 10.16.xx.xx:44834 | 2023-12-29 16:49:47 |
internal | test | Query | 0 | OK | e6e4ce9567b04859-8eeab8d6b5513e38 |
SHOW PROCESSLIST
|
-| | 50 | root | 192.168.xx.xx:52837 | 2023-12-29 16:51:34 |
internal | | Sleep | 1837 | EOF | deaf13c52b3b4a3b-b25e8254b50ff8cb |
SELECT @@session.transaction_isolation
|
-| | 51 | root | 192.168.xx.xx:52843 | 2023-12-29 16:51:35 |
internal | | Sleep | 907 | EOF | 437f219addc0404f-9befe7f6acf9a700 |
/* ApplicationName=DBeaver Ultimate 23.1.3 - Metadata */ SHOW STATUS
|
-| | 55 | root | 192.168.xx.xx:55533 | 2023-12-29 17:09:32 |
internal | test | Sleep | 271 | EOF | f02603dc163a4da3-beebbb5d1ced760c |
/* ApplicationName=DBeaver Ultimate 23.1.3 - SQLEditor <Console> */ SELECT
DATABASE() |
-| | 47 | root | 10.16.xx.xx:35678 | 2023-12-29 16:21:56 |
internal | test | Sleep | 3528 | EOF | f4944c543dc34a99-b0d0f3986c8f1c98 |
select * from test
|
-+------------------+------+------+--------------------+---------------------+----------+---------+---------+------+-------+-----------------------------------+---------------------------------------------------------------------------------------+
-5 rows in set (0.00 sec)
+Note that by default, `SHOW PROCESSLIST` only displays all session connections
on the FE node that the current session is connected to, and does not display
session connections from other FE nodes.
+
+If you want to display session connections from all FE nodes, you need to set
the following session variable:
+
+```
+SET show_all_fe_connection=true;
```
+Then execute the `SHOW PROCESSLIST` command again to display session
connections from all FE nodes.
-- Id is the unique identifier for the connection, also known as processlist_id.
-- QueryId is the unique identifier for the query.
+You can also view through the system table in `information_schema`:
+
+```
+SELECT * FROM information_schema.processlist;
+```
+By default, `processlist` displays session connections from all FE nodes
without requiring additional settings.
+### TRACE ID
-## Kill Query
+> This feature is supported since versions 2.1.11 and 3.0.7.
-Syntax:
+By default, the system automatically generates a Query ID for each query.
Users need to first obtain the Query ID through the `processlist` system table
before performing a KILL operation.
+In addition, users can also customize a Trace ID and perform KILL operations
using the Trace ID.
-```sql
-KILL QUERY query_id | processlist_id
+```
+SET session_context = "trace_id:your_trace_id";
```
-This command is used to terminate a specific query or the query being executed
on a specific connection. For example:
+Where `your_trace_id` is the user-defined Trace ID. It can be any string but
cannot contain the `;` symbol.
-```sql
-kill query 55;
-Query OK, 0 rows affected (0.01 sec)
-```
+Trace ID is a session-level parameter and only applies to the current session.
Doris will map subsequent query requests in the current session to this Trace
ID.
-This terminates the query currently running on the connection with Id=55, but
the connection itself remains active.
+## Kill Requests
-```sql
-kill query 'f02603dc163a4da3-beebbb5d1ced760c';
-Query OK, 0 rows affected (0.01 sec)
-```
+The `KILL` statement supports canceling specified query operations as well as
disconnecting specified session connections.
-This terminates the query with QueryId=f02603dc163a4da3-beebbb5d1ced760c,
which is actually the same query as the one with processlist_id=55.
+Regular users can cancel queries sent by their own user through the `KILL`
operation. ADMIN users can cancel queries sent by themselves and any other
users.
-## Kill Connection
+### Kill Query
Syntax:
-
```sql
-KILL CONNECTION processlist_id
+KILL QUERY "query_id" | "trace_id" | connection_id;
```
-For example:
+`KILL QUERY` is used to cancel a specified running query operation.
+
+- `"query_id"`
+ The Query ID obtained through the `processlist` system table. Must be
wrapped in quotes. For example:
+
+ `KILL QUERY "d36417cc05ff41ab-9d3afe49be251055";`
+
+ This operation will attempt to find the Query ID on all FE nodes and
cancel the corresponding query.
+
+- `"trace_id"`
+
+ The Trace ID customized through `session_context`. Must be wrapped in
quotes. For example:
+
+ `KILL QUERY "your_trace_id";`
+
+ This operation will attempt to find the Trace ID on all FE nodes and
cancel the corresponding query.
+
+ > This feature is supported since versions 2.1.11 and 3.0.7.
+
+- `connection_id`
+
+ The Connection ID obtained through the `processlist` system table. Must
be an integer greater than 0 and cannot be wrapped in quotes. For example:
+
+ `KILL QUERY 55;`
+
+ This operation only applies to session connections on the currently
connected FE, and will cancel the query currently being executed on the
corresponding session connection.
+
+### Kill Connection
+
+Killing a connection will disconnect the specified session connection and also
cancel any query operations being executed on the connection.
+
+Syntax:
```sql
-kill CONNECTION 55;
-Query OK, 0 rows affected (0.01 sec)
+KILL [CONNECTION] connection_id;
```
-This command disconnects the connection with Id=55, and any query currently
being executed on this connection will also be canceled.
+The `CONNECTION` keyword can be omitted.
+
+- `connection_id`
+
+ The Connection ID obtained through the `processlist` system table. Must
be an integer greater than 0 and cannot be wrapped in quotes. For example:
+
+ ```sql
+ KILL CONNECTION 55;
+ KILL 55;
+ ```
+
+ Connection IDs on different FEs may be the same, but this operation
only affects the session connection on the currently connected FE.
+
+## Best Practices
+
+1. Implementing query management through custom Trace ID
+
+ Custom Trace IDs allow you to specify unique identifiers for queries in
advance, making it easier for management system to implement the [Cancel Query]
function. You can customize Trace IDs in the following ways:
+
+ - Set `session_context` before each query
+
+ Users generate their own Trace ID. It is recommended to use
UUID to ensure the uniqueness of the Trace ID.
+
+ ```sql
+ SET session_context="trace_id:your_trace_id";
+ SELECT * FROM table ...;
+ ```
+
+ - Add Trace ID in the query statement
+
+ ```sql
+ SELECT /*+SET_VAR(session_context=trace_id:your_trace_id)*/ *
FROM table ...;
+ ```
+
+ Afterward, management system can cancel running operations at any time
using the Trace ID.
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/workload-management/kill-query.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/workload-management/kill-query.md
index 8afa1a53040..28c8e85e453 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/workload-management/kill-query.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/workload-management/kill-query.md
@@ -24,73 +24,152 @@ specific language governing permissions and limitations
under the License.
-->
-## 获取查询列表
+可以通过 `KILL` 命令取消当前正在执行的操作或断开当前连接会话。本文档介绍相关操作和注意事项
-语法：
+## 获取查询标识
-```sql
-SHOW PROCESSLIST;
-```
+`KILL` 需通过查询标识取消对应的查询请求。查询标识包括：查询 ID（Query ID） 、连接 ID（Connection ID）和 Trace ID。
-可以显示当前 FE 所有的连接，以及每个连接上正在运行的 Query 的列表，例如：
+可以通过以下方式获取查询标识。
+
+### PROCESSLIST
+
+通过 `processlist` 系统表可以获取当前所有的会话连接，以及连接中正在执行的查询操作。其中包含查询 ID 和连接 ID。
```sql
-SHOW PROCESSLIST;
-+------------------+------+------+--------------------+---------------------+----------+---------+---------+------+-------+-----------------------------------+---------------------------------------------------------------------------------------+
-| CurrentConnected | Id | User | Host | LoginTime |
Catalog | Db | Command | Time | State | QueryId
| Info
|
-+------------------+------+------+--------------------+---------------------+----------+---------+---------+------+-------+-----------------------------------+---------------------------------------------------------------------------------------+
-| Yes | 48 | root | 10.16.xx.xx:44834 | 2023-12-29 16:49:47 |
internal | test | Query | 0 | OK | e6e4ce9567b04859-8eeab8d6b5513e38 |
SHOW PROCESSLIST
|
-| | 50 | root | 192.168.xx.xx:52837 | 2023-12-29 16:51:34 |
internal | | Sleep | 1837 | EOF | deaf13c52b3b4a3b-b25e8254b50ff8cb |
SELECT @@session.transaction_isolation
|
-| | 51 | root | 192.168.xx.xx:52843 | 2023-12-29 16:51:35 |
internal | | Sleep | 907 | EOF | 437f219addc0404f-9befe7f6acf9a700 |
/* ApplicationName=DBeaver Ultimate 23.1.3 - Metadata */ SHOW STATUS
|
-| | 55 | root | 192.168.xx.xx:55533 | 2023-12-29 17:09:32 |
internal | test | Sleep | 271 | EOF | f02603dc163a4da3-beebbb5d1ced760c |
/* ApplicationName=DBeaver Ultimate 23.1.3 - SQLEditor <Console> */ SELECT
DATABASE() |
-| | 47 | root | 10.16.xx.xx:35678 | 2023-12-29 16:21:56 |
internal | test | Sleep | 3528 | EOF | f4944c543dc34a99-b0d0f3986c8f1c98 |
select * from test
|
-+------------------+------+------+--------------------+---------------------+----------+---------+---------+------+-------+-----------------------------------+---------------------------------------------------------------------------------------+
-5 rows in set (0.00 sec)
+mysql> SHOW PROCESSLIST;
++------------------+------+------+---------------------+---------------------+----------+------+---------+------+-------+-----------------------------------+------------------+---------------+--------------+
+| CurrentConnected | Id | User | Host | LoginTime |
Catalog | Db | Command | Time | State | QueryId |
Info | FE | CloudCluster |
++------------------+------+------+---------------------+---------------------+----------+------+---------+------+-------+-----------------------------------+------------------+---------------+--------------+
+| No | 2 | root | 172.20.32.136:54850 | 2025-05-11 10:41:52 |
internal | | Query | 6 | OK | 12ccf7f95c1c4d2c-b03fa9c652757c15 |
select sleep(20) | 172.20.32.152 | NULL |
+| Yes | 3 | root | 172.20.32.136:54862 | 2025-05-11 10:41:55 |
internal | | Query | 0 | OK | b710ed990d4144ee-8b15bb53002b7710 |
show processlist | 172.20.32.152 | NULL |
+| No | 1 | root | 172.20.32.136:47964 | 2025-05-11 10:41:54 |
internal | | Sleep | 11 | EOF | b60daa992bac4fe4-b29466aacce67d27 |
| 172.20.32.153 | NULL |
++------------------+------+------+---------------------+---------------------+----------+------+---------+------+-------+-----------------------------------+------------------+---------------+--------------+
```
+- `CurrentConnected`：`Yes` 表示当前会话所对应的连接。
+- `Id`：连接的唯一标识，即 Connection ID。
+- `QueryId`：Query 的唯一标识。显示最仅执行的、或正在执行的 SQL 命令的 Query Id。
-- Id 是连接的唯一标识，也可以称为 processlist_id；
-- QueryId 是 Query 的唯一标识。
+注意，在默认情况下，`SHOW PROCESSLIST` 仅显示当前会话所连接到的 FE 节点上的所有会话连接，并不会显示其他 FE 节点的会话连接。
+如果要显示所有 FE 节点的会话连接，需设置一下会话变量：
+```
+SET show_all_fe_connection=true;
+```
-## Kill 查询
+然后再执行 `SHOW PROCESSLIST` 命令，即可显示所有 FE 节点的会话连接。
-语法：
+也可以通过 `information_schema` 中的系统表查看：
-```sql
-KILL QUERY query_id | processlist_id
+```
+SELECT * FROM information_schema.processlist;
```
-用于 Kill 某一个指定的 Query，或者某一个连接上正在运行的 Query，例如：
+`processlist` 默认会显示所有 FE 节点的会话连接，不需要额外进行设置。
-```sql
-kill query 55;
-Query OK, 0 rows affected (0.01 sec)
-```
+### TRACE ID
-表示 Kill 连接 Id=55 上正在运行的 Query，但是连接仍然有效。
+> 该功能自 2.1.11 和 3.0.7 版本支持。
-```sql
-kill query 'f02603dc163a4da3-beebbb5d1ced760c';
-Query OK, 0 rows affected (0.01 sec)
+默认情况下，系统会为每个查询自动生成 Query ID。用户需先通过 `processlist` 系统表获取到 Query ID 后，再进行 KILL 操作。
+
+除此之外，用户还可以自定义 Trace ID，并通过 Trace ID 进行 KILL 操作。
+
+```
+SET session_context = "trace_id:your_trace_id"
```
-表示 Kill QueryId=f02603dc163a4da3-beebbb5d1ced760c 的 Query，与之前的
processlist_id=55 实际是同一个 Query。
+其中 `your_trace_id ` 为用户自定义的 Trace ID。可以是任意字符串，但不可以包含 `;` 符号。
-## Kill 连接
+Trace ID 是会话级别参数，仅作用于当前会话。Doris 会将之后发生在当前会话中的查询请求映射到这个 Trace ID 上。
+
+## Kill 请求
+
+`KILL` 语句支持通过取消指定的查询操作，也支持断开指定的会话连接。
+
+普通用户可以通过 `KILL` 操作取消掉自身用户发送的查询。ADMIN 用户可以取消自身和任意其他用户发送的查询。
+
+### Kill 查询
语法：
```sql
-KILL CONNECTION processlist_id
+KILL QUERY "query_id" | "trace_id" | connection_id;
```
-例如：
+`KILL QUERY` 用于取消一个指定的正在运行的查询操作。
+
+- `"query_id"`
+
+ 通过 `processlist` 系统表获取到的 Query ID。需用引号包裹。如：
+
+ `KILL QUERY "d36417cc05ff41ab-9d3afe49be251055";`
+
+ 该操作会尝试在所有 FE 节点查找 Query ID 并取消对应的查询。
+
+- `"trace_id"`
+
+ 通过 `session_context` 自定义的 Trace ID。需用引号包裹。如：
+
+ `KILL QUERY "your_trace_id";`
+
+ 该操作会尝试在所有 FE 节点查找 Trace ID 并取消对应的查询。
+
+ > 该功能自 2.1.11 和 3.0.7 版本支持。
+
+- `connection_id`
+
+ 通过 `processlist` 系统表获取到的 Connection ID。必须是一个大于 0 的整数，不可用引号包裹。如：
+
+ `KILL QUERY 55;`
+
+ 该操作仅作用于当前连接到的 FE 上的会话连接，会取消对应会话连接上正在执行的查询。
+
+### Kill 连接
+
+Kill 连接会断开指定的会话连接，同时也会取消连接上正在执行的查询操作。
+
+语法：
```sql
-kill CONNECTION 55;
-Query OK, 0 rows affected (0.01 sec)
+KILL [CONNECTION] connection_id;
```
-表示断开 Id=55 这个连接，这个连接上正在执行的 Query 也会被 Cancel。
\ No newline at end of file
+其中 `CONNECTION` 关键词可以省略。
+
+- `connection_id `
+
+ 通过 `processlist` 系统表获取到的 Connection ID。必须是一个大于 0 的整数，不可用引号包裹。如：
+
+ ```sql
+ KILL CONNECTION 55;
+ KILL 55;
+ ```
+
+ 不同 FE 上的连接 ID 可能相同，但该操作仅作用于当前连接到的 FE 上的会话连接。
+
+## 最佳实践
+
+1. 通过自定义 Trace ID 实现查询管理
+
+ 通过自定义 Trace ID 可以预先为查询指定唯一标识，方便管控工具实现【取消查询】的功能。可以通过如下方式自定义 Trace ID：
+
+ - 每次查询前设置 `session_context`
+
+ 用户自行生成 Trace ID。建议使用 UUID 以确保 Trace ID 的唯一性。
+
+ ```sql
+ SET session_context="trace_id:your_trace_id";
+ SELECT * FROM table ...;
+ ```
+
+ - 在查询语句中添加 Trace ID
+
+ ```sql
+ SELECT /*+SET_VAR(session_context=trace_id:your_trace_id)*/ *
FROM table ...;
+ ```
+
+ 之后，管控工具可以通过 Trace ID 随时取消正在执行的操作。
+
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/admin-manual/workload-management/kill-query.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/admin-manual/workload-management/kill-query.md
index 8afa1a53040..28c8e85e453 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/admin-manual/workload-management/kill-query.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/admin-manual/workload-management/kill-query.md
@@ -24,73 +24,152 @@ specific language governing permissions and limitations
under the License.
-->
-## 获取查询列表
+可以通过 `KILL` 命令取消当前正在执行的操作或断开当前连接会话。本文档介绍相关操作和注意事项
-语法：
+## 获取查询标识
-```sql
-SHOW PROCESSLIST;
-```
+`KILL` 需通过查询标识取消对应的查询请求。查询标识包括：查询 ID（Query ID） 、连接 ID（Connection ID）和 Trace ID。
-可以显示当前 FE 所有的连接，以及每个连接上正在运行的 Query 的列表，例如：
+可以通过以下方式获取查询标识。
+
+### PROCESSLIST
+
+通过 `processlist` 系统表可以获取当前所有的会话连接，以及连接中正在执行的查询操作。其中包含查询 ID 和连接 ID。
```sql
-SHOW PROCESSLIST;
-+------------------+------+------+--------------------+---------------------+----------+---------+---------+------+-------+-----------------------------------+---------------------------------------------------------------------------------------+
-| CurrentConnected | Id | User | Host | LoginTime |
Catalog | Db | Command | Time | State | QueryId
| Info
|
-+------------------+------+------+--------------------+---------------------+----------+---------+---------+------+-------+-----------------------------------+---------------------------------------------------------------------------------------+
-| Yes | 48 | root | 10.16.xx.xx:44834 | 2023-12-29 16:49:47 |
internal | test | Query | 0 | OK | e6e4ce9567b04859-8eeab8d6b5513e38 |
SHOW PROCESSLIST
|
-| | 50 | root | 192.168.xx.xx:52837 | 2023-12-29 16:51:34 |
internal | | Sleep | 1837 | EOF | deaf13c52b3b4a3b-b25e8254b50ff8cb |
SELECT @@session.transaction_isolation
|
-| | 51 | root | 192.168.xx.xx:52843 | 2023-12-29 16:51:35 |
internal | | Sleep | 907 | EOF | 437f219addc0404f-9befe7f6acf9a700 |
/* ApplicationName=DBeaver Ultimate 23.1.3 - Metadata */ SHOW STATUS
|
-| | 55 | root | 192.168.xx.xx:55533 | 2023-12-29 17:09:32 |
internal | test | Sleep | 271 | EOF | f02603dc163a4da3-beebbb5d1ced760c |
/* ApplicationName=DBeaver Ultimate 23.1.3 - SQLEditor <Console> */ SELECT
DATABASE() |
-| | 47 | root | 10.16.xx.xx:35678 | 2023-12-29 16:21:56 |
internal | test | Sleep | 3528 | EOF | f4944c543dc34a99-b0d0f3986c8f1c98 |
select * from test
|
-+------------------+------+------+--------------------+---------------------+----------+---------+---------+------+-------+-----------------------------------+---------------------------------------------------------------------------------------+
-5 rows in set (0.00 sec)
+mysql> SHOW PROCESSLIST;
++------------------+------+------+---------------------+---------------------+----------+------+---------+------+-------+-----------------------------------+------------------+---------------+--------------+
+| CurrentConnected | Id | User | Host | LoginTime |
Catalog | Db | Command | Time | State | QueryId |
Info | FE | CloudCluster |
++------------------+------+------+---------------------+---------------------+----------+------+---------+------+-------+-----------------------------------+------------------+---------------+--------------+
+| No | 2 | root | 172.20.32.136:54850 | 2025-05-11 10:41:52 |
internal | | Query | 6 | OK | 12ccf7f95c1c4d2c-b03fa9c652757c15 |
select sleep(20) | 172.20.32.152 | NULL |
+| Yes | 3 | root | 172.20.32.136:54862 | 2025-05-11 10:41:55 |
internal | | Query | 0 | OK | b710ed990d4144ee-8b15bb53002b7710 |
show processlist | 172.20.32.152 | NULL |
+| No | 1 | root | 172.20.32.136:47964 | 2025-05-11 10:41:54 |
internal | | Sleep | 11 | EOF | b60daa992bac4fe4-b29466aacce67d27 |
| 172.20.32.153 | NULL |
++------------------+------+------+---------------------+---------------------+----------+------+---------+------+-------+-----------------------------------+------------------+---------------+--------------+
```
+- `CurrentConnected`：`Yes` 表示当前会话所对应的连接。
+- `Id`：连接的唯一标识，即 Connection ID。
+- `QueryId`：Query 的唯一标识。显示最仅执行的、或正在执行的 SQL 命令的 Query Id。
-- Id 是连接的唯一标识，也可以称为 processlist_id；
-- QueryId 是 Query 的唯一标识。
+注意，在默认情况下，`SHOW PROCESSLIST` 仅显示当前会话所连接到的 FE 节点上的所有会话连接，并不会显示其他 FE 节点的会话连接。
+如果要显示所有 FE 节点的会话连接，需设置一下会话变量：
+```
+SET show_all_fe_connection=true;
+```
-## Kill 查询
+然后再执行 `SHOW PROCESSLIST` 命令，即可显示所有 FE 节点的会话连接。
-语法：
+也可以通过 `information_schema` 中的系统表查看：
-```sql
-KILL QUERY query_id | processlist_id
+```
+SELECT * FROM information_schema.processlist;
```
-用于 Kill 某一个指定的 Query，或者某一个连接上正在运行的 Query，例如：
+`processlist` 默认会显示所有 FE 节点的会话连接，不需要额外进行设置。
-```sql
-kill query 55;
-Query OK, 0 rows affected (0.01 sec)
-```
+### TRACE ID
-表示 Kill 连接 Id=55 上正在运行的 Query，但是连接仍然有效。
+> 该功能自 2.1.11 和 3.0.7 版本支持。
-```sql
-kill query 'f02603dc163a4da3-beebbb5d1ced760c';
-Query OK, 0 rows affected (0.01 sec)
+默认情况下，系统会为每个查询自动生成 Query ID。用户需先通过 `processlist` 系统表获取到 Query ID 后，再进行 KILL 操作。
+
+除此之外，用户还可以自定义 Trace ID，并通过 Trace ID 进行 KILL 操作。
+
+```
+SET session_context = "trace_id:your_trace_id"
```
-表示 Kill QueryId=f02603dc163a4da3-beebbb5d1ced760c 的 Query，与之前的
processlist_id=55 实际是同一个 Query。
+其中 `your_trace_id ` 为用户自定义的 Trace ID。可以是任意字符串，但不可以包含 `;` 符号。
-## Kill 连接
+Trace ID 是会话级别参数，仅作用于当前会话。Doris 会将之后发生在当前会话中的查询请求映射到这个 Trace ID 上。
+
+## Kill 请求
+
+`KILL` 语句支持通过取消指定的查询操作，也支持断开指定的会话连接。
+
+普通用户可以通过 `KILL` 操作取消掉自身用户发送的查询。ADMIN 用户可以取消自身和任意其他用户发送的查询。
+
+### Kill 查询
语法：
```sql
-KILL CONNECTION processlist_id
+KILL QUERY "query_id" | "trace_id" | connection_id;
```
-例如：
+`KILL QUERY` 用于取消一个指定的正在运行的查询操作。
+
+- `"query_id"`
+
+ 通过 `processlist` 系统表获取到的 Query ID。需用引号包裹。如：
+
+ `KILL QUERY "d36417cc05ff41ab-9d3afe49be251055";`
+
+ 该操作会尝试在所有 FE 节点查找 Query ID 并取消对应的查询。
+
+- `"trace_id"`
+
+ 通过 `session_context` 自定义的 Trace ID。需用引号包裹。如：
+
+ `KILL QUERY "your_trace_id";`
+
+ 该操作会尝试在所有 FE 节点查找 Trace ID 并取消对应的查询。
+
+ > 该功能自 2.1.11 和 3.0.7 版本支持。
+
+- `connection_id`
+
+ 通过 `processlist` 系统表获取到的 Connection ID。必须是一个大于 0 的整数，不可用引号包裹。如：
+
+ `KILL QUERY 55;`
+
+ 该操作仅作用于当前连接到的 FE 上的会话连接，会取消对应会话连接上正在执行的查询。
+
+### Kill 连接
+
+Kill 连接会断开指定的会话连接，同时也会取消连接上正在执行的查询操作。
+
+语法：
```sql
-kill CONNECTION 55;
-Query OK, 0 rows affected (0.01 sec)
+KILL [CONNECTION] connection_id;
```
-表示断开 Id=55 这个连接，这个连接上正在执行的 Query 也会被 Cancel。
\ No newline at end of file
+其中 `CONNECTION` 关键词可以省略。
+
+- `connection_id `
+
+ 通过 `processlist` 系统表获取到的 Connection ID。必须是一个大于 0 的整数，不可用引号包裹。如：
+
+ ```sql
+ KILL CONNECTION 55;
+ KILL 55;
+ ```
+
+ 不同 FE 上的连接 ID 可能相同，但该操作仅作用于当前连接到的 FE 上的会话连接。
+
+## 最佳实践
+
+1. 通过自定义 Trace ID 实现查询管理
+
+ 通过自定义 Trace ID 可以预先为查询指定唯一标识，方便管控工具实现【取消查询】的功能。可以通过如下方式自定义 Trace ID：
+
+ - 每次查询前设置 `session_context`
+
+ 用户自行生成 Trace ID。建议使用 UUID 以确保 Trace ID 的唯一性。
+
+ ```sql
+ SET session_context="trace_id:your_trace_id";
+ SELECT * FROM table ...;
+ ```
+
+ - 在查询语句中添加 Trace ID
+
+ ```sql
+ SELECT /*+SET_VAR(session_context=trace_id:your_trace_id)*/ *
FROM table ...;
+ ```
+
+ 之后，管控工具可以通过 Trace ID 随时取消正在执行的操作。
+
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/admin-manual/workload-management/kill-query.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/admin-manual/workload-management/kill-query.md
index 8afa1a53040..28c8e85e453 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/admin-manual/workload-management/kill-query.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/admin-manual/workload-management/kill-query.md
@@ -24,73 +24,152 @@ specific language governing permissions and limitations
under the License.
-->
-## 获取查询列表
+可以通过 `KILL` 命令取消当前正在执行的操作或断开当前连接会话。本文档介绍相关操作和注意事项
-语法：
+## 获取查询标识
-```sql
-SHOW PROCESSLIST;
-```
+`KILL` 需通过查询标识取消对应的查询请求。查询标识包括：查询 ID（Query ID） 、连接 ID（Connection ID）和 Trace ID。
-可以显示当前 FE 所有的连接，以及每个连接上正在运行的 Query 的列表，例如：
+可以通过以下方式获取查询标识。
+
+### PROCESSLIST
+
+通过 `processlist` 系统表可以获取当前所有的会话连接，以及连接中正在执行的查询操作。其中包含查询 ID 和连接 ID。
```sql
-SHOW PROCESSLIST;
-+------------------+------+------+--------------------+---------------------+----------+---------+---------+------+-------+-----------------------------------+---------------------------------------------------------------------------------------+
-| CurrentConnected | Id | User | Host | LoginTime |
Catalog | Db | Command | Time | State | QueryId
| Info
|
-+------------------+------+------+--------------------+---------------------+----------+---------+---------+------+-------+-----------------------------------+---------------------------------------------------------------------------------------+
-| Yes | 48 | root | 10.16.xx.xx:44834 | 2023-12-29 16:49:47 |
internal | test | Query | 0 | OK | e6e4ce9567b04859-8eeab8d6b5513e38 |
SHOW PROCESSLIST
|
-| | 50 | root | 192.168.xx.xx:52837 | 2023-12-29 16:51:34 |
internal | | Sleep | 1837 | EOF | deaf13c52b3b4a3b-b25e8254b50ff8cb |
SELECT @@session.transaction_isolation
|
-| | 51 | root | 192.168.xx.xx:52843 | 2023-12-29 16:51:35 |
internal | | Sleep | 907 | EOF | 437f219addc0404f-9befe7f6acf9a700 |
/* ApplicationName=DBeaver Ultimate 23.1.3 - Metadata */ SHOW STATUS
|
-| | 55 | root | 192.168.xx.xx:55533 | 2023-12-29 17:09:32 |
internal | test | Sleep | 271 | EOF | f02603dc163a4da3-beebbb5d1ced760c |
/* ApplicationName=DBeaver Ultimate 23.1.3 - SQLEditor <Console> */ SELECT
DATABASE() |
-| | 47 | root | 10.16.xx.xx:35678 | 2023-12-29 16:21:56 |
internal | test | Sleep | 3528 | EOF | f4944c543dc34a99-b0d0f3986c8f1c98 |
select * from test
|
-+------------------+------+------+--------------------+---------------------+----------+---------+---------+------+-------+-----------------------------------+---------------------------------------------------------------------------------------+
-5 rows in set (0.00 sec)
+mysql> SHOW PROCESSLIST;
++------------------+------+------+---------------------+---------------------+----------+------+---------+------+-------+-----------------------------------+------------------+---------------+--------------+
+| CurrentConnected | Id | User | Host | LoginTime |
Catalog | Db | Command | Time | State | QueryId |
Info | FE | CloudCluster |
++------------------+------+------+---------------------+---------------------+----------+------+---------+------+-------+-----------------------------------+------------------+---------------+--------------+
+| No | 2 | root | 172.20.32.136:54850 | 2025-05-11 10:41:52 |
internal | | Query | 6 | OK | 12ccf7f95c1c4d2c-b03fa9c652757c15 |
select sleep(20) | 172.20.32.152 | NULL |
+| Yes | 3 | root | 172.20.32.136:54862 | 2025-05-11 10:41:55 |
internal | | Query | 0 | OK | b710ed990d4144ee-8b15bb53002b7710 |
show processlist | 172.20.32.152 | NULL |
+| No | 1 | root | 172.20.32.136:47964 | 2025-05-11 10:41:54 |
internal | | Sleep | 11 | EOF | b60daa992bac4fe4-b29466aacce67d27 |
| 172.20.32.153 | NULL |
++------------------+------+------+---------------------+---------------------+----------+------+---------+------+-------+-----------------------------------+------------------+---------------+--------------+
```
+- `CurrentConnected`：`Yes` 表示当前会话所对应的连接。
+- `Id`：连接的唯一标识，即 Connection ID。
+- `QueryId`：Query 的唯一标识。显示最仅执行的、或正在执行的 SQL 命令的 Query Id。
-- Id 是连接的唯一标识，也可以称为 processlist_id；
-- QueryId 是 Query 的唯一标识。
+注意，在默认情况下，`SHOW PROCESSLIST` 仅显示当前会话所连接到的 FE 节点上的所有会话连接，并不会显示其他 FE 节点的会话连接。
+如果要显示所有 FE 节点的会话连接，需设置一下会话变量：
+```
+SET show_all_fe_connection=true;
+```
-## Kill 查询
+然后再执行 `SHOW PROCESSLIST` 命令，即可显示所有 FE 节点的会话连接。
-语法：
+也可以通过 `information_schema` 中的系统表查看：
-```sql
-KILL QUERY query_id | processlist_id
+```
+SELECT * FROM information_schema.processlist;
```
-用于 Kill 某一个指定的 Query，或者某一个连接上正在运行的 Query，例如：
+`processlist` 默认会显示所有 FE 节点的会话连接，不需要额外进行设置。
-```sql
-kill query 55;
-Query OK, 0 rows affected (0.01 sec)
-```
+### TRACE ID
-表示 Kill 连接 Id=55 上正在运行的 Query，但是连接仍然有效。
+> 该功能自 2.1.11 和 3.0.7 版本支持。
-```sql
-kill query 'f02603dc163a4da3-beebbb5d1ced760c';
-Query OK, 0 rows affected (0.01 sec)
+默认情况下，系统会为每个查询自动生成 Query ID。用户需先通过 `processlist` 系统表获取到 Query ID 后，再进行 KILL 操作。
+
+除此之外，用户还可以自定义 Trace ID，并通过 Trace ID 进行 KILL 操作。
+
+```
+SET session_context = "trace_id:your_trace_id"
```
-表示 Kill QueryId=f02603dc163a4da3-beebbb5d1ced760c 的 Query，与之前的
processlist_id=55 实际是同一个 Query。
+其中 `your_trace_id ` 为用户自定义的 Trace ID。可以是任意字符串，但不可以包含 `;` 符号。
-## Kill 连接
+Trace ID 是会话级别参数，仅作用于当前会话。Doris 会将之后发生在当前会话中的查询请求映射到这个 Trace ID 上。
+
+## Kill 请求
+
+`KILL` 语句支持通过取消指定的查询操作，也支持断开指定的会话连接。
+
+普通用户可以通过 `KILL` 操作取消掉自身用户发送的查询。ADMIN 用户可以取消自身和任意其他用户发送的查询。
+
+### Kill 查询
语法：
```sql
-KILL CONNECTION processlist_id
+KILL QUERY "query_id" | "trace_id" | connection_id;
```
-例如：
+`KILL QUERY` 用于取消一个指定的正在运行的查询操作。
+
+- `"query_id"`
+
+ 通过 `processlist` 系统表获取到的 Query ID。需用引号包裹。如：
+
+ `KILL QUERY "d36417cc05ff41ab-9d3afe49be251055";`
+
+ 该操作会尝试在所有 FE 节点查找 Query ID 并取消对应的查询。
+
+- `"trace_id"`
+
+ 通过 `session_context` 自定义的 Trace ID。需用引号包裹。如：
+
+ `KILL QUERY "your_trace_id";`
+
+ 该操作会尝试在所有 FE 节点查找 Trace ID 并取消对应的查询。
+
+ > 该功能自 2.1.11 和 3.0.7 版本支持。
+
+- `connection_id`
+
+ 通过 `processlist` 系统表获取到的 Connection ID。必须是一个大于 0 的整数，不可用引号包裹。如：
+
+ `KILL QUERY 55;`
+
+ 该操作仅作用于当前连接到的 FE 上的会话连接，会取消对应会话连接上正在执行的查询。
+
+### Kill 连接
+
+Kill 连接会断开指定的会话连接，同时也会取消连接上正在执行的查询操作。
+
+语法：
```sql
-kill CONNECTION 55;
-Query OK, 0 rows affected (0.01 sec)
+KILL [CONNECTION] connection_id;
```
-表示断开 Id=55 这个连接，这个连接上正在执行的 Query 也会被 Cancel。
\ No newline at end of file
+其中 `CONNECTION` 关键词可以省略。
+
+- `connection_id `
+
+ 通过 `processlist` 系统表获取到的 Connection ID。必须是一个大于 0 的整数，不可用引号包裹。如：
+
+ ```sql
+ KILL CONNECTION 55;
+ KILL 55;
+ ```
+
+ 不同 FE 上的连接 ID 可能相同，但该操作仅作用于当前连接到的 FE 上的会话连接。
+
+## 最佳实践
+
+1. 通过自定义 Trace ID 实现查询管理
+
+ 通过自定义 Trace ID 可以预先为查询指定唯一标识，方便管控工具实现【取消查询】的功能。可以通过如下方式自定义 Trace ID：
+
+ - 每次查询前设置 `session_context`
+
+ 用户自行生成 Trace ID。建议使用 UUID 以确保 Trace ID 的唯一性。
+
+ ```sql
+ SET session_context="trace_id:your_trace_id";
+ SELECT * FROM table ...;
+ ```
+
+ - 在查询语句中添加 Trace ID
+
+ ```sql
+ SELECT /*+SET_VAR(session_context=trace_id:your_trace_id)*/ *
FROM table ...;
+ ```
+
+ 之后，管控工具可以通过 Trace ID 随时取消正在执行的操作。
+
diff --git
a/versioned_docs/version-2.1/admin-manual/workload-management/kill-query.md
b/versioned_docs/version-2.1/admin-manual/workload-management/kill-query.md
index 24959b45f39..7b8701edffc 100644
--- a/versioned_docs/version-2.1/admin-manual/workload-management/kill-query.md
+++ b/versioned_docs/version-2.1/admin-manual/workload-management/kill-query.md
@@ -24,77 +24,151 @@ specific language governing permissions and limitations
under the License.
-->
-## Retrieve the List of Queries
+You can cancel currently executing operations or disconnect current connection
sessions using the `KILL` command. This document introduces related operations
and considerations.
-Syntax:
+## Getting Query Identifiers
+
+`KILL` requires a query identifier to cancel the corresponding query request.
Query identifiers include: Query ID, Connection ID, and Trace ID.
+
+You can obtain query identifiers through the following methods.
+### PROCESSLIST
+
+Through the `processlist` system table, you can get all current session
connections and query operations being executed in the connections. This
includes the Query ID and Connection ID.
```sql
-SHOW PROCESSLIST;
+mysql> SHOW PROCESSLIST;
++------------------+------+------+---------------------+---------------------+----------+------+---------+------+-------+-----------------------------------+------------------+---------------+--------------+
+| CurrentConnected | Id | User | Host | LoginTime |
Catalog | Db | Command | Time | State | QueryId |
Info | FE | CloudCluster |
++------------------+------+------+---------------------+---------------------+----------+------+---------+------+-------+-----------------------------------+------------------+---------------+--------------+
+| No | 2 | root | 172.20.32.136:54850 | 2025-05-11 10:41:52 |
internal | | Query | 6 | OK | 12ccf7f95c1c4d2c-b03fa9c652757c15 |
select sleep(20) | 172.20.32.152 | NULL |
+| Yes | 3 | root | 172.20.32.136:54862 | 2025-05-11 10:41:55 |
internal | | Query | 0 | OK | b710ed990d4144ee-8b15bb53002b7710 |
show processlist | 172.20.32.152 | NULL |
+| No | 1 | root | 172.20.32.136:47964 | 2025-05-11 10:41:54 |
internal | | Sleep | 11 | EOF | b60daa992bac4fe4-b29466aacce67d27 |
| 172.20.32.153 | NULL |
++------------------+------+------+---------------------+---------------------+----------+------+---------+------+-------+-----------------------------------+------------------+---------------+--------------+
```
-This command displays all current connections to the FE and the list of
queries being executed on each connection. For example:
+- `CurrentConnected`: `Yes` indicates the connection corresponding to the
current session.
+- `Id`: The unique identifier of the connection, i.e., Connection ID.
+- `QueryId`: The unique identifier of the Query. Displays the Query Id of the
most recently executed or currently executing SQL command.
-```sql
-SHOW PROCESSLIST;
-+------------------+------+------+--------------------+---------------------+----------+---------+---------+------+-------+-----------------------------------+---------------------------------------------------------------------------------------+
-| CurrentConnected | Id | User | Host | LoginTime |
Catalog | Db | Command | Time | State | QueryId
| Info
|
-+------------------+------+------+--------------------+---------------------+----------+---------+---------+------+-------+-----------------------------------+---------------------------------------------------------------------------------------+
-| Yes | 48 | root | 10.16.xx.xx:44834 | 2023-12-29 16:49:47 |
internal | test | Query | 0 | OK | e6e4ce9567b04859-8eeab8d6b5513e38 |
SHOW PROCESSLIST
|
-| | 50 | root | 192.168.xx.xx:52837 | 2023-12-29 16:51:34 |
internal | | Sleep | 1837 | EOF | deaf13c52b3b4a3b-b25e8254b50ff8cb |
SELECT @@session.transaction_isolation
|
-| | 51 | root | 192.168.xx.xx:52843 | 2023-12-29 16:51:35 |
internal | | Sleep | 907 | EOF | 437f219addc0404f-9befe7f6acf9a700 |
/* ApplicationName=DBeaver Ultimate 23.1.3 - Metadata */ SHOW STATUS
|
-| | 55 | root | 192.168.xx.xx:55533 | 2023-12-29 17:09:32 |
internal | test | Sleep | 271 | EOF | f02603dc163a4da3-beebbb5d1ced760c |
/* ApplicationName=DBeaver Ultimate 23.1.3 - SQLEditor <Console> */ SELECT
DATABASE() |
-| | 47 | root | 10.16.xx.xx:35678 | 2023-12-29 16:21:56 |
internal | test | Sleep | 3528 | EOF | f4944c543dc34a99-b0d0f3986c8f1c98 |
select * from test
|
-+------------------+------+------+--------------------+---------------------+----------+---------+---------+------+-------+-----------------------------------+---------------------------------------------------------------------------------------+
-5 rows in set (0.00 sec)
+Note that by default, `SHOW PROCESSLIST` only displays all session connections
on the FE node that the current session is connected to, and does not display
session connections from other FE nodes.
+
+If you want to display session connections from all FE nodes, you need to set
the following session variable:
+
+```
+SET show_all_fe_connection=true;
```
+Then execute the `SHOW PROCESSLIST` command again to display session
connections from all FE nodes.
-- Id is the unique identifier for the connection, also known as processlist_id.
-- QueryId is the unique identifier for the query.
+You can also view through the system table in `information_schema`:
+
+```
+SELECT * FROM information_schema.processlist;
+```
+By default, `processlist` displays session connections from all FE nodes
without requiring additional settings.
+### TRACE ID
-## Kill Query
+> This feature is supported since versions 2.1.11 and 3.0.7.
-Syntax:
+By default, the system automatically generates a Query ID for each query.
Users need to first obtain the Query ID through the `processlist` system table
before performing a KILL operation.
+In addition, users can also customize a Trace ID and perform KILL operations
using the Trace ID.
-```sql
-KILL QUERY query_id | processlist_id
+```
+SET session_context = "trace_id:your_trace_id";
```
-This command is used to terminate a specific query or the query being executed
on a specific connection. For example:
+Where `your_trace_id` is the user-defined Trace ID. It can be any string but
cannot contain the `;` symbol.
-```sql
-kill query 55;
-Query OK, 0 rows affected (0.01 sec)
-```
+Trace ID is a session-level parameter and only applies to the current session.
Doris will map subsequent query requests in the current session to this Trace
ID.
-This terminates the query currently running on the connection with Id=55, but
the connection itself remains active.
+## Kill Requests
-```sql
-kill query 'f02603dc163a4da3-beebbb5d1ced760c';
-Query OK, 0 rows affected (0.01 sec)
-```
+The `KILL` statement supports canceling specified query operations as well as
disconnecting specified session connections.
-This terminates the query with QueryId=f02603dc163a4da3-beebbb5d1ced760c,
which is actually the same query as the one with processlist_id=55.
+Regular users can cancel queries sent by their own user through the `KILL`
operation. ADMIN users can cancel queries sent by themselves and any other
users.
-## Kill Connection
+### Kill Query
Syntax:
-
```sql
-KILL CONNECTION processlist_id
+KILL QUERY "query_id" | "trace_id" | connection_id;
```
-For example:
+`KILL QUERY` is used to cancel a specified running query operation.
+
+- `"query_id"`
+ The Query ID obtained through the `processlist` system table. Must be
wrapped in quotes. For example:
+
+ `KILL QUERY "d36417cc05ff41ab-9d3afe49be251055";`
+
+ This operation will attempt to find the Query ID on all FE nodes and
cancel the corresponding query.
+
+- `"trace_id"`
+
+ The Trace ID customized through `session_context`. Must be wrapped in
quotes. For example:
+
+ `KILL QUERY "your_trace_id";`
+
+ This operation will attempt to find the Trace ID on all FE nodes and
cancel the corresponding query.
+
+ > This feature is supported since versions 2.1.11 and 3.0.7.
+
+- `connection_id`
+
+ The Connection ID obtained through the `processlist` system table. Must
be an integer greater than 0 and cannot be wrapped in quotes. For example:
+
+ `KILL QUERY 55;`
+
+ This operation only applies to session connections on the currently
connected FE, and will cancel the query currently being executed on the
corresponding session connection.
+
+### Kill Connection
+
+Killing a connection will disconnect the specified session connection and also
cancel any query operations being executed on the connection.
+
+Syntax:
```sql
-kill CONNECTION 55;
-Query OK, 0 rows affected (0.01 sec)
+KILL [CONNECTION] connection_id;
```
-This command disconnects the connection with Id=55, and any query currently
being executed on this connection will also be canceled.
+The `CONNECTION` keyword can be omitted.
+
+- `connection_id`
+
+ The Connection ID obtained through the `processlist` system table. Must
be an integer greater than 0 and cannot be wrapped in quotes. For example:
+
+ ```sql
+ KILL CONNECTION 55;
+ KILL 55;
+ ```
+
+ Connection IDs on different FEs may be the same, but this operation
only affects the session connection on the currently connected FE.
+
+## Best Practices
+
+1. Implementing query management through custom Trace ID
+
+ Custom Trace IDs allow you to specify unique identifiers for queries in
advance, making it easier for management system to implement the [Cancel Query]
function. You can customize Trace IDs in the following ways:
+
+ - Set `session_context` before each query
+
+ Users generate their own Trace ID. It is recommended to use
UUID to ensure the uniqueness of the Trace ID.
+
+ ```sql
+ SET session_context="trace_id:your_trace_id";
+ SELECT * FROM table ...;
+ ```
+
+ - Add Trace ID in the query statement
+
+ ```sql
+ SELECT /*+SET_VAR(session_context=trace_id:your_trace_id)*/ *
FROM table ...;
+ ```
+
+ Afterward, management system can cancel running operations at any time
using the Trace ID.
diff --git
a/versioned_docs/version-3.0/admin-manual/workload-management/kill-query.md
b/versioned_docs/version-3.0/admin-manual/workload-management/kill-query.md
index 24959b45f39..7b8701edffc 100644
--- a/versioned_docs/version-3.0/admin-manual/workload-management/kill-query.md
+++ b/versioned_docs/version-3.0/admin-manual/workload-management/kill-query.md
@@ -24,77 +24,151 @@ specific language governing permissions and limitations
under the License.
-->
-## Retrieve the List of Queries
+You can cancel currently executing operations or disconnect current connection
sessions using the `KILL` command. This document introduces related operations
and considerations.
-Syntax:
+## Getting Query Identifiers
+
+`KILL` requires a query identifier to cancel the corresponding query request.
Query identifiers include: Query ID, Connection ID, and Trace ID.
+
+You can obtain query identifiers through the following methods.
+### PROCESSLIST
+
+Through the `processlist` system table, you can get all current session
connections and query operations being executed in the connections. This
includes the Query ID and Connection ID.
```sql
-SHOW PROCESSLIST;
+mysql> SHOW PROCESSLIST;
++------------------+------+------+---------------------+---------------------+----------+------+---------+------+-------+-----------------------------------+------------------+---------------+--------------+
+| CurrentConnected | Id | User | Host | LoginTime |
Catalog | Db | Command | Time | State | QueryId |
Info | FE | CloudCluster |
++------------------+------+------+---------------------+---------------------+----------+------+---------+------+-------+-----------------------------------+------------------+---------------+--------------+
+| No | 2 | root | 172.20.32.136:54850 | 2025-05-11 10:41:52 |
internal | | Query | 6 | OK | 12ccf7f95c1c4d2c-b03fa9c652757c15 |
select sleep(20) | 172.20.32.152 | NULL |
+| Yes | 3 | root | 172.20.32.136:54862 | 2025-05-11 10:41:55 |
internal | | Query | 0 | OK | b710ed990d4144ee-8b15bb53002b7710 |
show processlist | 172.20.32.152 | NULL |
+| No | 1 | root | 172.20.32.136:47964 | 2025-05-11 10:41:54 |
internal | | Sleep | 11 | EOF | b60daa992bac4fe4-b29466aacce67d27 |
| 172.20.32.153 | NULL |
++------------------+------+------+---------------------+---------------------+----------+------+---------+------+-------+-----------------------------------+------------------+---------------+--------------+
```
-This command displays all current connections to the FE and the list of
queries being executed on each connection. For example:
+- `CurrentConnected`: `Yes` indicates the connection corresponding to the
current session.
+- `Id`: The unique identifier of the connection, i.e., Connection ID.
+- `QueryId`: The unique identifier of the Query. Displays the Query Id of the
most recently executed or currently executing SQL command.
-```sql
-SHOW PROCESSLIST;
-+------------------+------+------+--------------------+---------------------+----------+---------+---------+------+-------+-----------------------------------+---------------------------------------------------------------------------------------+
-| CurrentConnected | Id | User | Host | LoginTime |
Catalog | Db | Command | Time | State | QueryId
| Info
|
-+------------------+------+------+--------------------+---------------------+----------+---------+---------+------+-------+-----------------------------------+---------------------------------------------------------------------------------------+
-| Yes | 48 | root | 10.16.xx.xx:44834 | 2023-12-29 16:49:47 |
internal | test | Query | 0 | OK | e6e4ce9567b04859-8eeab8d6b5513e38 |
SHOW PROCESSLIST
|
-| | 50 | root | 192.168.xx.xx:52837 | 2023-12-29 16:51:34 |
internal | | Sleep | 1837 | EOF | deaf13c52b3b4a3b-b25e8254b50ff8cb |
SELECT @@session.transaction_isolation
|
-| | 51 | root | 192.168.xx.xx:52843 | 2023-12-29 16:51:35 |
internal | | Sleep | 907 | EOF | 437f219addc0404f-9befe7f6acf9a700 |
/* ApplicationName=DBeaver Ultimate 23.1.3 - Metadata */ SHOW STATUS
|
-| | 55 | root | 192.168.xx.xx:55533 | 2023-12-29 17:09:32 |
internal | test | Sleep | 271 | EOF | f02603dc163a4da3-beebbb5d1ced760c |
/* ApplicationName=DBeaver Ultimate 23.1.3 - SQLEditor <Console> */ SELECT
DATABASE() |
-| | 47 | root | 10.16.xx.xx:35678 | 2023-12-29 16:21:56 |
internal | test | Sleep | 3528 | EOF | f4944c543dc34a99-b0d0f3986c8f1c98 |
select * from test
|
-+------------------+------+------+--------------------+---------------------+----------+---------+---------+------+-------+-----------------------------------+---------------------------------------------------------------------------------------+
-5 rows in set (0.00 sec)
+Note that by default, `SHOW PROCESSLIST` only displays all session connections
on the FE node that the current session is connected to, and does not display
session connections from other FE nodes.
+
+If you want to display session connections from all FE nodes, you need to set
the following session variable:
+
+```
+SET show_all_fe_connection=true;
```
+Then execute the `SHOW PROCESSLIST` command again to display session
connections from all FE nodes.
-- Id is the unique identifier for the connection, also known as processlist_id.
-- QueryId is the unique identifier for the query.
+You can also view through the system table in `information_schema`:
+
+```
+SELECT * FROM information_schema.processlist;
+```
+By default, `processlist` displays session connections from all FE nodes
without requiring additional settings.
+### TRACE ID
-## Kill Query
+> This feature is supported since versions 2.1.11 and 3.0.7.
-Syntax:
+By default, the system automatically generates a Query ID for each query.
Users need to first obtain the Query ID through the `processlist` system table
before performing a KILL operation.
+In addition, users can also customize a Trace ID and perform KILL operations
using the Trace ID.
-```sql
-KILL QUERY query_id | processlist_id
+```
+SET session_context = "trace_id:your_trace_id";
```
-This command is used to terminate a specific query or the query being executed
on a specific connection. For example:
+Where `your_trace_id` is the user-defined Trace ID. It can be any string but
cannot contain the `;` symbol.
-```sql
-kill query 55;
-Query OK, 0 rows affected (0.01 sec)
-```
+Trace ID is a session-level parameter and only applies to the current session.
Doris will map subsequent query requests in the current session to this Trace
ID.
-This terminates the query currently running on the connection with Id=55, but
the connection itself remains active.
+## Kill Requests
-```sql
-kill query 'f02603dc163a4da3-beebbb5d1ced760c';
-Query OK, 0 rows affected (0.01 sec)
-```
+The `KILL` statement supports canceling specified query operations as well as
disconnecting specified session connections.
-This terminates the query with QueryId=f02603dc163a4da3-beebbb5d1ced760c,
which is actually the same query as the one with processlist_id=55.
+Regular users can cancel queries sent by their own user through the `KILL`
operation. ADMIN users can cancel queries sent by themselves and any other
users.
-## Kill Connection
+### Kill Query
Syntax:
-
```sql
-KILL CONNECTION processlist_id
+KILL QUERY "query_id" | "trace_id" | connection_id;
```
-For example:
+`KILL QUERY` is used to cancel a specified running query operation.
+
+- `"query_id"`
+ The Query ID obtained through the `processlist` system table. Must be
wrapped in quotes. For example:
+
+ `KILL QUERY "d36417cc05ff41ab-9d3afe49be251055";`
+
+ This operation will attempt to find the Query ID on all FE nodes and
cancel the corresponding query.
+
+- `"trace_id"`
+
+ The Trace ID customized through `session_context`. Must be wrapped in
quotes. For example:
+
+ `KILL QUERY "your_trace_id";`
+
+ This operation will attempt to find the Trace ID on all FE nodes and
cancel the corresponding query.
+
+ > This feature is supported since versions 2.1.11 and 3.0.7.
+
+- `connection_id`
+
+ The Connection ID obtained through the `processlist` system table. Must
be an integer greater than 0 and cannot be wrapped in quotes. For example:
+
+ `KILL QUERY 55;`
+
+ This operation only applies to session connections on the currently
connected FE, and will cancel the query currently being executed on the
corresponding session connection.
+
+### Kill Connection
+
+Killing a connection will disconnect the specified session connection and also
cancel any query operations being executed on the connection.
+
+Syntax:
```sql
-kill CONNECTION 55;
-Query OK, 0 rows affected (0.01 sec)
+KILL [CONNECTION] connection_id;
```
-This command disconnects the connection with Id=55, and any query currently
being executed on this connection will also be canceled.
+The `CONNECTION` keyword can be omitted.
+
+- `connection_id`
+
+ The Connection ID obtained through the `processlist` system table. Must
be an integer greater than 0 and cannot be wrapped in quotes. For example:
+
+ ```sql
+ KILL CONNECTION 55;
+ KILL 55;
+ ```
+
+ Connection IDs on different FEs may be the same, but this operation
only affects the session connection on the currently connected FE.
+
+## Best Practices
+
+1. Implementing query management through custom Trace ID
+
+ Custom Trace IDs allow you to specify unique identifiers for queries in
advance, making it easier for management system to implement the [Cancel Query]
function. You can customize Trace IDs in the following ways:
+
+ - Set `session_context` before each query
+
+ Users generate their own Trace ID. It is recommended to use
UUID to ensure the uniqueness of the Trace ID.
+
+ ```sql
+ SET session_context="trace_id:your_trace_id";
+ SELECT * FROM table ...;
+ ```
+
+ - Add Trace ID in the query statement
+
+ ```sql
+ SELECT /*+SET_VAR(session_context=trace_id:your_trace_id)*/ *
FROM table ...;
+ ```
+
+ Afterward, management system can cancel running operations at any time
using the Trace ID.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
