Skip to content

[Docs] Remove obsolete Workload Policy session-variable references #3959

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

Open
feiniaofeiafei wants to merge 2 commits into
base: master
Choose a base branch
from
Open

[Docs] Remove obsolete Workload Policy session-variable references #3959

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
948974f
remove cn and en
feiniaofeiafei Jun 29, 2026
7eef1e6
add ja
feiniaofeiafei Jun 29, 2026
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
34 changes: 1 addition & 33 deletions docs/admin-manual/workload-management/sql-blocking.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -221,20 +221,18 @@ Conditions specify when the policy is triggered. Multiple conditions are separat

| Condition | Description |
|-----------|------|
| `username` | The username carried by the query. Only triggers the `set_session_variable` Action on the FE |
| `be_scan_rows` | The number of rows scanned by a SQL within a single BE process. Cumulative value under concurrent execution |
| `be_scan_bytes` | The number of bytes scanned by a SQL within a single BE process. Cumulative value under concurrent execution (unit: bytes) |
| `query_time` | The execution time of a SQL on a single BE process (unit: milliseconds) |
| `query_be_memory_bytes` | The memory used by a SQL within a single BE process. Cumulative value under concurrent execution (unit: bytes) |

#### Actions

Actions specify what to do when the conditions are triggered. Currently, a Policy can define only one Action (except for `set_session_variable`).
Actions specify what to do when the conditions are triggered. Currently, a Policy can define only one Action.

| Action | Description |
|--------|------|
| `cancel_query` | Cancel the query |
| `set_session_variable` | Execute a set session variable statement. The same Policy can include multiple of these options. Currently, this is only triggered on the FE by the `username` Condition |

#### Policy Properties

