Skip to content

[fix](kill) opt kill query doc #2371

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Merged
morningman merged 2 commits into from
May 26, 2025
Merged

[fix](kill) opt kill query doc #2371

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
af0cc4b
[fix](kill) opt kill query doc
morningman May 11, 2025
fc2bc30
fix version
morningman May 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
154 changes: 114 additions & 40 deletions docs/admin-manual/workload-management/kill-query.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
157 changes: 118 additions & 39 deletions ...urus-plugin-content-docs/current/admin-manual/workload-management/kill-query.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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。
其中 `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 随时取消正在执行的操作。

Loading