This is an automated email from the ASF dual-hosted git repository.
CalvinKirs 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 bc2589c1453 docs: add sql block partition filter docs (#3617)
bc2589c1453 is described below
commit bc2589c14531725726ceb0b9ec0fd725aa378ce3
Author: Calvin Kirs <[email protected]>
AuthorDate: Tue May 12 11:18:40 2026 +0800
docs: add sql block partition filter docs (#3617)
## Versions
- [ ] dev
- [ ] 4.x
- [ ] 3.x
- [ ] 2.1 or older (not covered by version/language sync gate)
## Languages
- [ ] Chinese
- [ ] English
- [ ] Japanese candidate translation needed
## Docs Checklist
- [ ] Checked by AI
- [ ] Test Cases Built
- [ ] Updated required version and language counterparts, or explained
why not
- [ ] If only one language changed, confirmed whether source/translation
counterparts need sync
---
.../workload-management/sql-blocking.md | 17 ++++++++++++++
.../data-governance/CREATE-SQL_BLOCK_RULE.md | 27 +++++++++++++++++++++-
.../data-governance/SHOW-SQL_BLOCK_RULE.md | 22 +++++++++---------
.../workload-management/sql-blocking.md | 17 ++++++++++++++
.../data-governance/CREATE-SQL_BLOCK_RULE.md | 27 +++++++++++++++++++++-
.../data-governance/SHOW-SQL_BLOCK_RULE.md | 22 +++++++++---------
6 files changed, 108 insertions(+), 24 deletions(-)
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 129ed29488a..af91e54cbd0 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
@@ -31,6 +31,7 @@ SQL Block Rule 用于在查询规划阶段阻止符合特定模式的语句执
| `cardinality` | 允许扫描的最大行数 | 正整数 |
| `partition_num` | 允许扫描的最大分区数 | 正整数 |
| `tablet_num` | 允许扫描的最大分桶数 | 正整数 |
+| `require_partition_filter` | 查询分区内表和 Hive 表时是否必须包含有效分区过滤条件。该属性在 Doris 4.0
系列中从 4.0.6 起支持，在 Doris 4.1 系列中从 4.1.2 起支持。 | `"true"` 或 `"false"` |
| `global` | 是否为全局规则 | `"true"`（全局生效）或 `"false"`（仅对绑定用户生效） |
| `enable` | 是否启用规则 | `"true"` 或 `"false"` |
@@ -143,6 +144,22 @@ PROPERTIES(
- 如果想对一个用户添加多个规则，在规则列表中列举所有的规则名字，以英文逗号隔开。
- 如果想移除一个用户的所有规则，将规则列表置为空字符串即可：`SET PROPERTY FOR 'root' 'SQL_block_rules' =
'';`
+#### 场景六：要求分区过滤条件
+
+对于分区内表和 Hive 表，缺少分区列过滤条件可能导致全分区扫描。可以要求这些分区表查询必须包含有效的分区过滤条件：
+
+```sql
+CREATE SQL_BLOCK_RULE rule_require_partition_filter
+PROPERTIES
+(
+ "require_partition_filter" = "true",
+ "global" = "true",
+ "enable" = "true"
+);
+```
+
+开启规则后，`SELECT * FROM partitioned_table` 这类未包含分区过滤条件的查询会被阻止。包含分区过滤条件的查询，例如
`SELECT * FROM partitioned_table WHERE dt = '2024-01-01'`，可以继续执行。
+
如果需要修改或者删除阻止规则，可以参考阻止规则的 SQL 手册。
### 注意事项
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/data-governance/CREATE-SQL_BLOCK_RULE.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/data-governance/CREATE-SQL_BLOCK_RULE.md
index 2f3bab0cbc3..cb611c05a01 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/data-governance/CREATE-SQL_BLOCK_RULE.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/data-governance/CREATE-SQL_BLOCK_RULE.md
@@ -51,6 +51,7 @@ PROPERTIES (
> - partition_num: 一个表将扫描的最大 partition 数量
> - tablet_num: 一个表将扫描的最大 tablet 数量
> - cardinality: 一个表将扫描的数据行数
+> - require_partition_filter：查询分区内表或 Hive 表时是否必须包含有效的分区过滤条件。设置为 `true`
后，如果查询支持的分区表但没有在分区列上添加过滤条件，则会被阻止执行。默认值为 `false`。该属性在 Doris 4.0 系列中从 4.0.6 起支持，在
Doris 4.1 系列中从 4.1.2 起支持。目前仅对内表和 Hive 表生效。
>
> **开关类**
>
@@ -125,6 +126,30 @@ PROPERTIES (
SET PROPERTY FOR 'jack' 'sql_block_rules' = 'test_rule4';
```
+5. 创建要求分区内表和 Hive 表查询必须包含分区过滤条件的规则
+
+ ```sql
+ CREATE SQL_BLOCK_RULE test_rule5
+ PROPERTIES(
+ "require_partition_filter"="true",
+ "global"="true",
+ "enable"="true"
+ );
+ ```
+
+ 开启规则后，未包含分区列过滤条件的受支持分区表查询会被阻止：
+
+ ```sql
+ SELECT * FROM partitioned_table;
+ ERROR 1105 (HY000): errCode = 2, detailMessage = sql hits sql block rule:
test_rule5, missing partition filter
+ ```
+
+ 包含有效分区过滤条件的查询可以继续执行：
+
+ ```sql
+ SELECT * FROM partitioned_table WHERE dt = '2024-01-01';
+ ```
+
## 其它
常用正则表达式如下：
@@ -157,4 +182,4 @@ $ ：匹配字符串的结尾。例如，xyz$ 匹配以 'xyz' 结尾的字符串
\d：匹配任何数字字符，相当于 [0-9]。
\w：匹配任何单词字符，包括字母、数字和下划线，相当于 [a-zA-Z0-9_]。
-```
\ No newline at end of file
+```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/data-governance/SHOW-SQL_BLOCK_RULE.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/data-governance/SHOW-SQL_BLOCK_RULE.md
index cc0ac3f4e05..dd43d076a53 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/data-governance/SHOW-SQL_BLOCK_RULE.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/data-governance/SHOW-SQL_BLOCK_RULE.md
@@ -37,12 +37,12 @@ SHOW SQL_BLOCK_RULE;
```
```text
-+------------+----------------------------+---------+-------------+------------+-------------+--------+--------+
-| Name | Sql | SqlHash | PartitionNum | TabletNum
| Cardinality | Global | Enable |
-+------------+----------------------------+---------+-------------+------------+-------------+--------+--------+
-| test_rule | select * from order_analysis | NULL | 0 | 0
| 0 | true | true |
-| test_rule2 | NULL | NULL | 30 | 0
| 10000000000 | false | true |
-+------------+----------------------------+---------+-------------+------------+-------------+--------+--------+
++------------+------------------------------+---------+-------------+-----------+-------------+--------+--------+------------------------+
+| Name | Sql | SqlHash | PartitionNum |
TabletNum | Cardinality | Global | Enable | RequirePartitionFilter |
++------------+------------------------------+---------+-------------+-----------+-------------+--------+--------+------------------------+
+| test_rule | select * from order_analysis | NULL | 0 | 0
| 0 | true | true | false |
+| test_rule2 | NULL | NULL | 30 | 0
| 10000000000 | false | true | false |
++------------+------------------------------+---------+-------------+-----------+-------------+--------+--------+------------------------+
```
2. 查看指定的 SQL 阻止规则
@@ -51,9 +51,9 @@ SHOW SQL_BLOCK_RULE FOR test_rule2;
```
```text
-+------------+------+---------+-------------+------------+-------------+--------+--------+
-| Name | Sql | SqlHash | PartitionNum | TabletNum | Cardinality |
Global | Enable |
-+------------+------+---------+-------------+------------+-------------+--------+--------+
-| test_rule2 | NULL | NULL | 30 | 0 | 10000000000 | false
| true |
-+------------+------+---------+-------------+------------+-------------+--------+--------+
++------------+------+---------+-------------+-----------+-------------+--------+--------+------------------------+
+| Name | Sql | SqlHash | PartitionNum | TabletNum | Cardinality |
Global | Enable | RequirePartitionFilter |
++------------+------+---------+-------------+-----------+-------------+--------+--------+------------------------+
+| test_rule2 | NULL | NULL | 30 | 0 | 10000000000 | false
| true | false |
++------------+------+---------+-------------+-----------+-------------+--------+--------+------------------------+
```
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 bb42e1c8a98..a704974a724 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
@@ -31,6 +31,7 @@ Each rule is defined by the following properties that control
its behavior and s
| `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 |
+| `require_partition_filter` | Whether partitioned internal table and Hive
table queries must include an effective partition filter. Supported in Doris
4.0.6 and later in the 4.0 series, and in Doris 4.1.2 and later in the 4.1
series. | `"true"` or `"false"` |
| `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"` |
@@ -143,6 +144,22 @@ By default, block rules apply globally (`"global" =
"true"`). To apply a rule on
- 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' = '';`
+#### Case 6: Requiring Partition Filters
+
+For partitioned internal tables and Hive tables, missing partition-column
filters can cause full partition scans. You can require queries on these
partitioned tables to include an effective partition filter:
+
+```sql
+CREATE SQL_BLOCK_RULE rule_require_partition_filter
+PROPERTIES
+(
+ "require_partition_filter" = "true",
+ "global" = "true",
+ "enable" = "true"
+);
+```
+
+After the rule is enabled, a query such as `SELECT * FROM partitioned_table`
will be blocked. Queries with partition predicates, such as `SELECT * FROM
partitioned_table WHERE dt = '2024-01-01'`, can continue to run.
+
To modify or delete block rules, refer to the SQL manual for block rules.
### Important Notes
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-statements/data-governance/CREATE-SQL_BLOCK_RULE.md
b/versioned_docs/version-4.x/sql-manual/sql-statements/data-governance/CREATE-SQL_BLOCK_RULE.md
index 7c2d724c172..ef8ad3dc4e5 100644
---
a/versioned_docs/version-4.x/sql-manual/sql-statements/data-governance/CREATE-SQL_BLOCK_RULE.md
+++
b/versioned_docs/version-4.x/sql-manual/sql-statements/data-governance/CREATE-SQL_BLOCK_RULE.md
@@ -48,6 +48,7 @@ PROPERTIES (
> - partition_num: The maximum number of partitions that a table will scan.
> - tablet_num: The maximum number of tablets that a table will scan.
> - cardinality: The number of rows of data that a table will scan.
+> - require_partition_filter: Whether a query on a partitioned internal table
or Hive table must contain an effective partition filter. When set to `true`,
queries that scan a supported partitioned table without filtering on a
partition column will be blocked. The default is `false`. This property is
supported in Doris 4.0.6 and later in the 4.0 series, and in Doris 4.1.2 and
later in the 4.1 series. Currently, it only takes effect on internal tables and
Hive tables.
>
> **Switch Category**
>
@@ -129,6 +130,30 @@ The user executing this SQL command must have at least the
following permissions
SET PROPERTY FOR 'jack' 'sql_block_rules' = 'test_rule4';
```
+5. Create a rule that requires partitioned internal table and Hive table
queries to include a partition filter
+
+ ```sql
+ CREATE SQL_BLOCK_RULE test_rule5
+ PROPERTIES(
+ "require_partition_filter"="true",
+ "global"="true",
+ "enable"="true"
+ );
+ ```
+
+ After the rule is enabled, a query on a supported partitioned table without
a partition-column filter will be blocked:
+
+ ```sql
+ SELECT * FROM partitioned_table;
+ ERROR 1105 (HY000): errCode = 2, detailMessage = sql hits sql block rule:
test_rule5, missing partition filter
+ ```
+
+ Queries that include an effective partition filter can continue to run:
+
+ ```sql
+ SELECT * FROM partitioned_table WHERE dt = '2024-01-01';
+ ```
+
## Others
Common regular expressions are as follows:
@@ -163,4 +188,4 @@ $ : Matches the end of a string. For example, xyz$ matches
strings ending with '
\d : Matches any digit character, equivalent to [0-9].
\w : Matches any word character, including letters, digits, and underscores,
equivalent to [a-zA-Z0-9_].
-```
\ No newline at end of file
+```
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-statements/data-governance/SHOW-SQL_BLOCK_RULE.md
b/versioned_docs/version-4.x/sql-manual/sql-statements/data-governance/SHOW-SQL_BLOCK_RULE.md
index e57a06de5fd..db6dcff8044 100644
---
a/versioned_docs/version-4.x/sql-manual/sql-statements/data-governance/SHOW-SQL_BLOCK_RULE.md
+++
b/versioned_docs/version-4.x/sql-manual/sql-statements/data-governance/SHOW-SQL_BLOCK_RULE.md
@@ -36,12 +36,12 @@ SHOW SQL_BLOCK_RULE;
```
```text
-+------------+----------------------------+---------+-------------+------------+-------------+--------+--------+
-| Name | Sql | SqlHash | PartitionNum | TabletNum
| Cardinality | Global | Enable |
-+------------+----------------------------+---------+-------------+------------+-------------+--------+--------+
-| test_rule | select * from order_analysis | NULL | 0 | 0
| 0 | true | true |
-| test_rule2 | NULL | NULL | 30 | 0
| 10000000000 | false | true |
-+------------+----------------------------+---------+-------------+------------+-------------+--------+--------+
++------------+------------------------------+---------+-------------+-----------+-------------+--------+--------+------------------------+
+| Name | Sql | SqlHash | PartitionNum |
TabletNum | Cardinality | Global | Enable | RequirePartitionFilter |
++------------+------------------------------+---------+-------------+-----------+-------------+--------+--------+------------------------+
+| test_rule | select * from order_analysis | NULL | 0 | 0
| 0 | true | true | false |
+| test_rule2 | NULL | NULL | 30 | 0
| 10000000000 | false | true | false |
++------------+------------------------------+---------+-------------+-----------+-------------+--------+--------+------------------------+
```
2. Display a specific SQL blocking rule
@@ -50,9 +50,9 @@ SHOW SQL_BLOCK_RULE FOR test_rule2;
```
```text
-+------------+------+---------+-------------+------------+-------------+--------+--------+
-| Name | Sql | SqlHash | PartitionNum | TabletNum | Cardinality |
Global | Enable |
-+------------+------+---------+-------------+------------+-------------+--------+--------+
-| test_rule2 | NULL | NULL | 30 | 0 | 10000000000 | false
| true |
-+------------+------+---------+-------------+------------+-------------+--------+--------+
++------------+------+---------+-------------+-----------+-------------+--------+--------+------------------------+
+| Name | Sql | SqlHash | PartitionNum | TabletNum | Cardinality |
Global | Enable | RequirePartitionFilter |
++------------+------+---------+-------------+-----------+-------------+--------+--------+------------------------+
+| test_rule2 | NULL | NULL | 30 | 0 | 10000000000 | false
| true | false |
++------------+------+---------+-------------+-----------+-------------+--------+--------+------------------------+
```
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