Expand Down Expand Up @@ -302,38 +300,8 @@ MySQL [hits]> SELECT REGEXP_REPLACE(Referer, '^https?://(?:www\\.)?([^/]+)/.*$',
ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[CANCELLED]query cancelled by workload policy,id:12345
```

#### Example 2: Automatically Adjust User Session Variables

Workload Policy can automatically modify session variables for a specific user, for example, lowering concurrency to reduce resource consumption:

```sql
-- Check the current concurrency parameter for the admin user
MySQL [(none)]> show variables like '%parallel_fragment_exec_instance_num%';
+-------------------------------------+-------+---------------+---------+
| Variable_name | Value | Default_Value | Changed |
+-------------------------------------+-------+---------------+---------+
| parallel_fragment_exec_instance_num | 8 | 8 | 0 |
+-------------------------------------+-------+---------------+---------+
1 row in set (0.00 sec)

-- Create a policy: set the concurrency parameter for the admin user to 1
CREATE WORKLOAD POLICY test_set_var_policy
CONDITIONS(username='admin')
ACTIONS(set_session_variable 'parallel_fragment_exec_instance_num=1');

-- Check again later, the parameter has taken effect
MySQL [(none)]> show variables like '%parallel_fragment_exec_instance_num%';
+-------------------------------------+-------+---------------+---------+
| Variable_name | Value | Default_Value | Changed |
+-------------------------------------+-------+---------------+---------+
| parallel_fragment_exec_instance_num | 1 | 8 | 1 |
+-------------------------------------+-------+---------------+---------+
1 row in set (0.01 sec)
```

### Notes

- **FE/BE side isolation**: The Condition and Action of the same Policy must belong to the same side (FE or BE). For example, `set_session_variable` (FE side) and `cancel_query` (BE side) cannot be configured in the same Policy. The same applies to `username` (FE side) and `be_scan_rows` (BE side).
- **Asynchronous execution latency**: Policies are checked by an asynchronous thread every 500 ms, so policy enforcement has some lag. Queries that run for a very short time may complete before the check is triggered and bypass the policy.
- **Priority mechanism**: A query may match multiple Policies, but only the one with the highest priority (largest `priority` value) takes effect.
- **Modification limit**: Currently, directly modifying the Action and Condition of an existing Policy is not supported. Delete the Policy and recreate it.
1 change: 0 additions & 1 deletion .../sql-statements/cluster-management/compute-management/CREATE-WORKLOAD-POLICY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,6 @@ CONDITIONS(<conditions>) ACTIONS(<actions>)
- query_be_memory_bytes: Supported since version 2.1.5. The memory usage of a SQL within a single BE process. If the SQL is executed with multiple concurrencies on the BE, this is the cumulative value of the concurrent executions, in bytes.

3. `<actions>`
- set_session_variable: This action executes a `set_session_variable` statement. A single Policy may contain multiple `set_session_variable` actions, allowing one Policy to execute multiple session-variable updates.
- cancel_query: Cancel the query.

## Optional Parameters
Expand Down
34 changes: 1 addition & 33 deletions ...us-plugin-content-docs/current/admin-manual/workload-management/sql-blocking.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -221,20 +221,18 @@ Conditions 表示策略的触发条件，多个条件之间以逗号 `,` 分隔

| Condition | 说明 |
|-----------|------|
| `username` | 查询携带的用户名，只会在 FE 触发 `set_session_variable` Action |
| `be_scan_rows` | 一个 SQL 在单个 BE 进程内扫描的行数，多并发执行时为累加值 |
| `be_scan_bytes` | 一个 SQL 在单个 BE 进程内扫描的字节数，多并发执行时为累加值（单位：字节） |
| `query_time` | 一个 SQL 在单个 BE 进程上的运行时间（单位：毫秒） |
| `query_be_memory_bytes` | 一个 SQL 在单个 BE 进程内使用的内存量，多并发执行时为累加值（单位：字节） |

#### 执行动作（Actions）

Actions 表示条件触发时采取的动作。目前一个 Policy 只能定义一个 Action（`set_session_variable` 除外）。
Actions 表示条件触发时采取的动作。目前一个 Policy 只能定义一个 Action。

| Action | 说明 |
|--------|------|
| `cancel_query` | 取消查询 |
| `set_session_variable` | 执行 set session variable 语句；同一个 Policy 可包含多个该选项，目前只会在 FE 由 `username` Condition 触发 |

#### 策略属性（Properties）

Expand Down Expand Up @@ -302,38 +300,8 @@ MySQL [hits]> SELECT REGEXP_REPLACE(Referer, '^https?://(?:www\\.)?([^/]+)/.*$',
ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[CANCELLED]query cancelled by workload policy,id:12345
```

#### 示例二：自动调整用户 Session 变量

通过 Workload Policy 可自动修改特定用户的 session 变量，例如降低其并发度以减少资源占用：

```sql
-- 查看 admin 用户当前并发参数
MySQL [(none)]> show variables like '%parallel_fragment_exec_instance_num%';
+-------------------------------------+-------+---------------+---------+
| Variable_name | Value | Default_Value | Changed |
+-------------------------------------+-------+---------------+---------+
| parallel_fragment_exec_instance_num | 8 | 8 | 0 |
+-------------------------------------+-------+---------------+---------+
1 row in set (0.00 sec)

-- 创建策略：将 admin 用户的并发参数调整为 1
CREATE WORKLOAD POLICY test_set_var_policy
CONDITIONS(username='admin')
ACTIONS(set_session_variable 'parallel_fragment_exec_instance_num=1');

-- 稍后再次查看，参数已生效
MySQL [(none)]> show variables like '%parallel_fragment_exec_instance_num%';
+-------------------------------------+-------+---------------+---------+
| Variable_name | Value | Default_Value | Changed |
+-------------------------------------+-------+---------------+---------+
| parallel_fragment_exec_instance_num | 1 | 8 | 1 |
+-------------------------------------+-------+---------------+---------+
1 row in set (0.01 sec)
```

### 注意事项

- **FE/BE 侧隔离**：同一个 Policy 的 Condition 和 Action 必须属于同一侧（FE 或 BE）。例如，`set_session_variable`（FE 侧）和 `cancel_query`（BE 侧）不能配置在同一 Policy 中；`username`（FE 侧）和 `be_scan_rows`（BE 侧）同理。
- **异步执行延迟**：Policy 由异步线程每 500 ms 执行一次检查，策略生效存在一定滞后。运行时间极短的查询可能会在检查触发前已完成，从而绕过策略。
- **优先级机制**：一个查询可能匹配多个 Policy，但只有优先级最高（`priority` 值最大）的 Policy 会生效。
- **修改限制**：目前不支持直接修改已有 Policy 的 Action 和 Condition，需删除后重新创建。
3 changes: 1 addition & 2 deletions .../sql-statements/cluster-management/compute-management/CREATE-WORKLOAD-POLICY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,6 @@ CONDITIONS(<conditions>) ACTIONS(<actions>)
- query_be_memory_bytes，从 2.1.5 版本开始支持。一个 SQL 在单个 BE 进程内使用的内存用量，如果这个 SQL 在 BE 上是多并发执行，那么就是多个并发的累加值，单位是字节。

3. `<actions>`
- set_session_variable，这个 Action 可以执行一条 `set_session_variable` 的语句。同一个 Policy 可以有多个 `set_session_variable`，也就是说一个 Policy 可以执行多个修改 session 变量的语句。
- cancel_query，取消查询。

## 可选参数
Expand Down Expand Up @@ -70,4 +69,4 @@ CONDITIONS(<conditions>) ACTIONS(<actions>)

```Java
create workload policy kill_big_query conditions(query_time > 3000) actions(cancel_query) properties('workload_group'='compute_group_a.wg1')
```
```
36 changes: 2 additions & 34 deletions ...lugin-content-docs/version-2.1/admin-manual/workload-management/sql-blocking.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -235,18 +235,16 @@ properties('enabled'='true');

| Conditions | 说明 |
|-----------------------|---------------------------------------------------------------------|
| username | 查询携带的用户名，只会在 FE 触发 set_session_variable Action |
| be_scan_rows | 一个 SQL 在单个 BE 进程内 scan 的行数，如果这个 SQL 在 BE 上是多并发执行，那么就是多个并发的累加值。 |
| be_scan_bytes | 一个 SQL 在单个 BE 进程内 scan 的字节数，如果这个 SQL 在 BE 上是多并发执行，那么就是多个并发的累加值，单位是字节。 |
| query_time | 一个 SQL 在单个 BE 进程上的运行时间，时间单位是毫秒。 |
| query_be_memory_bytes | 一个 SQL 在单个 BE 进程内使用的内存用量，如果这个 SQL 在 BE 上是多并发执行，那么就是多个并发的累加值，单位是字节。 |

- Action 表示条件触发时采取的动作，目前一个 Policy 只能定义一个 Action（除 set_session_variable）。在上例中，cancel_query 表示取消查询；目前支持的 Actions 有：
- Action 表示条件触发时采取的动作，目前一个 Policy 只能定义一个 Action。在上例中，cancel_query 表示取消查询；目前支持的 Actions 有：

| Actions | 说明 |
|-----------------------|------------------------------------------------------------------------------------------------------|
| cancel_query | 取消查询。 |
| set_session_variable | 触发 set session variable 语句。同一个 policy 可以有多个 set_session_variable 选项，目前只会在 FE 由 username Condition 触发 |


- Properties，定义了当前 Policy 的属性，包括是否启用和优先级。
Expand All @@ -268,43 +266,14 @@ properties('workload_group'='normal')
```

### 注意事项
- 同一个 Policy 的 Condition 和 Action 要么都是 FE 的，要么都是 BE 的，比如 set_session_variable 和 cancel_query 无法配置到同一个 Policy 中。Condition be_scan_rows 和 Condition username 无法配置到同一个 Policy 中。
- 由于目前的 Policy 是异步线程以固定时间间隔执行的，因此策略的生效存在一定的滞后性。比如用户配置了 scan 行数大于 100 万就取消查询的策略，如果此时集群资源比较空闲，那么有可能在取消策略生效之前查询就已经结束了。目前这个时间间隔为 500ms，这意味着运行时间过短的查询可能会绕过策略的检查。
- 当前支持的负载类型包括 select/insert select/stream load/broker load/routine load。
- 一个查询可能匹配到多个 Policy，但是只有优先级最高的 Policy 会生效。
- 目前不支持 Action 和 Condition 的修改，只能通过删除新建的方式修改。

### Workload Policy 效果演示

#### 1 session 变量修改测试
尝试修改 Admin 账户的 session 变量中的并发相关的参数

```sql
// 登录 admin账户查看并发参数
mySQL [(none)]>show variables like '%parallel_fragment_exec_instance_num%';
+-------------------------------------+-------+---------------+---------+
| Variable_name | Value | Default_Value | Changed |
+-------------------------------------+-------+---------------+---------+
| parallel_fragment_exec_instance_num | 8 | 8 | 0 |
+-------------------------------------+-------+---------------+---------+
1 row in set (0.00 sec)

// 创建修改admin账户并发参数的Policy
create workload Policy test_set_var_Policy
Conditions(username='admin')
Actions(set_session_variable 'parallel_fragment_exec_instance_num=1')

// 过段时间后再次查看admin账户的参数
mySQL [(none)]>show variables like '%parallel_fragment_exec_instance_num%';
+-------------------------------------+-------+---------------+---------+
| Variable_name | Value | Default_Value | Changed |
+-------------------------------------+-------+---------------+---------+
| parallel_fragment_exec_instance_num | 1 | 8 | 1 |
+-------------------------------------+-------+---------------+---------+
1 row in set (0.01 sec)
```

#### 2 大查询熔断测试
#### 大查询熔断测试
测试对运行时间超过 3s 的查询进行熔断，以下是一个 ckbench 的 q29 运行成功时的审计日志，可以看到这个 SQL 跑完需要 4.5s 的时间

```sql
Expand Down Expand Up @@ -339,4 +308,3 @@ Actions(cancel_query)
mySQL [hits]>SELECT REGEXP_REPLACE(Referer, '^https?://(?:www\.)?([^/]+)/.*$', '\1') AS k, AVG(length(Referer)) AS l, COUNT(*) AS c, MIN(Referer) FROM hits WHERE Referer <> '' GROUP BY k HAVING COUNT(*) > 100000 ORDER BY l DESC LIMIT 25;
ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[CANCELLED]query cancelled by workload Policy,id:12345
```

3 changes: 1 addition & 2 deletions .../sql-statements/cluster-management/compute-management/CREATE-WORKLOAD-POLICY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,6 @@ CONDITIONS(<conditions>) ACTIONS(<actions>)
- query_be_memory_bytes，从 2.1.5 版本开始支持。一个 SQL 在单个 BE 进程内使用的内存用量，如果这个 SQL 在 BE 上是多并发执行，那么就是多个并发的累加值，单位是字节。

3. `<actions>`
- set_session_variable，这个 Action 可以执行一条 `set_session_variable` 的语句。同一个 Policy 可以有多个 `set_session_variable`，也就是说一个 Policy 可以执行多个修改 session 变量的语句。
- cancel_query，取消查询。

## 可选参数
Expand All @@ -55,4 +54,4 @@ CONDITIONS(<conditions>) ACTIONS(<actions>)

```Java
create workload policy kill_big_query conditions(query_time > 3000) actions(cancel_query) properties('enabled'='false')
```
```
34 changes: 1 addition & 33 deletions ...lugin-content-docs/version-3.x/admin-manual/workload-management/sql-blocking.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -189,20 +189,18 @@ Conditions 表示策略的触发条件，多个 Condition 之间以逗号 `,`

| Condition | 说明 |
|-----------------------|-----------------------------------------------------------------------------------------------|
| username | 查询携带的用户名，只会在 FE 触发 set_session_variable Action |
| be_scan_rows | 一个 SQL 在单个 BE 进程内 scan 的行数，多并发执行时为累加值 |
| be_scan_bytes | 一个 SQL 在单个 BE 进程内 scan 的字节数，多并发执行时为累加值，单位是字节 |
| query_time | 一个 SQL 在单个 BE 进程上的运行时间，单位是毫秒 |
| query_be_memory_bytes | 一个 SQL 在单个 BE 进程内使用的内存用量，多并发执行时为累加值，单位是字节 |

#### 执行动作（Actions）

Actions 表示条件触发时采取的动作，目前一个 Policy 只能定义一个 Action（set_session_variable 除外）。
Actions 表示条件触发时采取的动作，目前一个 Policy 只能定义一个 Action。

| Action | 说明 |
|----------------------|------------------------------------------------------------------------------------------------------------|
| cancel_query | 取消查询 |
| set_session_variable | 触发 set session variable 语句。同一个 Policy 可以有多个 set_session_variable 选项，目前只会在 FE 由 username Condition 触发 |

#### 策略属性（Properties）

Expand Down Expand Up @@ -264,38 +262,8 @@ MySQL [hits]> SELECT REGEXP_REPLACE(Referer, '^https?://(?:www\\.)?([^/]+)/.*$',
ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[CANCELLED]query cancelled by workload policy,id:12345
```

#### 示例二：修改用户 session 变量

通过 Workload Policy 可以自动修改特定用户的 session 变量，例如调整并发参数：

```sql
-- 登录 admin 账户查看并发参数
MySQL [(none)]> show variables like '%parallel_fragment_exec_instance_num%';
+-------------------------------------+-------+---------------+---------+
| Variable_name | Value | Default_Value | Changed |
+-------------------------------------+-------+---------------+---------+
| parallel_fragment_exec_instance_num | 8 | 8 | 0 |
+-------------------------------------+-------+---------------+---------+
1 row in set (0.00 sec)

-- 创建修改 admin 账户并发参数的 Policy
CREATE WORKLOAD POLICY test_set_var_policy
CONDITIONS(username='admin')
ACTIONS(set_session_variable 'parallel_fragment_exec_instance_num=1')

-- 过段时间后再次查看 admin 账户的参数
MySQL [(none)]> show variables like '%parallel_fragment_exec_instance_num%';
+-------------------------------------+-------+---------------+---------+
| Variable_name | Value | Default_Value | Changed |
+-------------------------------------+-------+---------------+---------+
| parallel_fragment_exec_instance_num | 1 | 8 | 1 |
+-------------------------------------+-------+---------------+---------+
1 row in set (0.01 sec)
```

### 注意事项

- 同一个 Policy 的 Condition 和 Action 必须属于同一侧（FE 或 BE）。例如，set_session_variable 和 cancel_query 无法配置到同一个 Policy 中；Condition be_scan_rows 和 Condition username 也无法配置到同一个 Policy 中。
- Policy 由异步线程以固定时间间隔（当前为 500 ms）执行，因此策略生效存在一定滞后性。运行时间过短的查询可能会绕过策略检查。
- 一个查询可能匹配到多个 Policy，但只有优先级最高的 Policy 会生效。
- 目前不支持直接修改 Action 和 Condition，只能通过删除后重新创建的方式修改。
3 changes: 1 addition & 2 deletions .../sql-statements/cluster-management/compute-management/CREATE-WORKLOAD-POLICY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,6 @@ CONDITIONS(<conditions>) ACTIONS(<actions>)
- query_be_memory_bytes，从 2.1.5 版本开始支持。一个 SQL 在单个 BE 进程内使用的内存用量，如果这个 SQL 在 BE 上是多并发执行，那么就是多个并发的累加值，单位是字节。

3. `<actions>`
- set_session_variable，这个 Action 可以执行一条 `set_session_variable` 的语句。同一个 Policy 可以有多个 `set_session_variable`，也就是说一个 Policy 可以执行多个修改 session 变量的语句。
- cancel_query，取消查询。

## 可选参数
Expand All @@ -55,4 +54,4 @@ CONDITIONS(<conditions>) ACTIONS(<actions>)

```Java
create workload policy kill_big_query conditions(query_time > 3000) actions(cancel_query) properties('enabled'='false')
```
```
Loading