大网数据广告活动
数据库部署与 SQL 参考

查询熔断:SQL Block Rule 与 Workload Policy 配置指南

· 52CE 我爱测

查询熔断是一种保护机制,用于防止长时间运行或消耗过多资源的查询影响集群稳定性。当查询超过预设的资源或时间限制时,熔断机制自动终止该查询,避免单个查询耗尽系统资源、拖慢其他业务。

查询熔断是一种保护机制,用于防止长时间运行或消耗过多资源的查询影响集群稳定性。当查询超过预设的资源或时间限制时,熔断机制自动终止该查询,避免单个查询耗尽系统资源、拖慢其他业务。

Doris 提供两种熔断策略,分别作用于查询生命周期的不同阶段:

对比维度 SQL Block Rule(规划时熔断) Workload Policy(运行时熔断)
生效阶段 查询规划阶段,执行前拦截 查询执行阶段,运行中熔断
判断依据 预估扫描量、SQL 模式匹配 实际执行时间、内存占用、扫描量等实时指标
准确性 基于代价估算,可能存在误判 基于实时监测,更加准确
适用场景 阻止已知危险 SQL 模式和全表扫描 熔断运行中超出预期的大查询
适用语句 任意语句(DDL、DML) select、insert into select、stream load、routine load

SQL Block Rule

SQL Block Rule(SQL 阻止规则)在查询规划阶段拦截符合特定模式的语句,阻止其进入执行阶段。通常由 DBA 配置,用于防止全表扫描、危险函数调用等已知风险操作。

规则属性说明

每条规则由以下属性定义其行为和作用范围:

属性 说明 取值
sql 匹配查询语句的正则表达式 Java 正则表达式字符串
sqlHash 匹配查询语句的哈希值 SQL 哈希值字符串
cardinality 允许扫描的最大行数 正整数
partition_num 允许扫描的最大分区数 正整数
tablet_num 允许扫描的最大分桶数 正整数
global 是否为全局规则 "true"(全局生效)/ "false"(仅对绑定用户生效)
enable 是否启用规则 "true" / "false"

使用场景与示例

场景一:限制扫描行数

问题:SELECT * FROM t 等全表扫描操作会大量消耗 BE 的 IO 和 CPU 资源。

方案:设置单表扫描行数上限,超过阈值的查询将被阻止。

CREATE SQL_BLOCK_RULE rule_card 
PROPERTIES
(
    "cardinality" = "1000",
    "global" = "true",
    "enable" = "true"
);

单表扫描超过 1000 行时,查询将被拒绝执行。

场景二:限制扫描分区数

问题:扫描过多分区会显著增加 BE 的 CPU 消耗;查询外表时还会带来额外的网络开销和元数据拉取开销,通常由遗漏或写错分区过滤条件导致。

方案:设置单次查询可扫描的最大分区数。

CREATE SQL_BLOCK_RULE rule_part_num 
PROPERTIES
(
    "partition_num" = "30",
    "global" = "true",
    "enable" = "true"
);

单表扫描分区数超过 30 个时,查询将被拒绝执行。

场景三:限制扫描分桶数

问题:扫描过多分桶同样会显著增加 BE 的 CPU 消耗。

方案:设置单次查询可扫描的最大分桶数。

CREATE SQL_BLOCK_RULE rule_tablet_num 
PROPERTIES
(
    "tablet_num" = "200",
    "global" = "true",
    "enable" = "true"
);

单表扫描分桶数超过 200 个时,查询将被拒绝执行。

场景四:阻止特定 SQL 模式

问题:某些查询模式(如调用特定函数、执行危险操作)可能导致计算复杂度过高或规划时间过长。

方案:通过正则表达式匹配阻止这类查询。

示例 1:阻止使用特定函数

以下规则阻止所有包含 abs 函数的查询:

CREATE SQL_BLOCK_RULE rule_abs
PROPERTIES(
    "sql"="(?i)abs\\s*\\(.+\\)",
    "global"="true",
    "enable"="true"
);

