You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@doris.apache.org by mo...@apache.org on 2026/03/24 07:04:31 UTC
(doris-website) branch master updated: [opt] opt sql block rule doc (#3485)
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 55c6e7ed383 [opt] opt sql block rule doc (#3485)
55c6e7ed383 is described below
commit 55c6e7ed38325ed9a1846b1e1837a28e2eada6b1
Author: Mingyu Chen (Rayner) <mo...@163.com>
AuthorDate: Tue Mar 24 00:04:25 2026 -0700
[opt] opt sql block rule doc (#3485)
## Versions
- [x] dev
- [x] 4.x
- [x] 3.x
- [ ] 2.1
## Languages
- [x] Chinese
- [x] English
## Docs Checklist
- [ ] Checked by AI
- [ ] Test Cases Built
---
.../workload-management/sql-blocking.md | 388 +++++++++-----------
.../workload-management/sql-blocking.md | 391 +++++++++------------
.../workload-management/sql-blocking.md | 391 +++++++++------------
.../workload-management/sql-blocking.md | 391 +++++++++------------
.../workload-management/sql-blocking.md | 388 +++++++++-----------
.../workload-management/sql-blocking.md | 388 +++++++++-----------
6 files changed, 1041 insertions(+), 1296 deletions(-)
diff --git a/docs/admin-manual/workload-management/sql-blocking.md b/docs/admin-manual/workload-management/sql-blocking.md
index ff93fb5ee0b..bb42e1c8a98 100644
--- a/docs/admin-manual/workload-management/sql-blocking.md
+++ b/docs/admin-manual/workload-management/sql-blocking.md
@@ -2,116 +2,43 @@
{
"title": "Query Circuit Breaker",
"language": "en",
- "description": "Query circuit breaking is a protective mechanism used to prevent long-running or resource-consuming queries from having a negative impact on the "
+ "description": "Apache Doris query circuit breaker mechanism, supporting SQL Block Rule (planning-time blocking) and Workload Policy (runtime circuit breaking) strategies to automatically terminate abnormal queries by limiting scan rows, partitions, execution time, memory, and more to ensure cluster stability."
}
---
Query circuit breaking is a protective mechanism used to prevent long-running or resource-consuming queries from having a negative impact on the system. When a query exceeds predefined resource or time limits, the circuit breaker mechanism automatically terminates the query to avoid adverse effects on system performance, resource usage, and other queries. This mechanism ensures the stability of the cluster in a multi-user environment, preventing a single query from exhausting system reso [...]
-In Doris, there are two types of circuit breaker strategies:
+Doris provides two circuit breaker strategies that operate at different stages of the query lifecycle:
-- **Planning-time circuit breaking**, namely **SQL Block Rule**, which is used to prevent the execution of statements that match specific patterns. Block rules apply to any statements, including DDL and DML. Typically, block rules are configured by database administrators (DBAs) to enhance cluster stability. For example,
-
- - Preventing a query from scanning too many rows of data
- - Preventing a query from scanning too many partitions
- - Preventing a statement that modifies global variables to avoid accidental changes to cluster configurations.
- - Preventing a query pattern that typically consumes excessive resources
-
-- **Runtime circuit breaking**, namely **Workload Policy**, which monitors in real-time during runtime the execution time of queries, the amount of data scanned, and memory consumption to implement rule-based query circuit breaking.
+| Dimension | SQL Block Rule (Planning-time) | Workload Policy (Runtime) |
+|-----------|-------------------------------|--------------------------|
+| Effective Stage | Planning phase, blocked before execution | Execution phase, circuit broken during runtime |
+| Judgment Basis | Estimated scan volume, SQL pattern matching | Real-time metrics such as execution time, memory usage, and scan volume |
+| Accuracy | Based on cost estimation, may have false positives | Based on real-time monitoring, more accurate |
+| Use Cases | Block known dangerous SQL patterns and full table scans | Circuit break unexpectedly large queries during execution |
+| Applicable Statements | Any statement (DDL, DML) | select, insert into select, stream load, routine load |
## SQL Block Rule
-According to the block pattern, it can be divided into:
-
-- Scan row count block rule
-- Scan partition count block rule
-- Scan bucket count block rule
-- Query statement regex matching block rule
-- Query statement hash value matching block rule
-
-Blocking rules can be categorized according to the scope of blocking into:
-
-- Global-level blocking rules
-- User-level blocking rules
-
-### Usage
-
-#### Global-level blocking rules
-
-```sql
-CREATE SQL_BLOCK_RULE rule_001
-PROPERTIES (
- "sql"="select \\* from t",
- "global" = "true",
- "enable" = "true"
-)
-```
-
-In this way, we have created a global-level blocking rule. The rule is named rule_001. A query statement regex matching rule has been configured to block all query statements that match the regex `select \\* from t`.
+SQL Block Rule is used to block statements that match specific patterns during the query planning phase. It is typically configured by database administrators (DBAs) to enhance cluster stability.
-Since this is a global-level blocking rule, any user executing statements that match the above regex will be blocked. For example:
+Each rule is defined by the following properties that control its behavior and scope:
-```sql
-MySQL root@127.0.0.1:test> select * from t;
-(1105, 'errCode = 2, detailMessage = errCode = 2, detailMessage = SQL match regex SQL block rule: rule_001')
-```
-
-#### User-level Blocking Rule
+| Property | Description | Values |
+|----------|-------------|--------|
+| `sql` | Regular expression to match query statements | Java regex string |
+| `sqlHash` | Hash value to match query statements | SQL hash value string |
+| `cardinality` | Maximum number of rows allowed to scan | Positive integer |
+| `partition_num` | Maximum number of partitions allowed to scan | Positive integer |
+| `tablet_num` | Maximum number of buckets allowed to scan | Positive integer |
+| `global` | Whether the rule is global | `"true"` (applies to all users) or `"false"` (applies only to bound users) |
+| `enable` | Whether the rule is enabled | `"true"` or `"false"` |
-```sql
-CREATE SQL_BLOCK_RULE rule_001
-PROPERTIES (
- "sql"="select * from t",
- "global" = "false",
- "enable" = "true"
-)
-```
+### Use Cases and Examples
-Unlike global-level blocking rules, user-level blocking rules only apply to specified users. When we create a blocking rule, set the property "global" to "false". Then, this blocking rule will be considered a user-level blocking rule.
+#### Case 1: Limiting Scan Row Count
-To make user-level blocking rules effective, you also need to set the corresponding properties for the users who need to use this rule. For example:
-
-```sql
-set property for 'root' 'SQL_block_rules' = 'rule_001';
-```
-
-Thus, after the above configuration, when the root user executes a query, the blocking rule named rule_001 will be applied.
-
-```sql
-MySQL root@127.0.0.1:test> set property for 'root' 'SQL_block_rules' = '';
-Query OK, 0 rows affected
-Time: 0.018s
-MySQL root@127.0.0.1:test> select * from t;
-+----+----+
-| id | c1 |
-+----+----+
-| 1 | 1 |
-+----+----+
-
-1 row in set
-Time: 0.027s
-MySQL root@127.0.0.1:test> set property for 'root' 'SQL_block_rules' = 'rule_001';
-Query OK, 0 rows affected
-Time: 0.008s
-MySQL root@127.0.0.1:test> select * from t;
-(1105, 'errCode = 2, detailMessage = errCode = 2, detailMessage = SQL match regex SQL block rule: rule_001')
-```
-- If you want to add multiple user-level blocking rules for a user, list all the rule names in the rule list, separated by commas.
-- If you want to remove all user-level blocking rules for a user, set the rule list to an empty string.
-
-#### Other Operations
-If you need to modify or delete blocking rules, refer to the SQL manual for blocking rules.
-
-### Use Cases
-You can use the following scenarios:
-
-* Blocking scans that exceed a specified number of rows
-* Blocking scans that exceed a specified number of partitions
-* Blocking scans that exceed a specified number of buckets
-* Blocking queries with specific patterns
-
-#### Blocking Scans that Exceed a Specified Number of Rows
-Scanning data significantly consumes BE's IO and CPU resources. Therefore, unnecessary data scans pose a substantial challenge to cluster stability. In daily use, blind full table scan operations often occur, such as `SELECT * FROM t`. To prevent such queries from damaging the cluster, you can set an upper limit on the number of rows scanned by a single query on a single table.
+In daily use, blind full table scan operations often occur, such as `SELECT * FROM t`. Scanning data significantly consumes BE's IO and CPU resources, posing a substantial challenge to cluster stability. You can set an upper limit on the number of rows scanned by a single query on a single table to prevent such operations:
```sql
CREATE SQL_BLOCK_RULE rule_card
@@ -123,12 +50,11 @@ PROPERTIES
);
```
-When the above rules are set, if a single table scan exceeds 1000 rows, the execution of the query is prohibited.
-It should be noted that since the calculation of the number of rows scanned is done during the planning phase, not the execution phase. Therefore, when calculating the number of rows, only partition and bucket pruning are considered, and the impact of other filtering conditions on the number of rows scanned is not taken into account. In other words, the worst-case scenario is considered. Therefore, queries where the actual number of rows scanned is less than the set value may also be blocked.
+When a single table scan exceeds 1000 rows, the query execution will be blocked.
-#### Prevent Scanning Data from Exceeding the Specified Number of Partitions
-Scanning too many partitions can significantly increase the CPU consumption of BE. Additionally, if the query is on an external table, it is more likely to incur significant network overhead and metadata retrieval overhead. In daily use, this is often due to forgetting to write filtering conditions on partition columns or writing them incorrectly. To prevent such queries from damaging the cluster, you can set an upper limit on the number of partitions scanned by a single query on a singl [...]
+#### Case 2: Limiting Scan Partition Count
+Scanning too many partitions can significantly increase BE's CPU consumption. Additionally, if the query targets an external table, it may incur significant network overhead and metadata retrieval overhead. This is often caused by forgetting to write filtering conditions on partition columns or writing them incorrectly. You can set a partition count limit to avoid such issues:
```sql
CREATE SQL_BLOCK_RULE rule_part_num
@@ -139,12 +65,12 @@ PROPERTIES
"enable" = "true"
);
```
-When the above rules are set, if the number of partitions scanned for a single table exceeds 30, the execution of the query is prohibited.
-It should be noted that the calculation of the number of scanned partitions is completed during the planning phase, not the execution phase. Therefore, there may be cases where more partitions are retained due to incomplete partition pruning. Thus, queries where the actual number of scanned partitions is less than the set value may also be blocked.
-#### Prevent Scanning Data with Excessive Bucket Counts
-Scanning too many buckets can significantly increase the BE's CPU consumption. To prevent such queries from harming the cluster, you can set an upper limit on the number of partitions a single query can scan on a single table.
+When the number of partitions scanned for a single table exceeds 30, the query execution will be blocked.
+
+#### Case 3: Limiting Scan Bucket Count
+Scanning too many buckets can also significantly increase BE's CPU consumption. You can set a bucket count limit to avoid such issues:
```sql
CREATE SQL_BLOCK_RULE rule_teblet_num
@@ -155,16 +81,16 @@ PROPERTIES
"enable" = "true"
);
```
-When the above rules are set, if the number of buckets scanned in a single table exceeds 200, the execution of the query is prohibited.
-It is important to note that the calculation of the number of scanned buckets is done during the planning phase, not the execution phase. Therefore, it is possible that due to incomplete bucket pruning, more partitions are retained. As a result, queries with an actual number of scanned buckets less than the set value may also be blocked.
+When the number of buckets scanned in a single table exceeds 200, the query execution will be blocked.
-#### Blocking Queries with Specific Patterns
+#### Case 4: Blocking Specific SQL Patterns
-For various reasons, such as high computational complexity or long planning time, you may want to block queries that use certain patterns.
+Certain query patterns may cause high computational complexity, long planning time, and other issues. You can block these queries using regular expression matching.
-For example, to block the `abs` function. You can use the following regular expression block rule to achieve this purpose.
+**Example 1: Blocking a specific function**
+For example, to block the `abs` function:
```sql
CREATE SQL_BLOCK_RULE rule_abs
@@ -175,142 +101,136 @@ PROPERTIES(
);
```
-In the above regular expressions:
+In the above regular expression:
-- `(?i)` indicates case-insensitive matching.
-- `abs` is the target function to be blocked.
-- `\s*` signifies that any amount of whitespace is allowed between `abs` and the left parenthesis.
-- `\(.+\)` matches the function parameters.
+- `(?i)` indicates case-insensitive matching
+- `abs` is the target function to be blocked
+- `\\s*` signifies that any amount of whitespace is allowed between `abs` and the left parenthesis
+- `\\(.+\\)` matches the function parameters
-Similarly, similar methods can be used to block `set global` to prevent unintended variable changes, or block `truncate table` to prevent unintended data deletions.
+**Example 2: Blocking other dangerous operations**
-### FAQ
+Similarly, you can use the same method to block `set global` to prevent unintended variable changes, or block `truncate table` to prevent unintended data deletions.
-#### Q: Will regular expression blocking rules have side effects on the cluster?
-A: Yes. Regular expression matching is computationally intensive. When using complex regular expressions or too many regex blocking rules, it can significantly increase the CPU load on the FE. Therefore, add regex blocking rules cautiously. Avoid using complex regular expressions unless necessary.
+#### Case 5: Setting Rules for Specific Users
-#### Q: Can a blocking rule be temporarily disabled?
-A: Yes. Modify the blocking rule by setting its "enable" property to "false".
+By default, block rules apply globally (`"global" = "true"`). To apply a rule only to specific users, you can create a user-level block rule:
-#### Q: What standard do the regular expressions in blocking rules use?
-A: The regular expressions in blocking rules use Java's regular expression syntax. Common expressions can refer to the SQL syntax manual. The complete manual can be found at https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html
+1. Set `"global"` to `"false"` when creating the rule:
-## Workload Policy
-
-SQL Block Rule is a configuration for circuit breaking during planning, but because the cost calculation during planning may be inaccurate (especially for very complex queries, making it difficult to estimate accurately), it can lead to rules not being effective or false positives. Workload Policy addresses this limitation by allowing real-time monitoring of certain metrics during query execution, and circuit breaking queries whose runtime state does not meet expectations. This prevents [...]
+ ```sql
+ CREATE SQL_BLOCK_RULE rule_001
+ PROPERTIES (
+ "sql"="select * from t",
+ "global" = "false",
+ "enable" = "true"
+ )
+ ```
-* Query execution time
-* Number of rows scanned per BE
-* Number of bytes scanned per BE
-* Memory usage per BE
+2. Bind the rule to the target user:
-### Version Notes
+ ```sql
+ SET PROPERTY FOR 'root' 'SQL_block_rules' = 'rule_001';
+ ```
-Since Doris version 2.1, Workload Policy can be used to implement circuit breaking for large queries.
+3. Verify the rule is effective:
-| Version | since 2.1 |
-|--------------------|-----------|
-| select | yes |
-| insert into select | yes |
-| insert into values | no |
-| stream load | yes |
-| routine load | yes |
-| backup | no |
-| compaction | no |
+ ```sql
+ MySQL root@127.0.0.1:test> select * from t;
+ (1105, 'errCode = 2, detailMessage = errCode = 2, detailMessage = SQL match regex SQL block rule: rule_001')
+ ```
-### Creating Workload Policy
-Use the `CREATE WORKLOAD Policy` command to create a resource management policy.
+- To add multiple rules for a user, list all rule names in the rule list, separated by commas.
+- To remove all rules for a user, set the rule list to an empty string: `SET PROPERTY FOR 'root' 'SQL_block_rules' = '';`
-In the example below, create a Policy named `test_cancel_Policy`, which will cancel queries running in the cluster for more than 1000ms. The current status is enabled. Creating a Workload Policy requires `admin_priv` privileges.
+To modify or delete block rules, refer to the SQL manual for block rules.
-```sql
-create workload policy test_cancel_Policy
-Conditions(query_time > 1000)
-Actions(cancel_query)
-properties('enabled'='true');
-```
-
-When creating a Workload Policy, the following must be specified:
+### Important Notes
-- **Condition** represents the policy trigger condition. Multiple Conditions can be linked using commas "," to represent an "AND" relationship. In the example above, `query_time > 1000` indicates that the Policy is triggered when the query time exceeds 1 second. Currently supported Conditions are:
+- The calculation of scan row count, partition count, and bucket count is performed during the planning phase. Only partition and bucket pruning are considered, and other filtering conditions are not taken into account (i.e., the worst-case scenario is estimated). Therefore, queries with actual scan volumes below the set values may also be blocked.
+- Regular expression matching is a computationally intensive operation. Too many or overly complex regex rules can put significant pressure on FE's CPU. Use them cautiously and avoid complex regular expressions unless necessary.
+- To temporarily disable a rule, set its `"enable"` property to `"false"`.
+- Regular expressions in block rules use Java's regular expression syntax. For the complete reference, see https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html
-| Conditions | Description |
-|-----------------------|-------------------------------------------------------------------------------------------------------------|
-| username | The username carried by the query, only triggers the `set_session_variable` Action in FE. |
-| be_scan_rows | The number of rows scanned by a SQL in a single BE process. If the SQL is executed concurrently on BE, it is the cumulative value of multiple concurrent executions. |
-| be_scan_bytes | The number of bytes scanned by a SQL in a single BE process. If the SQL is executed concurrently on BE, it is the cumulative value of multiple concurrent executions, in bytes. |
-| query_time | The runtime of a SQL in a single BE process, in milliseconds. |
-| query_be_memory_bytes | The memory usage of a SQL in a single BE process. If the SQL is executed concurrently on BE, it is the cumulative value of multiple concurrent executions, in bytes. |
+## Workload Policy
-- **Action** represents the action taken when the condition is triggered. Currently, a Policy can only define one Action (except for `set_session_variable`). In the example above, `cancel_query` indicates cancelling the query. Currently supported Actions are:
+SQL Block Rule performs circuit breaking during the planning phase, but since cost estimation during planning may be inaccurate (especially for complex queries), it can lead to rules not being effective or false positives. Workload Policy addresses this limitation by monitoring real-time metrics during query execution and circuit breaking queries whose runtime state does not meet expectations, preventing unexpectedly large queries from consuming excessive resources and affecting cluster [...]
-| Actions | Description |
-|------------------------|------------------------------------------------------------------------------------------------------------------|
-| cancel_query | Cancel the query. |
-| set_session_variable | Triggers the `set session variable` statement. A single policy can have multiple `set_session_variable` options, currently only triggered in FE by the `username` Condition. |
+Workload Policy has been supported since Doris version 2.1. The support status for each load type is as follows:
-- **Properties** define the attributes of the current Policy, including whether it is enabled and its priority.
+| Load Type | Supported |
+|--------------------|-----------|
+| select | Yes |
+| insert into select | Yes |
+| insert into values | No |
+| stream load | Yes |
+| routine load | Yes |
+| backup | No |
+| compaction | No |
-| Properties | Description |
-|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| enabled | Can be `true` or `false`, default is `true`, indicating the Policy is enabled. `false` indicates the Policy is disabled. |
-| priority | An integer ranging from 0 to 100, default is 0, representing the Policy's priority. The higher the value, the higher the priority. This attribute mainly ensures that when a query matches multiple Policies, only the Policy with the highest priority is selected. |
-| workload_group | Currently, a Policy can bind to one workload group, meaning this Policy only applies to queries from a specific Workload Group. The default is empty, meaning it applies to all queries. |
+### Creation and Configuration
-### Binding Workload Policy to Workload Group
+Use the `CREATE WORKLOAD POLICY` command to create a policy. Creating a Workload Policy requires `admin_priv` privileges.
-By default, Workload Policies apply to all supported queries. If you want to specify that a Policy only targets a specific Workload Group, you need to bind the Workload Group through the `workload_group` option. The statement is as follows:
+The following example creates a policy named test_cancel_policy that cancels queries running longer than 1000 ms:
```sql
-create workload policy test_cancel_big_query
-Conditions(query_time > 1000)
-Actions(cancel_query)
-properties('workload_group'='normal')
+CREATE WORKLOAD POLICY test_cancel_policy
+CONDITIONS(query_time > 1000)
+ACTIONS(cancel_query)
+PROPERTIES('enabled'='true');
```
-### Important Notes
-- The Conditions and Actions of the same Policy must either both be FE or both be BE. For example, `set_session_variable` and `cancel_query` cannot be configured within the same Policy. Conditions `be_scan_rows` and `username` cannot be configured within the same Policy.
-- Currently, Policies are executed by asynchronous threads at fixed time intervals, which introduces a certain latency in policy enforcement. For example, if a user configures a policy to cancel a query when the number of scanned rows exceeds 1,000,000, and the cluster resources are relatively idle at that time, the query may finish before the cancellation policy takes effect. The current interval is 500ms, meaning that queries with run times shorter than this interval may bypass the pol [...]
-- Currently supported load types include select/insert, select/stream load, broker load, and routine load.
-- A single query may match multiple Policies, but only the Policy with the highest priority will take effect.
-- Modifications to Actions and Conditions are currently not supported; they can only be modified by deleting and recreating them.
+When creating a Workload Policy, three components must be specified:
-### Workload Policy Demonstration
+#### Conditions
-#### 1. Session Variable Modification Test
-Attempt to modify concurrency-related parameters in the session variables of the Admin account.
+Conditions represent the policy trigger conditions. Multiple Conditions are separated by commas `,` to represent an "AND" relationship.
-```sql
--- log on admin to check variables
-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)
+| Condition | Description |
+|-----------------------|------------------------------------------------------------------------------------------------------|
+| username | The username carried by the query; only triggers the set_session_variable Action in FE |
+| be_scan_rows | Number of rows scanned by a SQL in a single BE process; cumulative value when executed concurrently |
+| be_scan_bytes | Number of bytes scanned by a SQL in a single BE process; cumulative value when executed concurrently, in bytes |
+| query_time | Runtime of a SQL in a single BE process, in milliseconds |
+| query_be_memory_bytes | Memory usage of a SQL in a single BE process; cumulative value when executed concurrently, in bytes |
--- Create a Policy to modify the concurrency parameters of the admin account.
-create workload Policy test_set_var_Policy
-Conditions(username='admin')
-Actions(set_session_variable 'parallel_fragment_exec_instance_num=1')
+#### Actions
--- After some time, check the admin account's parameters again.
-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)
+Actions represent the action taken when the condition is triggered. Currently, a Policy can only define one Action (except for set_session_variable).
+
+| Action | Description |
+|----------------------|-----------------------------------------------------------------------------------------------------------------|
+| cancel_query | Cancel the query |
+| set_session_variable | Triggers a set session variable statement. A single Policy can have multiple set_session_variable options; currently only triggered in FE by the username Condition |
+
+#### Properties
+
+| Property | Description |
+|----------------|---------------------------------------------------------------------------------------------------------------------|
+| enabled | Whether the policy is enabled; values are true or false, default is true |
+| priority | Priority, an integer from 0 to 100, default is 0. Higher values mean higher priority; when a query matches multiple Policies, only the one with the highest priority takes effect |
+| workload_group | The name of the bound Workload Group; when specified, the Policy only applies to queries from that Workload Group. Default is empty, meaning it applies to all queries |
+
+#### Binding to a Workload Group
+
+By default, Workload Policies apply to all supported queries. To specify that a Policy only targets a specific Workload Group, bind it through the `workload_group` property:
+
+```sql
+CREATE WORKLOAD POLICY test_cancel_big_query
+CONDITIONS(query_time > 1000)
+ACTIONS(cancel_query)
+PROPERTIES('workload_group'='normal')
```
-#### 2. Big Query Circuit Breaker Test
-Test to circuit break queries that run longer than 3s. Below is an audit log of a successful run of ckbench's q29, showing that this SQL took 4.5s to complete.
+### Usage Examples
+
+#### Example 1: Circuit Breaking Timeout Queries
+Below is an audit log of a successful run of ckbench's q29, showing that this SQL took 4.5s to complete:
```sql
-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;
+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;
+-----------------------------------------------------------------------+------------------+----------+---------------------------------------------------------------------------------------------------------------------+
| k | l | c | min(Referer) |
+-----------------------------------------------------------------------+------------------+----------+---------------------------------------------------------------------------------------------------------------------+
@@ -329,17 +249,53 @@ mySQL [hits]>SELECT REGEXP_REPLACE(Referer, '^https?://(?:www\.)?([^/]+)/.*$', '
11 rows in set (4.50 sec)
```
-Create a Policy that cancels a query if it runs longer than 3 seconds.
+Create a Policy that cancels queries running longer than 3 seconds:
+
+```sql
+CREATE WORKLOAD POLICY test_cancel_3s_query
+CONDITIONS(query_time > 3000)
+ACTIONS(cancel_query)
+```
+
+Upon re-executing the SQL, you can see the query is circuit broken:
+
```sql
-create workload Policy test_cancel_3s_query
-Conditions(query_time > 3000)
-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
```
-Upon re-executing the SQL, you can see that the SQL execution will directly report an error.
+#### Example 2: Modifying User Session Variables
+
+Workload Policy can automatically modify session variables for specific users, for example, adjusting concurrency parameters:
```sql
-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
+-- Log in to admin account and check concurrency parameters
+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 to modify the concurrency parameters of the admin account
+CREATE WORKLOAD POLICY test_set_var_policy
+CONDITIONS(username='admin')
+ACTIONS(set_session_variable 'parallel_fragment_exec_instance_num=1')
+
+-- After some time, check the admin account's parameters again
+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)
```
+### Important Notes
+
+- The Conditions and Actions of the same Policy must belong to the same side (FE or BE). For example, set_session_variable and cancel_query cannot be configured within the same Policy; Condition be_scan_rows and Condition username also cannot be configured within the same Policy.
+- Policies are executed by asynchronous threads at fixed time intervals (currently 500 ms), so there is a certain latency in policy enforcement. Queries with very short run times may bypass the policy check.
+- A single query may match multiple Policies, but only the Policy with the highest priority will take effect.
+- Modifications to Actions and Conditions are currently not supported; they can only be modified by deleting and recreating them.
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 188c5e40782..129ed29488a 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
@@ -2,121 +2,43 @@
{
"title": "查询熔断",
"language": "zh-CN",
- "description": "查询熔断是一种保护机制，用于防止长时间运行或消耗过多资源的查询对系统产生负面影响。当查询超过预设的资源或时间限制时，熔断机制会自动终止该查询，以避免对系统性能、资源使用以及其他查询造成不利影响。这种机制确保了集群在多用户环境下的稳定性，防止单个查询导致系统资源耗尽、响应变慢，"
+ "description": "Apache Doris 查询熔断机制，支持 SQL Block Rule（规划时阻止）和 Workload Policy（运行时熔断）两种策略，通过限制扫描行数、分区数、执行时间、内存等指标，自动终止异常查询，保障集群稳定性。"
}
---
查询熔断是一种保护机制，用于防止长时间运行或消耗过多资源的查询对系统产生负面影响。当查询超过预设的资源或时间限制时，熔断机制会自动终止该查询，以避免对系统性能、资源使用以及其他查询造成不利影响。这种机制确保了集群在多用户环境下的稳定性，防止单个查询导致系统资源耗尽、响应变慢，从而提高整体的可用性和效率。
-在 Doris 内，有两种熔断策略：
+Doris 提供了两种熔断策略，分别在查询生命周期的不同阶段发挥作用：
-- 规划时熔断，即 SQL Block Rule，用于阻止符合特定模式的语句执行。阻止规则对任意的语句生效，包括 DDL 和 DML。通常，阻止规则由数据库管理员（DBA）进行配置，用以提升集群的稳定性。比如，
-
- - 阻止一个查询扫描过多行的数据
-
- - 阻止一个查询扫描过多的分区
-
- - 阻止一个修改全局变量的语句，以防止集群配置被意外的修改。
-
- - 阻止一个通常会占用非常多资源的查询模式
-
-- 运行时熔断，即 Workload Policy，它是在运行时，实时监测查询的执行时间，扫描的数据量，消耗的内存，实现基于规则的查询熔断。
+| 对比维度 | SQL Block Rule（规划时熔断） | Workload Policy（运行时熔断） |
+|---------|--------------------------|---------------------------|
+| 生效阶段 | 查询规划阶段，执行前拦截 | 查询执行阶段，运行中熔断 |
+| 判断依据 | 预估扫描量、SQL 模式匹配 | 实际执行时间、内存占用、扫描量等实时指标 |
+| 准确性 | 基于代价估算，可能存在误判 | 基于实时监测，更加准确 |
+| 适用场景 | 阻止已知的危险 SQL 模式和全表扫描 | 熔断运行中超出预期的大查询 |
+| 适用语句 | 任意语句（DDL、DML） | select、insert into select、stream load、routine load |
## SQL Block Rule
-按照阻止模式，可以分为：
-
-- 扫描行数阻止规则
-- 扫描分区数阻止规则
-- 扫描分桶数阻止规则
-- 查询语句正则匹配阻止规则
-- 查询语句哈希值匹配阻止规则
-
-阻止规则按照阻止范围，可以分为：
-
-- 全局级别阻止规则
-- 用户级别阻止规则
-
-### 使用方法
-
-#### 全局级别阻止规则
-
-```sql
-CREATE SQL_BLOCK_RULE rule_001
-PROPERTIES (
- "sql"="select \\* from t",
- "global" = "true",
- "enable" = "true"
-)
-```
-
-这样，我们就创建了一个全局级别的阻止规则。规则名为 rule_001。配置了查询语句正则匹配规则，用于阻止所有可以被正则 `select \\* from t` 所匹配的查询语句。
-
-由于是全局级别的阻止规则，所以任意用户执行可以被上述正则匹配的语句都会被阻止。例如：
-
-```sql
-MySQL root@127.0.0.1:test> select * from t;
-(1105, 'errCode = 2, detailMessage = errCode = 2, detailMessage = SQL match regex SQL block rule: rule_001')
-```
-
-#### 用户级别阻止规则
-
-```sql
-CREATE SQL_BLOCK_RULE rule_001
-PROPERTIES (
- "sql"="select * from t",
- "global" = "false",
- "enable" = "true"
-)
-```
-
-不同于全局级别的阻止规则。用户级别的阻止规则只对指定用户生效。当我们创建阻止规则时，设置属性"global"为"false"。那么这个阻止规则，将被视为用户级别的阻止规则。
-
-为了使得用户级别的阻止规则生效。还需要为需要使用此规则的用户设置相应的属性。例如：
-
-```sql
-set property for 'root' 'SQL_block_rules' = 'rule_001';
-```
-
-这样，经过上面的配置，root 用户在执行查询时，将被应用名为 rule_001 的阻止规则。
-
-```sql
-MySQL root@127.0.0.1:test> set property for 'root' 'SQL_block_rules' = '';
-Query OK, 0 rows affected
-Time: 0.018s
-MySQL root@127.0.0.1:test> select * from t;
-+----+----+
-| id | c1 |
-+----+----+
-| 1 | 1 |
-+----+----+
-
-1 row in set
-Time: 0.027s
-MySQL root@127.0.0.1:test> set property for 'root' 'SQL_block_rules' = 'rule_001';
-Query OK, 0 rows affected
-Time: 0.008s
-MySQL root@127.0.0.1:test> select * from t;
-(1105, 'errCode = 2, detailMessage = errCode = 2, detailMessage = SQL match regex SQL block rule: rule_001')
-```
-- 如果想对一个用户添加多个用户级别的阻止规则。在规则列表中列举所有的规则名字，以英文逗号隔开。
-- 如果想移除一个用户的所有用户级别阻止规则。将规则列表置为空字符串即可。
-#### 其他操作
-如果需要修改或者删除阻止规则，可以参考阻止规则的 SQL 手册。
+SQL Block Rule 用于在查询规划阶段阻止符合特定模式的语句执行，通常由数据库管理员（DBA）配置，用以提升集群稳定性。
-### 使用场景
-可以在以下几种场景使用：
+每条规则通过以下属性来定义其行为和作用范围：
-* 阻止扫描超过指定行数的数据
+| 属性 | 说明 | 取值 |
+|------|------|------|
+| `sql` | 用于匹配查询语句的正则表达式 | Java 正则表达式字符串 |
+| `sqlHash` | 用于匹配查询语句的哈希值 | SQL 哈希值字符串 |
+| `cardinality` | 允许扫描的最大行数 | 正整数 |
+| `partition_num` | 允许扫描的最大分区数 | 正整数 |
+| `tablet_num` | 允许扫描的最大分桶数 | 正整数 |
+| `global` | 是否为全局规则 | `"true"`（全局生效）或 `"false"`（仅对绑定用户生效） |
+| `enable` | 是否启用规则 | `"true"` 或 `"false"` |
-* 阻止扫描超过指定分区数量的数据
+### 使用场景与示例
-* 阻止扫描超过指定分桶数量的数据
+#### 场景一：限制扫描行数
-* 阻止特定模式的查询
-
-#### 阻止扫描超过指定行数的数据
-由于扫描数据会显著消耗 BE 的 IO 资源和 CPU 资源。所以，不必要的数据扫描会对集群的稳定性带来比较大的挑战。日常使用中，经常会出现盲目的全表扫描操作。例如 `SELECT * FROM t`。为了防止这种查询对集群产生破坏。可以设置单个查询扫描单表行数的上限。
+日常使用中，经常会出现盲目的全表扫描操作，例如 `SELECT * FROM t`。扫描数据会显著消耗 BE 的 IO 和 CPU 资源，对集群稳定性带来较大挑战。可以通过设置单个查询扫描单表行数的上限来防止此类操作：
```sql
CREATE SQL_BLOCK_RULE rule_card
@@ -127,11 +49,12 @@ PROPERTIES
"enable" = "true"
);
```
-当设置了如上的规则，当单表扫描超过 1000 行时，将禁止此查询的执行。
-需要注意，由于扫描行数的计算是在规划阶段，而非执行阶段完成的。所以计算行数时，只会考虑分区和分桶裁剪，而不会考虑其他过滤条件对于扫描行数的影响。也就是考虑最坏情况。所以，实际扫描的行数小于设置值的查询也有可能被阻止。
-#### 阻止扫描超过指定分区数量的数据
-对过多分区的扫描会显著的增加 BE 的 CPU 消耗。同时，如果查询的外表，那更有可能带来显著的网络开销和元数据拉取的开销。在日常使用中，这多是由于忘记写分区列上的过滤条件或者写错导致的。为了防止这种查询对集群产生破坏。可以设置单个查询扫描单表的分区数的上限。
+当单表扫描超过 1000 行时，将禁止此查询的执行。
+
+#### 场景二：限制扫描分区数
+
+对过多分区的扫描会显著增加 BE 的 CPU 消耗。同时，如果查询的是外表，还可能带来显著的网络开销和元数据拉取开销。这多是由于忘记写分区列上的过滤条件或者写错导致的。可以通过设置分区数上限来避免此类问题：
```sql
CREATE SQL_BLOCK_RULE rule_part_num
@@ -142,11 +65,12 @@ PROPERTIES
"enable" = "true"
);
```
-当设置了如上的规则，当单表扫描分区数超过 30 个时，则禁止此查询的执行。
-需要注意的是，由于扫描分区数的计算是在规划阶段，而非执行阶段完成的。所以有可能出现因为分区裁剪不完全，而保留了更多分区的情况。所以，实际扫描的分区数小于设置值的查询也有可能被阻止。
-#### 阻止扫描超过指定分桶数量的数据
-对过多分桶的扫描会显著的增加 BE 的 CPU 消耗。为了防止这种查询对集群产生破坏。可以设置单个查询扫描单表的分区数的上限。
+当单表扫描分区数超过 30 个时，则禁止此查询的执行。
+
+#### 场景三：限制扫描分桶数
+
+对过多分桶的扫描同样会显著增加 BE 的 CPU 消耗。可以通过设置分桶数上限来避免此类问题：
```sql
CREATE SQL_BLOCK_RULE rule_teblet_num
@@ -157,12 +81,16 @@ PROPERTIES
"enable" = "true"
);
```
-当设置了如上的规则，当单表扫描分桶数量超过 200 个时，则禁止此查询的执行。
-需要注意的是，由于扫描分桶数的计算是在规划阶段，而非执行阶段完成的。所以有可能出现因为分桶裁剪不完全，而保留了更多分区的情况。所以，实际扫描的分桶数小于设置值的查询也有可能被阻止。
-#### 阻止特定模式的查询
-由于各种原因，比如计算复杂度高，规划时间长等，可能会希望阻止使用模式的查询。
-以阻止函数 abs 举例。可以使用如下的正则表达式阻止规则，完成此目的。
+当单表扫描分桶数量超过 200 个时，则禁止此查询的执行。
+
+#### 场景四：阻止特定 SQL 模式
+
+某些查询模式可能导致计算复杂度高、规划时间长等问题，可以通过正则表达式匹配来阻止这些查询。
+
+**示例一：阻止使用特定函数**
+
+以阻止函数 `abs` 为例：
```sql
CREATE SQL_BLOCK_RULE rule_abs
@@ -173,142 +101,136 @@ PROPERTIES(
);
```
-上述正则表达式中
+上述正则表达式中：
-- (?i) 表示大小写不敏感
+- `(?i)` 表示大小写不敏感
+- `abs` 为想要阻止的目标函数
+- `\\s*` 表示在 abs 和左括号之间可以有任意个空白
+- `\\(.+\\)` 匹配函数参数
-- abs 为想要阻止的目标函数
+**示例二：阻止其他危险操作**
-- \\s*表示在 abs 和左括号之间可以有任意个空白
+同理，也可以使用类似的方法阻止 `set global`，以防止非预期的变量改变。或者阻止 `truncate table`，以防止非预期的删除数据。
-- \\(.+\\) 匹配函数参数
- 同理，也可以使用类似的方法阻止 set global，以防止非预期的变量改变。或者阻止 truncate table，以防止非预期的删除数据。
+#### 场景五：针对特定用户设置规则
-### 常见问题
+默认情况下，阻止规则全局生效（`"global" = "true"`）。如需仅对特定用户生效，可以创建用户级别的阻止规则：
-#### Q：正则匹配阻止规则会对集群产生副作用吗？
-A：是的。由于正则匹配是计算密集型的。当使用复杂的正则表达式，或者正则匹配规则过多时。会给 FE 的 CPU 带来显著的压力提升。所以，要谨慎添加正则匹配的阻止规则。除非必要，尽量不要使用复杂的正则表达式。
+1. 创建规则时设置 `"global"` 为 `"false"`：
-#### Q：可以临时关闭一个阻止规则吗？
-A：可以。修改阻止规则，将其属性中的"enable"改为"false"即可。
+ ```sql
+ CREATE SQL_BLOCK_RULE rule_001
+ PROPERTIES (
+ "sql"="select * from t",
+ "global" = "false",
+ "enable" = "true"
+ )
+ ```
-#### Q：阻止规则中的正则表达式使用哪种规范？
-A：阻止规则的正则表达式使用 java 的正则表达式规范。常用表达式可以参考 SQL 语法手册。完整的手册可以参考 https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html
+2. 将规则绑定到目标用户：
-## Workload Policy
+ ```sql
+ SET PROPERTY FOR 'root' 'SQL_block_rules' = 'rule_001';
+ ```
+
+3. 验证规则生效：
+
+ ```sql
+ MySQL root@127.0.0.1:test> select * from t;
+ (1105, 'errCode = 2, detailMessage = errCode = 2, detailMessage = SQL match regex SQL block rule: rule_001')
+ ```
+
+- 如果想对一个用户添加多个规则，在规则列表中列举所有的规则名字，以英文逗号隔开。
+- 如果想移除一个用户的所有规则，将规则列表置为空字符串即可：`SET PROPERTY FOR 'root' 'SQL_block_rules' = '';`
+
+如果需要修改或者删除阻止规则，可以参考阻止规则的 SQL 手册。
+
+### 注意事项
-SQL Block Rule 是一种在规划时进行熔断的配置，但是由于规划中代价的计算可能不准确（尤其是针对一些非常复杂的查询时，更加难以准确估算），所以会导致规则不生效或者误判。Workload Policy 弥补了这个缺陷，它可以在查询运行时对一些指标进行实时的监测，对运行时状态不符合预期的查询进行熔断，避免不符合预期的大查询占用过多资源从而影响集群的稳定性，常用的运行时监控指标如下：
+- 扫描行数、分区数、分桶数的计算均在规划阶段完成，只会考虑分区和分桶裁剪，不会考虑其他过滤条件的影响（即按最坏情况估算）。因此，实际扫描量小于设置值的查询也有可能被阻止。
+- 正则匹配是计算密集型操作，过多或过于复杂的正则规则会给 FE 的 CPU 带来显著压力。建议谨慎添加，除非必要，尽量不要使用复杂的正则表达式。
+- 如需临时关闭某条规则，修改其属性中的 `"enable"` 为 `"false"` 即可。
+- 阻止规则的正则表达式使用 Java 的正则表达式规范，完整手册可参考 https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html
-* 查询执行时间
-* 查询在单 BE 上的扫描行数
-* 查询在单 BE 上的扫描行数扫描字节数
-* 查询的在单 BE 上的内存使用
+## Workload Policy
-### 版本说明
+SQL Block Rule 在规划阶段进行熔断，但由于规划中的代价估算可能不准确（尤其是复杂查询），可能导致规则不生效或误判。Workload Policy 弥补了这一缺陷，它在查询运行时对实时指标进行监测，对不符合预期的查询进行熔断，避免大查询占用过多资源从而影响集群稳定性。
-自 Doris 2.1 版本起，可以通过 Workload Policy 可以实现大查询的熔断。
+自 Doris 2.1 版本起支持 Workload Policy，各负载类型的支持情况如下：
-| 版本 | 自2.1起 |
-|--------------------|-------|
+| 负载类型 | 是否支持 |
+|-------------------|---------|
| select | 支持 |
| insert into select | 支持 |
-| insert into values | 不支持 |
+| insert into values | 不支持 |
| stream load | 支持 |
| routine load | 支持 |
-| backup | 不支持 |
-| compaction | 不支持 |
+| backup | 不支持 |
+| compaction | 不支持 |
+
+### 创建与配置
-### 创建熔断策略
-使用 `CREATE WORKLOAD Policy` 命令可以创建资源管理策略。
+使用 `CREATE WORKLOAD POLICY` 命令创建策略。创建 Workload Policy 需要 admin_priv 权限。
-在下面的例子中创建一个名为 test_cancel_Policy 的 Policy，它会取消掉集群中运行时间超过 1000ms 的查询，当前状态为启用。创建 Workload Policy 需要 admin_priv 权限。
+以下示例创建一个名为 test_cancel_policy 的策略，它会取消运行时间超过 1000 ms 的查询：
```sql
-create workload Policy test_cancel_Policy
-Conditions(query_time > 1000)
-Actions(cancel_query)
-properties('enabled'='true');
+CREATE WORKLOAD POLICY test_cancel_policy
+CONDITIONS(query_time > 1000)
+ACTIONS(cancel_query)
+PROPERTIES('enabled'='true');
```
-在创建 Workload Policy 时需要指定以下内容：
-- Condition 表示策略触发条件，可以多个 Condition 串联，使用逗号“,”隔开，表示“与”的关系。在上例中 query_time > 1000 表示在查询时间大于 1s 时触发 Policy；目前支持的 Conditions 有：
+创建 Workload Policy 时需要指定以下三个部分：
-| 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 上是多并发执行，那么就是多个并发的累加值，单位是字节。 |
+#### 触发条件（Conditions）
-- Action 表示条件触发时采取的动作，目前一个 Policy 只能定义一个 Action（除 set_session_variable）。在上例中，cancel_query 表示取消查询；目前支持的 Actions 有：
+Conditions 表示策略的触发条件，多个 Condition 之间以逗号 `,` 分隔，表示"与"的关系。
-| Actions | 说明 |
-|-----------------------|------------------------------------------------------------------------------------------------------|
-| cancel_query | 取消查询。 |
-| set_session_variable | 触发 set session variable 语句。同一个 policy 可以有多个 set_session_variable 选项，目前只会在 FE 由 username 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）
-- Properties，定义了当前 Policy 的属性，包括是否启用和优先级。
+Actions 表示条件触发时采取的动作，目前一个 Policy 只能定义一个 Action（set_session_variable 除外）。
-| Properties | 说明 |
-|-----------------------|----------------------------------------------------------------------------------------------------|
-| enabled | 取值为 true 或 false，默认值为 true，表示当前 Policy 处于启用状态，false 表示当前 Policy 处于禁用状态 |
-| priority | 取值范围为 0 到 100 的正整数，默认值为 0，代表 Policy 的优先级，该值越大，优先级越高。这个属性的主要作用是，当查询匹配到多个 Policy 时，只选择优先级最高的 Policy。 |
-| workload_group | 目前一个 Policy 可以绑定一个 workload group，代表这个 Policy 只对某个 Workload Group 的查询生效。默认为空，代表对所有查询生效。 |
+| Action | 说明 |
+|----------------------|------------------------------------------------------------------------------------------------------------|
+| cancel_query | 取消查询 |
+| set_session_variable | 触发 set session variable 语句。同一个 Policy 可以有多个 set_session_variable 选项，目前只会在 FE 由 username Condition 触发 |
-### 将熔断策略绑定 Workload Group
-默认情况下，Workload Policy 会对所有支持的查询生效。如果想指定 Policy 只针对与某一个 Workload Group，需要通过 workload_group 选项绑定 Workload Group。语句如下：
+#### 策略属性（Properties）
-```sql
-create workload Policy test_cancel_big_query
-Conditions(query_time > 1000)
-Actions(cancel_query)
-properties('workload_group'='normal')
-```
+| Property | 说明 |
+|----------------|--------------------------------------------------------------------------------------------------------------|
+| enabled | 是否启用，取值为 true 或 false，默认值为 true |
+| priority | 优先级，取值范围为 0 到 100 的正整数，默认值为 0。值越大优先级越高，当查询匹配到多个 Policy 时，只有优先级最高的 Policy 生效 |
+| workload_group | 绑定的 Workload Group 名称，指定后 Policy 仅对该 Workload Group 的查询生效。默认为空，表示对所有查询生效 |
-### 注意事项
-- 同一个 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 Group
-### Workload Policy 效果演示
-
-#### 1 session 变量修改测试
-尝试修改 Admin 账户的 session 变量中的并发相关的参数
+默认情况下，Workload Policy 对所有支持的查询生效。如需仅针对某个 Workload Group 生效，可通过 `workload_group` 属性绑定：
```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)
+CREATE WORKLOAD POLICY test_cancel_big_query
+CONDITIONS(query_time > 1000)
+ACTIONS(cancel_query)
+PROPERTIES('workload_group'='normal')
+```
-// 创建修改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 的时间
+以下是一个 ckbench 的 q29 运行成功时的审计日志，可以看到该 SQL 需要 4.5s 完成：
```sql
-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;
+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;
+-----------------------------------------------------------------------+------------------+----------+---------------------------------------------------------------------------------------------------------------------+
| k | l | c | min(Referer) |
+-----------------------------------------------------------------------+------------------+----------+---------------------------------------------------------------------------------------------------------------------+
@@ -327,16 +249,53 @@ mySQL [hits]>SELECT REGEXP_REPLACE(Referer, '^https?://(?:www\.)?([^/]+)/.*$', '
11 rows in set (4.50 sec)
```
-创建一个运行时间超过 3s 就取消查询的 Policy
+创建一个运行时间超过 3s 就取消查询的 Policy：
+
+```sql
+CREATE WORKLOAD POLICY test_cancel_3s_query
+CONDITIONS(query_time > 3000)
+ACTIONS(cancel_query)
+```
+
+再次执行 SQL，可以看到查询被熔断：
+
```sql
-create workload Policy test_cancel_3s_query
-Conditions(query_time > 3000)
-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
```
-再次执行 SQL 可以看到 SQL 执行会直接报错
+#### 示例二：修改用户 session 变量
+
+通过 Workload Policy 可以自动修改特定用户的 session 变量，例如调整并发参数：
+
```sql
-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
+-- 登录 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，只能通过删除后重新创建的方式修改。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/admin-manual/workload-management/sql-blocking.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/admin-manual/workload-management/sql-blocking.md
index 188c5e40782..129ed29488a 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/admin-manual/workload-management/sql-blocking.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/admin-manual/workload-management/sql-blocking.md
@@ -2,121 +2,43 @@
{
"title": "查询熔断",
"language": "zh-CN",
- "description": "查询熔断是一种保护机制，用于防止长时间运行或消耗过多资源的查询对系统产生负面影响。当查询超过预设的资源或时间限制时，熔断机制会自动终止该查询，以避免对系统性能、资源使用以及其他查询造成不利影响。这种机制确保了集群在多用户环境下的稳定性，防止单个查询导致系统资源耗尽、响应变慢，"
+ "description": "Apache Doris 查询熔断机制，支持 SQL Block Rule（规划时阻止）和 Workload Policy（运行时熔断）两种策略，通过限制扫描行数、分区数、执行时间、内存等指标，自动终止异常查询，保障集群稳定性。"
}
---
查询熔断是一种保护机制，用于防止长时间运行或消耗过多资源的查询对系统产生负面影响。当查询超过预设的资源或时间限制时，熔断机制会自动终止该查询，以避免对系统性能、资源使用以及其他查询造成不利影响。这种机制确保了集群在多用户环境下的稳定性，防止单个查询导致系统资源耗尽、响应变慢，从而提高整体的可用性和效率。
-在 Doris 内，有两种熔断策略：
+Doris 提供了两种熔断策略，分别在查询生命周期的不同阶段发挥作用：
-- 规划时熔断，即 SQL Block Rule，用于阻止符合特定模式的语句执行。阻止规则对任意的语句生效，包括 DDL 和 DML。通常，阻止规则由数据库管理员（DBA）进行配置，用以提升集群的稳定性。比如，
-
- - 阻止一个查询扫描过多行的数据
-
- - 阻止一个查询扫描过多的分区
-
- - 阻止一个修改全局变量的语句，以防止集群配置被意外的修改。
-
- - 阻止一个通常会占用非常多资源的查询模式
-
-- 运行时熔断，即 Workload Policy，它是在运行时，实时监测查询的执行时间，扫描的数据量，消耗的内存，实现基于规则的查询熔断。
+| 对比维度 | SQL Block Rule（规划时熔断） | Workload Policy（运行时熔断） |
+|---------|--------------------------|---------------------------|
+| 生效阶段 | 查询规划阶段，执行前拦截 | 查询执行阶段，运行中熔断 |
+| 判断依据 | 预估扫描量、SQL 模式匹配 | 实际执行时间、内存占用、扫描量等实时指标 |
+| 准确性 | 基于代价估算，可能存在误判 | 基于实时监测，更加准确 |
+| 适用场景 | 阻止已知的危险 SQL 模式和全表扫描 | 熔断运行中超出预期的大查询 |
+| 适用语句 | 任意语句（DDL、DML） | select、insert into select、stream load、routine load |
## SQL Block Rule
-按照阻止模式，可以分为：
-
-- 扫描行数阻止规则
-- 扫描分区数阻止规则
-- 扫描分桶数阻止规则
-- 查询语句正则匹配阻止规则
-- 查询语句哈希值匹配阻止规则
-
-阻止规则按照阻止范围，可以分为：
-
-- 全局级别阻止规则
-- 用户级别阻止规则
-
-### 使用方法
-
-#### 全局级别阻止规则
-
-```sql
-CREATE SQL_BLOCK_RULE rule_001
-PROPERTIES (
- "sql"="select \\* from t",
- "global" = "true",
- "enable" = "true"
-)
-```
-
-这样，我们就创建了一个全局级别的阻止规则。规则名为 rule_001。配置了查询语句正则匹配规则，用于阻止所有可以被正则 `select \\* from t` 所匹配的查询语句。
-
-由于是全局级别的阻止规则，所以任意用户执行可以被上述正则匹配的语句都会被阻止。例如：
-
-```sql
-MySQL root@127.0.0.1:test> select * from t;
-(1105, 'errCode = 2, detailMessage = errCode = 2, detailMessage = SQL match regex SQL block rule: rule_001')
-```
-
-#### 用户级别阻止规则
-
-```sql
-CREATE SQL_BLOCK_RULE rule_001
-PROPERTIES (
- "sql"="select * from t",
- "global" = "false",
- "enable" = "true"
-)
-```
-
-不同于全局级别的阻止规则。用户级别的阻止规则只对指定用户生效。当我们创建阻止规则时，设置属性"global"为"false"。那么这个阻止规则，将被视为用户级别的阻止规则。
-
-为了使得用户级别的阻止规则生效。还需要为需要使用此规则的用户设置相应的属性。例如：
-
-```sql
-set property for 'root' 'SQL_block_rules' = 'rule_001';
-```
-
-这样，经过上面的配置，root 用户在执行查询时，将被应用名为 rule_001 的阻止规则。
-
-```sql
-MySQL root@127.0.0.1:test> set property for 'root' 'SQL_block_rules' = '';
-Query OK, 0 rows affected
-Time: 0.018s
-MySQL root@127.0.0.1:test> select * from t;
-+----+----+
-| id | c1 |
-+----+----+
-| 1 | 1 |
-+----+----+
-
-1 row in set
-Time: 0.027s
-MySQL root@127.0.0.1:test> set property for 'root' 'SQL_block_rules' = 'rule_001';
-Query OK, 0 rows affected
-Time: 0.008s
-MySQL root@127.0.0.1:test> select * from t;
-(1105, 'errCode = 2, detailMessage = errCode = 2, detailMessage = SQL match regex SQL block rule: rule_001')
-```
-- 如果想对一个用户添加多个用户级别的阻止规则。在规则列表中列举所有的规则名字，以英文逗号隔开。
-- 如果想移除一个用户的所有用户级别阻止规则。将规则列表置为空字符串即可。
-#### 其他操作
-如果需要修改或者删除阻止规则，可以参考阻止规则的 SQL 手册。
+SQL Block Rule 用于在查询规划阶段阻止符合特定模式的语句执行，通常由数据库管理员（DBA）配置，用以提升集群稳定性。
-### 使用场景
-可以在以下几种场景使用：
+每条规则通过以下属性来定义其行为和作用范围：
-* 阻止扫描超过指定行数的数据
+| 属性 | 说明 | 取值 |
+|------|------|------|
+| `sql` | 用于匹配查询语句的正则表达式 | Java 正则表达式字符串 |
+| `sqlHash` | 用于匹配查询语句的哈希值 | SQL 哈希值字符串 |
+| `cardinality` | 允许扫描的最大行数 | 正整数 |
+| `partition_num` | 允许扫描的最大分区数 | 正整数 |
+| `tablet_num` | 允许扫描的最大分桶数 | 正整数 |
+| `global` | 是否为全局规则 | `"true"`（全局生效）或 `"false"`（仅对绑定用户生效） |
+| `enable` | 是否启用规则 | `"true"` 或 `"false"` |
-* 阻止扫描超过指定分区数量的数据
+### 使用场景与示例
-* 阻止扫描超过指定分桶数量的数据
+#### 场景一：限制扫描行数
-* 阻止特定模式的查询
-
-#### 阻止扫描超过指定行数的数据
-由于扫描数据会显著消耗 BE 的 IO 资源和 CPU 资源。所以，不必要的数据扫描会对集群的稳定性带来比较大的挑战。日常使用中，经常会出现盲目的全表扫描操作。例如 `SELECT * FROM t`。为了防止这种查询对集群产生破坏。可以设置单个查询扫描单表行数的上限。
+日常使用中，经常会出现盲目的全表扫描操作，例如 `SELECT * FROM t`。扫描数据会显著消耗 BE 的 IO 和 CPU 资源，对集群稳定性带来较大挑战。可以通过设置单个查询扫描单表行数的上限来防止此类操作：
```sql
CREATE SQL_BLOCK_RULE rule_card
@@ -127,11 +49,12 @@ PROPERTIES
"enable" = "true"
);
```
-当设置了如上的规则，当单表扫描超过 1000 行时，将禁止此查询的执行。
-需要注意，由于扫描行数的计算是在规划阶段，而非执行阶段完成的。所以计算行数时，只会考虑分区和分桶裁剪，而不会考虑其他过滤条件对于扫描行数的影响。也就是考虑最坏情况。所以，实际扫描的行数小于设置值的查询也有可能被阻止。
-#### 阻止扫描超过指定分区数量的数据
-对过多分区的扫描会显著的增加 BE 的 CPU 消耗。同时，如果查询的外表，那更有可能带来显著的网络开销和元数据拉取的开销。在日常使用中，这多是由于忘记写分区列上的过滤条件或者写错导致的。为了防止这种查询对集群产生破坏。可以设置单个查询扫描单表的分区数的上限。
+当单表扫描超过 1000 行时，将禁止此查询的执行。
+
+#### 场景二：限制扫描分区数
+
+对过多分区的扫描会显著增加 BE 的 CPU 消耗。同时，如果查询的是外表，还可能带来显著的网络开销和元数据拉取开销。这多是由于忘记写分区列上的过滤条件或者写错导致的。可以通过设置分区数上限来避免此类问题：
```sql
CREATE SQL_BLOCK_RULE rule_part_num
@@ -142,11 +65,12 @@ PROPERTIES
"enable" = "true"
);
```
-当设置了如上的规则，当单表扫描分区数超过 30 个时，则禁止此查询的执行。
-需要注意的是，由于扫描分区数的计算是在规划阶段，而非执行阶段完成的。所以有可能出现因为分区裁剪不完全，而保留了更多分区的情况。所以，实际扫描的分区数小于设置值的查询也有可能被阻止。
-#### 阻止扫描超过指定分桶数量的数据
-对过多分桶的扫描会显著的增加 BE 的 CPU 消耗。为了防止这种查询对集群产生破坏。可以设置单个查询扫描单表的分区数的上限。
+当单表扫描分区数超过 30 个时，则禁止此查询的执行。
+
+#### 场景三：限制扫描分桶数
+
+对过多分桶的扫描同样会显著增加 BE 的 CPU 消耗。可以通过设置分桶数上限来避免此类问题：
```sql
CREATE SQL_BLOCK_RULE rule_teblet_num
@@ -157,12 +81,16 @@ PROPERTIES
"enable" = "true"
);
```
-当设置了如上的规则，当单表扫描分桶数量超过 200 个时，则禁止此查询的执行。
-需要注意的是，由于扫描分桶数的计算是在规划阶段，而非执行阶段完成的。所以有可能出现因为分桶裁剪不完全，而保留了更多分区的情况。所以，实际扫描的分桶数小于设置值的查询也有可能被阻止。
-#### 阻止特定模式的查询
-由于各种原因，比如计算复杂度高，规划时间长等，可能会希望阻止使用模式的查询。
-以阻止函数 abs 举例。可以使用如下的正则表达式阻止规则，完成此目的。
+当单表扫描分桶数量超过 200 个时，则禁止此查询的执行。
+
+#### 场景四：阻止特定 SQL 模式
+
+某些查询模式可能导致计算复杂度高、规划时间长等问题，可以通过正则表达式匹配来阻止这些查询。
+
+**示例一：阻止使用特定函数**
+
+以阻止函数 `abs` 为例：
```sql
CREATE SQL_BLOCK_RULE rule_abs
@@ -173,142 +101,136 @@ PROPERTIES(
);
```
-上述正则表达式中
+上述正则表达式中：
-- (?i) 表示大小写不敏感
+- `(?i)` 表示大小写不敏感
+- `abs` 为想要阻止的目标函数
+- `\\s*` 表示在 abs 和左括号之间可以有任意个空白
+- `\\(.+\\)` 匹配函数参数
-- abs 为想要阻止的目标函数
+**示例二：阻止其他危险操作**
-- \\s*表示在 abs 和左括号之间可以有任意个空白
+同理，也可以使用类似的方法阻止 `set global`，以防止非预期的变量改变。或者阻止 `truncate table`，以防止非预期的删除数据。
-- \\(.+\\) 匹配函数参数
- 同理，也可以使用类似的方法阻止 set global，以防止非预期的变量改变。或者阻止 truncate table，以防止非预期的删除数据。
+#### 场景五：针对特定用户设置规则
-### 常见问题
+默认情况下，阻止规则全局生效（`"global" = "true"`）。如需仅对特定用户生效，可以创建用户级别的阻止规则：
-#### Q：正则匹配阻止规则会对集群产生副作用吗？
-A：是的。由于正则匹配是计算密集型的。当使用复杂的正则表达式，或者正则匹配规则过多时。会给 FE 的 CPU 带来显著的压力提升。所以，要谨慎添加正则匹配的阻止规则。除非必要，尽量不要使用复杂的正则表达式。
+1. 创建规则时设置 `"global"` 为 `"false"`：
-#### Q：可以临时关闭一个阻止规则吗？
-A：可以。修改阻止规则，将其属性中的"enable"改为"false"即可。
+ ```sql
+ CREATE SQL_BLOCK_RULE rule_001
+ PROPERTIES (
+ "sql"="select * from t",
+ "global" = "false",
+ "enable" = "true"
+ )
+ ```
-#### Q：阻止规则中的正则表达式使用哪种规范？
-A：阻止规则的正则表达式使用 java 的正则表达式规范。常用表达式可以参考 SQL 语法手册。完整的手册可以参考 https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html
+2. 将规则绑定到目标用户：
-## Workload Policy
+ ```sql
+ SET PROPERTY FOR 'root' 'SQL_block_rules' = 'rule_001';
+ ```
+
+3. 验证规则生效：
+
+ ```sql
+ MySQL root@127.0.0.1:test> select * from t;
+ (1105, 'errCode = 2, detailMessage = errCode = 2, detailMessage = SQL match regex SQL block rule: rule_001')
+ ```
+
+- 如果想对一个用户添加多个规则，在规则列表中列举所有的规则名字，以英文逗号隔开。
+- 如果想移除一个用户的所有规则，将规则列表置为空字符串即可：`SET PROPERTY FOR 'root' 'SQL_block_rules' = '';`
+
+如果需要修改或者删除阻止规则，可以参考阻止规则的 SQL 手册。
+
+### 注意事项
-SQL Block Rule 是一种在规划时进行熔断的配置，但是由于规划中代价的计算可能不准确（尤其是针对一些非常复杂的查询时，更加难以准确估算），所以会导致规则不生效或者误判。Workload Policy 弥补了这个缺陷，它可以在查询运行时对一些指标进行实时的监测，对运行时状态不符合预期的查询进行熔断，避免不符合预期的大查询占用过多资源从而影响集群的稳定性，常用的运行时监控指标如下：
+- 扫描行数、分区数、分桶数的计算均在规划阶段完成，只会考虑分区和分桶裁剪，不会考虑其他过滤条件的影响（即按最坏情况估算）。因此，实际扫描量小于设置值的查询也有可能被阻止。
+- 正则匹配是计算密集型操作，过多或过于复杂的正则规则会给 FE 的 CPU 带来显著压力。建议谨慎添加，除非必要，尽量不要使用复杂的正则表达式。
+- 如需临时关闭某条规则，修改其属性中的 `"enable"` 为 `"false"` 即可。
+- 阻止规则的正则表达式使用 Java 的正则表达式规范，完整手册可参考 https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html
-* 查询执行时间
-* 查询在单 BE 上的扫描行数
-* 查询在单 BE 上的扫描行数扫描字节数
-* 查询的在单 BE 上的内存使用
+## Workload Policy
-### 版本说明
+SQL Block Rule 在规划阶段进行熔断，但由于规划中的代价估算可能不准确（尤其是复杂查询），可能导致规则不生效或误判。Workload Policy 弥补了这一缺陷，它在查询运行时对实时指标进行监测，对不符合预期的查询进行熔断，避免大查询占用过多资源从而影响集群稳定性。
-自 Doris 2.1 版本起，可以通过 Workload Policy 可以实现大查询的熔断。
+自 Doris 2.1 版本起支持 Workload Policy，各负载类型的支持情况如下：
-| 版本 | 自2.1起 |
-|--------------------|-------|
+| 负载类型 | 是否支持 |
+|-------------------|---------|
| select | 支持 |
| insert into select | 支持 |
-| insert into values | 不支持 |
+| insert into values | 不支持 |
| stream load | 支持 |
| routine load | 支持 |
-| backup | 不支持 |
-| compaction | 不支持 |
+| backup | 不支持 |
+| compaction | 不支持 |
+
+### 创建与配置
-### 创建熔断策略
-使用 `CREATE WORKLOAD Policy` 命令可以创建资源管理策略。
+使用 `CREATE WORKLOAD POLICY` 命令创建策略。创建 Workload Policy 需要 admin_priv 权限。
-在下面的例子中创建一个名为 test_cancel_Policy 的 Policy，它会取消掉集群中运行时间超过 1000ms 的查询，当前状态为启用。创建 Workload Policy 需要 admin_priv 权限。
+以下示例创建一个名为 test_cancel_policy 的策略，它会取消运行时间超过 1000 ms 的查询：
```sql
-create workload Policy test_cancel_Policy
-Conditions(query_time > 1000)
-Actions(cancel_query)
-properties('enabled'='true');
+CREATE WORKLOAD POLICY test_cancel_policy
+CONDITIONS(query_time > 1000)
+ACTIONS(cancel_query)
+PROPERTIES('enabled'='true');
```
-在创建 Workload Policy 时需要指定以下内容：
-- Condition 表示策略触发条件，可以多个 Condition 串联，使用逗号“,”隔开，表示“与”的关系。在上例中 query_time > 1000 表示在查询时间大于 1s 时触发 Policy；目前支持的 Conditions 有：
+创建 Workload Policy 时需要指定以下三个部分：
-| 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 上是多并发执行，那么就是多个并发的累加值，单位是字节。 |
+#### 触发条件（Conditions）
-- Action 表示条件触发时采取的动作，目前一个 Policy 只能定义一个 Action（除 set_session_variable）。在上例中，cancel_query 表示取消查询；目前支持的 Actions 有：
+Conditions 表示策略的触发条件，多个 Condition 之间以逗号 `,` 分隔，表示"与"的关系。
-| Actions | 说明 |
-|-----------------------|------------------------------------------------------------------------------------------------------|
-| cancel_query | 取消查询。 |
-| set_session_variable | 触发 set session variable 语句。同一个 policy 可以有多个 set_session_variable 选项，目前只会在 FE 由 username 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）
-- Properties，定义了当前 Policy 的属性，包括是否启用和优先级。
+Actions 表示条件触发时采取的动作，目前一个 Policy 只能定义一个 Action（set_session_variable 除外）。
-| Properties | 说明 |
-|-----------------------|----------------------------------------------------------------------------------------------------|
-| enabled | 取值为 true 或 false，默认值为 true，表示当前 Policy 处于启用状态，false 表示当前 Policy 处于禁用状态 |
-| priority | 取值范围为 0 到 100 的正整数，默认值为 0，代表 Policy 的优先级，该值越大，优先级越高。这个属性的主要作用是，当查询匹配到多个 Policy 时，只选择优先级最高的 Policy。 |
-| workload_group | 目前一个 Policy 可以绑定一个 workload group，代表这个 Policy 只对某个 Workload Group 的查询生效。默认为空，代表对所有查询生效。 |
+| Action | 说明 |
+|----------------------|------------------------------------------------------------------------------------------------------------|
+| cancel_query | 取消查询 |
+| set_session_variable | 触发 set session variable 语句。同一个 Policy 可以有多个 set_session_variable 选项，目前只会在 FE 由 username Condition 触发 |
-### 将熔断策略绑定 Workload Group
-默认情况下，Workload Policy 会对所有支持的查询生效。如果想指定 Policy 只针对与某一个 Workload Group，需要通过 workload_group 选项绑定 Workload Group。语句如下：
+#### 策略属性（Properties）
-```sql
-create workload Policy test_cancel_big_query
-Conditions(query_time > 1000)
-Actions(cancel_query)
-properties('workload_group'='normal')
-```
+| Property | 说明 |
+|----------------|--------------------------------------------------------------------------------------------------------------|
+| enabled | 是否启用，取值为 true 或 false，默认值为 true |
+| priority | 优先级，取值范围为 0 到 100 的正整数，默认值为 0。值越大优先级越高，当查询匹配到多个 Policy 时，只有优先级最高的 Policy 生效 |
+| workload_group | 绑定的 Workload Group 名称，指定后 Policy 仅对该 Workload Group 的查询生效。默认为空，表示对所有查询生效 |
-### 注意事项
-- 同一个 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 Group
-### Workload Policy 效果演示
-
-#### 1 session 变量修改测试
-尝试修改 Admin 账户的 session 变量中的并发相关的参数
+默认情况下，Workload Policy 对所有支持的查询生效。如需仅针对某个 Workload Group 生效，可通过 `workload_group` 属性绑定：
```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)
+CREATE WORKLOAD POLICY test_cancel_big_query
+CONDITIONS(query_time > 1000)
+ACTIONS(cancel_query)
+PROPERTIES('workload_group'='normal')
+```
-// 创建修改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 的时间
+以下是一个 ckbench 的 q29 运行成功时的审计日志，可以看到该 SQL 需要 4.5s 完成：
```sql
-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;
+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;
+-----------------------------------------------------------------------+------------------+----------+---------------------------------------------------------------------------------------------------------------------+
| k | l | c | min(Referer) |
+-----------------------------------------------------------------------+------------------+----------+---------------------------------------------------------------------------------------------------------------------+
@@ -327,16 +249,53 @@ mySQL [hits]>SELECT REGEXP_REPLACE(Referer, '^https?://(?:www\.)?([^/]+)/.*$', '
11 rows in set (4.50 sec)
```
-创建一个运行时间超过 3s 就取消查询的 Policy
+创建一个运行时间超过 3s 就取消查询的 Policy：
+
+```sql
+CREATE WORKLOAD POLICY test_cancel_3s_query
+CONDITIONS(query_time > 3000)
+ACTIONS(cancel_query)
+```
+
+再次执行 SQL，可以看到查询被熔断：
+
```sql
-create workload Policy test_cancel_3s_query
-Conditions(query_time > 3000)
-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
```
-再次执行 SQL 可以看到 SQL 执行会直接报错
+#### 示例二：修改用户 session 变量
+
+通过 Workload Policy 可以自动修改特定用户的 session 变量，例如调整并发参数：
+
```sql
-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
+-- 登录 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，只能通过删除后重新创建的方式修改。
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 188c5e40782..129ed29488a 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
@@ -2,121 +2,43 @@
{
"title": "查询熔断",
"language": "zh-CN",
- "description": "查询熔断是一种保护机制，用于防止长时间运行或消耗过多资源的查询对系统产生负面影响。当查询超过预设的资源或时间限制时，熔断机制会自动终止该查询，以避免对系统性能、资源使用以及其他查询造成不利影响。这种机制确保了集群在多用户环境下的稳定性，防止单个查询导致系统资源耗尽、响应变慢，"
+ "description": "Apache Doris 查询熔断机制，支持 SQL Block Rule（规划时阻止）和 Workload Policy（运行时熔断）两种策略，通过限制扫描行数、分区数、执行时间、内存等指标，自动终止异常查询，保障集群稳定性。"
}
---
查询熔断是一种保护机制，用于防止长时间运行或消耗过多资源的查询对系统产生负面影响。当查询超过预设的资源或时间限制时，熔断机制会自动终止该查询，以避免对系统性能、资源使用以及其他查询造成不利影响。这种机制确保了集群在多用户环境下的稳定性，防止单个查询导致系统资源耗尽、响应变慢，从而提高整体的可用性和效率。
-在 Doris 内，有两种熔断策略：
+Doris 提供了两种熔断策略，分别在查询生命周期的不同阶段发挥作用：
-- 规划时熔断，即 SQL Block Rule，用于阻止符合特定模式的语句执行。阻止规则对任意的语句生效，包括 DDL 和 DML。通常，阻止规则由数据库管理员（DBA）进行配置，用以提升集群的稳定性。比如，
-
- - 阻止一个查询扫描过多行的数据
-
- - 阻止一个查询扫描过多的分区
-
- - 阻止一个修改全局变量的语句，以防止集群配置被意外的修改。
-
- - 阻止一个通常会占用非常多资源的查询模式
-
-- 运行时熔断，即 Workload Policy，它是在运行时，实时监测查询的执行时间，扫描的数据量，消耗的内存，实现基于规则的查询熔断。
+| 对比维度 | SQL Block Rule（规划时熔断） | Workload Policy（运行时熔断） |
+|---------|--------------------------|---------------------------|
+| 生效阶段 | 查询规划阶段，执行前拦截 | 查询执行阶段，运行中熔断 |
+| 判断依据 | 预估扫描量、SQL 模式匹配 | 实际执行时间、内存占用、扫描量等实时指标 |
+| 准确性 | 基于代价估算，可能存在误判 | 基于实时监测，更加准确 |
+| 适用场景 | 阻止已知的危险 SQL 模式和全表扫描 | 熔断运行中超出预期的大查询 |
+| 适用语句 | 任意语句（DDL、DML） | select、insert into select、stream load、routine load |
## SQL Block Rule
-按照阻止模式，可以分为：
-
-- 扫描行数阻止规则
-- 扫描分区数阻止规则
-- 扫描分桶数阻止规则
-- 查询语句正则匹配阻止规则
-- 查询语句哈希值匹配阻止规则
-
-阻止规则按照阻止范围，可以分为：
-
-- 全局级别阻止规则
-- 用户级别阻止规则
-
-### 使用方法
-
-#### 全局级别阻止规则
-
-```sql
-CREATE SQL_BLOCK_RULE rule_001
-PROPERTIES (
- "sql"="select \\* from t",
- "global" = "true",
- "enable" = "true"
-)
-```
-
-这样，我们就创建了一个全局级别的阻止规则。规则名为 rule_001。配置了查询语句正则匹配规则，用于阻止所有可以被正则 `select \\* from t` 所匹配的查询语句。
-
-由于是全局级别的阻止规则，所以任意用户执行可以被上述正则匹配的语句都会被阻止。例如：
-
-```sql
-MySQL root@127.0.0.1:test> select * from t;
-(1105, 'errCode = 2, detailMessage = errCode = 2, detailMessage = SQL match regex SQL block rule: rule_001')
-```
-
-#### 用户级别阻止规则
-
-```sql
-CREATE SQL_BLOCK_RULE rule_001
-PROPERTIES (
- "sql"="select * from t",
- "global" = "false",
- "enable" = "true"
-)
-```
-
-不同于全局级别的阻止规则。用户级别的阻止规则只对指定用户生效。当我们创建阻止规则时，设置属性"global"为"false"。那么这个阻止规则，将被视为用户级别的阻止规则。
-
-为了使得用户级别的阻止规则生效。还需要为需要使用此规则的用户设置相应的属性。例如：
-
-```sql
-set property for 'root' 'SQL_block_rules' = 'rule_001';
-```
-
-这样，经过上面的配置，root 用户在执行查询时，将被应用名为 rule_001 的阻止规则。
-
-```sql
-MySQL root@127.0.0.1:test> set property for 'root' 'SQL_block_rules' = '';
-Query OK, 0 rows affected
-Time: 0.018s
-MySQL root@127.0.0.1:test> select * from t;
-+----+----+
-| id | c1 |
-+----+----+
-| 1 | 1 |
-+----+----+
-
-1 row in set
-Time: 0.027s
-MySQL root@127.0.0.1:test> set property for 'root' 'SQL_block_rules' = 'rule_001';
-Query OK, 0 rows affected
-Time: 0.008s
-MySQL root@127.0.0.1:test> select * from t;
-(1105, 'errCode = 2, detailMessage = errCode = 2, detailMessage = SQL match regex SQL block rule: rule_001')
-```
-- 如果想对一个用户添加多个用户级别的阻止规则。在规则列表中列举所有的规则名字，以英文逗号隔开。
-- 如果想移除一个用户的所有用户级别阻止规则。将规则列表置为空字符串即可。
-#### 其他操作
-如果需要修改或者删除阻止规则，可以参考阻止规则的 SQL 手册。
+SQL Block Rule 用于在查询规划阶段阻止符合特定模式的语句执行，通常由数据库管理员（DBA）配置，用以提升集群稳定性。
-### 使用场景
-可以在以下几种场景使用：
+每条规则通过以下属性来定义其行为和作用范围：
-* 阻止扫描超过指定行数的数据
+| 属性 | 说明 | 取值 |
+|------|------|------|
+| `sql` | 用于匹配查询语句的正则表达式 | Java 正则表达式字符串 |
+| `sqlHash` | 用于匹配查询语句的哈希值 | SQL 哈希值字符串 |
+| `cardinality` | 允许扫描的最大行数 | 正整数 |
+| `partition_num` | 允许扫描的最大分区数 | 正整数 |
+| `tablet_num` | 允许扫描的最大分桶数 | 正整数 |
+| `global` | 是否为全局规则 | `"true"`（全局生效）或 `"false"`（仅对绑定用户生效） |
+| `enable` | 是否启用规则 | `"true"` 或 `"false"` |
-* 阻止扫描超过指定分区数量的数据
+### 使用场景与示例
-* 阻止扫描超过指定分桶数量的数据
+#### 场景一：限制扫描行数
-* 阻止特定模式的查询
-
-#### 阻止扫描超过指定行数的数据
-由于扫描数据会显著消耗 BE 的 IO 资源和 CPU 资源。所以，不必要的数据扫描会对集群的稳定性带来比较大的挑战。日常使用中，经常会出现盲目的全表扫描操作。例如 `SELECT * FROM t`。为了防止这种查询对集群产生破坏。可以设置单个查询扫描单表行数的上限。
+日常使用中，经常会出现盲目的全表扫描操作，例如 `SELECT * FROM t`。扫描数据会显著消耗 BE 的 IO 和 CPU 资源，对集群稳定性带来较大挑战。可以通过设置单个查询扫描单表行数的上限来防止此类操作：
```sql
CREATE SQL_BLOCK_RULE rule_card
@@ -127,11 +49,12 @@ PROPERTIES
"enable" = "true"
);
```
-当设置了如上的规则，当单表扫描超过 1000 行时，将禁止此查询的执行。
-需要注意，由于扫描行数的计算是在规划阶段，而非执行阶段完成的。所以计算行数时，只会考虑分区和分桶裁剪，而不会考虑其他过滤条件对于扫描行数的影响。也就是考虑最坏情况。所以，实际扫描的行数小于设置值的查询也有可能被阻止。
-#### 阻止扫描超过指定分区数量的数据
-对过多分区的扫描会显著的增加 BE 的 CPU 消耗。同时，如果查询的外表，那更有可能带来显著的网络开销和元数据拉取的开销。在日常使用中，这多是由于忘记写分区列上的过滤条件或者写错导致的。为了防止这种查询对集群产生破坏。可以设置单个查询扫描单表的分区数的上限。
+当单表扫描超过 1000 行时，将禁止此查询的执行。
+
+#### 场景二：限制扫描分区数
+
+对过多分区的扫描会显著增加 BE 的 CPU 消耗。同时，如果查询的是外表，还可能带来显著的网络开销和元数据拉取开销。这多是由于忘记写分区列上的过滤条件或者写错导致的。可以通过设置分区数上限来避免此类问题：
```sql
CREATE SQL_BLOCK_RULE rule_part_num
@@ -142,11 +65,12 @@ PROPERTIES
"enable" = "true"
);
```
-当设置了如上的规则，当单表扫描分区数超过 30 个时，则禁止此查询的执行。
-需要注意的是，由于扫描分区数的计算是在规划阶段，而非执行阶段完成的。所以有可能出现因为分区裁剪不完全，而保留了更多分区的情况。所以，实际扫描的分区数小于设置值的查询也有可能被阻止。
-#### 阻止扫描超过指定分桶数量的数据
-对过多分桶的扫描会显著的增加 BE 的 CPU 消耗。为了防止这种查询对集群产生破坏。可以设置单个查询扫描单表的分区数的上限。
+当单表扫描分区数超过 30 个时，则禁止此查询的执行。
+
+#### 场景三：限制扫描分桶数
+
+对过多分桶的扫描同样会显著增加 BE 的 CPU 消耗。可以通过设置分桶数上限来避免此类问题：
```sql
CREATE SQL_BLOCK_RULE rule_teblet_num
@@ -157,12 +81,16 @@ PROPERTIES
"enable" = "true"
);
```
-当设置了如上的规则，当单表扫描分桶数量超过 200 个时，则禁止此查询的执行。
-需要注意的是，由于扫描分桶数的计算是在规划阶段，而非执行阶段完成的。所以有可能出现因为分桶裁剪不完全，而保留了更多分区的情况。所以，实际扫描的分桶数小于设置值的查询也有可能被阻止。
-#### 阻止特定模式的查询
-由于各种原因，比如计算复杂度高，规划时间长等，可能会希望阻止使用模式的查询。
-以阻止函数 abs 举例。可以使用如下的正则表达式阻止规则，完成此目的。
+当单表扫描分桶数量超过 200 个时，则禁止此查询的执行。
+
+#### 场景四：阻止特定 SQL 模式
+
+某些查询模式可能导致计算复杂度高、规划时间长等问题，可以通过正则表达式匹配来阻止这些查询。
+
+**示例一：阻止使用特定函数**
+
+以阻止函数 `abs` 为例：
```sql
CREATE SQL_BLOCK_RULE rule_abs
@@ -173,142 +101,136 @@ PROPERTIES(
);
```
-上述正则表达式中
+上述正则表达式中：
-- (?i) 表示大小写不敏感
+- `(?i)` 表示大小写不敏感
+- `abs` 为想要阻止的目标函数
+- `\\s*` 表示在 abs 和左括号之间可以有任意个空白
+- `\\(.+\\)` 匹配函数参数
-- abs 为想要阻止的目标函数
+**示例二：阻止其他危险操作**
-- \\s*表示在 abs 和左括号之间可以有任意个空白
+同理，也可以使用类似的方法阻止 `set global`，以防止非预期的变量改变。或者阻止 `truncate table`，以防止非预期的删除数据。
-- \\(.+\\) 匹配函数参数
- 同理，也可以使用类似的方法阻止 set global，以防止非预期的变量改变。或者阻止 truncate table，以防止非预期的删除数据。
+#### 场景五：针对特定用户设置规则
-### 常见问题
+默认情况下，阻止规则全局生效（`"global" = "true"`）。如需仅对特定用户生效，可以创建用户级别的阻止规则：
-#### Q：正则匹配阻止规则会对集群产生副作用吗？
-A：是的。由于正则匹配是计算密集型的。当使用复杂的正则表达式，或者正则匹配规则过多时。会给 FE 的 CPU 带来显著的压力提升。所以，要谨慎添加正则匹配的阻止规则。除非必要，尽量不要使用复杂的正则表达式。
+1. 创建规则时设置 `"global"` 为 `"false"`：
-#### Q：可以临时关闭一个阻止规则吗？
-A：可以。修改阻止规则，将其属性中的"enable"改为"false"即可。
+ ```sql
+ CREATE SQL_BLOCK_RULE rule_001
+ PROPERTIES (
+ "sql"="select * from t",
+ "global" = "false",
+ "enable" = "true"
+ )
+ ```
-#### Q：阻止规则中的正则表达式使用哪种规范？
-A：阻止规则的正则表达式使用 java 的正则表达式规范。常用表达式可以参考 SQL 语法手册。完整的手册可以参考 https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html
+2. 将规则绑定到目标用户：
-## Workload Policy
+ ```sql
+ SET PROPERTY FOR 'root' 'SQL_block_rules' = 'rule_001';
+ ```
+
+3. 验证规则生效：
+
+ ```sql
+ MySQL root@127.0.0.1:test> select * from t;
+ (1105, 'errCode = 2, detailMessage = errCode = 2, detailMessage = SQL match regex SQL block rule: rule_001')
+ ```
+
+- 如果想对一个用户添加多个规则，在规则列表中列举所有的规则名字，以英文逗号隔开。
+- 如果想移除一个用户的所有规则，将规则列表置为空字符串即可：`SET PROPERTY FOR 'root' 'SQL_block_rules' = '';`
+
+如果需要修改或者删除阻止规则，可以参考阻止规则的 SQL 手册。
+
+### 注意事项
-SQL Block Rule 是一种在规划时进行熔断的配置，但是由于规划中代价的计算可能不准确（尤其是针对一些非常复杂的查询时，更加难以准确估算），所以会导致规则不生效或者误判。Workload Policy 弥补了这个缺陷，它可以在查询运行时对一些指标进行实时的监测，对运行时状态不符合预期的查询进行熔断，避免不符合预期的大查询占用过多资源从而影响集群的稳定性，常用的运行时监控指标如下：
+- 扫描行数、分区数、分桶数的计算均在规划阶段完成，只会考虑分区和分桶裁剪，不会考虑其他过滤条件的影响（即按最坏情况估算）。因此，实际扫描量小于设置值的查询也有可能被阻止。
+- 正则匹配是计算密集型操作，过多或过于复杂的正则规则会给 FE 的 CPU 带来显著压力。建议谨慎添加，除非必要，尽量不要使用复杂的正则表达式。
+- 如需临时关闭某条规则，修改其属性中的 `"enable"` 为 `"false"` 即可。
+- 阻止规则的正则表达式使用 Java 的正则表达式规范，完整手册可参考 https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html
-* 查询执行时间
-* 查询在单 BE 上的扫描行数
-* 查询在单 BE 上的扫描行数扫描字节数
-* 查询的在单 BE 上的内存使用
+## Workload Policy
-### 版本说明
+SQL Block Rule 在规划阶段进行熔断，但由于规划中的代价估算可能不准确（尤其是复杂查询），可能导致规则不生效或误判。Workload Policy 弥补了这一缺陷，它在查询运行时对实时指标进行监测，对不符合预期的查询进行熔断，避免大查询占用过多资源从而影响集群稳定性。
-自 Doris 2.1 版本起，可以通过 Workload Policy 可以实现大查询的熔断。
+自 Doris 2.1 版本起支持 Workload Policy，各负载类型的支持情况如下：
-| 版本 | 自2.1起 |
-|--------------------|-------|
+| 负载类型 | 是否支持 |
+|-------------------|---------|
| select | 支持 |
| insert into select | 支持 |
-| insert into values | 不支持 |
+| insert into values | 不支持 |
| stream load | 支持 |
| routine load | 支持 |
-| backup | 不支持 |
-| compaction | 不支持 |
+| backup | 不支持 |
+| compaction | 不支持 |
+
+### 创建与配置
-### 创建熔断策略
-使用 `CREATE WORKLOAD Policy` 命令可以创建资源管理策略。
+使用 `CREATE WORKLOAD POLICY` 命令创建策略。创建 Workload Policy 需要 admin_priv 权限。
-在下面的例子中创建一个名为 test_cancel_Policy 的 Policy，它会取消掉集群中运行时间超过 1000ms 的查询，当前状态为启用。创建 Workload Policy 需要 admin_priv 权限。
+以下示例创建一个名为 test_cancel_policy 的策略，它会取消运行时间超过 1000 ms 的查询：
```sql
-create workload Policy test_cancel_Policy
-Conditions(query_time > 1000)
-Actions(cancel_query)
-properties('enabled'='true');
+CREATE WORKLOAD POLICY test_cancel_policy
+CONDITIONS(query_time > 1000)
+ACTIONS(cancel_query)
+PROPERTIES('enabled'='true');
```
-在创建 Workload Policy 时需要指定以下内容：
-- Condition 表示策略触发条件，可以多个 Condition 串联，使用逗号“,”隔开，表示“与”的关系。在上例中 query_time > 1000 表示在查询时间大于 1s 时触发 Policy；目前支持的 Conditions 有：
+创建 Workload Policy 时需要指定以下三个部分：
-| 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 上是多并发执行，那么就是多个并发的累加值，单位是字节。 |
+#### 触发条件（Conditions）
-- Action 表示条件触发时采取的动作，目前一个 Policy 只能定义一个 Action（除 set_session_variable）。在上例中，cancel_query 表示取消查询；目前支持的 Actions 有：
+Conditions 表示策略的触发条件，多个 Condition 之间以逗号 `,` 分隔，表示"与"的关系。
-| Actions | 说明 |
-|-----------------------|------------------------------------------------------------------------------------------------------|
-| cancel_query | 取消查询。 |
-| set_session_variable | 触发 set session variable 语句。同一个 policy 可以有多个 set_session_variable 选项，目前只会在 FE 由 username 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）
-- Properties，定义了当前 Policy 的属性，包括是否启用和优先级。
+Actions 表示条件触发时采取的动作，目前一个 Policy 只能定义一个 Action（set_session_variable 除外）。
-| Properties | 说明 |
-|-----------------------|----------------------------------------------------------------------------------------------------|
-| enabled | 取值为 true 或 false，默认值为 true，表示当前 Policy 处于启用状态，false 表示当前 Policy 处于禁用状态 |
-| priority | 取值范围为 0 到 100 的正整数，默认值为 0，代表 Policy 的优先级，该值越大，优先级越高。这个属性的主要作用是，当查询匹配到多个 Policy 时，只选择优先级最高的 Policy。 |
-| workload_group | 目前一个 Policy 可以绑定一个 workload group，代表这个 Policy 只对某个 Workload Group 的查询生效。默认为空，代表对所有查询生效。 |
+| Action | 说明 |
+|----------------------|------------------------------------------------------------------------------------------------------------|
+| cancel_query | 取消查询 |
+| set_session_variable | 触发 set session variable 语句。同一个 Policy 可以有多个 set_session_variable 选项，目前只会在 FE 由 username Condition 触发 |
-### 将熔断策略绑定 Workload Group
-默认情况下，Workload Policy 会对所有支持的查询生效。如果想指定 Policy 只针对与某一个 Workload Group，需要通过 workload_group 选项绑定 Workload Group。语句如下：
+#### 策略属性（Properties）
-```sql
-create workload Policy test_cancel_big_query
-Conditions(query_time > 1000)
-Actions(cancel_query)
-properties('workload_group'='normal')
-```
+| Property | 说明 |
+|----------------|--------------------------------------------------------------------------------------------------------------|
+| enabled | 是否启用，取值为 true 或 false，默认值为 true |
+| priority | 优先级，取值范围为 0 到 100 的正整数，默认值为 0。值越大优先级越高，当查询匹配到多个 Policy 时，只有优先级最高的 Policy 生效 |
+| workload_group | 绑定的 Workload Group 名称，指定后 Policy 仅对该 Workload Group 的查询生效。默认为空，表示对所有查询生效 |
-### 注意事项
-- 同一个 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 Group
-### Workload Policy 效果演示
-
-#### 1 session 变量修改测试
-尝试修改 Admin 账户的 session 变量中的并发相关的参数
+默认情况下，Workload Policy 对所有支持的查询生效。如需仅针对某个 Workload Group 生效，可通过 `workload_group` 属性绑定：
```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)
+CREATE WORKLOAD POLICY test_cancel_big_query
+CONDITIONS(query_time > 1000)
+ACTIONS(cancel_query)
+PROPERTIES('workload_group'='normal')
+```
-// 创建修改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 的时间
+以下是一个 ckbench 的 q29 运行成功时的审计日志，可以看到该 SQL 需要 4.5s 完成：
```sql
-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;
+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;
+-----------------------------------------------------------------------+------------------+----------+---------------------------------------------------------------------------------------------------------------------+
| k | l | c | min(Referer) |
+-----------------------------------------------------------------------+------------------+----------+---------------------------------------------------------------------------------------------------------------------+
@@ -327,16 +249,53 @@ mySQL [hits]>SELECT REGEXP_REPLACE(Referer, '^https?://(?:www\.)?([^/]+)/.*$', '
11 rows in set (4.50 sec)
```
-创建一个运行时间超过 3s 就取消查询的 Policy
+创建一个运行时间超过 3s 就取消查询的 Policy：
+
+```sql
+CREATE WORKLOAD POLICY test_cancel_3s_query
+CONDITIONS(query_time > 3000)
+ACTIONS(cancel_query)
+```
+
+再次执行 SQL，可以看到查询被熔断：
+
```sql
-create workload Policy test_cancel_3s_query
-Conditions(query_time > 3000)
-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
```
-再次执行 SQL 可以看到 SQL 执行会直接报错
+#### 示例二：修改用户 session 变量
+
+通过 Workload Policy 可以自动修改特定用户的 session 变量，例如调整并发参数：
+
```sql
-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
+-- 登录 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，只能通过删除后重新创建的方式修改。
diff --git a/versioned_docs/version-3.x/admin-manual/workload-management/sql-blocking.md b/versioned_docs/version-3.x/admin-manual/workload-management/sql-blocking.md
index ff93fb5ee0b..bb42e1c8a98 100644
--- a/versioned_docs/version-3.x/admin-manual/workload-management/sql-blocking.md
+++ b/versioned_docs/version-3.x/admin-manual/workload-management/sql-blocking.md
@@ -2,116 +2,43 @@
{
"title": "Query Circuit Breaker",
"language": "en",
- "description": "Query circuit breaking is a protective mechanism used to prevent long-running or resource-consuming queries from having a negative impact on the "
+ "description": "Apache Doris query circuit breaker mechanism, supporting SQL Block Rule (planning-time blocking) and Workload Policy (runtime circuit breaking) strategies to automatically terminate abnormal queries by limiting scan rows, partitions, execution time, memory, and more to ensure cluster stability."
}
---
Query circuit breaking is a protective mechanism used to prevent long-running or resource-consuming queries from having a negative impact on the system. When a query exceeds predefined resource or time limits, the circuit breaker mechanism automatically terminates the query to avoid adverse effects on system performance, resource usage, and other queries. This mechanism ensures the stability of the cluster in a multi-user environment, preventing a single query from exhausting system reso [...]
-In Doris, there are two types of circuit breaker strategies:
+Doris provides two circuit breaker strategies that operate at different stages of the query lifecycle:
-- **Planning-time circuit breaking**, namely **SQL Block Rule**, which is used to prevent the execution of statements that match specific patterns. Block rules apply to any statements, including DDL and DML. Typically, block rules are configured by database administrators (DBAs) to enhance cluster stability. For example,
-
- - Preventing a query from scanning too many rows of data
- - Preventing a query from scanning too many partitions
- - Preventing a statement that modifies global variables to avoid accidental changes to cluster configurations.
- - Preventing a query pattern that typically consumes excessive resources
-
-- **Runtime circuit breaking**, namely **Workload Policy**, which monitors in real-time during runtime the execution time of queries, the amount of data scanned, and memory consumption to implement rule-based query circuit breaking.
+| Dimension | SQL Block Rule (Planning-time) | Workload Policy (Runtime) |
+|-----------|-------------------------------|--------------------------|
+| Effective Stage | Planning phase, blocked before execution | Execution phase, circuit broken during runtime |
+| Judgment Basis | Estimated scan volume, SQL pattern matching | Real-time metrics such as execution time, memory usage, and scan volume |
+| Accuracy | Based on cost estimation, may have false positives | Based on real-time monitoring, more accurate |
+| Use Cases | Block known dangerous SQL patterns and full table scans | Circuit break unexpectedly large queries during execution |
+| Applicable Statements | Any statement (DDL, DML) | select, insert into select, stream load, routine load |
## SQL Block Rule
-According to the block pattern, it can be divided into:
-
-- Scan row count block rule
-- Scan partition count block rule
-- Scan bucket count block rule
-- Query statement regex matching block rule
-- Query statement hash value matching block rule
-
-Blocking rules can be categorized according to the scope of blocking into:
-
-- Global-level blocking rules
-- User-level blocking rules
-
-### Usage
-
-#### Global-level blocking rules
-
-```sql
-CREATE SQL_BLOCK_RULE rule_001
-PROPERTIES (
- "sql"="select \\* from t",
- "global" = "true",
- "enable" = "true"
-)
-```
-
-In this way, we have created a global-level blocking rule. The rule is named rule_001. A query statement regex matching rule has been configured to block all query statements that match the regex `select \\* from t`.
+SQL Block Rule is used to block statements that match specific patterns during the query planning phase. It is typically configured by database administrators (DBAs) to enhance cluster stability.
-Since this is a global-level blocking rule, any user executing statements that match the above regex will be blocked. For example:
+Each rule is defined by the following properties that control its behavior and scope:
-```sql
-MySQL root@127.0.0.1:test> select * from t;
-(1105, 'errCode = 2, detailMessage = errCode = 2, detailMessage = SQL match regex SQL block rule: rule_001')
-```
-
-#### User-level Blocking Rule
+| Property | Description | Values |
+|----------|-------------|--------|
+| `sql` | Regular expression to match query statements | Java regex string |
+| `sqlHash` | Hash value to match query statements | SQL hash value string |
+| `cardinality` | Maximum number of rows allowed to scan | Positive integer |
+| `partition_num` | Maximum number of partitions allowed to scan | Positive integer |
+| `tablet_num` | Maximum number of buckets allowed to scan | Positive integer |
+| `global` | Whether the rule is global | `"true"` (applies to all users) or `"false"` (applies only to bound users) |
+| `enable` | Whether the rule is enabled | `"true"` or `"false"` |
-```sql
-CREATE SQL_BLOCK_RULE rule_001
-PROPERTIES (
- "sql"="select * from t",
- "global" = "false",
- "enable" = "true"
-)
-```
+### Use Cases and Examples
-Unlike global-level blocking rules, user-level blocking rules only apply to specified users. When we create a blocking rule, set the property "global" to "false". Then, this blocking rule will be considered a user-level blocking rule.
+#### Case 1: Limiting Scan Row Count
-To make user-level blocking rules effective, you also need to set the corresponding properties for the users who need to use this rule. For example:
-
-```sql
-set property for 'root' 'SQL_block_rules' = 'rule_001';
-```
-
-Thus, after the above configuration, when the root user executes a query, the blocking rule named rule_001 will be applied.
-
-```sql
-MySQL root@127.0.0.1:test> set property for 'root' 'SQL_block_rules' = '';
-Query OK, 0 rows affected
-Time: 0.018s
-MySQL root@127.0.0.1:test> select * from t;
-+----+----+
-| id | c1 |
-+----+----+
-| 1 | 1 |
-+----+----+
-
-1 row in set
-Time: 0.027s
-MySQL root@127.0.0.1:test> set property for 'root' 'SQL_block_rules' = 'rule_001';
-Query OK, 0 rows affected
-Time: 0.008s
-MySQL root@127.0.0.1:test> select * from t;
-(1105, 'errCode = 2, detailMessage = errCode = 2, detailMessage = SQL match regex SQL block rule: rule_001')
-```
-- If you want to add multiple user-level blocking rules for a user, list all the rule names in the rule list, separated by commas.
-- If you want to remove all user-level blocking rules for a user, set the rule list to an empty string.
-
-#### Other Operations
-If you need to modify or delete blocking rules, refer to the SQL manual for blocking rules.
-
-### Use Cases
-You can use the following scenarios:
-
-* Blocking scans that exceed a specified number of rows
-* Blocking scans that exceed a specified number of partitions
-* Blocking scans that exceed a specified number of buckets
-* Blocking queries with specific patterns
-
-#### Blocking Scans that Exceed a Specified Number of Rows
-Scanning data significantly consumes BE's IO and CPU resources. Therefore, unnecessary data scans pose a substantial challenge to cluster stability. In daily use, blind full table scan operations often occur, such as `SELECT * FROM t`. To prevent such queries from damaging the cluster, you can set an upper limit on the number of rows scanned by a single query on a single table.
+In daily use, blind full table scan operations often occur, such as `SELECT * FROM t`. Scanning data significantly consumes BE's IO and CPU resources, posing a substantial challenge to cluster stability. You can set an upper limit on the number of rows scanned by a single query on a single table to prevent such operations:
```sql
CREATE SQL_BLOCK_RULE rule_card
@@ -123,12 +50,11 @@ PROPERTIES
);
```
-When the above rules are set, if a single table scan exceeds 1000 rows, the execution of the query is prohibited.
-It should be noted that since the calculation of the number of rows scanned is done during the planning phase, not the execution phase. Therefore, when calculating the number of rows, only partition and bucket pruning are considered, and the impact of other filtering conditions on the number of rows scanned is not taken into account. In other words, the worst-case scenario is considered. Therefore, queries where the actual number of rows scanned is less than the set value may also be blocked.
+When a single table scan exceeds 1000 rows, the query execution will be blocked.
-#### Prevent Scanning Data from Exceeding the Specified Number of Partitions
-Scanning too many partitions can significantly increase the CPU consumption of BE. Additionally, if the query is on an external table, it is more likely to incur significant network overhead and metadata retrieval overhead. In daily use, this is often due to forgetting to write filtering conditions on partition columns or writing them incorrectly. To prevent such queries from damaging the cluster, you can set an upper limit on the number of partitions scanned by a single query on a singl [...]
+#### Case 2: Limiting Scan Partition Count
+Scanning too many partitions can significantly increase BE's CPU consumption. Additionally, if the query targets an external table, it may incur significant network overhead and metadata retrieval overhead. This is often caused by forgetting to write filtering conditions on partition columns or writing them incorrectly. You can set a partition count limit to avoid such issues:
```sql
CREATE SQL_BLOCK_RULE rule_part_num
@@ -139,12 +65,12 @@ PROPERTIES
"enable" = "true"
);
```
-When the above rules are set, if the number of partitions scanned for a single table exceeds 30, the execution of the query is prohibited.
-It should be noted that the calculation of the number of scanned partitions is completed during the planning phase, not the execution phase. Therefore, there may be cases where more partitions are retained due to incomplete partition pruning. Thus, queries where the actual number of scanned partitions is less than the set value may also be blocked.
-#### Prevent Scanning Data with Excessive Bucket Counts
-Scanning too many buckets can significantly increase the BE's CPU consumption. To prevent such queries from harming the cluster, you can set an upper limit on the number of partitions a single query can scan on a single table.
+When the number of partitions scanned for a single table exceeds 30, the query execution will be blocked.
+
+#### Case 3: Limiting Scan Bucket Count
+Scanning too many buckets can also significantly increase BE's CPU consumption. You can set a bucket count limit to avoid such issues:
```sql
CREATE SQL_BLOCK_RULE rule_teblet_num
@@ -155,16 +81,16 @@ PROPERTIES
"enable" = "true"
);
```
-When the above rules are set, if the number of buckets scanned in a single table exceeds 200, the execution of the query is prohibited.
-It is important to note that the calculation of the number of scanned buckets is done during the planning phase, not the execution phase. Therefore, it is possible that due to incomplete bucket pruning, more partitions are retained. As a result, queries with an actual number of scanned buckets less than the set value may also be blocked.
+When the number of buckets scanned in a single table exceeds 200, the query execution will be blocked.
-#### Blocking Queries with Specific Patterns
+#### Case 4: Blocking Specific SQL Patterns
-For various reasons, such as high computational complexity or long planning time, you may want to block queries that use certain patterns.
+Certain query patterns may cause high computational complexity, long planning time, and other issues. You can block these queries using regular expression matching.
-For example, to block the `abs` function. You can use the following regular expression block rule to achieve this purpose.
+**Example 1: Blocking a specific function**
+For example, to block the `abs` function:
```sql
CREATE SQL_BLOCK_RULE rule_abs
@@ -175,142 +101,136 @@ PROPERTIES(
);
```
-In the above regular expressions:
+In the above regular expression:
-- `(?i)` indicates case-insensitive matching.
-- `abs` is the target function to be blocked.
-- `\s*` signifies that any amount of whitespace is allowed between `abs` and the left parenthesis.
-- `\(.+\)` matches the function parameters.
+- `(?i)` indicates case-insensitive matching
+- `abs` is the target function to be blocked
+- `\\s*` signifies that any amount of whitespace is allowed between `abs` and the left parenthesis
+- `\\(.+\\)` matches the function parameters
-Similarly, similar methods can be used to block `set global` to prevent unintended variable changes, or block `truncate table` to prevent unintended data deletions.
+**Example 2: Blocking other dangerous operations**
-### FAQ
+Similarly, you can use the same method to block `set global` to prevent unintended variable changes, or block `truncate table` to prevent unintended data deletions.
-#### Q: Will regular expression blocking rules have side effects on the cluster?
-A: Yes. Regular expression matching is computationally intensive. When using complex regular expressions or too many regex blocking rules, it can significantly increase the CPU load on the FE. Therefore, add regex blocking rules cautiously. Avoid using complex regular expressions unless necessary.
+#### Case 5: Setting Rules for Specific Users
-#### Q: Can a blocking rule be temporarily disabled?
-A: Yes. Modify the blocking rule by setting its "enable" property to "false".
+By default, block rules apply globally (`"global" = "true"`). To apply a rule only to specific users, you can create a user-level block rule:
-#### Q: What standard do the regular expressions in blocking rules use?
-A: The regular expressions in blocking rules use Java's regular expression syntax. Common expressions can refer to the SQL syntax manual. The complete manual can be found at https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html
+1. Set `"global"` to `"false"` when creating the rule:
-## Workload Policy
-
-SQL Block Rule is a configuration for circuit breaking during planning, but because the cost calculation during planning may be inaccurate (especially for very complex queries, making it difficult to estimate accurately), it can lead to rules not being effective or false positives. Workload Policy addresses this limitation by allowing real-time monitoring of certain metrics during query execution, and circuit breaking queries whose runtime state does not meet expectations. This prevents [...]
+ ```sql
+ CREATE SQL_BLOCK_RULE rule_001
+ PROPERTIES (
+ "sql"="select * from t",
+ "global" = "false",
+ "enable" = "true"
+ )
+ ```
-* Query execution time
-* Number of rows scanned per BE
-* Number of bytes scanned per BE
-* Memory usage per BE
+2. Bind the rule to the target user:
-### Version Notes
+ ```sql
+ SET PROPERTY FOR 'root' 'SQL_block_rules' = 'rule_001';
+ ```
-Since Doris version 2.1, Workload Policy can be used to implement circuit breaking for large queries.
+3. Verify the rule is effective:
-| Version | since 2.1 |
-|--------------------|-----------|
-| select | yes |
-| insert into select | yes |
-| insert into values | no |
-| stream load | yes |
-| routine load | yes |
-| backup | no |
-| compaction | no |
+ ```sql
+ MySQL root@127.0.0.1:test> select * from t;
+ (1105, 'errCode = 2, detailMessage = errCode = 2, detailMessage = SQL match regex SQL block rule: rule_001')
+ ```
-### Creating Workload Policy
-Use the `CREATE WORKLOAD Policy` command to create a resource management policy.
+- To add multiple rules for a user, list all rule names in the rule list, separated by commas.
+- To remove all rules for a user, set the rule list to an empty string: `SET PROPERTY FOR 'root' 'SQL_block_rules' = '';`
-In the example below, create a Policy named `test_cancel_Policy`, which will cancel queries running in the cluster for more than 1000ms. The current status is enabled. Creating a Workload Policy requires `admin_priv` privileges.
+To modify or delete block rules, refer to the SQL manual for block rules.
-```sql
-create workload policy test_cancel_Policy
-Conditions(query_time > 1000)
-Actions(cancel_query)
-properties('enabled'='true');
-```
-
-When creating a Workload Policy, the following must be specified:
+### Important Notes
-- **Condition** represents the policy trigger condition. Multiple Conditions can be linked using commas "," to represent an "AND" relationship. In the example above, `query_time > 1000` indicates that the Policy is triggered when the query time exceeds 1 second. Currently supported Conditions are:
+- The calculation of scan row count, partition count, and bucket count is performed during the planning phase. Only partition and bucket pruning are considered, and other filtering conditions are not taken into account (i.e., the worst-case scenario is estimated). Therefore, queries with actual scan volumes below the set values may also be blocked.
+- Regular expression matching is a computationally intensive operation. Too many or overly complex regex rules can put significant pressure on FE's CPU. Use them cautiously and avoid complex regular expressions unless necessary.
+- To temporarily disable a rule, set its `"enable"` property to `"false"`.
+- Regular expressions in block rules use Java's regular expression syntax. For the complete reference, see https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html
-| Conditions | Description |
-|-----------------------|-------------------------------------------------------------------------------------------------------------|
-| username | The username carried by the query, only triggers the `set_session_variable` Action in FE. |
-| be_scan_rows | The number of rows scanned by a SQL in a single BE process. If the SQL is executed concurrently on BE, it is the cumulative value of multiple concurrent executions. |
-| be_scan_bytes | The number of bytes scanned by a SQL in a single BE process. If the SQL is executed concurrently on BE, it is the cumulative value of multiple concurrent executions, in bytes. |
-| query_time | The runtime of a SQL in a single BE process, in milliseconds. |
-| query_be_memory_bytes | The memory usage of a SQL in a single BE process. If the SQL is executed concurrently on BE, it is the cumulative value of multiple concurrent executions, in bytes. |
+## Workload Policy
-- **Action** represents the action taken when the condition is triggered. Currently, a Policy can only define one Action (except for `set_session_variable`). In the example above, `cancel_query` indicates cancelling the query. Currently supported Actions are:
+SQL Block Rule performs circuit breaking during the planning phase, but since cost estimation during planning may be inaccurate (especially for complex queries), it can lead to rules not being effective or false positives. Workload Policy addresses this limitation by monitoring real-time metrics during query execution and circuit breaking queries whose runtime state does not meet expectations, preventing unexpectedly large queries from consuming excessive resources and affecting cluster [...]
-| Actions | Description |
-|------------------------|------------------------------------------------------------------------------------------------------------------|
-| cancel_query | Cancel the query. |
-| set_session_variable | Triggers the `set session variable` statement. A single policy can have multiple `set_session_variable` options, currently only triggered in FE by the `username` Condition. |
+Workload Policy has been supported since Doris version 2.1. The support status for each load type is as follows:
-- **Properties** define the attributes of the current Policy, including whether it is enabled and its priority.
+| Load Type | Supported |
+|--------------------|-----------|
+| select | Yes |
+| insert into select | Yes |
+| insert into values | No |
+| stream load | Yes |
+| routine load | Yes |
+| backup | No |
+| compaction | No |
-| Properties | Description |
-|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| enabled | Can be `true` or `false`, default is `true`, indicating the Policy is enabled. `false` indicates the Policy is disabled. |
-| priority | An integer ranging from 0 to 100, default is 0, representing the Policy's priority. The higher the value, the higher the priority. This attribute mainly ensures that when a query matches multiple Policies, only the Policy with the highest priority is selected. |
-| workload_group | Currently, a Policy can bind to one workload group, meaning this Policy only applies to queries from a specific Workload Group. The default is empty, meaning it applies to all queries. |
+### Creation and Configuration
-### Binding Workload Policy to Workload Group
+Use the `CREATE WORKLOAD POLICY` command to create a policy. Creating a Workload Policy requires `admin_priv` privileges.
-By default, Workload Policies apply to all supported queries. If you want to specify that a Policy only targets a specific Workload Group, you need to bind the Workload Group through the `workload_group` option. The statement is as follows:
+The following example creates a policy named test_cancel_policy that cancels queries running longer than 1000 ms:
```sql
-create workload policy test_cancel_big_query
-Conditions(query_time > 1000)
-Actions(cancel_query)
-properties('workload_group'='normal')
+CREATE WORKLOAD POLICY test_cancel_policy
+CONDITIONS(query_time > 1000)
+ACTIONS(cancel_query)
+PROPERTIES('enabled'='true');
```
-### Important Notes
-- The Conditions and Actions of the same Policy must either both be FE or both be BE. For example, `set_session_variable` and `cancel_query` cannot be configured within the same Policy. Conditions `be_scan_rows` and `username` cannot be configured within the same Policy.
-- Currently, Policies are executed by asynchronous threads at fixed time intervals, which introduces a certain latency in policy enforcement. For example, if a user configures a policy to cancel a query when the number of scanned rows exceeds 1,000,000, and the cluster resources are relatively idle at that time, the query may finish before the cancellation policy takes effect. The current interval is 500ms, meaning that queries with run times shorter than this interval may bypass the pol [...]
-- Currently supported load types include select/insert, select/stream load, broker load, and routine load.
-- A single query may match multiple Policies, but only the Policy with the highest priority will take effect.
-- Modifications to Actions and Conditions are currently not supported; they can only be modified by deleting and recreating them.
+When creating a Workload Policy, three components must be specified:
-### Workload Policy Demonstration
+#### Conditions
-#### 1. Session Variable Modification Test
-Attempt to modify concurrency-related parameters in the session variables of the Admin account.
+Conditions represent the policy trigger conditions. Multiple Conditions are separated by commas `,` to represent an "AND" relationship.
-```sql
--- log on admin to check variables
-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)
+| Condition | Description |
+|-----------------------|------------------------------------------------------------------------------------------------------|
+| username | The username carried by the query; only triggers the set_session_variable Action in FE |
+| be_scan_rows | Number of rows scanned by a SQL in a single BE process; cumulative value when executed concurrently |
+| be_scan_bytes | Number of bytes scanned by a SQL in a single BE process; cumulative value when executed concurrently, in bytes |
+| query_time | Runtime of a SQL in a single BE process, in milliseconds |
+| query_be_memory_bytes | Memory usage of a SQL in a single BE process; cumulative value when executed concurrently, in bytes |
--- Create a Policy to modify the concurrency parameters of the admin account.
-create workload Policy test_set_var_Policy
-Conditions(username='admin')
-Actions(set_session_variable 'parallel_fragment_exec_instance_num=1')
+#### Actions
--- After some time, check the admin account's parameters again.
-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)
+Actions represent the action taken when the condition is triggered. Currently, a Policy can only define one Action (except for set_session_variable).
+
+| Action | Description |
+|----------------------|-----------------------------------------------------------------------------------------------------------------|
+| cancel_query | Cancel the query |
+| set_session_variable | Triggers a set session variable statement. A single Policy can have multiple set_session_variable options; currently only triggered in FE by the username Condition |
+
+#### Properties
+
+| Property | Description |
+|----------------|---------------------------------------------------------------------------------------------------------------------|
+| enabled | Whether the policy is enabled; values are true or false, default is true |
+| priority | Priority, an integer from 0 to 100, default is 0. Higher values mean higher priority; when a query matches multiple Policies, only the one with the highest priority takes effect |
+| workload_group | The name of the bound Workload Group; when specified, the Policy only applies to queries from that Workload Group. Default is empty, meaning it applies to all queries |
+
+#### Binding to a Workload Group
+
+By default, Workload Policies apply to all supported queries. To specify that a Policy only targets a specific Workload Group, bind it through the `workload_group` property:
+
+```sql
+CREATE WORKLOAD POLICY test_cancel_big_query
+CONDITIONS(query_time > 1000)
+ACTIONS(cancel_query)
+PROPERTIES('workload_group'='normal')
```
-#### 2. Big Query Circuit Breaker Test
-Test to circuit break queries that run longer than 3s. Below is an audit log of a successful run of ckbench's q29, showing that this SQL took 4.5s to complete.
+### Usage Examples
+
+#### Example 1: Circuit Breaking Timeout Queries
+Below is an audit log of a successful run of ckbench's q29, showing that this SQL took 4.5s to complete:
```sql
-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;
+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;
+-----------------------------------------------------------------------+------------------+----------+---------------------------------------------------------------------------------------------------------------------+
| k | l | c | min(Referer) |
+-----------------------------------------------------------------------+------------------+----------+---------------------------------------------------------------------------------------------------------------------+
@@ -329,17 +249,53 @@ mySQL [hits]>SELECT REGEXP_REPLACE(Referer, '^https?://(?:www\.)?([^/]+)/.*$', '
11 rows in set (4.50 sec)
```
-Create a Policy that cancels a query if it runs longer than 3 seconds.
+Create a Policy that cancels queries running longer than 3 seconds:
+
+```sql
+CREATE WORKLOAD POLICY test_cancel_3s_query
+CONDITIONS(query_time > 3000)
+ACTIONS(cancel_query)
+```
+
+Upon re-executing the SQL, you can see the query is circuit broken:
+
```sql
-create workload Policy test_cancel_3s_query
-Conditions(query_time > 3000)
-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
```
-Upon re-executing the SQL, you can see that the SQL execution will directly report an error.
+#### Example 2: Modifying User Session Variables
+
+Workload Policy can automatically modify session variables for specific users, for example, adjusting concurrency parameters:
```sql
-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
+-- Log in to admin account and check concurrency parameters
+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 to modify the concurrency parameters of the admin account
+CREATE WORKLOAD POLICY test_set_var_policy
+CONDITIONS(username='admin')
+ACTIONS(set_session_variable 'parallel_fragment_exec_instance_num=1')
+
+-- After some time, check the admin account's parameters again
+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)
```
+### Important Notes
+
+- The Conditions and Actions of the same Policy must belong to the same side (FE or BE). For example, set_session_variable and cancel_query cannot be configured within the same Policy; Condition be_scan_rows and Condition username also cannot be configured within the same Policy.
+- Policies are executed by asynchronous threads at fixed time intervals (currently 500 ms), so there is a certain latency in policy enforcement. Queries with very short run times may bypass the policy check.
+- A single query may match multiple Policies, but only the Policy with the highest priority will take effect.
+- Modifications to Actions and Conditions are currently not supported; they can only be modified by deleting and recreating them.
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 ff93fb5ee0b..bb42e1c8a98 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
@@ -2,116 +2,43 @@
{
"title": "Query Circuit Breaker",
"language": "en",
- "description": "Query circuit breaking is a protective mechanism used to prevent long-running or resource-consuming queries from having a negative impact on the "
+ "description": "Apache Doris query circuit breaker mechanism, supporting SQL Block Rule (planning-time blocking) and Workload Policy (runtime circuit breaking) strategies to automatically terminate abnormal queries by limiting scan rows, partitions, execution time, memory, and more to ensure cluster stability."
}
---
Query circuit breaking is a protective mechanism used to prevent long-running or resource-consuming queries from having a negative impact on the system. When a query exceeds predefined resource or time limits, the circuit breaker mechanism automatically terminates the query to avoid adverse effects on system performance, resource usage, and other queries. This mechanism ensures the stability of the cluster in a multi-user environment, preventing a single query from exhausting system reso [...]
-In Doris, there are two types of circuit breaker strategies:
+Doris provides two circuit breaker strategies that operate at different stages of the query lifecycle:
-- **Planning-time circuit breaking**, namely **SQL Block Rule**, which is used to prevent the execution of statements that match specific patterns. Block rules apply to any statements, including DDL and DML. Typically, block rules are configured by database administrators (DBAs) to enhance cluster stability. For example,
-
- - Preventing a query from scanning too many rows of data
- - Preventing a query from scanning too many partitions
- - Preventing a statement that modifies global variables to avoid accidental changes to cluster configurations.
- - Preventing a query pattern that typically consumes excessive resources
-
-- **Runtime circuit breaking**, namely **Workload Policy**, which monitors in real-time during runtime the execution time of queries, the amount of data scanned, and memory consumption to implement rule-based query circuit breaking.
+| Dimension | SQL Block Rule (Planning-time) | Workload Policy (Runtime) |
+|-----------|-------------------------------|--------------------------|
+| Effective Stage | Planning phase, blocked before execution | Execution phase, circuit broken during runtime |
+| Judgment Basis | Estimated scan volume, SQL pattern matching | Real-time metrics such as execution time, memory usage, and scan volume |
+| Accuracy | Based on cost estimation, may have false positives | Based on real-time monitoring, more accurate |
+| Use Cases | Block known dangerous SQL patterns and full table scans | Circuit break unexpectedly large queries during execution |
+| Applicable Statements | Any statement (DDL, DML) | select, insert into select, stream load, routine load |
## SQL Block Rule
-According to the block pattern, it can be divided into:
-
-- Scan row count block rule
-- Scan partition count block rule
-- Scan bucket count block rule
-- Query statement regex matching block rule
-- Query statement hash value matching block rule
-
-Blocking rules can be categorized according to the scope of blocking into:
-
-- Global-level blocking rules
-- User-level blocking rules
-
-### Usage
-
-#### Global-level blocking rules
-
-```sql
-CREATE SQL_BLOCK_RULE rule_001
-PROPERTIES (
- "sql"="select \\* from t",
- "global" = "true",
- "enable" = "true"
-)
-```
-
-In this way, we have created a global-level blocking rule. The rule is named rule_001. A query statement regex matching rule has been configured to block all query statements that match the regex `select \\* from t`.
+SQL Block Rule is used to block statements that match specific patterns during the query planning phase. It is typically configured by database administrators (DBAs) to enhance cluster stability.
-Since this is a global-level blocking rule, any user executing statements that match the above regex will be blocked. For example:
+Each rule is defined by the following properties that control its behavior and scope:
-```sql
-MySQL root@127.0.0.1:test> select * from t;
-(1105, 'errCode = 2, detailMessage = errCode = 2, detailMessage = SQL match regex SQL block rule: rule_001')
-```
-
-#### User-level Blocking Rule
+| Property | Description | Values |
+|----------|-------------|--------|
+| `sql` | Regular expression to match query statements | Java regex string |
+| `sqlHash` | Hash value to match query statements | SQL hash value string |
+| `cardinality` | Maximum number of rows allowed to scan | Positive integer |
+| `partition_num` | Maximum number of partitions allowed to scan | Positive integer |
+| `tablet_num` | Maximum number of buckets allowed to scan | Positive integer |
+| `global` | Whether the rule is global | `"true"` (applies to all users) or `"false"` (applies only to bound users) |
+| `enable` | Whether the rule is enabled | `"true"` or `"false"` |
-```sql
-CREATE SQL_BLOCK_RULE rule_001
-PROPERTIES (
- "sql"="select * from t",
- "global" = "false",
- "enable" = "true"
-)
-```
+### Use Cases and Examples
-Unlike global-level blocking rules, user-level blocking rules only apply to specified users. When we create a blocking rule, set the property "global" to "false". Then, this blocking rule will be considered a user-level blocking rule.
+#### Case 1: Limiting Scan Row Count
-To make user-level blocking rules effective, you also need to set the corresponding properties for the users who need to use this rule. For example:
-
-```sql
-set property for 'root' 'SQL_block_rules' = 'rule_001';
-```
-
-Thus, after the above configuration, when the root user executes a query, the blocking rule named rule_001 will be applied.
-
-```sql
-MySQL root@127.0.0.1:test> set property for 'root' 'SQL_block_rules' = '';
-Query OK, 0 rows affected
-Time: 0.018s
-MySQL root@127.0.0.1:test> select * from t;
-+----+----+
-| id | c1 |
-+----+----+
-| 1 | 1 |
-+----+----+
-
-1 row in set
-Time: 0.027s
-MySQL root@127.0.0.1:test> set property for 'root' 'SQL_block_rules' = 'rule_001';
-Query OK, 0 rows affected
-Time: 0.008s
-MySQL root@127.0.0.1:test> select * from t;
-(1105, 'errCode = 2, detailMessage = errCode = 2, detailMessage = SQL match regex SQL block rule: rule_001')
-```
-- If you want to add multiple user-level blocking rules for a user, list all the rule names in the rule list, separated by commas.
-- If you want to remove all user-level blocking rules for a user, set the rule list to an empty string.
-
-#### Other Operations
-If you need to modify or delete blocking rules, refer to the SQL manual for blocking rules.
-
-### Use Cases
-You can use the following scenarios:
-
-* Blocking scans that exceed a specified number of rows
-* Blocking scans that exceed a specified number of partitions
-* Blocking scans that exceed a specified number of buckets
-* Blocking queries with specific patterns
-
-#### Blocking Scans that Exceed a Specified Number of Rows
-Scanning data significantly consumes BE's IO and CPU resources. Therefore, unnecessary data scans pose a substantial challenge to cluster stability. In daily use, blind full table scan operations often occur, such as `SELECT * FROM t`. To prevent such queries from damaging the cluster, you can set an upper limit on the number of rows scanned by a single query on a single table.
+In daily use, blind full table scan operations often occur, such as `SELECT * FROM t`. Scanning data significantly consumes BE's IO and CPU resources, posing a substantial challenge to cluster stability. You can set an upper limit on the number of rows scanned by a single query on a single table to prevent such operations:
```sql
CREATE SQL_BLOCK_RULE rule_card
@@ -123,12 +50,11 @@ PROPERTIES
);
```
-When the above rules are set, if a single table scan exceeds 1000 rows, the execution of the query is prohibited.
-It should be noted that since the calculation of the number of rows scanned is done during the planning phase, not the execution phase. Therefore, when calculating the number of rows, only partition and bucket pruning are considered, and the impact of other filtering conditions on the number of rows scanned is not taken into account. In other words, the worst-case scenario is considered. Therefore, queries where the actual number of rows scanned is less than the set value may also be blocked.
+When a single table scan exceeds 1000 rows, the query execution will be blocked.
-#### Prevent Scanning Data from Exceeding the Specified Number of Partitions
-Scanning too many partitions can significantly increase the CPU consumption of BE. Additionally, if the query is on an external table, it is more likely to incur significant network overhead and metadata retrieval overhead. In daily use, this is often due to forgetting to write filtering conditions on partition columns or writing them incorrectly. To prevent such queries from damaging the cluster, you can set an upper limit on the number of partitions scanned by a single query on a singl [...]
+#### Case 2: Limiting Scan Partition Count
+Scanning too many partitions can significantly increase BE's CPU consumption. Additionally, if the query targets an external table, it may incur significant network overhead and metadata retrieval overhead. This is often caused by forgetting to write filtering conditions on partition columns or writing them incorrectly. You can set a partition count limit to avoid such issues:
```sql
CREATE SQL_BLOCK_RULE rule_part_num
@@ -139,12 +65,12 @@ PROPERTIES
"enable" = "true"
);
```
-When the above rules are set, if the number of partitions scanned for a single table exceeds 30, the execution of the query is prohibited.
-It should be noted that the calculation of the number of scanned partitions is completed during the planning phase, not the execution phase. Therefore, there may be cases where more partitions are retained due to incomplete partition pruning. Thus, queries where the actual number of scanned partitions is less than the set value may also be blocked.
-#### Prevent Scanning Data with Excessive Bucket Counts
-Scanning too many buckets can significantly increase the BE's CPU consumption. To prevent such queries from harming the cluster, you can set an upper limit on the number of partitions a single query can scan on a single table.
+When the number of partitions scanned for a single table exceeds 30, the query execution will be blocked.
+
+#### Case 3: Limiting Scan Bucket Count
+Scanning too many buckets can also significantly increase BE's CPU consumption. You can set a bucket count limit to avoid such issues:
```sql
CREATE SQL_BLOCK_RULE rule_teblet_num
@@ -155,16 +81,16 @@ PROPERTIES
"enable" = "true"
);
```
-When the above rules are set, if the number of buckets scanned in a single table exceeds 200, the execution of the query is prohibited.
-It is important to note that the calculation of the number of scanned buckets is done during the planning phase, not the execution phase. Therefore, it is possible that due to incomplete bucket pruning, more partitions are retained. As a result, queries with an actual number of scanned buckets less than the set value may also be blocked.
+When the number of buckets scanned in a single table exceeds 200, the query execution will be blocked.
-#### Blocking Queries with Specific Patterns
+#### Case 4: Blocking Specific SQL Patterns
-For various reasons, such as high computational complexity or long planning time, you may want to block queries that use certain patterns.
+Certain query patterns may cause high computational complexity, long planning time, and other issues. You can block these queries using regular expression matching.
-For example, to block the `abs` function. You can use the following regular expression block rule to achieve this purpose.
+**Example 1: Blocking a specific function**
+For example, to block the `abs` function:
```sql
CREATE SQL_BLOCK_RULE rule_abs
@@ -175,142 +101,136 @@ PROPERTIES(
);
```
-In the above regular expressions:
+In the above regular expression:
-- `(?i)` indicates case-insensitive matching.
-- `abs` is the target function to be blocked.
-- `\s*` signifies that any amount of whitespace is allowed between `abs` and the left parenthesis.
-- `\(.+\)` matches the function parameters.
+- `(?i)` indicates case-insensitive matching
+- `abs` is the target function to be blocked
+- `\\s*` signifies that any amount of whitespace is allowed between `abs` and the left parenthesis
+- `\\(.+\\)` matches the function parameters
-Similarly, similar methods can be used to block `set global` to prevent unintended variable changes, or block `truncate table` to prevent unintended data deletions.
+**Example 2: Blocking other dangerous operations**
-### FAQ
+Similarly, you can use the same method to block `set global` to prevent unintended variable changes, or block `truncate table` to prevent unintended data deletions.
-#### Q: Will regular expression blocking rules have side effects on the cluster?
-A: Yes. Regular expression matching is computationally intensive. When using complex regular expressions or too many regex blocking rules, it can significantly increase the CPU load on the FE. Therefore, add regex blocking rules cautiously. Avoid using complex regular expressions unless necessary.
+#### Case 5: Setting Rules for Specific Users
-#### Q: Can a blocking rule be temporarily disabled?
-A: Yes. Modify the blocking rule by setting its "enable" property to "false".
+By default, block rules apply globally (`"global" = "true"`). To apply a rule only to specific users, you can create a user-level block rule:
-#### Q: What standard do the regular expressions in blocking rules use?
-A: The regular expressions in blocking rules use Java's regular expression syntax. Common expressions can refer to the SQL syntax manual. The complete manual can be found at https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html
+1. Set `"global"` to `"false"` when creating the rule:
-## Workload Policy
-
-SQL Block Rule is a configuration for circuit breaking during planning, but because the cost calculation during planning may be inaccurate (especially for very complex queries, making it difficult to estimate accurately), it can lead to rules not being effective or false positives. Workload Policy addresses this limitation by allowing real-time monitoring of certain metrics during query execution, and circuit breaking queries whose runtime state does not meet expectations. This prevents [...]
+ ```sql
+ CREATE SQL_BLOCK_RULE rule_001
+ PROPERTIES (
+ "sql"="select * from t",
+ "global" = "false",
+ "enable" = "true"
+ )
+ ```
-* Query execution time
-* Number of rows scanned per BE
-* Number of bytes scanned per BE
-* Memory usage per BE
+2. Bind the rule to the target user:
-### Version Notes
+ ```sql
+ SET PROPERTY FOR 'root' 'SQL_block_rules' = 'rule_001';
+ ```
-Since Doris version 2.1, Workload Policy can be used to implement circuit breaking for large queries.
+3. Verify the rule is effective:
-| Version | since 2.1 |
-|--------------------|-----------|
-| select | yes |
-| insert into select | yes |
-| insert into values | no |
-| stream load | yes |
-| routine load | yes |
-| backup | no |
-| compaction | no |
+ ```sql
+ MySQL root@127.0.0.1:test> select * from t;
+ (1105, 'errCode = 2, detailMessage = errCode = 2, detailMessage = SQL match regex SQL block rule: rule_001')
+ ```
-### Creating Workload Policy
-Use the `CREATE WORKLOAD Policy` command to create a resource management policy.
+- To add multiple rules for a user, list all rule names in the rule list, separated by commas.
+- To remove all rules for a user, set the rule list to an empty string: `SET PROPERTY FOR 'root' 'SQL_block_rules' = '';`
-In the example below, create a Policy named `test_cancel_Policy`, which will cancel queries running in the cluster for more than 1000ms. The current status is enabled. Creating a Workload Policy requires `admin_priv` privileges.
+To modify or delete block rules, refer to the SQL manual for block rules.
-```sql
-create workload policy test_cancel_Policy
-Conditions(query_time > 1000)
-Actions(cancel_query)
-properties('enabled'='true');
-```
-
-When creating a Workload Policy, the following must be specified:
+### Important Notes
-- **Condition** represents the policy trigger condition. Multiple Conditions can be linked using commas "," to represent an "AND" relationship. In the example above, `query_time > 1000` indicates that the Policy is triggered when the query time exceeds 1 second. Currently supported Conditions are:
+- The calculation of scan row count, partition count, and bucket count is performed during the planning phase. Only partition and bucket pruning are considered, and other filtering conditions are not taken into account (i.e., the worst-case scenario is estimated). Therefore, queries with actual scan volumes below the set values may also be blocked.
+- Regular expression matching is a computationally intensive operation. Too many or overly complex regex rules can put significant pressure on FE's CPU. Use them cautiously and avoid complex regular expressions unless necessary.
+- To temporarily disable a rule, set its `"enable"` property to `"false"`.
+- Regular expressions in block rules use Java's regular expression syntax. For the complete reference, see https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html
-| Conditions | Description |
-|-----------------------|-------------------------------------------------------------------------------------------------------------|
-| username | The username carried by the query, only triggers the `set_session_variable` Action in FE. |
-| be_scan_rows | The number of rows scanned by a SQL in a single BE process. If the SQL is executed concurrently on BE, it is the cumulative value of multiple concurrent executions. |
-| be_scan_bytes | The number of bytes scanned by a SQL in a single BE process. If the SQL is executed concurrently on BE, it is the cumulative value of multiple concurrent executions, in bytes. |
-| query_time | The runtime of a SQL in a single BE process, in milliseconds. |
-| query_be_memory_bytes | The memory usage of a SQL in a single BE process. If the SQL is executed concurrently on BE, it is the cumulative value of multiple concurrent executions, in bytes. |
+## Workload Policy
-- **Action** represents the action taken when the condition is triggered. Currently, a Policy can only define one Action (except for `set_session_variable`). In the example above, `cancel_query` indicates cancelling the query. Currently supported Actions are:
+SQL Block Rule performs circuit breaking during the planning phase, but since cost estimation during planning may be inaccurate (especially for complex queries), it can lead to rules not being effective or false positives. Workload Policy addresses this limitation by monitoring real-time metrics during query execution and circuit breaking queries whose runtime state does not meet expectations, preventing unexpectedly large queries from consuming excessive resources and affecting cluster [...]
-| Actions | Description |
-|------------------------|------------------------------------------------------------------------------------------------------------------|
-| cancel_query | Cancel the query. |
-| set_session_variable | Triggers the `set session variable` statement. A single policy can have multiple `set_session_variable` options, currently only triggered in FE by the `username` Condition. |
+Workload Policy has been supported since Doris version 2.1. The support status for each load type is as follows:
-- **Properties** define the attributes of the current Policy, including whether it is enabled and its priority.
+| Load Type | Supported |
+|--------------------|-----------|
+| select | Yes |
+| insert into select | Yes |
+| insert into values | No |
+| stream load | Yes |
+| routine load | Yes |
+| backup | No |
+| compaction | No |
-| Properties | Description |
-|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| enabled | Can be `true` or `false`, default is `true`, indicating the Policy is enabled. `false` indicates the Policy is disabled. |
-| priority | An integer ranging from 0 to 100, default is 0, representing the Policy's priority. The higher the value, the higher the priority. This attribute mainly ensures that when a query matches multiple Policies, only the Policy with the highest priority is selected. |
-| workload_group | Currently, a Policy can bind to one workload group, meaning this Policy only applies to queries from a specific Workload Group. The default is empty, meaning it applies to all queries. |
+### Creation and Configuration
-### Binding Workload Policy to Workload Group
+Use the `CREATE WORKLOAD POLICY` command to create a policy. Creating a Workload Policy requires `admin_priv` privileges.
-By default, Workload Policies apply to all supported queries. If you want to specify that a Policy only targets a specific Workload Group, you need to bind the Workload Group through the `workload_group` option. The statement is as follows:
+The following example creates a policy named test_cancel_policy that cancels queries running longer than 1000 ms:
```sql
-create workload policy test_cancel_big_query
-Conditions(query_time > 1000)
-Actions(cancel_query)
-properties('workload_group'='normal')
+CREATE WORKLOAD POLICY test_cancel_policy
+CONDITIONS(query_time > 1000)
+ACTIONS(cancel_query)
+PROPERTIES('enabled'='true');
```
-### Important Notes
-- The Conditions and Actions of the same Policy must either both be FE or both be BE. For example, `set_session_variable` and `cancel_query` cannot be configured within the same Policy. Conditions `be_scan_rows` and `username` cannot be configured within the same Policy.
-- Currently, Policies are executed by asynchronous threads at fixed time intervals, which introduces a certain latency in policy enforcement. For example, if a user configures a policy to cancel a query when the number of scanned rows exceeds 1,000,000, and the cluster resources are relatively idle at that time, the query may finish before the cancellation policy takes effect. The current interval is 500ms, meaning that queries with run times shorter than this interval may bypass the pol [...]
-- Currently supported load types include select/insert, select/stream load, broker load, and routine load.
-- A single query may match multiple Policies, but only the Policy with the highest priority will take effect.
-- Modifications to Actions and Conditions are currently not supported; they can only be modified by deleting and recreating them.
+When creating a Workload Policy, three components must be specified:
-### Workload Policy Demonstration
+#### Conditions
-#### 1. Session Variable Modification Test
-Attempt to modify concurrency-related parameters in the session variables of the Admin account.
+Conditions represent the policy trigger conditions. Multiple Conditions are separated by commas `,` to represent an "AND" relationship.
-```sql
--- log on admin to check variables
-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)
+| Condition | Description |
+|-----------------------|------------------------------------------------------------------------------------------------------|
+| username | The username carried by the query; only triggers the set_session_variable Action in FE |
+| be_scan_rows | Number of rows scanned by a SQL in a single BE process; cumulative value when executed concurrently |
+| be_scan_bytes | Number of bytes scanned by a SQL in a single BE process; cumulative value when executed concurrently, in bytes |
+| query_time | Runtime of a SQL in a single BE process, in milliseconds |
+| query_be_memory_bytes | Memory usage of a SQL in a single BE process; cumulative value when executed concurrently, in bytes |
--- Create a Policy to modify the concurrency parameters of the admin account.
-create workload Policy test_set_var_Policy
-Conditions(username='admin')
-Actions(set_session_variable 'parallel_fragment_exec_instance_num=1')
+#### Actions
--- After some time, check the admin account's parameters again.
-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)
+Actions represent the action taken when the condition is triggered. Currently, a Policy can only define one Action (except for set_session_variable).
+
+| Action | Description |
+|----------------------|-----------------------------------------------------------------------------------------------------------------|
+| cancel_query | Cancel the query |
+| set_session_variable | Triggers a set session variable statement. A single Policy can have multiple set_session_variable options; currently only triggered in FE by the username Condition |
+
+#### Properties
+
+| Property | Description |
+|----------------|---------------------------------------------------------------------------------------------------------------------|
+| enabled | Whether the policy is enabled; values are true or false, default is true |
+| priority | Priority, an integer from 0 to 100, default is 0. Higher values mean higher priority; when a query matches multiple Policies, only the one with the highest priority takes effect |
+| workload_group | The name of the bound Workload Group; when specified, the Policy only applies to queries from that Workload Group. Default is empty, meaning it applies to all queries |
+
+#### Binding to a Workload Group
+
+By default, Workload Policies apply to all supported queries. To specify that a Policy only targets a specific Workload Group, bind it through the `workload_group` property:
+
+```sql
+CREATE WORKLOAD POLICY test_cancel_big_query
+CONDITIONS(query_time > 1000)
+ACTIONS(cancel_query)
+PROPERTIES('workload_group'='normal')
```
-#### 2. Big Query Circuit Breaker Test
-Test to circuit break queries that run longer than 3s. Below is an audit log of a successful run of ckbench's q29, showing that this SQL took 4.5s to complete.
+### Usage Examples
+
+#### Example 1: Circuit Breaking Timeout Queries
+Below is an audit log of a successful run of ckbench's q29, showing that this SQL took 4.5s to complete:
```sql
-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;
+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;
+-----------------------------------------------------------------------+------------------+----------+---------------------------------------------------------------------------------------------------------------------+
| k | l | c | min(Referer) |
+-----------------------------------------------------------------------+------------------+----------+---------------------------------------------------------------------------------------------------------------------+
@@ -329,17 +249,53 @@ mySQL [hits]>SELECT REGEXP_REPLACE(Referer, '^https?://(?:www\.)?([^/]+)/.*$', '
11 rows in set (4.50 sec)
```
-Create a Policy that cancels a query if it runs longer than 3 seconds.
+Create a Policy that cancels queries running longer than 3 seconds:
+
+```sql
+CREATE WORKLOAD POLICY test_cancel_3s_query
+CONDITIONS(query_time > 3000)
+ACTIONS(cancel_query)
+```
+
+Upon re-executing the SQL, you can see the query is circuit broken:
+
```sql
-create workload Policy test_cancel_3s_query
-Conditions(query_time > 3000)
-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
```
-Upon re-executing the SQL, you can see that the SQL execution will directly report an error.
+#### Example 2: Modifying User Session Variables
+
+Workload Policy can automatically modify session variables for specific users, for example, adjusting concurrency parameters:
```sql
-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
+-- Log in to admin account and check concurrency parameters
+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 to modify the concurrency parameters of the admin account
+CREATE WORKLOAD POLICY test_set_var_policy
+CONDITIONS(username='admin')
+ACTIONS(set_session_variable 'parallel_fragment_exec_instance_num=1')
+
+-- After some time, check the admin account's parameters again
+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)
```
+### Important Notes
+
+- The Conditions and Actions of the same Policy must belong to the same side (FE or BE). For example, set_session_variable and cancel_query cannot be configured within the same Policy; Condition be_scan_rows and Condition username also cannot be configured within the same Policy.
+- Policies are executed by asynchronous threads at fixed time intervals (currently 500 ms), so there is a certain latency in policy enforcement. Queries with very short run times may bypass the policy check.
+- A single query may match multiple Policies, but only the Policy with the highest priority will take effect.
+- Modifications to Actions and Conditions are currently not supported; they can only be modified by deleting and recreating them.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@doris.apache.org
For additional commands, e-mail: commits-help@doris.apache.org