This is an automated email from the ASF dual-hosted git repository.
yiguolei pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new 16cedb2e877 [doc](cache) Add Cache Query Limit description in
file-cache and data-cache (#3310)
16cedb2e877 is described below
commit 16cedb2e877280a85a02b006b01ca0d92383722d
Author: Wen Zhenghu <[email protected]>
AuthorDate: Wed Feb 4 09:56:33 2026 +0800
[doc](cache) Add Cache Query Limit description in file-cache and
data-cache (#3310)
related doris pr：https://github.com/apache/doris/pull/55772
## Versions
- [x] dev
- [x] 4.x
- [ ] 3.x
- [ ] 2.1
## Languages
- [x] Chinese
- [x] English
## Docs Checklist
- [x] Checked by AI
- [ ] Test Cases Built
---
.../file-cache/file-cache.md | 45 ++++++++++++++++++++++
docs/lakehouse/data-cache.md | 45 ++++++++++++++++++++++
.../file-cache/file-cache.md | 45 ++++++++++++++++++++++
.../current/lakehouse/data-cache.md | 45 ++++++++++++++++++++++
.../file-cache/file-cache.md | 45 ++++++++++++++++++++++
.../version-4.x/lakehouse/data-cache.md | 45 ++++++++++++++++++++++
.../file-cache/file-cache.md | 45 ++++++++++++++++++++++
versioned_docs/version-4.x/lakehouse/data-cache.md | 45 ++++++++++++++++++++++
8 files changed, 360 insertions(+)
diff --git a/docs/compute-storage-decoupled/file-cache/file-cache.md
b/docs/compute-storage-decoupled/file-cache/file-cache.md
index a390ae0d8eb..3e09db3e8d5 100644
--- a/docs/compute-storage-decoupled/file-cache/file-cache.md
+++ b/docs/compute-storage-decoupled/file-cache/file-cache.md
@@ -97,6 +97,51 @@ file_cache_exit_need_evict_cache_in_advance_percent Default:
"85"
- Parameter Description: This configuration item sets the threshold percentage
for stopping pre-eviction. When the cache space drops to this percentage,the
system stops pre-eviction.
+## Cache Query Limit
+
+> This feature is supported since version 4.0.3.
+
+The Cache Query Limit feature allows users to limit the percentage of file
cache that a single query can use. In scenarios where multiple users or complex
queries share cache resources, a single large query might occupy too much cache
space, causing other queries' hot data to be evicted. By setting a query limit,
you can ensure fair resource usage and prevent cache thrashing.
+
+The cache space occupied by a query refers to the total size of data populated
into the cache due to cache misses. If the total size populated by the query
reaches the quota limit, subsequent data populated by the query will replace
the previously populated data based on the LRU algorithm.
+
+### Configuration
+
+This feature involves configuration on BE and FE, as well as session variable
settings.
+
+**1. BE Configuration**
+
+- `enable_file_cache_query_limit`:
+ - Type: Boolean
+ - Default: `false`
+ - Description: The master switch for the file cache query limit feature on
the BE side. Only when enabled will the BE process the query limit parameters
passed from the FE.
+
+**2. FE Configuration**
+
+- `file_cache_query_limit_max_percent`:
+ - Type: Integer
+ - Default: `100`
+ - Description: The max query limit constraint used to validate the upper
limit of session variables. It ensures that the query limit set by users does
not exceed this value.
+
+**3. Session Variables**
+
+- `file_cache_query_limit_percent`:
+ - Type: Integer (1-100)
+ - Description: The file cache query limit percentage. It sets the maximum
percentage of cache a query can use. This value is constrained by
`file_cache_query_limit_max_percent`. It is recommended that the calculated
cache quota is not less than 256MB. If it is lower than this value, the BE will
print a warning in the log.
+
+**Usage Example**
+
+```sql
+-- Set session variable to limit a query to use at most 50% of the cache
+SET file_cache_query_limit_percent = 50;
+
+-- Execute query
+SELECT * FROM large_table;
+```
+
+**Note:**
+1. The value must be within the range [0,
`file_cache_query_limit_max_percent`].
+
## Cache Warm Up
Doris provides a cache warming feature that allows users to actively pull data
from remote storage into the local cache. This feature supports the following
three modes:
diff --git a/docs/lakehouse/data-cache.md b/docs/lakehouse/data-cache.md
index 6da66d04613..2599d01d95e 100644
--- a/docs/lakehouse/data-cache.md
+++ b/docs/lakehouse/data-cache.md
@@ -107,6 +107,51 @@ If `BytesScannedFromRemote` is 0, it means the cache is
fully hit.
Users can view cache statistics for each Backend node through the system table
[`file_cache_statistics`](../admin-manual/system-tables/information_schema/file_cache_statistics).
+## Cache Query Limit
+
+> This feature is supported since version 4.0.3.
+
+The Cache Query Limit feature allows users to limit the percentage of file
cache that a single query can use. In scenarios where multiple users or complex
queries share cache resources, a single large query might occupy too much cache
space, causing other queries' hot data to be evicted. By setting a query limit,
you can ensure fair resource usage and prevent cache thrashing.
+
+The cache space occupied by a query refers to the total size of data populated
into the cache due to cache misses. If the total size populated by the query
reaches the quota limit, subsequent data populated by the query will replace
the previously populated data based on the LRU algorithm.
+
+### Configuration
+
+This feature involves configuration on BE and FE, as well as session variable
settings.
+
+**1. BE Configuration**
+
+- `enable_file_cache_query_limit`:
+ - Type: Boolean
+ - Default: `false`
+ - Description: The master switch for the file cache query limit feature on
the BE side. Only when enabled will the BE process the query limit parameters
passed from the FE.
+
+**2. FE Configuration**
+
+- `file_cache_query_limit_max_percent`:
+ - Type: Integer
+ - Default: `100`
+ - Description: The max query limit constraint used to validate the upper
limit of session variables. It ensures that the query limit set by users does
not exceed this value.
+
+**3. Session Variables**
+
+- `file_cache_query_limit_percent`:
+ - Type: Integer (1-100)
+ - Description: The file cache query limit percentage. It sets the maximum
percentage of cache a query can use. This value is constrained by
`file_cache_query_limit_max_percent`. It is recommended that the calculated
cache quota is not less than 256MB. If it is lower than this value, the BE will
print a warning in the log.
+
+**Usage Example**
+
+```sql
+-- Set session variable to limit a query to use at most 50% of the cache
+SET file_cache_query_limit_percent = 50;
+
+-- Execute query
+SELECT * FROM large_table;
+```
+
+**Note:**
+1. The value must be within the range [0,
`file_cache_query_limit_max_percent`].
+
## Cache Warmup
Data Cache provides a cache "warmup" feature that allows preloading external
data into the local cache of BE nodes, thereby improving cache hit rates and
query performance for subsequent first-time queries.
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compute-storage-decoupled/file-cache/file-cache.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compute-storage-decoupled/file-cache/file-cache.md
index c728ab51dbb..f02e66c8c25 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compute-storage-decoupled/file-cache/file-cache.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compute-storage-decoupled/file-cache/file-cache.md
@@ -108,6 +108,51 @@ file_cache_exit_need_evict_cache_in_advance_percent 默认 "85"
- 参数说明：此配置项用于设置停止预先淘汰的阈值百分比。当缓存使用空间降至此百分比时，系统停止进行预先淘汰。
+## 缓存的配额
+
+> 该功能自 4.0.3 版本支持。
+
+缓存配额（Cache Query
Limit）功能允许用户限制单个查询可以使用的文件缓存百分比。在多用户或复杂查询共享缓存资源的场景下，单个大查询可能会占用过多的缓存空间，导致其他查询的热点数据被淘汰。通过设置查询配额，可以保证资源的公平使用，防止缓存抖动。
+
+查询占用的缓存空间指的是该查询因数据未命中而填充到缓存中的数据总大小。如果该查询填充的总大小已经达到配额限制，那么查询后续填充的数据会基于 LRU
算法替换先前填充的数据。
+
+### 配置说明
+
+该功能涉及 BE 和 FE 两端的配置，以及会话变量（Session Variable）的设置。
+
+**1. BE 配置**
+
+- `enable_file_cache_query_limit`:
+ - 类型：Boolean
+ - 默认值：`false`
+ - 说明：BE 端文件缓存查询限制功能的主开关。只有开启此开关，BE 才会处理 FE 传递的查询限制参数。
+
+**2. FE 配置**
+
+- `file_cache_query_limit_max_percent`:
+ - 类型：Integer
+ - 默认值：`100`
+ - 说明：查询的最大配额约束，用于校验会话变量的上限。它确保用户设置的查询限制不会超过此值。
+
+**3. 会话变量 (Session Variables)**
+
+- `file_cache_query_limit_percent`:
+ - 类型：Integer (1-100)
+ - 说明：文件缓存查询限制百分比。设置单个查询可使用的最大缓存比例。该值上限受 `file_cache_query_limit_max_percent`
约束。建议计算后的缓存配额不低于 256MB，如果低于该值，BE 会在日志中进行告警提示。
+
+**使用示例**
+
+```sql
+-- 设置会话变量，限制单个查询最多使用 50% 的缓存
+SET file_cache_query_limit_percent = 50;
+
+-- 执行查询
+SELECT * FROM large_table;
+```
+
+**注意：**
+1. 设置的值必须在 [0, `file_cache_query_limit_max_percent`] 范围内。
+
## 缓存的预热
Doris 提供了缓存预热功能，允许用户从远端存储主动拉取数据至本地缓存。该功能支持以下三种模式：
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/data-cache.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/data-cache.md
index 1e0ce1cc9ae..9582364896a 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/data-cache.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/data-cache.md
@@ -107,6 +107,51 @@ SET GLOBAL enable_file_cache = true;
用户可以通过系统表
[`file_cache_statistics`](../admin-manual/system-tables/information_schema/file_cache_statistics)
查看各个 Backend 节点的缓存统计指标。
+## 缓存的配额
+
+> 该功能自 4.0.3 版本支持。
+
+缓存配额（Cache Query
Limit）功能允许用户限制单个查询可以使用的文件缓存百分比。在多用户或复杂查询共享缓存资源的场景下，单个大查询可能会占用过多的缓存空间，导致其他查询的热点数据被淘汰。通过设置查询配额，可以保证资源的公平使用，防止缓存抖动。
+
+查询占用的缓存空间指的是该查询因数据未命中而填充到缓存中的数据总大小。如果该查询填充的总大小已经达到配额限制，那么查询后续填充的数据会基于 LRU
算法替换先前填充的数据。
+
+### 配置说明
+
+该功能涉及 BE 和 FE 两端的配置，以及会话变量（Session Variable）的设置。
+
+**1. BE 配置**
+
+- `enable_file_cache_query_limit`:
+ - 类型：Boolean
+ - 默认值：`false`
+ - 说明：BE 端文件缓存查询限制功能的主开关。只有开启此开关，BE 才会处理 FE 传递的查询限制参数。
+
+**2. FE 配置**
+
+- `file_cache_query_limit_max_percent`:
+ - 类型：Integer
+ - 默认值：`100`
+ - 说明：查询的最大配额约束，用于校验会话变量的上限。它确保用户设置的查询限制不会超过此值。
+
+**3. 会话变量 (Session Variables)**
+
+- `file_cache_query_limit_percent`:
+ - 类型：Integer (1-100)
+ - 说明：文件缓存查询限制百分比。设置单个查询可使用的最大缓存比例。该值上限受 `file_cache_query_limit_max_percent`
约束。建议计算后的缓存配额不低于 256MB，如果低于该值，BE 会在日志中进行告警提示。
+
+**使用示例**
+
+```sql
+-- 设置会话变量，限制单个查询最多使用 50% 的缓存
+SET file_cache_query_limit_percent = 50;
+
+-- 执行查询
+SELECT * FROM large_table;
+```
+
+**注意：**
+1. 设置的值必须在 [0, `file_cache_query_limit_max_percent`] 范围内。
+
## 缓存预热
Data Cache 提供缓存“预热（Warmup）”功能，允许将外部数据提前加载到 BE 节点的本地缓存中，从而提升后续首次查询的命中率和查询性能。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/compute-storage-decoupled/file-cache/file-cache.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/compute-storage-decoupled/file-cache/file-cache.md
index c728ab51dbb..f02e66c8c25 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/compute-storage-decoupled/file-cache/file-cache.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/compute-storage-decoupled/file-cache/file-cache.md
@@ -108,6 +108,51 @@ file_cache_exit_need_evict_cache_in_advance_percent 默认 "85"
- 参数说明：此配置项用于设置停止预先淘汰的阈值百分比。当缓存使用空间降至此百分比时，系统停止进行预先淘汰。
+## 缓存的配额
+
+> 该功能自 4.0.3 版本支持。
+
+缓存配额（Cache Query
Limit）功能允许用户限制单个查询可以使用的文件缓存百分比。在多用户或复杂查询共享缓存资源的场景下，单个大查询可能会占用过多的缓存空间，导致其他查询的热点数据被淘汰。通过设置查询配额，可以保证资源的公平使用，防止缓存抖动。
+
+查询占用的缓存空间指的是该查询因数据未命中而填充到缓存中的数据总大小。如果该查询填充的总大小已经达到配额限制，那么查询后续填充的数据会基于 LRU
算法替换先前填充的数据。
+
+### 配置说明
+
+该功能涉及 BE 和 FE 两端的配置，以及会话变量（Session Variable）的设置。
+
+**1. BE 配置**
+
+- `enable_file_cache_query_limit`:
+ - 类型：Boolean
+ - 默认值：`false`
+ - 说明：BE 端文件缓存查询限制功能的主开关。只有开启此开关，BE 才会处理 FE 传递的查询限制参数。
+
+**2. FE 配置**
+
+- `file_cache_query_limit_max_percent`:
+ - 类型：Integer
+ - 默认值：`100`
+ - 说明：查询的最大配额约束，用于校验会话变量的上限。它确保用户设置的查询限制不会超过此值。
+
+**3. 会话变量 (Session Variables)**
+
+- `file_cache_query_limit_percent`:
+ - 类型：Integer (1-100)
+ - 说明：文件缓存查询限制百分比。设置单个查询可使用的最大缓存比例。该值上限受 `file_cache_query_limit_max_percent`
约束。建议计算后的缓存配额不低于 256MB，如果低于该值，BE 会在日志中进行告警提示。
+
+**使用示例**
+
+```sql
+-- 设置会话变量，限制单个查询最多使用 50% 的缓存
+SET file_cache_query_limit_percent = 50;
+
+-- 执行查询
+SELECT * FROM large_table;
+```
+
+**注意：**
+1. 设置的值必须在 [0, `file_cache_query_limit_max_percent`] 范围内。
+
## 缓存的预热
Doris 提供了缓存预热功能，允许用户从远端存储主动拉取数据至本地缓存。该功能支持以下三种模式：
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/data-cache.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/data-cache.md
index 1e0ce1cc9ae..9582364896a 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/data-cache.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/data-cache.md
@@ -107,6 +107,51 @@ SET GLOBAL enable_file_cache = true;
用户可以通过系统表
[`file_cache_statistics`](../admin-manual/system-tables/information_schema/file_cache_statistics)
查看各个 Backend 节点的缓存统计指标。
+## 缓存的配额
+
+> 该功能自 4.0.3 版本支持。
+
+缓存配额（Cache Query
Limit）功能允许用户限制单个查询可以使用的文件缓存百分比。在多用户或复杂查询共享缓存资源的场景下，单个大查询可能会占用过多的缓存空间，导致其他查询的热点数据被淘汰。通过设置查询配额，可以保证资源的公平使用，防止缓存抖动。
+
+查询占用的缓存空间指的是该查询因数据未命中而填充到缓存中的数据总大小。如果该查询填充的总大小已经达到配额限制，那么查询后续填充的数据会基于 LRU
算法替换先前填充的数据。
+
+### 配置说明
+
+该功能涉及 BE 和 FE 两端的配置，以及会话变量（Session Variable）的设置。
+
+**1. BE 配置**
+
+- `enable_file_cache_query_limit`:
+ - 类型：Boolean
+ - 默认值：`false`
+ - 说明：BE 端文件缓存查询限制功能的主开关。只有开启此开关，BE 才会处理 FE 传递的查询限制参数。
+
+**2. FE 配置**
+
+- `file_cache_query_limit_max_percent`:
+ - 类型：Integer
+ - 默认值：`100`
+ - 说明：查询的最大配额约束，用于校验会话变量的上限。它确保用户设置的查询限制不会超过此值。
+
+**3. 会话变量 (Session Variables)**
+
+- `file_cache_query_limit_percent`:
+ - 类型：Integer (1-100)
+ - 说明：文件缓存查询限制百分比。设置单个查询可使用的最大缓存比例。该值上限受 `file_cache_query_limit_max_percent`
约束。建议计算后的缓存配额不低于 256MB，如果低于该值，BE 会在日志中进行告警提示。
+
+**使用示例**
+
+```sql
+-- 设置会话变量，限制单个查询最多使用 50% 的缓存
+SET file_cache_query_limit_percent = 50;
+
+-- 执行查询
+SELECT * FROM large_table;
+```
+
+**注意：**
+1. 设置的值必须在 [0, `file_cache_query_limit_max_percent`] 范围内。
+
## 缓存预热
Data Cache 提供缓存“预热（Warmup）”功能，允许将外部数据提前加载到 BE 节点的本地缓存中，从而提升后续首次查询的命中率和查询性能。
diff --git
a/versioned_docs/version-4.x/compute-storage-decoupled/file-cache/file-cache.md
b/versioned_docs/version-4.x/compute-storage-decoupled/file-cache/file-cache.md
index a390ae0d8eb..3e09db3e8d5 100644
---
a/versioned_docs/version-4.x/compute-storage-decoupled/file-cache/file-cache.md
+++
b/versioned_docs/version-4.x/compute-storage-decoupled/file-cache/file-cache.md
@@ -97,6 +97,51 @@ file_cache_exit_need_evict_cache_in_advance_percent Default:
"85"
- Parameter Description: This configuration item sets the threshold percentage
for stopping pre-eviction. When the cache space drops to this percentage,the
system stops pre-eviction.
+## Cache Query Limit
+
+> This feature is supported since version 4.0.3.
+
+The Cache Query Limit feature allows users to limit the percentage of file
cache that a single query can use. In scenarios where multiple users or complex
queries share cache resources, a single large query might occupy too much cache
space, causing other queries' hot data to be evicted. By setting a query limit,
you can ensure fair resource usage and prevent cache thrashing.
+
+The cache space occupied by a query refers to the total size of data populated
into the cache due to cache misses. If the total size populated by the query
reaches the quota limit, subsequent data populated by the query will replace
the previously populated data based on the LRU algorithm.
+
+### Configuration
+
+This feature involves configuration on BE and FE, as well as session variable
settings.
+
+**1. BE Configuration**
+
+- `enable_file_cache_query_limit`:
+ - Type: Boolean
+ - Default: `false`
+ - Description: The master switch for the file cache query limit feature on
the BE side. Only when enabled will the BE process the query limit parameters
passed from the FE.
+
+**2. FE Configuration**
+
+- `file_cache_query_limit_max_percent`:
+ - Type: Integer
+ - Default: `100`
+ - Description: The max query limit constraint used to validate the upper
limit of session variables. It ensures that the query limit set by users does
not exceed this value.
+
+**3. Session Variables**
+
+- `file_cache_query_limit_percent`:
+ - Type: Integer (1-100)
+ - Description: The file cache query limit percentage. It sets the maximum
percentage of cache a query can use. This value is constrained by
`file_cache_query_limit_max_percent`. It is recommended that the calculated
cache quota is not less than 256MB. If it is lower than this value, the BE will
print a warning in the log.
+
+**Usage Example**
+
+```sql
+-- Set session variable to limit a query to use at most 50% of the cache
+SET file_cache_query_limit_percent = 50;
+
+-- Execute query
+SELECT * FROM large_table;
+```
+
+**Note:**
+1. The value must be within the range [0,
`file_cache_query_limit_max_percent`].
+
## Cache Warm Up
Doris provides a cache warming feature that allows users to actively pull data
from remote storage into the local cache. This feature supports the following
three modes:
diff --git a/versioned_docs/version-4.x/lakehouse/data-cache.md
b/versioned_docs/version-4.x/lakehouse/data-cache.md
index 6da66d04613..2599d01d95e 100644
--- a/versioned_docs/version-4.x/lakehouse/data-cache.md
+++ b/versioned_docs/version-4.x/lakehouse/data-cache.md
@@ -107,6 +107,51 @@ If `BytesScannedFromRemote` is 0, it means the cache is
fully hit.
Users can view cache statistics for each Backend node through the system table
[`file_cache_statistics`](../admin-manual/system-tables/information_schema/file_cache_statistics).
+## Cache Query Limit
+
+> This feature is supported since version 4.0.3.
+
+The Cache Query Limit feature allows users to limit the percentage of file
cache that a single query can use. In scenarios where multiple users or complex
queries share cache resources, a single large query might occupy too much cache
space, causing other queries' hot data to be evicted. By setting a query limit,
you can ensure fair resource usage and prevent cache thrashing.
+
+The cache space occupied by a query refers to the total size of data populated
into the cache due to cache misses. If the total size populated by the query
reaches the quota limit, subsequent data populated by the query will replace
the previously populated data based on the LRU algorithm.
+
+### Configuration
+
+This feature involves configuration on BE and FE, as well as session variable
settings.
+
+**1. BE Configuration**
+
+- `enable_file_cache_query_limit`:
+ - Type: Boolean
+ - Default: `false`
+ - Description: The master switch for the file cache query limit feature on
the BE side. Only when enabled will the BE process the query limit parameters
passed from the FE.
+
+**2. FE Configuration**
+
+- `file_cache_query_limit_max_percent`:
+ - Type: Integer
+ - Default: `100`
+ - Description: The max query limit constraint used to validate the upper
limit of session variables. It ensures that the query limit set by users does
not exceed this value.
+
+**3. Session Variables**
+
+- `file_cache_query_limit_percent`:
+ - Type: Integer (1-100)
+ - Description: The file cache query limit percentage. It sets the maximum
percentage of cache a query can use. This value is constrained by
`file_cache_query_limit_max_percent`. It is recommended that the calculated
cache quota is not less than 256MB. If it is lower than this value, the BE will
print a warning in the log.
+
+**Usage Example**
+
+```sql
+-- Set session variable to limit a query to use at most 50% of the cache
+SET file_cache_query_limit_percent = 50;
+
+-- Execute query
+SELECT * FROM large_table;
+```
+
+**Note:**
+1. The value must be within the range [0,
`file_cache_query_limit_max_percent`].
+
## Cache Warmup
Data Cache provides a cache "warmup" feature that allows preloading external
data into the local cache of BE nodes, thereby improving cache hit rates and
query performance for subsequent first-time queries.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