正则说明:

  • (?i):大小写不敏感匹配
  • abs:目标函数名
  • \\s*:允许函数名与左括号之间有任意空白
  • \\(.+\\):匹配函数参数部分

示例 2:阻止危险操作

同理,可用正则阻止 set global(防止非预期的变量修改)或 truncate table(防止非预期的数据删除)。

正则表达式使用 Java 规范,详见 Pattern 文档。

场景五:针对特定用户设置规则

问题:默认规则全局生效,但某些场景下只需对特定用户启用限制。

方案:创建非全局规则并绑定到目标用户。

  1. 创建规则时将 global 设为 "false":

    CREATE SQL_BLOCK_RULE rule_001
    PROPERTIES (
        "sql"="select \\* from t",
        "global" = "false",
        "enable" = "true"
    );
    
  2. 将规则绑定到目标用户:

    SET PROPERTY FOR 'root' 'SQL_block_rules' = 'rule_001';
    
  3. 验证规则已生效:

    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')
    

多规则管理:

  • 为一个用户绑定多条规则:在规则列表中以英文逗号分隔所有规则名,例如 'rule_001,rule_002'。
  • 移除用户的所有规则:将规则列表置为空字符串,例如 SET PROPERTY FOR 'root' 'SQL_block_rules' = '';。

注意事项

  • 估算方式:扫描行数、分区数、分桶数均在规划阶段基于最坏情况估算(仅考虑分区裁剪和分桶裁剪,不计其他过滤条件),实际扫描量小于设置值的查询也可能被阻止。
  • 性能影响:正则匹配是计算密集型操作,过多或过于复杂的正则规则会给 FE 的 CPU 带来显著压力,建议谨慎添加。
  • 临时关闭规则:将规则属性中的 "enable" 修改为 "false" 即可临时禁用,无需删除规则。

Workload Policy

Workload Policy(负载策略)在查询运行时对实时指标进行监测,并对超出预期的查询执行熔断或变量调整等动作。相比 SQL Block Rule 的静态规划估算,Workload Policy 基于实际运行数据,判断更加准确。

Workload Policy 自 Doris 2.1 版本起支持,各负载类型的支持情况如下:

负载类型 是否支持
select 支持
insert into select 支持
insert into values 不支持
stream load 支持
routine load 支持
backup 不支持
compaction 不支持

创建与配置

使用 CREATE WORKLOAD POLICY 命令创建策略,需要 admin_priv 权限。

基本语法:

CREATE WORKLOAD POLICY <policy_name>
CONDITIONS(<condition_expr>)
ACTIONS(<action_expr>) 
PROPERTIES('<key>'='<value>');

以下示例创建一个取消运行时间超过 1000 ms 的查询的策略:

CREATE WORKLOAD POLICY test_cancel_policy
CONDITIONS(query_time > 1000)
ACTIONS(cancel_query) 
PROPERTIES('enabled'='true'); 

触发条件(Conditions)

Conditions 表示策略的触发条件,多个条件之间以逗号 , 分隔,表示"与"关系。

Condition 说明
username 查询携带的用户名,自 Doris 4.1.3 版本起,可与 query_time、be_scan_rows、be_scan_bytes、query_be_memory_bytes 等 BE 侧运行时指标组合,用于触发 cancel_query。该条件仅支持等值比较(=),用户名不能为空
be_scan_rows 一个 SQL 在单个 BE 进程内扫描的行数,多并发执行时为累加值
be_scan_bytes 一个 SQL 在单个 BE 进程内扫描的字节数,多并发执行时为累加值(单位:字节)
query_time 一个 SQL 在单个 BE 进程上的运行时间(单位:毫秒)
query_be_memory_bytes 一个 SQL 在单个 BE 进程内使用的内存量,多并发执行时为累加值(单位:字节)

执行动作(Actions)

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

Action 说明
cancel_query 取消查询

策略属性(Properties)

Property 说明 默认值
enabled 是否启用,取值为 true 或 false true
priority 优先级,取值范围 0~100,值越大优先级越高;多个 Policy 匹配时只有优先级最高的生效 0
workload_group 绑定的 Workload Group 名称,指定后 Policy 仅对该 Workload Group 的查询生效;为空时对所有查询生效 空(全局)

