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 2b285cadbc0 docs: add sql block partition filter docs (#3920)
2b285cadbc0 is described below
commit 2b285cadbc0a237bbf7246d13b4dd542c37c44f5
Author: Calvin Kirs <[email protected]>
AuthorDate: Tue Jun 9 12:36:59 2026 +0800
docs: add sql block partition filter docs (#3920)
Re-adds documentation for the `require_partition_filter` SQL block rule
property (originally PR #3617, which was later removed from master by
#3716). The 4.0-series support version is corrected to **4.0.7** (4.0
supports this property starting from 4.0.7; 4.1 series from 4.1.2).
Covers, for version-4.x in both English and Chinese:
- `admin-manual/workload-management/sql-blocking.md` — property table
row + "Requiring Partition Filters" scenario
- `sql-manual/.../CREATE-SQL_BLOCK_RULE.md` — property description +
example
- `sql-manual/.../SHOW-SQL_BLOCK_RULE.md` — `RequirePartitionFilter`
output column
## Versions
- [ ] dev
- [x] 4.x
- [ ] 3.x
- [ ] 2.1 or older (not covered by version/language sync gate)
## Languages
- [x] Chinese
- [x] English
- [ ] Japanese candidate translation needed
## Docs Checklist
- [x] Checked by AI
- [ ] Test Cases Built
- [x] Updated required version and language counterparts, or explained
why not
- [x] If only one language changed, confirmed whether source/translation
counterparts need sync
---
.../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 08ba3258efc..626b91a492b 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
@@ -39,6 +39,7 @@ SQL Block Rule（SQL 阻止规则）在查询**规划阶段**拦截符合特定
| `cardinality` | 允许扫描的最大行数 | 正整数 |
| `partition_num` | 允许扫描的最大分区数 | 正整数 |
| `tablet_num` | 允许扫描的最大分桶数 | 正整数 |
+| `require_partition_filter` | 查询分区内表和 Hive 表时是否必须包含有效分区过滤条件。该属性在 Doris 4.0
系列中从 4.0.7 起支持，在 Doris 4.1 系列中从 4.1.2 起支持。 | `"true"` 或 `"false"` |
| `global` | 是否为全局规则 | `"true"`（全局生效）/ `"false"`（仅对绑定用户生效） |
| `enable` | 是否启用规则 | `"true"` / `"false"` |
@@ -167,6 +168,22 @@ PROPERTIES(
- 为一个用户绑定多条规则：在规则列表中以英文逗号分隔所有规则名，例如 `'rule_001,rule_002'`。
- 移除用户的所有规则：将规则列表置为空字符串，例如 `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'`，可以继续执行。
+
### 注意事项
-
**估算方式**：扫描行数、分区数、分桶数均在规划阶段基于最坏情况估算（仅考虑分区裁剪和分桶裁剪，不计其他过滤条件），实际扫描量小于设置值的查询也可能被阻止。
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..ed22c275274 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.7 起支持，在
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 c0f7a729c99..2c07945ffe5 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
@@ -39,6 +39,7 @@ Each rule is defined by the following properties that
determine its behavior and
| `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 tablets 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.7 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"` (global) / `"false"` (only
applies to bound users) |
| `enable` | Whether the rule is enabled | `"true"` / `"false"` |
@@ -167,6 +168,22 @@ Similarly, you can use regular expressions to block `set
global` (to prevent uni
- To bind multiple rules to a user: separate all rule names in the rule list
with commas, for example `'rule_001,rule_002'`.
- To remove all rules from a user: set the rule list to an empty string, for
example `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.
+
### Notes
- **Estimation method**: The number of scanned rows, partitions, and tablets
is estimated at the planning stage based on the worst case (only partition
pruning and tablet pruning are considered; other filter conditions are not).
Queries whose actual scan volume is less than the configured value may also be
blocked.
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 610e1bd60a0..d0418f52c5c 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.7 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 e233d783b12..b568677382f 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]
