This is an automated email from the ASF dual-hosted git repository.
yiguolei 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 ee7e530f7d9 [doc](workload) Document BE-side username condition for
workload policy (#3931)
ee7e530f7d9 is described below
commit ee7e530f7d9ca12250533b6aee8f8f1c7ad2a35e
Author: Wen Zhenghu <[email protected]>
AuthorDate: Wed Jul 1 10:43:14 2026 +0800
[doc](workload) Document BE-side username condition for workload policy
(#3931)
Summary:
- Document that username can be used with BE-side runtime metrics to
trigger cancel_query starting from Doris 4.1.3.
- Add dev and 4.x examples in both English and Chinese.
- Clarify username only supports equality and cannot be empty.
## Versions
- [x] dev
- [x] 4.x
- [ ] 3.x
- [ ] 2.1 or older (not covered by version/language sync gate)
## Languages
- [x] Chinese
- [x] English
- [ ] Japanese candidate translation needed
## Docs Checklist
- [x] Checked by AI
- [ ] Test Cases Built
- [x] Updated required version and language counterparts, or explained
why not
- [x] If only one language changed, confirmed whether source/translation
counterparts need sync
---
docs/admin-manual/workload-management/sql-blocking.md | 17 +++++++++++++++--
.../admin-manual/workload-management/sql-blocking.md | 17 +++++++++++++++--
.../admin-manual/workload-management/sql-blocking.md | 17 +++++++++++++++--
.../admin-manual/workload-management/sql-blocking.md | 17 +++++++++++++++--
4 files changed, 60 insertions(+), 8 deletions(-)
diff --git a/docs/admin-manual/workload-management/sql-blocking.md
b/docs/admin-manual/workload-management/sql-blocking.md
index c0f7a729c99..95cc74a9630 100644
--- a/docs/admin-manual/workload-management/sql-blocking.md
+++ b/docs/admin-manual/workload-management/sql-blocking.md
@@ -221,7 +221,7 @@ 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 |
+| `username` | The username carried by the query. It can trigger the FE-side
`set_session_variable` Action. Starting from Doris 4.1.3, it can also be
combined with BE-side runtime metrics such as `query_time`, `be_scan_rows`,
`be_scan_bytes`, and `query_be_memory_bytes` to trigger `cancel_query`. This
condition only supports the equality operator (`=`), and the username cannot be
empty |
| `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) |
@@ -331,9 +331,22 @@ MySQL [(none)]> show variables like
'%parallel_fragment_exec_instance_num%';
1 row in set (0.01 sec)
```
+#### Example 3: Break Runtime Large Queries for a Specific User
+
+Starting from Doris 4.1.3, you can combine `username` with BE-side runtime
metrics to cancel only the queries of a specific user. The following policy
cancels queries submitted by `test_user` when their running time on a single BE
exceeds 3000 ms:
+
+```sql
+CREATE WORKLOAD POLICY cancel_user_long_query
+CONDITIONS(username='test_user', query_time > 3000)
+ACTIONS(cancel_query);
+```
+
+Similarly, `username` can be combined with `be_scan_rows`, `be_scan_bytes`, or
`query_be_memory_bytes` to limit the scan volume or BE memory usage of a
specific user.
+
### 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).
+- **FE/BE side isolation**: The Condition and Action of the same Policy must
belong to the same side (FE or BE). `set_session_variable` is an FE-side Action
and cannot be combined with BE-side metrics such as `query_time` or
`be_scan_rows`. `cancel_query` is a BE-side Action and can be combined with
BE-side runtime metrics.
+- **`username` condition limit**: `username` is a shared condition. It can be
used with FE-side `set_session_variable`; starting from Doris 4.1.3, it can
also be used with BE-side runtime metrics to trigger `cancel_query`. The
`username` condition only supports equality (`=`); comparison operators such as
`>`, `>=`, `<`, and `<=` are not supported. If the BE cannot obtain explicit
user information for a query, the `username` condition does not match.
- **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.
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/workload-management/sql-blocking.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/workload-management/sql-blocking.md
index 08ba3258efc..0587b236b15 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/workload-management/sql-blocking.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/workload-management/sql-blocking.md
@@ -221,7 +221,7 @@ Conditions 表示策略的触发条件，多个条件之间以逗号 `,` 分隔
| Condition | 说明 |
|-----------|------|
-| `username` | 查询携带的用户名，只会在 FE 触发 `set_session_variable` Action |
+| `username` | 查询携带的用户名。可用于 FE 侧触发 `set_session_variable` Action；自 Doris 4.1.3
版本起，也可与 `query_time`、`be_scan_rows`、`be_scan_bytes`、`query_be_memory_bytes` 等
BE 侧运行时指标组合，用于触发 `cancel_query`。该条件仅支持等值比较（`=`），用户名不能为空 |
| `be_scan_rows` | 一个 SQL 在单个 BE 进程内扫描的行数，多并发执行时为累加值 |
| `be_scan_bytes` | 一个 SQL 在单个 BE 进程内扫描的字节数，多并发执行时为累加值（单位：字节） |
| `query_time` | 一个 SQL 在单个 BE 进程上的运行时间（单位：毫秒） |
@@ -331,9 +331,22 @@ MySQL [(none)]> show variables like
'%parallel_fragment_exec_instance_num%';
1 row in set (0.01 sec)
```
+#### 示例三：按用户熔断运行时大查询
+
+自 Doris 4.1.3 版本起，可以将 `username` 与 BE 侧运行时指标组合，仅取消特定用户的查询。以下策略会在 `test_user`
提交的查询在单个 BE 上运行超过 3000 ms 时取消该查询：
+
+```sql
+CREATE WORKLOAD POLICY cancel_user_long_query
+CONDITIONS(username='test_user', query_time > 3000)
+ACTIONS(cancel_query);
+```
+
+同理，也可以将 `username` 与 `be_scan_rows`、`be_scan_bytes` 或 `query_be_memory_bytes`
组合，用于限制特定用户的扫描量或 BE 内存使用量。
+
### 注意事项
-- **FE/BE 侧隔离**：同一个 Policy 的 Condition 和 Action 必须属于同一侧（FE 或
BE）。例如，`set_session_variable`（FE 侧）和 `cancel_query`（BE 侧）不能配置在同一 Policy
中；`username`（FE 侧）和 `be_scan_rows`（BE 侧）同理。
+- **FE/BE 侧隔离**：同一个 Policy 的 Condition 和 Action 必须属于同一侧（FE 或
BE）。`set_session_variable` 是 FE 侧 Action，不能与 `query_time`、`be_scan_rows` 等 BE
侧指标组合；`cancel_query` 是 BE 侧 Action，可与 BE 侧运行时指标组合。
+- **`username` 条件限制**：`username` 是共享条件，可用于 FE 侧 `set_session_variable`；自 Doris
4.1.3 版本起，也可与 BE 侧运行时指标组合触发 `cancel_query`。`username` 条件仅支持等值比较（`=`），不支持
`>`、`>=`、`<`、`<=` 等比较操作符。如果 BE 无法获取查询明确携带的用户信息，则 `username` 条件不会匹配。
- **异步执行延迟**：Policy 由异步线程每 500 ms
执行一次检查，策略生效存在一定滞后。运行时间极短的查询可能会在检查触发前已完成，从而绕过策略。
- **优先级机制**：一个查询可能匹配多个 Policy，但只有优先级最高（`priority` 值最大）的 Policy 会生效。
- **修改限制**：目前不支持直接修改已有 Policy 的 Action 和 Condition，需删除后重新创建。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/admin-manual/workload-management/sql-blocking.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/admin-manual/workload-management/sql-blocking.md
index 626b91a492b..9f64d42f702 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/admin-manual/workload-management/sql-blocking.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/admin-manual/workload-management/sql-blocking.md
@@ -238,7 +238,7 @@ Conditions 表示策略的触发条件，多个条件之间以逗号 `,` 分隔
| Condition | 说明 |
|-----------|------|
-| `username` | 查询携带的用户名，只会在 FE 触发 `set_session_variable` Action |
+| `username` | 查询携带的用户名。可用于 FE 侧触发 `set_session_variable` Action；自 Doris 4.1.3
版本起，也可与 `query_time`、`be_scan_rows`、`be_scan_bytes`、`query_be_memory_bytes` 等
BE 侧运行时指标组合，用于触发 `cancel_query`。该条件仅支持等值比较（`=`），用户名不能为空 |
| `be_scan_rows` | 一个 SQL 在单个 BE 进程内扫描的行数，多并发执行时为累加值 |
| `be_scan_bytes` | 一个 SQL 在单个 BE 进程内扫描的字节数，多并发执行时为累加值（单位：字节） |
| `query_time` | 一个 SQL 在单个 BE 进程上的运行时间（单位：毫秒） |
@@ -348,9 +348,22 @@ MySQL [(none)]> show variables like
'%parallel_fragment_exec_instance_num%';
1 row in set (0.01 sec)
```
+#### 示例三：按用户熔断运行时大查询
+
+自 Doris 4.1.3 版本起，可以将 `username` 与 BE 侧运行时指标组合，仅取消特定用户的查询。以下策略会在 `test_user`
提交的查询在单个 BE 上运行超过 3000 ms 时取消该查询：
+
+```sql
+CREATE WORKLOAD POLICY cancel_user_long_query
+CONDITIONS(username='test_user', query_time > 3000)
+ACTIONS(cancel_query);
+```
+
+同理，也可以将 `username` 与 `be_scan_rows`、`be_scan_bytes` 或 `query_be_memory_bytes`
组合，用于限制特定用户的扫描量或 BE 内存使用量。
+
### 注意事项
-- **FE/BE 侧隔离**：同一个 Policy 的 Condition 和 Action 必须属于同一侧（FE 或
BE）。例如，`set_session_variable`（FE 侧）和 `cancel_query`（BE 侧）不能配置在同一 Policy
中；`username`（FE 侧）和 `be_scan_rows`（BE 侧）同理。
+- **FE/BE 侧隔离**：同一个 Policy 的 Condition 和 Action 必须属于同一侧（FE 或
BE）。`set_session_variable` 是 FE 侧 Action，不能与 `query_time`、`be_scan_rows` 等 BE
侧指标组合；`cancel_query` 是 BE 侧 Action，可与 BE 侧运行时指标组合。
+- **`username` 条件限制**：`username` 是共享条件，可用于 FE 侧 `set_session_variable`；自 Doris
4.1.3 版本起，也可与 BE 侧运行时指标组合触发 `cancel_query`。`username` 条件仅支持等值比较（`=`），不支持
`>`、`>=`、`<`、`<=` 等比较操作符。如果 BE 无法获取查询明确携带的用户信息，则 `username` 条件不会匹配。
- **异步执行延迟**：Policy 由异步线程每 500 ms
执行一次检查，策略生效存在一定滞后。运行时间极短的查询可能会在检查触发前已完成，从而绕过策略。
- **优先级机制**：一个查询可能匹配多个 Policy，但只有优先级最高（`priority` 值最大）的 Policy 会生效。
- **修改限制**：目前不支持直接修改已有 Policy 的 Action 和 Condition，需删除后重新创建。
diff --git
a/versioned_docs/version-4.x/admin-manual/workload-management/sql-blocking.md
b/versioned_docs/version-4.x/admin-manual/workload-management/sql-blocking.md
index 2c07945ffe5..f7813a2fe12 100644
---
a/versioned_docs/version-4.x/admin-manual/workload-management/sql-blocking.md
+++
b/versioned_docs/version-4.x/admin-manual/workload-management/sql-blocking.md
@@ -238,7 +238,7 @@ 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 |
+| `username` | The username carried by the query. It can trigger the FE-side
`set_session_variable` Action. Starting from Doris 4.1.3, it can also be
combined with BE-side runtime metrics such as `query_time`, `be_scan_rows`,
`be_scan_bytes`, and `query_be_memory_bytes` to trigger `cancel_query`. This
condition only supports the equality operator (`=`), and the username cannot be
empty |
| `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) |
@@ -348,9 +348,22 @@ MySQL [(none)]> show variables like
'%parallel_fragment_exec_instance_num%';
1 row in set (0.01 sec)
```
+#### Example 3: Break Runtime Large Queries for a Specific User
+
+Starting from Doris 4.1.3, you can combine `username` with BE-side runtime
metrics to cancel only the queries of a specific user. The following policy
cancels queries submitted by `test_user` when their running time on a single BE
exceeds 3000 ms:
+
+```sql
+CREATE WORKLOAD POLICY cancel_user_long_query
+CONDITIONS(username='test_user', query_time > 3000)
+ACTIONS(cancel_query);
+```
+
+Similarly, `username` can be combined with `be_scan_rows`, `be_scan_bytes`, or
`query_be_memory_bytes` to limit the scan volume or BE memory usage of a
specific user.
+
### 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).
+- **FE/BE side isolation**: The Condition and Action of the same Policy must
belong to the same side (FE or BE). `set_session_variable` is an FE-side Action
and cannot be combined with BE-side metrics such as `query_time` or
`be_scan_rows`. `cancel_query` is a BE-side Action and can be combined with
BE-side runtime metrics.
+- **`username` condition limit**: `username` is a shared condition. It can be
used with FE-side `set_session_variable`; starting from Doris 4.1.3, it can
also be used with BE-side runtime metrics to trigger `cancel_query`. The
`username` condition only supports equality (`=`); comparison operators such as
`>`, `>=`, `<`, and `<=` are not supported. If the BE cannot obtain explicit
user information for a query, the `username` condition does not match.
- **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.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