绑定 Workload Group

如需将策略限定在某个 Workload Group 内,通过 workload_group 属性绑定:

CREATE WORKLOAD POLICY test_cancel_big_query
CONDITIONS(query_time > 1000)
ACTIONS(cancel_query) 
PROPERTIES('workload_group'='normal');

上例中的 'workload_group'='normal' 仅适用于存算一体模式。存算分离模式(Cloud 模式)下必须使用 <compute_group>.<workload_group> 完整限定形式,例如 'workload_group'='compute_group_a.normal',否则会报错:workload_group must be '<compute_group>.<workload_group>' in cloud mode。详见 CREATE WORKLOAD POLICY。

使用示例

示例一:熔断超时查询

以下审计日志显示,某个 SQL 正常执行需要 4.5 秒:

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)                                                                                                        |
+-----------------------------------------------------------------------+------------------+----------+---------------------------------------------------------------------------------------------------------------------+
| 1                                                                     | 85.4611926713085 | 67259319 | http://%26ad%3D1%25EA%25D0%26utm_source=web&cd=19590&input_onlist/би-2 место будущей кондицин                       |
| http:%2F%2Fwwww.regnancies/search&evL8gE&where=all&filmId=bEmYZc_WTDE |               69 |   207347 | http:%2F%2Fwwww.regnancies/search&evL8gE&where=all&filmId=bEmYZc_WTDE                                               |
| http://новострашная                                                   |               31 |   740277 | http://новострашная                                                                                                 |
| http://loveche.html?ctid                                              |               24 |   144901 | http://loveche.html?ctid                                                                                            |
| http://rukodeliveresult                                               |               23 |   226135 | http://rukodeliveresult                                                                                             |
| http://holodilnik.ru                                                  |               20 |   133893 | http://holodilnik.ru                                                                                                |
| http://smeshariki.ru                                                  |               20 |   210736 | http://smeshariki.ru                                                                                                |
| http:%2F%2Fviewtopic                                                  |               20 |   391115 | http:%2F%2Fviewtopic                                                                                                |
| http:%2F%2Fwwww.ukr                                                   |               19 |   655178 | http:%2F%2Fwwww.ukr                                                                                                 |
| http:%2F%2FviewType                                                   |               19 |   148907 | http:%2F%2FviewType                                                                                                 |
| http://state=2008                                                     |               17 |   139630 | http://state=2008                                                                                                   |
+-----------------------------------------------------------------------+------------------+----------+---------------------------------------------------------------------------------------------------------------------+
11 rows in set (4.50 sec)

创建一个运行时间超过 3 秒即取消查询的策略:

CREATE WORKLOAD POLICY test_cancel_3s_query
CONDITIONS(query_time > 3000)
ACTIONS(cancel_query); 

再次执行同一 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

示例二:按用户熔断运行时大查询

自 Doris 4.1.3 版本起,可以将 username 与 BE 侧运行时指标组合,仅取消特定用户的查询。以下策略会在 test_user 提交的查询在单个 BE 上运行超过 3000 ms 时取消该查询:

CREATE WORKLOAD POLICY cancel_user_long_query
CONDITIONS(username='test_user', query_time > 3000)
ACTIONS(cancel_query);

同理,也可以将 username 与 be_scan_rows、be_scan_bytes 或 query_be_memory_bytes 组合,用于限制特定用户的扫描量或 BE 内存使用量。

注意事项

  • 异步执行延迟:Policy 由异步线程每 500 ms 执行一次检查,策略生效存在一定滞后。运行时间极短的查询可能会在检查触发前已完成,从而绕过策略。
  • 优先级机制:一个查询可能匹配多个 Policy,但只有优先级最高(priority 值最大)的 Policy 会生效。
  • 修改限制:目前不支持直接修改已有 Policy 的 Action 和 Condition,需删除后重新创建。

本文来自 Apache Doris 文档贡献者,按 Apache 2.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
Apache Doris 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
Apache 2.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。