This is an automated email from the ASF dual-hosted git repository.
bobhan1 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 8b344f9ee58 [docs](file-cache) Document query-level cache write limit
(#4041)
8b344f9ee58 is described below
commit 8b344f9ee582c196b543645d7bdc8b777f13c5a7
Author: bobhan1 <[email protected]>
AuthorDate: Thu Aug 6 17:20:30 2026 +0800
[docs](file-cache) Document query-level cache write limit (#4041)
## Summary
- document the `file_cache_query_limit_bytes` session variable
introduced by apache/doris#65058
- document the `enable_file_cache_query_limit_segment_meta` BE
configuration and its default metadata-accounting behavior
- distinguish the new no-more-write threshold from the existing
eviction-based `file_cache_query_limit_percent` quota
- add usage, per-BE scope, cache-block granularity, Profile counters,
caveats, and tuning guidance to the File Cache and Lakehouse Data Cache
pages
- synchronize the current and 4.x English, Chinese, and Japanese pages
- state in every 4.x page that the byte-threshold feature is supported
only in Doris 4.1.x and is not supported in Doris 4.0.x
## Scope
This PR updates the File Cache and Lakehouse Data Cache pages across the
current and 4.x English, Chinese, and Japanese documentation. The 4.x
pages explicitly identify the byte-threshold feature as available only
in Doris 4.1.x.
## Validation
- `git diff --check`
- `python3 scripts/check_md_links_single.py <file> --no-external` for
all 12 changed pages
- front matter JSON, Markdown fence, and admonition balance checks for
all 12 changed pages
- matching current/4.x section checks across all three languages,
allowing only the 4.1.x-specific version note
A full Docusaurus build was not run for this documentation-only change.
## Versions
- [x] 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
---
.../file-cache/file-cache.md | 110 +++++++++++++++--
docs/lakehouse/data-cache.md | 72 +++++++++--
.../file-cache/file-cache.md | 110 +++++++++++++++--
.../current/lakehouse/data-cache.md | 60 ++++++++-
.../file-cache/file-cache.md | 112 +++++++++++++++--
.../version-4.x/lakehouse/data-cache.md | 62 +++++++++-
.../file-cache/file-cache.md | 134 ++++++++++++++++----
.../current/lakehouse/data-cache.md | 93 ++++++++++----
.../file-cache/file-cache.md | 136 +++++++++++++++++----
.../version-4.x/lakehouse/data-cache.md | 87 ++++++++++---
.../file-cache/file-cache.md | 112 +++++++++++++++--
versioned_docs/version-4.x/lakehouse/data-cache.md | 74 +++++++++--
12 files changed, 994 insertions(+), 168 deletions(-)
diff --git a/docs/compute-storage-decoupled/file-cache/file-cache.md
b/docs/compute-storage-decoupled/file-cache/file-cache.md
index 5f27b1ed124..78efbff3d59 100644
--- a/docs/compute-storage-decoupled/file-cache/file-cache.md
+++ b/docs/compute-storage-decoupled/file-cache/file-cache.md
@@ -3,8 +3,8 @@
"title": "File Cache Configuration and Usage Guide (Compute-Storage
Decoupled)",
"sidebar_label": "File Cache Configuration",
"language": "en",
- "description": "Covers file cache configuration, index-only cache writes,
quota management, cache warmup and eviction, hit-rate monitoring, and TTL
policies for Doris in compute-storage decoupled mode to improve query
performance and reduce object storage costs.",
- "keywords": ["Doris file cache", "compute-storage decoupled cache", "file
cache", "index-only cache writes", "cache warmup", "cache quota", "TTL cache",
"LRU", "cache hit rate", "object storage acceleration"]
+ "description": "Covers file cache configuration, index-only cache writes,
query-level cache controls, cache warmup and eviction, hit-rate monitoring, and
TTL policies for Doris in compute-storage decoupled mode to improve query
performance and reduce object storage costs.",
+ "keywords": ["Doris file cache", "compute-storage decoupled cache", "file
cache", "index-only cache writes", "cache warmup", "cache quota",
"file_cache_query_limit_bytes", "TTL cache", "LRU", "cache hit rate", "object
storage acceleration"]
}
---
@@ -174,13 +174,18 @@ Proactive eviction actively frees space when cache
utilization reaches a thresho
<!-- Knowledge type: Configuration parameters -->
<!-- Applicable scenarios: Multi-user shared cache / Preventing large-query
cache thrashing -->
-> This feature is supported starting from version 4.0.3.
+Doris provides two independent query-level File Cache controls. Choose the
parameter according to whether you need to control the cache footprint already
held by a query or stop later cache fills:
-The **Cache Query Limit** feature allows you to limit the proportion of the
file cache that a single query can fill. In scenarios where multiple users or
complex queries share cache resources, a single large query may occupy too much
cache and evict hot data belonging to other queries. Setting a query quota
ensures fair use of resources and prevents cache thrashing.
+| Control | Primary parameter | Behavior after the limit | Use case |
+|---|---|---|---|
+| Limit by cache footprint percentage | `file_cache_query_limit_percent` | New
cache blocks can still be written. BE first evicts releasable blocks recorded
for the current query and then evicts from other cache queues when necessary |
Limit a query's cache footprint while allowing later cache fills |
+| Stop remote-scan cache writes by byte threshold |
`file_cache_query_limit_bytes` | When the next cache block would make the
admitted byte count exceed the threshold, the query enters remote-only-on-miss
mode on that BE. Later misses are read from remote storage without further File
Cache writes | Limit cache writes and churn caused by a large remote scan |
-The cache space occupied by a query refers to the total size of data that the
query fills into the cache due to cache misses. If the total fill reaches the
quota ceiling, subsequent data written by the query replaces data that the same
query wrote earlier, based on the LRU algorithm.
+### Limit by Cache Footprint Percentage
-### Configuration
+> This feature is supported starting from version 4.0.3.
+
+The cache-footprint percentage limit controls the maximum percentage of each
File Cache instance that a single query can use. When multiple users or complex
queries share cache resources, it reduces the risk that one large query retains
too much cache and evicts other hot data.
This feature involves three levels of configuration: BE configuration, FE
configuration, and session variables.
@@ -198,11 +203,13 @@ This feature involves three levels of configuration: BE
configuration, FE config
**Session Variables**
-| Variable | Type | Description |
-|---|---|---|
-| `file_cache_query_limit_percent` | Integer (1-100) | Maximum percentage of
cache that a single query may use. The upper bound is governed by
`file_cache_query_limit_max_percent`. The calculated cache quota should not be
lower than 256 MB; if it is, BE outputs a warning in the log |
+| Variable | Type | Default | Description |
+|---|---|---|---|
+| `file_cache_query_limit_percent` | Integer | `-1` | When explicitly set, the
value must be in `[1, file_cache_query_limit_max_percent]`. It specifies the
maximum percentage of cache that a single query may use. The calculated quota
should not be lower than 256 MB; otherwise, BE writes a warning to the log |
+
+Before using this control, enable both `enable_file_cache` and
`enable_file_cache_query_limit` on the BE, and ensure that `enable_file_cache`
is `true` in the query session.
-### Usage Example
+**Usage Example**
```sql
-- Limit a single query to using at most 50% of the cache
@@ -212,7 +219,88 @@ SET file_cache_query_limit_percent = 50;
SELECT * FROM large_table;
```
-> **Note:** The value must be within the range `[0,
file_cache_query_limit_max_percent]`.
+Later cache misses remain eligible for File Cache writes. When the query's
cache footprint exceeds the quota, BE releases space through the query-level
LRU record and other cache queues. This control does not switch the query into
a no-more-write mode.
+
+### Stop Remote-Scan Cache Writes by Byte Threshold
+
+`file_cache_query_limit_bytes` limits the cumulative bytes admitted for
read-through File Cache writes caused by remote-scan cache misses for one
SELECT query on **each BE**. It takes effect only in compute-storage decoupled
mode when `enable_file_cache=true` on the BE. It does not depend on
`enable_file_cache_query_limit` or `file_cache_query_limit_max_percent`.
+
+Parallel scanners for the same query share one threshold on a BE, but the
threshold is not a query-wide or cluster-wide total. For example, if a query
runs on 10 BEs with a 1 GiB threshold, each BE can admit approximately 1 GiB
independently; the limit is not 1 GiB across all BEs.
+
+**Parameters**
+
+| Parameter | Location | Type | Default | Required | Description |
+|---|---|---|---|---|---|
+| `file_cache_query_limit_bytes` | Session Variable | BigInt | `-1` | Yes |
Remote-scan cache-fill threshold for one query on each BE, in bytes. A value
below `0` disables the control; `0` disables cache fills from the start of the
query; a positive value accumulates admitted bytes by cache block |
+| `enable_file_cache_query_limit_segment_meta` | BE configuration | Boolean |
`false` | No | Whether Segment footer and Segment metadata cache writes count
toward the same byte threshold. This parameter is dynamically configurable.
Data-page and inverted-index writes are subject to the byte threshold whenever
this control is active |
+
+`file_cache_query_limit_bytes` has the following behavior:
+
+| Value | Behavior |
+|---|---|
+| `< 0` | Disables this control and preserves the original cache-miss fill
behavior |
+| `= 0` | Places the query in remote-only-on-miss mode on every BE from the
start. A request range fully covered by local cache can still be read locally;
a range that is not fully covered is read directly from remote storage without
a cache fill |
+| `> 0` | Allows cache blocks while their cumulative admitted bytes do not
exceed the threshold. When the next block would exceed it, that block is
rejected and later misses for the query on that BE no longer fill the cache |
+
+Admission is evaluated by cache block, so actual writes are not guaranteed to
equal the threshold. If the remaining budget is smaller than the next cache
block, the entire block is skipped, and the remaining budget is not used for
smaller later blocks. After the query enters remote-only-on-miss mode on a BE,
cache filling does not resume there.
+
+**Limit Remote-Scan Cache Fills**
+
+The following example assumes that `large_table` is in a compute-storage
decoupled cluster and File Cache is enabled on every BE. It allows up to 1 GiB
of remote-scan cache blocks to be admitted on each BE:
+
+```sql
+SET enable_profile = true;
+SET profile_level = 2;
+SET file_cache_query_limit_bytes = 1073741824;
+
+SELECT COUNT(*) FROM large_table;
+```
+
+The query result is unchanged. When the next cache block on a BE would make
admitted bytes exceed 1 GiB, later cache misses for that query on the same BE
read remote data without additional local cache writes.
+
+To prevent a one-time scan from filling File Cache from the start, set the
threshold to `0`, and restore the default after the query:
+
+```sql
+SET file_cache_query_limit_bytes = 0;
+SELECT COUNT(*) FROM large_table;
+
+SET file_cache_query_limit_bytes = -1;
+```
+
+**Whether Segment Metadata Is Counted**
+
+By default, data-page and inverted-index cache writes count toward the
threshold, while Segment footer and Segment metadata writes do not. Segment
footer and metadata may therefore still be written after the query enters
remote-only-on-miss mode, and the total write volume shown in the Profile may
exceed `file_cache_query_limit_bytes`.
+
+To stop Segment footer and metadata fills as well, set the following
configuration on every BE in the same compute group:
+
+```properties
+enable_file_cache_query_limit_segment_meta=true
+```
+
+This parameter can be changed immediately through the BE dynamic configuration
API. To retain it across restarts, add it to `be.conf` or use persistent
dynamic configuration. For details, see [BE
Configuration](../../admin-manual/config/be-config.md).
+
+**Verify with Query Profile**
+
+After enabling Query Profile, inspect the `FileCache` metric group under the
Scanner:
+
+| Metric | Description |
+|---|---|
+| `RemoteOnlyOnMissTriggered` | A value of `1` means that the Scanner observed
the query entering remote-only-on-miss mode |
+| `RemoteOnlyOnMissThresholdBytes` | Byte threshold configured for the query |
+| `BytesWriteIntoCache` | Total bytes actually written to File Cache |
+| `InvertedIndexBytesWriteIntoCache` | Inverted-index bytes actually written
to File Cache |
+| `SegmentFooterIndexBytesWriteIntoCache` | Segment footer and metadata bytes
actually written to File Cache |
+| `NumSkipCacheIOTotal` | Number of I/O operations that skipped the cache.
This metric can also include I/O skipped by other cache policies, so evaluate
it together with `RemoteOnlyOnMissTriggered` |
+
+If admitted bytes equal the threshold exactly and no later cache block
attempts to exceed it before the query finishes, `RemoteOnlyOnMissTriggered`
can remain `0`. The state changes only when a subsequent block would exceed the
threshold.
+
+**Recommendations and Caveats**
+
+- For one-time full scans, low-reuse ETL, or ad hoc queries, use a small
positive threshold or `0` to disable cache fills from the start and avoid
replacing hot data with cold data.
+- This parameter limits File Cache fills after query-read misses. It does not
limit remote bytes read, terminate the query, or affect cache writes produced
by ingestion, Compaction, Schema Change, or explicit cache warmup.
+- In remote-only-on-miss mode, request ranges fully covered by local cache can
still be read locally. Ranges that are not fully covered access remote storage
directly, which may increase object-storage I/O and query latency.
+- Use `file_cache_query_limit_percent` when the goal is to limit the cache
footprint retained by a query while allowing later cache misses to fill the
cache. Use `file_cache_query_limit_bytes` when the goal is to stop later fills
after a specified amount has been admitted.
+- Excluding Segment footer and metadata by default preserves the cache benefit
of highly reusable metadata. Enable
`enable_file_cache_query_limit_segment_meta` only when those writes must also
stop after the threshold, and verify the result with Query Profile.
## Cache Warmup
diff --git a/docs/lakehouse/data-cache.md b/docs/lakehouse/data-cache.md
index c7772bf552a..7cdd83c1137 100644
--- a/docs/lakehouse/data-cache.md
+++ b/docs/lakehouse/data-cache.md
@@ -2,7 +2,7 @@
{
"title": "Data Cache",
"language": "en",
- "description": "Apache Doris Data Cache accelerates Lakehouse queries by
caching HDFS and object storage data locally. Supports cache warmup, quota
control, and admission control for Hive, Iceberg, Hudi, and Paimon tables."
+ "description": "Apache Doris Data Cache accelerates Lakehouse queries by
caching HDFS and object storage data locally. Supports cache warmup,
query-level cache-fill controls, and admission control for Hive, Iceberg, Hudi,
and Paimon tables."
}
---
@@ -109,13 +109,18 @@ Users can view cache statistics for each Backend node
through the system table [
## Cache Query Limit
-> This feature is supported since version 4.0.3.
+Doris provides two independent query-level Data Cache controls:
+
+| Control | Primary parameter | Behavior after the limit |
+|---|---|---|
+| Limit by cache footprint percentage | `file_cache_query_limit_percent` |
Cache-miss fills remain allowed, while BE releases space through the
query-level LRU record and other cache queues |
+| Stop remote-scan cache writes by byte threshold |
`file_cache_query_limit_bytes` | When the next cache block would make admitted
bytes exceed the threshold, later misses are read from remote storage without
filling the local cache |
-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.
+### Limit by Cache Footprint Percentage
-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.
+> This feature is supported since version 4.0.3.
-### Configuration
+The cache-footprint percentage limit controls the maximum percentage of each
File Cache instance that a single query can use. When multiple users or complex
queries share cache resources, it reduces the risk that one large query retains
too much cache and evicts other hot data.
This feature involves configuration on BE and FE, as well as session variable
settings.
@@ -131,26 +136,69 @@ This feature involves configuration on BE and FE, as well
as session variable se
- `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.
+ - Description: The maximum query limit constraint used to validate the upper
bound of the session variable.
**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.
+ - Default: `-1`
+ - Description: The maximum percentage of cache that a query can use. This
value is constrained by `file_cache_query_limit_max_percent`. The calculated
cache quota should be at least 256 MB; otherwise, BE writes a warning to the
log.
**Usage Example**
```sql
--- Set session variable to limit a query to use at most 50% of the cache
+-- Set the session variable to limit a query to at most 50% of the cache
SET file_cache_query_limit_percent = 50;
--- Execute query
+-- Execute the query
SELECT * FROM large_table;
```
-**Note:**
-1. The value must be within the range [0,
`file_cache_query_limit_max_percent`].
+**Notes:**
+
+1. The value must be in `[1, file_cache_query_limit_max_percent]`.
+2. Before using this control, enable both `enable_file_cache` and
`enable_file_cache_query_limit` on the BE, and ensure that `enable_file_cache`
is `true` in the query session.
+3. Cache misses remain eligible for Data Cache writes after the percentage
quota is reached. This control does not switch the query into a no-more-write
mode.
+
+### Stop Remote-Scan Cache Writes by Byte Threshold
+
+In compute-storage decoupled mode, the `file_cache_query_limit_bytes` session
variable limits cumulative bytes admitted for Data Cache fills caused by Hive,
Iceberg, Hudi, or Paimon data-file cache misses for one SELECT query on **each
BE**. It requires `enable_file_cache=true` on the BE but does not depend on
`enable_file_cache_query_limit` or `file_cache_query_limit_max_percent`.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `file_cache_query_limit_bytes` | BigInt | `-1` | Remote-scan cache-fill
threshold for one query on each BE, in bytes. A value below `0` disables the
control; `0` disables cache fills from the start of the query; a positive value
accumulates admitted bytes by cache block |
+
+Parallel scanners for the same query share one threshold on a BE. The
threshold is not a query-wide or cluster-wide total. When the next cache block
would make admitted bytes exceed the threshold, the query enters
remote-only-on-miss mode on that BE: a request range fully covered by local
cache can still be read locally; a range that is not fully covered is read
directly from remote storage without filling Data Cache. The query result is
unchanged.
+
+The following example sets a 1 GiB remote-scan cache-fill threshold on each BE:
+
+```sql
+SET enable_profile = true;
+SET profile_level = 2;
+SET file_cache_query_limit_bytes = 1073741824;
+
+SELECT COUNT(*) FROM hive_catalog.sales.orders;
+```
+
+To prevent a one-time scan from writing Data Cache from the start, set the
threshold to `0`, and restore the default after the query:
+
+```sql
+SET file_cache_query_limit_bytes = 0;
+SELECT COUNT(*) FROM hive_catalog.sales.orders;
+
+SET file_cache_query_limit_bytes = -1;
+```
+
+After enabling Query Profile, inspect `RemoteOnlyOnMissTriggered` and
`RemoteOnlyOnMissThresholdBytes` in the Scanner's `FileCache` metric group.
When `RemoteOnlyOnMissTriggered=1`, the Scanner observed the query entering
remote-only-on-miss mode. Use `BytesWriteIntoCache` and `NumSkipCacheIOTotal`
to inspect actual writes and skipped-cache I/O. Because `NumSkipCacheIOTotal`
can also include I/O skipped by other cache policies, it is not sufficient by
itself to prove that the threshold w [...]
+
+:::note
+
+- This control applies only to Data Cache fills after SELECT query misses in
compute-storage decoupled mode. It does not limit remote bytes read or affect
explicit cache warmup. Remote-only-on-miss mode may increase remote I/O and
query latency.
+- Admission is evaluated by cache block. If the remaining budget is smaller
than the next block, the entire block is skipped. `RemoteOnlyOnMissTriggered`
changes to `1` only when a block would exceed the threshold.
+- The BE parameter `enable_file_cache_query_limit_segment_meta` controls
whether Doris internal-table Segment footer and Segment metadata writes count
toward the same threshold. Cache fills for Hive, Iceberg, Hudi, and Paimon data
files are always subject to `file_cache_query_limit_bytes`. For the complete
parameter scope and internal-table behavior, see [File Cache Configuration and
Usage Guide](../compute-storage-decoupled/file-cache/file-cache.md).
+
+:::
## Cache Warmup
@@ -368,4 +416,4 @@ Key fields and decision descriptions:
### Principle
-Data caching caches accessed remote data to the local BE node. The original
data file is split into Blocks based on the accessed IO size, and Blocks are
stored in the local file `cache_path/hash(filepath).substr(0,
3)/hash(filepath)/offset`, with Block metadata saved in the BE node. When
accessing the same remote file, Doris checks whether the cache data of the file
exists in the local cache and determines which data to read from the local
Block and which data to pull from the remote bas [...]
\ No newline at end of file
+Data caching caches accessed remote data to the local BE node. The original
data file is split into Blocks based on the accessed IO size, and Blocks are
stored in the local file `cache_path/hash(filepath).substr(0,
3)/hash(filepath)/offset`, with Block metadata saved in the BE node. When
accessing the same remote file, Doris checks whether the cache data of the file
exists in the local cache and determines which data to read from the local
Block and which data to pull from the remote bas [...]
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 beba5576faf..d68e2953f22 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
@@ -3,8 +3,8 @@
"title": "文件缓存配置与使用指南（存算分离）",
"sidebar_label": "文件缓存配置",
"language": "zh-CN",
- "description": "介绍存算分离架构下 Doris 文件缓存的配置、索引优先写入、配额管理、缓存预热与清理、命中率监控及 TTL
策略，助力提升查询性能、降低对象存储成本。",
- "keywords": ["Doris 文件缓存", "存算分离缓存", "file cache", "索引优先缓存", "缓存预热",
"缓存配额", "TTL 缓存", "LRU", "缓存命中率", "对象存储加速"]
+ "description": "介绍存算分离架构下 Doris 文件缓存的配置、索引优先写入、查询级缓存限制、缓存预热与清理、命中率监控及 TTL
策略，助力提升查询性能、降低对象存储成本。",
+ "keywords": ["Doris 文件缓存", "存算分离缓存", "file cache", "索引优先缓存", "缓存预热",
"缓存配额", "file_cache_query_limit_bytes", "TTL 缓存", "LRU", "缓存命中率", "对象存储加速"]
}
---
@@ -174,13 +174,18 @@ file_cache_path 默认：BE 部署路径下的 storage 目录
<!-- 知识类型: 配置参数 -->
<!-- 适用场景: 多用户共享缓存 / 防止大查询缓存抖动 -->
-> 该功能自 4.0.3 版本起支持。
+Doris 提供两种相互独立的查询级 File Cache 限制机制。应根据希望控制的是“查询已占用的缓存空间”还是“查询后续是否继续回填缓存”选择参数：
-**缓存配额（Cache Query
Limit）**功能允许限制单个查询可填充的文件缓存比例。在多用户或复杂查询共享缓存资源的场景下，单个大查询可能占用过多缓存，导致其他查询的热点数据被淘汰。通过设置查询配额，可保证资源的公平使用，防止缓存抖动。
+| 机制 | 主要参数 | 达到限制后的行为 | 适用场景 |
+|---|---|---|---|
+| 按缓存占用比例限制 | `file_cache_query_limit_percent` | 新缓存块仍可写入；BE
优先淘汰当前查询记录的可释放缓存块，并在需要时从其他缓存队列淘汰 | 限制单个查询的缓存占用，兼顾后续缓存回填 |
+| 按远端扫描回填字节数停止写入 | `file_cache_query_limit_bytes` | 当下一个缓存块会使累计准入字节数超过阈值时，查询在该
BE 上进入 remote-only-on-miss 状态；后续未命中范围从远端读取但不再写入 File Cache |
限制一次大范围远端扫描造成的缓存写入和缓存抖动 |
-查询占用的缓存空间指该查询因数据未命中而填充到缓存中的数据总大小。若填充总量达到配额上限，后续填充的数据将基于 LRU 算法替换该查询先前填充的数据。
+### 按缓存占用比例限制
-### 配置说明
+> 该功能自 4.0.3 版本起支持。
+
+缓存占用比例限制用于控制单个查询在每个 File Cache
实例中可使用的最大缓存比例。在多用户或复杂查询共享缓存资源的场景下，该机制可以降低单个大查询长期占用过多缓存并淘汰其他热点数据的风险。
该功能涉及 BE 配置、FE 配置与会话变量三个层面。
@@ -198,11 +203,13 @@ file_cache_path 默认：BE 部署路径下的 storage 目录
**会话变量**
-| 变量 | 类型 | 说明 |
-|---|---|---|
-| `file_cache_query_limit_percent` | Integer (1–100) | 单个查询可使用的最大缓存比例（%）。上限受
`file_cache_query_limit_max_percent` 约束。建议计算后的缓存配额不低于 256 MB，低于该值时 BE 会在日志中输出告警
|
+| 变量 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `file_cache_query_limit_percent` | Integer | `-1` | 设置时取值范围为 `[1,
file_cache_query_limit_max_percent]`。表示单个查询可使用的最大缓存比例（%）。建议计算后的缓存配额不低于 256
MB，低于该值时 BE 会在日志中输出告警 |
+
+使用前，需要在 BE 上同时启用 `enable_file_cache` 和
`enable_file_cache_query_limit`，并确保查询会话中的 `enable_file_cache` 为 `true`。
-### 使用示例
+**使用示例**
```sql
-- 限制单个查询最多使用 50% 的缓存
@@ -212,7 +219,88 @@ SET file_cache_query_limit_percent = 50;
SELECT * FROM large_table;
```
-> **注意：** 设置的值必须在 `[0, file_cache_query_limit_max_percent]` 范围内。
+后续缓存未命中仍允许写入 File Cache；当查询的缓存占用超过配额时，BE 会通过查询级 LRU
记录和其他缓存队列释放空间。该机制不会把查询切换为“后续不再写缓存”的模式。
+
+### 按远端扫描回填字节数停止写入
+
+`file_cache_query_limit_bytes` 用于限制单个 SELECT 查询在**每个 BE** 上因远端扫描缓存未命中而获准回填
File Cache 的累计字节数。该机制仅在存算分离模式且 BE 的 `enable_file_cache=true` 时生效，不依赖
`enable_file_cache_query_limit` 或 `file_cache_query_limit_max_percent`。
+
+该阈值由同一查询在一个 BE 上的并行 Scanner 共享，但不是整个查询或整个集群的总量限制。例如，一个查询在 10 个 BE 上执行并将阈值设为 1
GiB，理论上最多可在每个 BE 上分别准入约 1 GiB，而不是所有 BE 合计 1 GiB。
+
+**参数说明**
+
+| 参数 | 位置 | 类型 | 默认值 | 是否必选 | 说明 |
+|---|---|---|---|---|---|
+| `file_cache_query_limit_bytes` | Session Variable | BigInt | `-1` | 是 |
单个查询在每个 BE 上的远端扫描缓存回填阈值，单位为字节。小于 `0` 时关闭限制；等于 `0` 时从查询开始即不回填；大于 `0`
时按缓存块累计准入字节数 |
+| `enable_file_cache_query_limit_segment_meta` | BE 配置 | Boolean | `false` | 否
| 是否将 Segment footer 和 Segment 元数据的缓存写入纳入同一个字节阈值。该参数支持动态修改；数据页和倒排索引写入始终受字节阈值约束 |
+
+`file_cache_query_limit_bytes` 的取值行为如下：
+
+| 取值 | 行为 |
+|---|---|
+| `< 0` | 关闭该限制，保留原有的缓存未命中回填行为 |
+| `= 0` | 查询从开始就在每个 BE 上进入 remote-only-on-miss
状态；已完整覆盖请求范围的本地缓存仍可读取，未完整覆盖的范围直接从远端读取且不回填 |
+| `> 0` | 允许累计准入字节数不超过阈值的缓存块写入；当下一个缓存块会使累计值超过阈值时拒绝该块，并使该查询在当前 BE 上的后续未命中读取不再回填
|
+
+阈值按缓存块进行准入判断，并不保证实际写入量恰好等于阈值。如果剩余预算小于下一个缓存块，该块会被整体跳过，剩余预算不会继续用于更小的后续块。一旦进入
remote-only-on-miss 状态，同一查询在该 BE 上不会恢复缓存回填。
+
+**限制远端扫描回填量**
+
+以下示例假设 `large_table` 位于存算分离集群中，并且所有 BE 已启用 File Cache。该设置允许查询在每个 BE 上最多准入 1
GiB 的远端扫描缓存块：
+
+```sql
+SET enable_profile = true;
+SET profile_level = 2;
+SET file_cache_query_limit_bytes = 1073741824;
+
+SELECT COUNT(*) FROM large_table;
+```
+
+查询结果不受影响。当某个 BE 上的下一个缓存块会使累计准入量超过 1 GiB 时，该 BE
上同一查询的后续缓存未命中会直接读取远端数据，不再产生对应的本地缓存写入。
+
+如果希望一次性扫描从开始就不污染 File Cache，可将阈值设为 `0`；查询结束后可恢复默认值：
+
+```sql
+SET file_cache_query_limit_bytes = 0;
+SELECT COUNT(*) FROM large_table;
+
+SET file_cache_query_limit_bytes = -1;
+```
+
+**是否计入 Segment 元数据**
+
+默认情况下，数据页和倒排索引缓存写入计入阈值，Segment footer 和 Segment 元数据不计入。此时即使查询已经进入
remote-only-on-miss 状态，Segment footer 和元数据仍可能写入 File Cache，因此 Profile
中的总写入量可能大于 `file_cache_query_limit_bytes`。
+
+如果需要连 Segment footer 和元数据也停止回填，请在同一计算组的所有 BE 上设置：
+
+```properties
+enable_file_cache_query_limit_segment_meta=true
+```
+
+该参数可通过 BE 动态配置接口即时修改；若需重启后继续生效，应写入 `be.conf` 或使用持久化动态配置。具体方法参见 [BE
配置](../../admin-manual/config/be-config.md)。
+
+**通过 Profile 验证**
+
+开启 Query Profile 后，可在 Scanner 的 `FileCache` 指标组中关注：
+
+| 指标 | 说明 |
+|---|---|
+| `RemoteOnlyOnMissTriggered` | 值为 `1` 表示该 Scanner 已观察到查询进入
remote-only-on-miss 状态 |
+| `RemoteOnlyOnMissThresholdBytes` | 当前查询配置的字节阈值 |
+| `BytesWriteIntoCache` | 实际写入 File Cache 的总字节数 |
+| `InvertedIndexBytesWriteIntoCache` | 倒排索引实际写入 File Cache 的字节数 |
+| `SegmentFooterIndexBytesWriteIntoCache` | Segment footer 和元数据实际写入 File Cache
的字节数 |
+| `NumSkipCacheIOTotal` | 跳过缓存的 I/O 次数；该指标还可能包含其他跳过缓存策略造成的 I/O，应与
`RemoteOnlyOnMissTriggered` 一起判断 |
+
+如果累计准入量恰好等于阈值，且查询结束前没有新的缓存块尝试超过阈值，`RemoteOnlyOnMissTriggered` 仍可能为
`0`。只有出现会超过阈值的下一个缓存块时，状态才会切换。
+
+**使用建议与注意事项**
+
+- 对一次性全表扫描、低复用率 ETL 或 Ad-hoc 查询，可设置较小的正值，或使用 `0` 从查询开始禁止缓存回填，避免冷数据置换热点数据。
+- 该参数限制的是查询读取未命中后的 File Cache 回填，不限制远端读取量，不会终止查询，也不影响导入、Compaction、Schema
Change 或显式缓存预热产生的缓存写入。
+- 进入 remote-only-on-miss 状态后，已完整缓存的请求范围仍可从本地读取；未完整覆盖的请求范围会直接访问远端存储，可能增加对象存储
I/O 和查询延迟。
+- 如果目标是限制查询保留在缓存中的占用比例，并允许后续未命中继续回填，应使用
`file_cache_query_limit_percent`；如果目标是在一定回填量后停止后续写入，应使用
`file_cache_query_limit_bytes`。
+- 默认不计入 Segment footer 和元数据可以保留高复用元数据的缓存收益。如果业务要求查询达到阈值后不再产生这类写入，再启用
`enable_file_cache_query_limit_segment_meta`，并结合 Profile 验证效果。
## 缓存预热
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 2f47bdacb85..74df8a7263f 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
@@ -2,7 +2,7 @@
{
"title": "数据缓存",
"language": "zh-CN",
- "description": "Apache Doris 数据缓存（Data Cache）将 HDFS 及对象存储数据缓存至本地磁盘，加速
Lakehouse 查询性能。支持缓存预热、配额限制与准入控制，适用于 Hive、Iceberg、Hudi、Paimon 表查询场景。"
+ "description": "Apache Doris 数据缓存（Data Cache）将 HDFS 及对象存储数据缓存至本地磁盘，加速
Lakehouse 查询性能。支持缓存预热、查询级回填限制与准入控制，适用于 Hive、Iceberg、Hudi、Paimon 表查询场景。"
}
---
@@ -109,13 +109,18 @@ SET GLOBAL enable_file_cache = true;
## 缓存的配额
-> 该功能自 4.0.3 版本支持。
+Doris 提供两种相互独立的查询级 Data Cache 限制机制：
+
+| 机制 | 主要参数 | 达到限制后的行为 |
+|---|---|---|
+| 按缓存占用比例限制 | `file_cache_query_limit_percent` | 继续允许缓存未命中回填，并通过查询级 LRU
记录和其他缓存队列释放空间 |
+| 按远端扫描回填字节数停止写入 | `file_cache_query_limit_bytes` |
当下一个缓存块会使累计准入字节数超过阈值时，后续未命中范围从远端读取但不再回填本地缓存 |
-缓存配额（Cache Query
Limit）功能允许用户限制单个查询可以使用的文件缓存百分比。在多用户或复杂查询共享缓存资源的场景下，单个大查询可能会占用过多的缓存空间，导致其他查询的热点数据被淘汰。通过设置查询配额，可以保证资源的公平使用，防止缓存抖动。
+### 按缓存占用比例限制
-查询占用的缓存空间指的是该查询因数据未命中而填充到缓存中的数据总大小。如果该查询填充的总大小已经达到配额限制，那么查询后续填充的数据会基于 LRU
算法替换先前填充的数据。
+> 该功能自 4.0.3 版本支持。
-### 配置说明
+缓存占用比例限制用于控制单个查询在每个 File Cache
实例中可使用的最大缓存比例。在多用户或复杂查询共享缓存资源的场景下，该机制可以降低单个大查询长期占用过多缓存并淘汰其他热点数据的风险。
该功能涉及 BE 和 FE 两端的配置，以及会话变量（Session Variable）的设置。
@@ -137,6 +142,7 @@ SET GLOBAL enable_file_cache = true;
- `file_cache_query_limit_percent`:
- 类型：Integer (1-100)
+ - 默认值：`-1`
- 说明：文件缓存查询限制百分比。设置单个查询可使用的最大缓存比例。该值上限受 `file_cache_query_limit_max_percent`
约束。建议计算后的缓存配额不低于 256MB，如果低于该值，BE 会在日志中进行告警提示。
**使用示例**
@@ -150,7 +156,49 @@ SELECT * FROM large_table;
```
**注意：**
-1. 设置的值必须在 [0, `file_cache_query_limit_max_percent`] 范围内。
+
+1. 设置的值必须在 `[1, file_cache_query_limit_max_percent]` 范围内。
+2. 使用前，需要在 BE 上同时启用 `enable_file_cache` 和
`enable_file_cache_query_limit`，并确保查询会话中的 `enable_file_cache` 为 `true`。
+3. 达到百分比配额后，后续缓存未命中仍可写入 Data Cache；该机制不会将查询切换为“后续不再写缓存”的模式。
+
+### 按远端扫描回填字节数停止写入
+
+在存算分离模式下，可通过会话变量 `file_cache_query_limit_bytes` 限制单个 SELECT 查询在**每个 BE** 上因
Hive、Iceberg、Hudi 或 Paimon 数据文件缓存未命中而获准回填 Data Cache 的累计字节数。该功能要求 BE 的
`enable_file_cache=true`，但不依赖 `enable_file_cache_query_limit` 或
`file_cache_query_limit_max_percent`。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `file_cache_query_limit_bytes` | BigInt | `-1` | 单个查询在每个 BE
上的远端扫描缓存回填阈值，单位为字节。小于 `0` 时关闭限制；等于 `0` 时从查询开始即不回填；大于 `0` 时按缓存块累计准入字节数 |
+
+该阈值由同一查询在一个 BE 上的并行 Scanner 共享，不是整个查询或整个集群的总量限制。当下一个缓存块会使累计准入字节数超过阈值时，该查询在当前
BE 上进入 remote-only-on-miss 状态：已完整覆盖请求范围的本地缓存仍可读取；未完整覆盖的范围直接从远端存储读取，且不再回填 Data
Cache。查询结果不受影响。
+
+以下示例将每个 BE 的远端扫描回填阈值设为 1 GiB：
+
+```sql
+SET enable_profile = true;
+SET profile_level = 2;
+SET file_cache_query_limit_bytes = 1073741824;
+
+SELECT COUNT(*) FROM hive_catalog.sales.orders;
+```
+
+如果希望一次性扫描从开始就不写 Data Cache，可将阈值设为 `0`；查询完成后恢复默认值：
+
+```sql
+SET file_cache_query_limit_bytes = 0;
+SELECT COUNT(*) FROM hive_catalog.sales.orders;
+
+SET file_cache_query_limit_bytes = -1;
+```
+
+开启 Query Profile 后，可在 Scanner 的 `FileCache` 指标组中查看 `RemoteOnlyOnMissTriggered`
和 `RemoteOnlyOnMissThresholdBytes`。当 `RemoteOnlyOnMissTriggered=1` 时，表示该
Scanner 已观察到查询进入 remote-only-on-miss 状态；可结合 `BytesWriteIntoCache` 与
`NumSkipCacheIOTotal` 判断实际写入和跳过缓存的情况。`NumSkipCacheIOTotal` 也可能包含其他跳过缓存策略造成的
I/O，不能单独作为阈值触发依据。
+
+:::note
+
+- 该机制仅限制存算分离 SELECT 查询读取未命中后的 Data Cache 回填，不限制远端读取量，也不影响显式缓存预热。进入
remote-only-on-miss 状态后，远端 I/O 和查询延迟可能增加。
+- 阈值按缓存块判断。如果剩余预算小于下一个缓存块，该块会被整体跳过；只有出现会超过阈值的缓存块时，`RemoteOnlyOnMissTriggered`
才会变为 `1`。
+- BE 参数 `enable_file_cache_query_limit_segment_meta` 控制 Doris 内表 Segment
footer 和 Segment 元数据是否计入同一阈值。Hive、Iceberg、Hudi 和 Paimon 数据文件的缓存回填始终受
`file_cache_query_limit_bytes`
约束。有关完整参数范围和内表行为，参见[文件缓存配置与使用指南](../compute-storage-decoupled/file-cache/file-cache.md)。
+
+:::
## 缓存预热
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 beba5576faf..2c846db4c41 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
@@ -3,8 +3,8 @@
"title": "文件缓存配置与使用指南（存算分离）",
"sidebar_label": "文件缓存配置",
"language": "zh-CN",
- "description": "介绍存算分离架构下 Doris 文件缓存的配置、索引优先写入、配额管理、缓存预热与清理、命中率监控及 TTL
策略，助力提升查询性能、降低对象存储成本。",
- "keywords": ["Doris 文件缓存", "存算分离缓存", "file cache", "索引优先缓存", "缓存预热",
"缓存配额", "TTL 缓存", "LRU", "缓存命中率", "对象存储加速"]
+ "description": "介绍存算分离架构下 Doris 文件缓存的配置、索引优先写入、查询级缓存限制、缓存预热与清理、命中率监控及 TTL
策略，助力提升查询性能、降低对象存储成本。",
+ "keywords": ["Doris 文件缓存", "存算分离缓存", "file cache", "索引优先缓存", "缓存预热",
"缓存配额", "file_cache_query_limit_bytes", "TTL 缓存", "LRU", "缓存命中率", "对象存储加速"]
}
---
@@ -174,13 +174,18 @@ file_cache_path 默认：BE 部署路径下的 storage 目录
<!-- 知识类型: 配置参数 -->
<!-- 适用场景: 多用户共享缓存 / 防止大查询缓存抖动 -->
-> 该功能自 4.0.3 版本起支持。
+Doris 提供两种相互独立的查询级 File Cache 限制机制。应根据希望控制的是“查询已占用的缓存空间”还是“查询后续是否继续回填缓存”选择参数：
-**缓存配额（Cache Query
Limit）**功能允许限制单个查询可填充的文件缓存比例。在多用户或复杂查询共享缓存资源的场景下，单个大查询可能占用过多缓存，导致其他查询的热点数据被淘汰。通过设置查询配额，可保证资源的公平使用，防止缓存抖动。
+| 机制 | 主要参数 | 达到限制后的行为 | 适用场景 |
+|---|---|---|---|
+| 按缓存占用比例限制 | `file_cache_query_limit_percent` | 新缓存块仍可写入；BE
优先淘汰当前查询记录的可释放缓存块，并在需要时从其他缓存队列淘汰 | 限制单个查询的缓存占用，兼顾后续缓存回填 |
+| 按远端扫描回填字节数停止写入 | `file_cache_query_limit_bytes` | 当下一个缓存块会使累计准入字节数超过阈值时，查询在该
BE 上进入 remote-only-on-miss 状态；后续未命中范围从远端读取但不再写入 File Cache |
限制一次大范围远端扫描造成的缓存写入和缓存抖动 |
-查询占用的缓存空间指该查询因数据未命中而填充到缓存中的数据总大小。若填充总量达到配额上限，后续填充的数据将基于 LRU 算法替换该查询先前填充的数据。
+### 按缓存占用比例限制
-### 配置说明
+> 该功能自 4.0.3 版本起支持。
+
+缓存占用比例限制用于控制单个查询在每个 File Cache
实例中可使用的最大缓存比例。在多用户或复杂查询共享缓存资源的场景下，该机制可以降低单个大查询长期占用过多缓存并淘汰其他热点数据的风险。
该功能涉及 BE 配置、FE 配置与会话变量三个层面。
@@ -198,11 +203,13 @@ file_cache_path 默认：BE 部署路径下的 storage 目录
**会话变量**
-| 变量 | 类型 | 说明 |
-|---|---|---|
-| `file_cache_query_limit_percent` | Integer (1–100) | 单个查询可使用的最大缓存比例（%）。上限受
`file_cache_query_limit_max_percent` 约束。建议计算后的缓存配额不低于 256 MB，低于该值时 BE 会在日志中输出告警
|
+| 变量 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `file_cache_query_limit_percent` | Integer | `-1` | 设置时取值范围为 `[1,
file_cache_query_limit_max_percent]`。表示单个查询可使用的最大缓存比例（%）。建议计算后的缓存配额不低于 256
MB，低于该值时 BE 会在日志中输出告警 |
+
+使用前，需要在 BE 上同时启用 `enable_file_cache` 和
`enable_file_cache_query_limit`，并确保查询会话中的 `enable_file_cache` 为 `true`。
-### 使用示例
+**使用示例**
```sql
-- 限制单个查询最多使用 50% 的缓存
@@ -212,7 +219,90 @@ SET file_cache_query_limit_percent = 50;
SELECT * FROM large_table;
```
-> **注意：** 设置的值必须在 `[0, file_cache_query_limit_max_percent]` 范围内。
+后续缓存未命中仍允许写入 File Cache；当查询的缓存占用超过配额时，BE 会通过查询级 LRU
记录和其他缓存队列释放空间。该机制不会把查询切换为“后续不再写缓存”的模式。
+
+### 按远端扫描回填字节数停止写入
+
+> 该功能仅在 Doris 4.1.x 中支持，Doris 4.0.x 不支持。
+
+`file_cache_query_limit_bytes` 用于限制单个 SELECT 查询在**每个 BE** 上因远端扫描缓存未命中而获准回填
File Cache 的累计字节数。该机制仅在存算分离模式且 BE 的 `enable_file_cache=true` 时生效，不依赖
`enable_file_cache_query_limit` 或 `file_cache_query_limit_max_percent`。
+
+该阈值由同一查询在一个 BE 上的并行 Scanner 共享，但不是整个查询或整个集群的总量限制。例如，一个查询在 10 个 BE 上执行并将阈值设为 1
GiB，理论上最多可在每个 BE 上分别准入约 1 GiB，而不是所有 BE 合计 1 GiB。
+
+**参数说明**
+
+| 参数 | 位置 | 类型 | 默认值 | 是否必选 | 说明 |
+|---|---|---|---|---|---|
+| `file_cache_query_limit_bytes` | Session Variable | BigInt | `-1` | 是 |
单个查询在每个 BE 上的远端扫描缓存回填阈值，单位为字节。小于 `0` 时关闭限制；等于 `0` 时从查询开始即不回填；大于 `0`
时按缓存块累计准入字节数 |
+| `enable_file_cache_query_limit_segment_meta` | BE 配置 | Boolean | `false` | 否
| 是否将 Segment footer 和 Segment 元数据的缓存写入纳入同一个字节阈值。该参数支持动态修改；数据页和倒排索引写入始终受字节阈值约束 |
+
+`file_cache_query_limit_bytes` 的取值行为如下：
+
+| 取值 | 行为 |
+|---|---|
+| `< 0` | 关闭该限制，保留原有的缓存未命中回填行为 |
+| `= 0` | 查询从开始就在每个 BE 上进入 remote-only-on-miss
状态；已完整覆盖请求范围的本地缓存仍可读取，未完整覆盖的范围直接从远端读取且不回填 |
+| `> 0` | 允许累计准入字节数不超过阈值的缓存块写入；当下一个缓存块会使累计值超过阈值时拒绝该块，并使该查询在当前 BE 上的后续未命中读取不再回填
|
+
+阈值按缓存块进行准入判断，并不保证实际写入量恰好等于阈值。如果剩余预算小于下一个缓存块，该块会被整体跳过，剩余预算不会继续用于更小的后续块。一旦进入
remote-only-on-miss 状态，同一查询在该 BE 上不会恢复缓存回填。
+
+**限制远端扫描回填量**
+
+以下示例假设 `large_table` 位于存算分离集群中，并且所有 BE 已启用 File Cache。该设置允许查询在每个 BE 上最多准入 1
GiB 的远端扫描缓存块：
+
+```sql
+SET enable_profile = true;
+SET profile_level = 2;
+SET file_cache_query_limit_bytes = 1073741824;
+
+SELECT COUNT(*) FROM large_table;
+```
+
+查询结果不受影响。当某个 BE 上的下一个缓存块会使累计准入量超过 1 GiB 时，该 BE
上同一查询的后续缓存未命中会直接读取远端数据，不再产生对应的本地缓存写入。
+
+如果希望一次性扫描从开始就不污染 File Cache，可将阈值设为 `0`；查询结束后可恢复默认值：
+
+```sql
+SET file_cache_query_limit_bytes = 0;
+SELECT COUNT(*) FROM large_table;
+
+SET file_cache_query_limit_bytes = -1;
+```
+
+**是否计入 Segment 元数据**
+
+默认情况下，数据页和倒排索引缓存写入计入阈值，Segment footer 和 Segment 元数据不计入。此时即使查询已经进入
remote-only-on-miss 状态，Segment footer 和元数据仍可能写入 File Cache，因此 Profile
中的总写入量可能大于 `file_cache_query_limit_bytes`。
+
+如果需要连 Segment footer 和元数据也停止回填，请在同一计算组的所有 BE 上设置：
+
+```properties
+enable_file_cache_query_limit_segment_meta=true
+```
+
+该参数可通过 BE 动态配置接口即时修改；若需重启后继续生效，应写入 `be.conf` 或使用持久化动态配置。具体方法参见 [BE
配置](../../admin-manual/config/be-config.md)。
+
+**通过 Profile 验证**
+
+开启 Query Profile 后，可在 Scanner 的 `FileCache` 指标组中关注：
+
+| 指标 | 说明 |
+|---|---|
+| `RemoteOnlyOnMissTriggered` | 值为 `1` 表示该 Scanner 已观察到查询进入
remote-only-on-miss 状态 |
+| `RemoteOnlyOnMissThresholdBytes` | 当前查询配置的字节阈值 |
+| `BytesWriteIntoCache` | 实际写入 File Cache 的总字节数 |
+| `InvertedIndexBytesWriteIntoCache` | 倒排索引实际写入 File Cache 的字节数 |
+| `SegmentFooterIndexBytesWriteIntoCache` | Segment footer 和元数据实际写入 File Cache
的字节数 |
+| `NumSkipCacheIOTotal` | 跳过缓存的 I/O 次数；该指标还可能包含其他跳过缓存策略造成的 I/O，应与
`RemoteOnlyOnMissTriggered` 一起判断 |
+
+如果累计准入量恰好等于阈值，且查询结束前没有新的缓存块尝试超过阈值，`RemoteOnlyOnMissTriggered` 仍可能为
`0`。只有出现会超过阈值的下一个缓存块时，状态才会切换。
+
+**使用建议与注意事项**
+
+- 对一次性全表扫描、低复用率 ETL 或 Ad-hoc 查询，可设置较小的正值，或使用 `0` 从查询开始禁止缓存回填，避免冷数据置换热点数据。
+- 该参数限制的是查询读取未命中后的 File Cache 回填，不限制远端读取量，不会终止查询，也不影响导入、Compaction、Schema
Change 或显式缓存预热产生的缓存写入。
+- 进入 remote-only-on-miss 状态后，已完整缓存的请求范围仍可从本地读取；未完整覆盖的请求范围会直接访问远端存储，可能增加对象存储
I/O 和查询延迟。
+- 如果目标是限制查询保留在缓存中的占用比例，并允许后续未命中继续回填，应使用
`file_cache_query_limit_percent`；如果目标是在一定回填量后停止后续写入，应使用
`file_cache_query_limit_bytes`。
+- 默认不计入 Segment footer 和元数据可以保留高复用元数据的缓存收益。如果业务要求查询达到阈值后不再产生这类写入，再启用
`enable_file_cache_query_limit_segment_meta`，并结合 Profile 验证效果。
## 缓存预热
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 2f47bdacb85..b1d74a0d4c5 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
@@ -2,7 +2,7 @@
{
"title": "数据缓存",
"language": "zh-CN",
- "description": "Apache Doris 数据缓存（Data Cache）将 HDFS 及对象存储数据缓存至本地磁盘，加速
Lakehouse 查询性能。支持缓存预热、配额限制与准入控制，适用于 Hive、Iceberg、Hudi、Paimon 表查询场景。"
+ "description": "Apache Doris 数据缓存（Data Cache）将 HDFS 及对象存储数据缓存至本地磁盘，加速
Lakehouse 查询性能。支持缓存预热、查询级回填限制与准入控制，适用于 Hive、Iceberg、Hudi、Paimon 表查询场景。"
}
---
@@ -109,13 +109,18 @@ SET GLOBAL enable_file_cache = true;
## 缓存的配额
-> 该功能自 4.0.3 版本支持。
+Doris 提供两种相互独立的查询级 Data Cache 限制机制：
+
+| 机制 | 主要参数 | 达到限制后的行为 |
+|---|---|---|
+| 按缓存占用比例限制 | `file_cache_query_limit_percent` | 继续允许缓存未命中回填，并通过查询级 LRU
记录和其他缓存队列释放空间 |
+| 按远端扫描回填字节数停止写入 | `file_cache_query_limit_bytes` |
当下一个缓存块会使累计准入字节数超过阈值时，后续未命中范围从远端读取但不再回填本地缓存 |
-缓存配额（Cache Query
Limit）功能允许用户限制单个查询可以使用的文件缓存百分比。在多用户或复杂查询共享缓存资源的场景下，单个大查询可能会占用过多的缓存空间，导致其他查询的热点数据被淘汰。通过设置查询配额，可以保证资源的公平使用，防止缓存抖动。
+### 按缓存占用比例限制
-查询占用的缓存空间指的是该查询因数据未命中而填充到缓存中的数据总大小。如果该查询填充的总大小已经达到配额限制，那么查询后续填充的数据会基于 LRU
算法替换先前填充的数据。
+> 该功能自 4.0.3 版本支持。
-### 配置说明
+缓存占用比例限制用于控制单个查询在每个 File Cache
实例中可使用的最大缓存比例。在多用户或复杂查询共享缓存资源的场景下，该机制可以降低单个大查询长期占用过多缓存并淘汰其他热点数据的风险。
该功能涉及 BE 和 FE 两端的配置，以及会话变量（Session Variable）的设置。
@@ -137,6 +142,7 @@ SET GLOBAL enable_file_cache = true;
- `file_cache_query_limit_percent`:
- 类型：Integer (1-100)
+ - 默认值：`-1`
- 说明：文件缓存查询限制百分比。设置单个查询可使用的最大缓存比例。该值上限受 `file_cache_query_limit_max_percent`
约束。建议计算后的缓存配额不低于 256MB，如果低于该值，BE 会在日志中进行告警提示。
**使用示例**
@@ -150,7 +156,51 @@ SELECT * FROM large_table;
```
**注意：**
-1. 设置的值必须在 [0, `file_cache_query_limit_max_percent`] 范围内。
+
+1. 设置的值必须在 `[1, file_cache_query_limit_max_percent]` 范围内。
+2. 使用前，需要在 BE 上同时启用 `enable_file_cache` 和
`enable_file_cache_query_limit`，并确保查询会话中的 `enable_file_cache` 为 `true`。
+3. 达到百分比配额后，后续缓存未命中仍可写入 Data Cache；该机制不会将查询切换为“后续不再写缓存”的模式。
+
+### 按远端扫描回填字节数停止写入
+
+> 该功能仅在 Doris 4.1.x 中支持，Doris 4.0.x 不支持。
+
+在存算分离模式下，可通过会话变量 `file_cache_query_limit_bytes` 限制单个 SELECT 查询在**每个 BE** 上因
Hive、Iceberg、Hudi 或 Paimon 数据文件缓存未命中而获准回填 Data Cache 的累计字节数。该功能要求 BE 的
`enable_file_cache=true`，但不依赖 `enable_file_cache_query_limit` 或
`file_cache_query_limit_max_percent`。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `file_cache_query_limit_bytes` | BigInt | `-1` | 单个查询在每个 BE
上的远端扫描缓存回填阈值，单位为字节。小于 `0` 时关闭限制；等于 `0` 时从查询开始即不回填；大于 `0` 时按缓存块累计准入字节数 |
+
+该阈值由同一查询在一个 BE 上的并行 Scanner 共享，不是整个查询或整个集群的总量限制。当下一个缓存块会使累计准入字节数超过阈值时，该查询在当前
BE 上进入 remote-only-on-miss 状态：已完整覆盖请求范围的本地缓存仍可读取；未完整覆盖的范围直接从远端存储读取，且不再回填 Data
Cache。查询结果不受影响。
+
+以下示例将每个 BE 的远端扫描回填阈值设为 1 GiB：
+
+```sql
+SET enable_profile = true;
+SET profile_level = 2;
+SET file_cache_query_limit_bytes = 1073741824;
+
+SELECT COUNT(*) FROM hive_catalog.sales.orders;
+```
+
+如果希望一次性扫描从开始就不写 Data Cache，可将阈值设为 `0`；查询完成后恢复默认值：
+
+```sql
+SET file_cache_query_limit_bytes = 0;
+SELECT COUNT(*) FROM hive_catalog.sales.orders;
+
+SET file_cache_query_limit_bytes = -1;
+```
+
+开启 Query Profile 后，可在 Scanner 的 `FileCache` 指标组中查看 `RemoteOnlyOnMissTriggered`
和 `RemoteOnlyOnMissThresholdBytes`。当 `RemoteOnlyOnMissTriggered=1` 时，表示该
Scanner 已观察到查询进入 remote-only-on-miss 状态；可结合 `BytesWriteIntoCache` 与
`NumSkipCacheIOTotal` 判断实际写入和跳过缓存的情况。`NumSkipCacheIOTotal` 也可能包含其他跳过缓存策略造成的
I/O，不能单独作为阈值触发依据。
+
+:::note
+
+- 该机制仅限制存算分离 SELECT 查询读取未命中后的 Data Cache 回填，不限制远端读取量，也不影响显式缓存预热。进入
remote-only-on-miss 状态后，远端 I/O 和查询延迟可能增加。
+- 阈值按缓存块判断。如果剩余预算小于下一个缓存块，该块会被整体跳过；只有出现会超过阈值的缓存块时，`RemoteOnlyOnMissTriggered`
才会变为 `1`。
+- BE 参数 `enable_file_cache_query_limit_segment_meta` 控制 Doris 内表 Segment
footer 和 Segment 元数据是否计入同一阈值。Hive、Iceberg、Hudi 和 Paimon 数据文件的缓存回填始终受
`file_cache_query_limit_bytes`
约束。有关完整参数范围和内表行为，参见[文件缓存配置与使用指南](../compute-storage-decoupled/file-cache/file-cache.md)。
+
+:::
## 缓存预热
diff --git
a/ja-source/docusaurus-plugin-content-docs/current/compute-storage-decoupled/file-cache/file-cache.md
b/ja-source/docusaurus-plugin-content-docs/current/compute-storage-decoupled/file-cache/file-cache.md
index 80d6c6ac955..78bb8434fd8 100644
---
a/ja-source/docusaurus-plugin-content-docs/current/compute-storage-decoupled/file-cache/file-cache.md
+++
b/ja-source/docusaurus-plugin-content-docs/current/compute-storage-decoupled/file-cache/file-cache.md
@@ -2,7 +2,7 @@
{
"title": "ファイルキャッシュ",
"language": "ja",
- "description":
"ストレージ・コンピューティング分離モードにおけるDorisファイルキャッシュの設定、インデックスのみの書き込み、クォータ、ウォームアップ、監視、およびTTL戦略について説明します。"
+ "description":
"ストレージ・コンピューティング分離モードにおけるDorisファイルキャッシュの設定、インデックスのみの書き込み、クエリ単位のキャッシュ制限、ウォームアップ、監視、およびTTL戦略について説明します。"
}
---
分離アーキテクチャでは、データはリモートストレージに保存されます。Dorisデータベースは、ローカルディスク上のキャッシュを利用してデータアクセスを高速化し、高度なマルチキューLRU（Least
Recently
Used）戦略を採用してキャッシュスペースを効率的に管理します。この戦略は特にインデックスとメタデータのアクセスパスを最適化し、頻繁にアクセスされるユーザーデータのキャッシュを最大化することを目的としています。マルチCompute
Group（Compute Group）シナリオでは、Dorisは新しいcompute
groupが確立された際に特定のデータ（テーブルやパーティションなど）をキャッシュに素早くロードするキャッシュウォーミング機能も提供し、それによりクエリパフォーマンスを向上させます。
@@ -155,47 +155,133 @@ file_cache_exit_need_evict_cache_in_advance_percent
Default: "85"
## Cache Query Limit
-> この機能はバージョン4.0.3以降でサポートされています。
+Doris には、クエリ単位で File Cache
を制御する独立した2つの方式があります。クエリがすでに占有しているキャッシュ容量を制限するのか、後続のキャッシュ書き込みを停止するのかに応じてパラメータを選択してください。
+
+| 制御方式 | 主なパラメータ | 制限到達後の動作 | 適用シナリオ |
+|---|---|---|---|
+| キャッシュ占有率による制限 | `file_cache_query_limit_percent` |
新しいキャッシュブロックの書き込みは継続できます。BE
はまず現在のクエリに記録された解放可能なブロックを削除し、必要に応じて他のキャッシュキューからも削除します |
後続のキャッシュ書き込みを許可しながら、単一クエリのキャッシュ占有量を制限する |
+| リモートスキャンの書き込みをバイト閾値で停止 | `file_cache_query_limit_bytes` |
次のキャッシュブロックによって許可済みバイト数が閾値を超える場合、その BE 上でクエリは remote-only-on-miss
状態になります。以降のキャッシュミスはリモートストレージから読み取られ、File Cache には書き込まれません |
大規模なリモートスキャンによるキャッシュ書き込みとキャッシュの入れ替わりを抑制する |
-Cache Query
Limit機能により、ユーザーは単一のクエリが使用できるファイルキャッシュのパーセンテージを制限できます。複数のユーザーや複雑なクエリがキャッシュリソースを共有するシナリオでは、単一の大きなクエリがキャッシュ容量を過度に占有し、他のクエリのホットデータが退避される可能性があります。クエリ制限を設定することで、公平なリソース使用を確保し、キャッシュスラッシングを防げます。
+### キャッシュ占有率による制限
-クエリが占有するキャッシュ容量とは、キャッシュミスによりキャッシュに投入されたデータの総サイズを指します。クエリによって投入された総サイズがクォータ制限に達した場合、そのクエリによる後続のデータ投入は、LRUアルゴリズムに基づいて以前に投入されたデータを置換します。
+> この機能はバージョン4.0.3以降でサポートされています。
-### 設定
+キャッシュ占有率による制限は、単一クエリが各 File Cache
インスタンスで使用できる最大割合を制御します。複数のユーザーや複雑なクエリがキャッシュリソースを共有する場合に、1つの大規模クエリが過剰なキャッシュを保持して他のホットデータを削除するリスクを軽減します。
-この機能には、BEとFEでの設定、およびセッション変数の設定が関わります。
+この機能には、BE設定、FE設定、およびセッション変数の3つの設定が関係します。
-**1. BE設定**
+**BE設定**
-- `enable_file_cache_query_limit`:
- - タイプ: Boolean
- - デフォルト: `false`
- - 説明: BE側のfile cache query
limit機能のマスタースイッチです。有効化された場合のみ、BEはFEから渡されたクエリ制限パラメータを処理します。
+| パラメータ | 型 | デフォルト値 | 説明 |
+|---|---|---|---|
+| `enable_file_cache_query_limit` | Boolean | `false` |
BE側のキャッシュクエリ制限のマスタースイッチです。有効な場合のみ、BEはFEから渡されたクエリ制限パラメータを処理します |
-**2. FE設定**
+**FE設定**
-- `file_cache_query_limit_max_percent`:
- - タイプ: Integer
- - デフォルト: `100`
- - 説明: セッション変数の上限値を検証するために使用される最大クエリ制限制約です。ユーザーが設定するクエリ制限がこの値を超えないことを保証します。
+| パラメータ | 型 | デフォルト値 | 説明 |
+|---|---|---|---|
+| `file_cache_query_limit_max_percent` | Integer | `100` |
クエリクォータの最大値です。セッション変数の上限を検証するために使用されます |
-**3. セッション変数**
+**セッション変数**
-- `file_cache_query_limit_percent`:
- - タイプ: Integer (1-100)
- - 説明:
ファイルキャッシュクエリ制限パーセンテージです。クエリが使用できるキャッシュの最大パーセンテージを設定します。この値は`file_cache_query_limit_max_percent`により制約されます。計算されたキャッシュクォータが256MB未満にならないことを推奨します。この値未満の場合、BEはログに警告を出力します。
+| 変数 | 型 | デフォルト値 | 説明 |
+|---|---|---|---|
+| `file_cache_query_limit_percent` | Integer | `-1` | 明示的に設定する場合、値は `[1,
file_cache_query_limit_max_percent]`
の範囲内である必要があります。単一クエリが使用できるキャッシュの最大割合を指定します。算出されたキャッシュクォータは256
MB以上を推奨します。これより小さい場合、BEはログに警告を出力します |
+
+この制御を使用する前に、BEで `enable_file_cache` と `enable_file_cache_query_limit`
の両方を有効にし、クエリセッションの `enable_file_cache` が `true` であることを確認してください。
**使用例**
```sql
--- Set session variable to limit a query to use at most 50% of the cache
+-- 単一クエリが使用できるキャッシュを最大50%に制限する
SET file_cache_query_limit_percent = 50;
--- Execute query
+-- クエリを実行する
SELECT * FROM large_table;
```
-**注意:**
-1. 値は[0, `file_cache_query_limit_max_percent`]の範囲内である必要があります。
+
+後続のキャッシュミスも File Cache
に書き込むことができます。クエリのキャッシュ占有量がクォータを超えると、BEはクエリ単位のLRU記録と他のキャッシュキューを使用して領域を解放します。この制御によって、クエリが「以降はキャッシュへ書き込まない」モードに切り替わることはありません。
+
+### リモートスキャンのキャッシュ書き込みをバイト閾値で停止する
+
+`file_cache_query_limit_bytes` は、単一の SELECT クエリについて、リモートスキャンのキャッシュミスにより
read-through で File Cache へ書き込むことを許可された累積バイト数を、**各 BE**
で制限します。この機能は、ストレージ・コンピューティング分離モードでBEの `enable_file_cache=true`
の場合にのみ有効です。`enable_file_cache_query_limit` または
`file_cache_query_limit_max_percent` には依存しません。
+
+同一クエリの並列Scannerは、1つのBE上で同じ閾値を共有します。ただし、この閾値はクエリ全体またはクラスタ全体の合計値ではありません。たとえば、10台のBEで実行するクエリに1
GiBを設定した場合、全BEの合計が1 GiBになるのではなく、各BEがそれぞれ約1 GiBまで許可できます。
+
+**パラメータ**
+
+| パラメータ | 設定場所 | 型 | デフォルト値 | 必須 | 説明 |
+|---|---|---|---|---|---|
+| `file_cache_query_limit_bytes` | セッション変数 | BigInt | `-1` | はい |
単一クエリについて、各BEで許可するリモートスキャンのキャッシュ書き込み閾値です。単位はバイトです。`0`未満では無効、`0`ではクエリ開始時からキャッシュへ書き込まず、正の値ではキャッシュブロック単位で許可済みバイト数を累積します
|
+| `enable_file_cache_query_limit_segment_meta` | BE設定 | Boolean | `false` |
いいえ | Segment
footerとSegmentメタデータのキャッシュ書き込みを同じバイト閾値に含めるかどうかを指定します。このパラメータは動的に変更できます。この制御が有効な場合、データページと転置インデックスの書き込みは常にバイト閾値の対象です
|
+
+`file_cache_query_limit_bytes` の値による動作は次のとおりです。
+
+| 値 | 動作 |
+|---|---|
+| `< 0` | この制御を無効にし、従来のキャッシュミス時の書き込み動作を維持します |
+| `= 0` |
クエリ開始時から各BEでremote-only-on-miss状態になります。要求範囲がローカルキャッシュで完全にカバーされている場合はローカルから読み取れます。完全にカバーされていない範囲はリモートストレージから直接読み取り、キャッシュへ書き込みません
|
+| `> 0` |
累積の許可済みバイト数が閾値を超えないキャッシュブロックの書き込みを許可します。次のブロックで閾値を超える場合、そのブロックを拒否し、そのBE上の同一クエリによる後続のキャッシュミスはキャッシュへ書き込みません
|
+
+許可判定はキャッシュブロック単位で行われるため、実際の書き込み量が閾値と完全に一致するとは限りません。残りの容量が次のキャッシュブロックより小さい場合、そのブロック全体がスキップされ、残りの容量が後続の小さいブロックに使用されることはありません。クエリがBE上でremote-only-on-miss状態になると、そのBEではキャッシュ書き込みを再開しません。
+
+**リモートスキャンのキャッシュ書き込み量を制限する**
+
+次の例では、`large_table` がストレージ・コンピューティング分離クラスタにあり、すべてのBEでFile
Cacheが有効であることを前提とします。各BEで最大1 GiBのリモートスキャンキャッシュブロックを許可します。
+
+```sql
+SET enable_profile = true;
+SET profile_level = 2;
+SET file_cache_query_limit_bytes = 1073741824;
+
+SELECT COUNT(*) FROM large_table;
+```
+
+クエリ結果は変わりません。あるBEで次のキャッシュブロックによって許可済みバイト数が1
GiBを超える場合、そのBE上の同一クエリによる後続のキャッシュミスはリモートデータを読み取り、ローカルキャッシュへ追加で書き込みません。
+
+一時的なスキャンで最初からFile Cacheへ書き込みたくない場合は閾値を `0` に設定し、クエリ終了後にデフォルト値へ戻します。
+
+```sql
+SET file_cache_query_limit_bytes = 0;
+SELECT COUNT(*) FROM large_table;
+
+SET file_cache_query_limit_bytes = -1;
+```
+
+**Segmentメタデータを含めるかどうか**
+
+デフォルトでは、データページと転置インデックスのキャッシュ書き込みは閾値に含まれますが、Segment
footerとSegmentメタデータは含まれません。そのため、クエリがremote-only-on-miss状態になった後もSegment
footerとメタデータがFile Cacheへ書き込まれる可能性があり、Profileに表示される合計書き込み量が
`file_cache_query_limit_bytes` を超えることがあります。
+
+Segment footerとメタデータの書き込みも停止するには、同じCompute GroupのすべてのBEで次を設定します。
+
+```properties
+enable_file_cache_query_limit_segment_meta=true
+```
+
+このパラメータはBEの動的設定APIから即時に変更できます。再起動後も維持するには、`be.conf`
に追加するか、永続化オプション付きの動的設定を使用します。詳細は[BE設定](../../admin-manual/config/be-config.md)を参照してください。
+
+**Query Profileで確認する**
+
+Query Profileを有効にした後、Scanner配下の `FileCache` メトリックグループを確認します。
+
+| メトリック | 説明 |
+|---|---|
+| `RemoteOnlyOnMissTriggered` | 値が `1`
の場合、そのScannerがクエリのremote-only-on-miss状態への移行を確認したことを示します |
+| `RemoteOnlyOnMissThresholdBytes` | クエリに設定されたバイト閾値 |
+| `BytesWriteIntoCache` | File Cacheへ実際に書き込まれた合計バイト数 |
+| `InvertedIndexBytesWriteIntoCache` | File Cacheへ実際に書き込まれた転置インデックスのバイト数 |
+| `SegmentFooterIndexBytesWriteIntoCache` | File Cacheへ実際に書き込まれたSegment
footerとメタデータのバイト数 |
+| `NumSkipCacheIOTotal` |
キャッシュをスキップしたI/O回数です。他のキャッシュポリシーによってスキップされたI/Oも含まれるため、`RemoteOnlyOnMissTriggered`
と合わせて判断してください |
+
+許可済みバイト数が閾値と完全に一致し、クエリ終了までに閾値を超える新しいキャッシュブロックがない場合、`RemoteOnlyOnMissTriggered`
は `0` のままになることがあります。状態は、後続のブロックによって閾値を超える場合にのみ切り替わります。
+
+**推奨事項と注意事項**
+
+- 一時的なフルスキャン、再利用率の低いETL、またはアドホッククエリでは、小さい正の閾値または `0`
を使用してクエリ開始時からキャッシュへの書き込みを停止し、コールドデータによるホットデータの置き換えを防ぎます。
+- このパラメータが制限するのは、クエリ読み取り時のキャッシュミス後に行われるFile
Cacheへの書き込みです。リモート読み取り量を制限したり、クエリを終了したりするものではなく、ロード、Compaction、Schema
Change、または明示的なキャッシュウォームアップによる書き込みにも影響しません。
+-
remote-only-on-miss状態でも、要求範囲がローカルキャッシュで完全にカバーされている場合はローカルから読み取れます。完全にカバーされていない範囲はリモートストレージへ直接アクセスするため、オブジェクトストレージI/Oとクエリレイテンシが増加する可能性があります。
+- クエリが保持するキャッシュ占有率を制限しながら、後続のキャッシュミスによる書き込みを許可する場合は
`file_cache_query_limit_percent` を使用します。一定量を許可した後の書き込みを停止する場合は
`file_cache_query_limit_bytes` を使用します。
+- Segment
footerとメタデータをデフォルトで対象外にすることで、再利用率の高いメタデータのキャッシュ効果を維持できます。閾値到達後にこれらの書き込みも停止する必要がある場合のみ
`enable_file_cache_query_limit_segment_meta` を有効にし、Query Profileで結果を確認してください。
## Cache Warm Up
diff --git
a/ja-source/docusaurus-plugin-content-docs/current/lakehouse/data-cache.md
b/ja-source/docusaurus-plugin-content-docs/current/lakehouse/data-cache.md
index d8eb74145cc..33ec36ab549 100644
--- a/ja-source/docusaurus-plugin-content-docs/current/lakehouse/data-cache.md
+++ b/ja-source/docusaurus-plugin-content-docs/current/lakehouse/data-cache.md
@@ -2,7 +2,7 @@
{
"title": "データキャッシュ",
"language": "ja",
- "description":
"データキャッシュは、リモートストレージシステム（HDFSまたはオブジェクト）から最近アクセスされたデータファイルをキャッシュすることで、同じデータの後続のクエリを高速化します"
+ "description":
"データキャッシュは、HDFSまたはオブジェクトストレージのデータをローカルにキャッシュしてLakehouseクエリを高速化し、ウォームアップ、クエリ単位のキャッシュ書き込み制限、およびキャッシュアドミッション制御をサポートします。"
}
---
Data
Cacheは、リモートストレージシステム（HDFSまたはオブジェクトストレージ）から最近アクセスされたデータファイルをローカルディスクにキャッシュすることで、同じデータの後続のクエリを高速化します。同じデータに頻繁にアクセスするシナリオでは、Data
Cacheは繰り返されるリモートデータアクセスのオーバーヘッドを回避し、ホットデータのクエリ分析のパフォーマンスと安定性を向上させることができます。
@@ -104,47 +104,96 @@ SET GLOBAL enable_file_cache = true;
## Cache Query Limit
-> この機能はバージョン4.0.3以降でサポートされています。
+Doris には、クエリ単位でData Cacheを制御する独立した2つの方式があります。
+
+| 制御方式 | 主なパラメータ | 制限到達後の動作 |
+|---|---|---|
+| キャッシュ占有率による制限 | `file_cache_query_limit_percent` |
キャッシュミス時の書き込みを継続しながら、BEはクエリ単位のLRU記録と他のキャッシュキューを使用して領域を解放します |
+| リモートスキャンの書き込みをバイト閾値で停止 | `file_cache_query_limit_bytes` |
次のキャッシュブロックによって許可済みバイト数が閾値を超える場合、後続のキャッシュミスはリモートストレージから読み取られ、ローカルキャッシュには書き込まれません
|
-Cache Query
Limit機能により、ユーザーは単一のクエリが使用できるファイルキャッシュの割合を制限できます。複数のユーザーや複雑なクエリがキャッシュリソースを共有するシナリオでは、単一の大きなクエリが過度にキャッシュ領域を占有し、他のクエリのホットデータが削除される可能性があります。クエリ制限を設定することで、公平なリソース使用を確保し、キャッシュスラッシングを防ぐことができます。
+### キャッシュ占有率による制限
-クエリが占有するキャッシュ領域とは、キャッシュミスによってキャッシュに投入されたデータの総サイズを指します。クエリによって投入された総サイズがクォータ制限に達すると、そのクエリによって投入される後続のデータは、LRUアルゴリズムに基づいて以前に投入されたデータを置き換えます。
+> この機能はバージョン4.0.3以降でサポートされています。
-### Configuration
+キャッシュ占有率による制限は、単一クエリが各File
Cacheインスタンスで使用できる最大割合を制御します。複数のユーザーや複雑なクエリがキャッシュリソースを共有する場合に、1つの大規模クエリが過剰なキャッシュを保持して他のホットデータを削除するリスクを軽減します。
-この機能はBEとFEでの設定、およびセッション変数設定が関係します。
+この機能には、BE設定、FE設定、およびセッション変数が関係します。
-**1. BE Configuration**
+**1. BE設定**
- `enable_file_cache_query_limit`:
- - Type: Boolean
- - Default: `false`
- - Description: BE側でのfile cache query
limit機能のマスタースイッチ。有効にした場合のみ、BEはFEから渡されたクエリ制限パラメータを処理します。
+ - 型: Boolean
+ - デフォルト値: `false`
+ - 説明: BE側のFile Cacheクエリ制限のマスタースイッチです。有効な場合のみ、BEはFEから渡されたクエリ制限パラメータを処理します。
-**2. FE Configuration**
+**2. FE設定**
- `file_cache_query_limit_max_percent`:
- - Type: Integer
- - Default: `100`
- - Description:
セッション変数の上限を検証するために使用される最大クエリ制限制約。ユーザーが設定するクエリ制限がこの値を超えないことを保証します。
+ - 型: Integer
+ - デフォルト値: `100`
+ - 説明: セッション変数の上限を検証するために使用されるクエリ制限の最大値です。
-**3. Session Variables**
+**3. セッション変数**
- `file_cache_query_limit_percent`:
- - Type: Integer (1-100)
- - Description:
ファイルキャッシュクエリ制限の割合。クエリが使用できるキャッシュの最大割合を設定します。この値は`file_cache_query_limit_max_percent`によって制約されます。算出されたキャッシュクォータは256MB以上にすることが推奨されます。この値より低い場合、BEはログに警告を出力します。
+ - 型: Integer (1-100)
+ - デフォルト値: `-1`
+ - 説明: クエリが使用できるキャッシュの最大割合です。この値は `file_cache_query_limit_max_percent`
によって制約されます。算出されたキャッシュクォータは256 MB以上を推奨します。これより小さい場合、BEはログに警告を出力します。
-**Usage Example**
+**使用例**
```sql
--- Set session variable to limit a query to use at most 50% of the cache
+-- 単一クエリが使用できるキャッシュを最大50%に制限する
SET file_cache_query_limit_percent = 50;
--- Execute query
+-- クエリを実行する
SELECT * FROM large_table;
```
-**注意:**
-1. 値は [0, `file_cache_query_limit_max_percent`] の範囲内である必要があります。
+
+**注意事項:**
+
+1. 値は `[1, file_cache_query_limit_max_percent]` の範囲内である必要があります。
+2. この制御を使用する前に、BEで `enable_file_cache` と `enable_file_cache_query_limit`
の両方を有効にし、クエリセッションの `enable_file_cache` が `true` であることを確認してください。
+3. キャッシュ占有率の上限に達した後も、キャッシュミスはData
Cacheへ書き込むことができます。この制御によって、クエリが「以降はキャッシュへ書き込まない」モードに切り替わることはありません。
+
+### リモートスキャンのキャッシュ書き込みをバイト閾値で停止する
+
+ストレージ・コンピューティング分離モードでは、セッション変数 `file_cache_query_limit_bytes`
により、Hive、Iceberg、Hudi、またはPaimonのデータファイルのキャッシュミスによってData
Cacheへの書き込みを許可された累積バイト数を、単一のSELECTクエリについて**各BE**で制限できます。この機能にはBEの
`enable_file_cache=true` が必要ですが、`enable_file_cache_query_limit` または
`file_cache_query_limit_max_percent` には依存しません。
+
+| パラメータ | 型 | デフォルト値 | 説明 |
+|---|---|---|---|
+| `file_cache_query_limit_bytes` | BigInt | `-1` |
単一クエリについて、各BEで許可するリモートスキャンのキャッシュ書き込み閾値です。単位はバイトです。`0`未満では無効、`0`ではクエリ開始時からキャッシュへ書き込まず、正の値ではキャッシュブロック単位で許可済みバイト数を累積します
|
+
+同一クエリの並列Scannerは、1つのBE上で同じ閾値を共有します。この閾値はクエリ全体またはクラスタ全体の合計値ではありません。次のキャッシュブロックによって許可済みバイト数が閾値を超える場合、そのBE上でクエリはremote-only-on-miss状態になります。要求範囲がローカルキャッシュで完全にカバーされている場合はローカルから読み取れます。完全にカバーされていない範囲はリモートストレージから直接読み取り、Data
Cacheへ書き込みません。クエリ結果は変わりません。
+
+次の例では、各BEのリモートスキャンキャッシュ書き込み閾値を1 GiBに設定します。
+
+```sql
+SET enable_profile = true;
+SET profile_level = 2;
+SET file_cache_query_limit_bytes = 1073741824;
+
+SELECT COUNT(*) FROM hive_catalog.sales.orders;
+```
+
+一時的なスキャンで最初からData Cacheへ書き込みたくない場合は閾値を `0` に設定し、クエリ終了後にデフォルト値へ戻します。
+
+```sql
+SET file_cache_query_limit_bytes = 0;
+SELECT COUNT(*) FROM hive_catalog.sales.orders;
+
+SET file_cache_query_limit_bytes = -1;
+```
+
+Query Profileを有効にした後、Scannerの `FileCache` メトリックグループで
`RemoteOnlyOnMissTriggered` と `RemoteOnlyOnMissThresholdBytes`
を確認します。`RemoteOnlyOnMissTriggered=1`
の場合、そのScannerがクエリのremote-only-on-miss状態への移行を確認したことを示します。`BytesWriteIntoCache` と
`NumSkipCacheIOTotal`
を使用して、実際の書き込みとキャッシュをスキップしたI/Oを確認できます。`NumSkipCacheIOTotal`
には他のキャッシュポリシーによってスキップされたI/Oも含まれるため、この値だけでは閾値が発動したことを判断できません。
+
+:::note
+
+- この制御は、ストレージ・コンピューティング分離モードのSELECTクエリで、キャッシュミス後にData
Cacheへ書き込む動作のみを制限します。リモート読み取り量を制限せず、明示的なキャッシュウォームアップにも影響しません。remote-only-on-miss状態では、リモートI/Oとクエリレイテンシが増加する可能性があります。
+-
許可判定はキャッシュブロック単位で行われます。残りの容量が次のブロックより小さい場合、そのブロック全体がスキップされます。`RemoteOnlyOnMissTriggered`
は、あるブロックによって閾値を超える場合にのみ `1` になります。
+- BEパラメータ `enable_file_cache_query_limit_segment_meta` は、Doris内部テーブルのSegment
footerとSegmentメタデータの書き込みを同じ閾値に含めるかどうかを制御します。Hive、Iceberg、Hudi、およびPaimonのデータファイルのキャッシュ書き込みは常に
`file_cache_query_limit_bytes`
の対象です。パラメータの完全な適用範囲と内部テーブルの動作については、[ファイルキャッシュの設定と使用ガイド](../compute-storage-decoupled/file-cache/file-cache.md)を参照してください。
+
+:::
## Cache Warmup
diff --git
a/ja-source/docusaurus-plugin-content-docs/version-4.x/compute-storage-decoupled/file-cache/file-cache.md
b/ja-source/docusaurus-plugin-content-docs/version-4.x/compute-storage-decoupled/file-cache/file-cache.md
index 2bc798e5deb..c872e5b3cdb 100644
---
a/ja-source/docusaurus-plugin-content-docs/version-4.x/compute-storage-decoupled/file-cache/file-cache.md
+++
b/ja-source/docusaurus-plugin-content-docs/version-4.x/compute-storage-decoupled/file-cache/file-cache.md
@@ -2,7 +2,7 @@
{
"title": "ファイルキャッシュ",
"language": "ja",
- "description":
"ストレージ・コンピューティング分離モードにおけるDorisファイルキャッシュの設定、インデックスのみの書き込み、クォータ、ウォームアップ、監視、およびTTL戦略について説明します。"
+ "description":
"ストレージ・コンピューティング分離モードにおけるDorisファイルキャッシュの設定、インデックスのみの書き込み、クエリ単位のキャッシュ制限、ウォームアップ、監視、およびTTL戦略について説明します。"
}
---
分散アーキテクチャでは、データはリモートストレージに保存されます。Dorisデータベースは、ローカルディスク上のキャッシュを利用してデータアクセスを高速化し、高度なマルチキューLRU（Least
Recently
Used）戦略を採用してキャッシュ領域を効率的に管理します。この戦略は特にインデックスとメタデータのアクセスパスを最適化し、頻繁にアクセスされるユーザーデータのキャッシュを最大化することを目指しています。マルチCompute
Group（Compute Group）シナリオでは、Dorisは新しいcompute
groupが確立された際に特定のデータ（テーブルやパーティションなど）をキャッシュに素早くロードするキャッシュウォーミング機能も提供し、クエリパフォーマンスを向上させます。
@@ -155,47 +155,135 @@ file_cache_exit_need_evict_cache_in_advance_percent
Default: "85"
## Cache Query Limit
-> この機能はバージョン4.0.3以降でサポートされています。
+Doris には、クエリ単位で File Cache
を制御する独立した2つの方式があります。クエリがすでに占有しているキャッシュ容量を制限するのか、後続のキャッシュ書き込みを停止するのかに応じてパラメータを選択してください。
+
+| 制御方式 | 主なパラメータ | 制限到達後の動作 | 適用シナリオ |
+|---|---|---|---|
+| キャッシュ占有率による制限 | `file_cache_query_limit_percent` |
新しいキャッシュブロックの書き込みは継続できます。BE
はまず現在のクエリに記録された解放可能なブロックを削除し、必要に応じて他のキャッシュキューからも削除します |
後続のキャッシュ書き込みを許可しながら、単一クエリのキャッシュ占有量を制限する |
+| リモートスキャンの書き込みをバイト閾値で停止 | `file_cache_query_limit_bytes` |
次のキャッシュブロックによって許可済みバイト数が閾値を超える場合、その BE 上でクエリは remote-only-on-miss
状態になります。以降のキャッシュミスはリモートストレージから読み取られ、File Cache には書き込まれません |
大規模なリモートスキャンによるキャッシュ書き込みとキャッシュの入れ替わりを抑制する |
-Cache Query
Limit機能により、ユーザーは単一のクエリが使用できるファイルキャッシュのパーセンテージを制限することができます。複数のユーザーや複雑なクエリがキャッシュリソースを共有するシナリオでは、単一の大きなクエリが過剰なキャッシュ領域を占有し、他のクエリのホットデータが退避される原因となる可能性があります。クエリ制限を設定することで、公平なリソース使用を確保し、キャッシュスラッシングを防ぐことができます。
+### キャッシュ占有率による制限
-クエリによって占有されるキャッシュ領域とは、キャッシュミスによりキャッシュに投入されたデータの合計サイズを指します。クエリによって投入された合計サイズがクォータ制限に達した場合、そのクエリによって後続に投入されるデータは、LRUアルゴリズムに基づいて以前に投入されたデータを置き換えます。
+> この機能はバージョン4.0.3以降でサポートされています。
-### 設定
+キャッシュ占有率による制限は、単一クエリが各 File Cache
インスタンスで使用できる最大割合を制御します。複数のユーザーや複雑なクエリがキャッシュリソースを共有する場合に、1つの大規模クエリが過剰なキャッシュを保持して他のホットデータを削除するリスクを軽減します。
-この機能は、BEとFEでの設定、およびセッション変数の設定を含みます。
+この機能には、BE設定、FE設定、およびセッション変数の3つの設定が関係します。
-**1. BE設定**
+**BE設定**
-- `enable_file_cache_query_limit`:
- - 型: Boolean
- - デフォルト: `false`
- - 説明: BE側でのfile cache query
limit機能のマスタースイッチです。有効にした場合のみ、BEはFEから渡されるクエリ制限パラメータを処理します。
+| パラメータ | 型 | デフォルト値 | 説明 |
+|---|---|---|---|
+| `enable_file_cache_query_limit` | Boolean | `false` |
BE側のキャッシュクエリ制限のマスタースイッチです。有効な場合のみ、BEはFEから渡されたクエリ制限パラメータを処理します |
-**2. FE設定**
+**FE設定**
-- `file_cache_query_limit_max_percent`:
- - 型: Integer
- - デフォルト: `100`
- - 説明: セッション変数の上限を検証するために使用される最大クエリ制限制約です。ユーザーが設定するクエリ制限がこの値を超えないことを保証します。
+| パラメータ | 型 | デフォルト値 | 説明 |
+|---|---|---|---|
+| `file_cache_query_limit_max_percent` | Integer | `100` |
クエリクォータの最大値です。セッション変数の上限を検証するために使用されます |
-**3. セッション変数**
+**セッション変数**
-- `file_cache_query_limit_percent`:
- - 型: Integer (1-100)
- - 説明:
ファイルキャッシュクエリ制限パーセンテージです。クエリが使用できるキャッシュの最大パーセンテージを設定します。この値は`file_cache_query_limit_max_percent`によって制約されます。計算されたキャッシュクォータが256MB未満にならないことが推奨されます。この値を下回る場合、BEはログに警告を出力します。
+| 変数 | 型 | デフォルト値 | 説明 |
+|---|---|---|---|
+| `file_cache_query_limit_percent` | Integer | `-1` | 明示的に設定する場合、値は `[1,
file_cache_query_limit_max_percent]`
の範囲内である必要があります。単一クエリが使用できるキャッシュの最大割合を指定します。算出されたキャッシュクォータは256
MB以上を推奨します。これより小さい場合、BEはログに警告を出力します |
+
+この制御を使用する前に、BEで `enable_file_cache` と `enable_file_cache_query_limit`
の両方を有効にし、クエリセッションの `enable_file_cache` が `true` であることを確認してください。
**使用例**
```sql
--- Set session variable to limit a query to use at most 50% of the cache
+-- 単一クエリが使用できるキャッシュを最大50%に制限する
SET file_cache_query_limit_percent = 50;
--- Execute query
+-- クエリを実行する
SELECT * FROM large_table;
```
-**注意:**
-1. 値は [0, `file_cache_query_limit_max_percent`] の範囲内である必要があります。
+
+後続のキャッシュミスも File Cache
に書き込むことができます。クエリのキャッシュ占有量がクォータを超えると、BEはクエリ単位のLRU記録と他のキャッシュキューを使用して領域を解放します。この制御によって、クエリが「以降はキャッシュへ書き込まない」モードに切り替わることはありません。
+
+### リモートスキャンのキャッシュ書き込みをバイト閾値で停止する
+
+> この機能は Doris 4.1.x でのみサポートされます。Doris 4.0.x ではサポートされません。
+
+`file_cache_query_limit_bytes` は、単一の SELECT クエリについて、リモートスキャンのキャッシュミスにより
read-through で File Cache へ書き込むことを許可された累積バイト数を、**各 BE**
で制限します。この機能は、ストレージ・コンピューティング分離モードでBEの `enable_file_cache=true`
の場合にのみ有効です。`enable_file_cache_query_limit` または
`file_cache_query_limit_max_percent` には依存しません。
+
+同一クエリの並列Scannerは、1つのBE上で同じ閾値を共有します。ただし、この閾値はクエリ全体またはクラスタ全体の合計値ではありません。たとえば、10台のBEで実行するクエリに1
GiBを設定した場合、全BEの合計が1 GiBになるのではなく、各BEがそれぞれ約1 GiBまで許可できます。
+
+**パラメータ**
+
+| パラメータ | 設定場所 | 型 | デフォルト値 | 必須 | 説明 |
+|---|---|---|---|---|---|
+| `file_cache_query_limit_bytes` | セッション変数 | BigInt | `-1` | はい |
単一クエリについて、各BEで許可するリモートスキャンのキャッシュ書き込み閾値です。単位はバイトです。`0`未満では無効、`0`ではクエリ開始時からキャッシュへ書き込まず、正の値ではキャッシュブロック単位で許可済みバイト数を累積します
|
+| `enable_file_cache_query_limit_segment_meta` | BE設定 | Boolean | `false` |
いいえ | Segment
footerとSegmentメタデータのキャッシュ書き込みを同じバイト閾値に含めるかどうかを指定します。このパラメータは動的に変更できます。この制御が有効な場合、データページと転置インデックスの書き込みは常にバイト閾値の対象です
|
+
+`file_cache_query_limit_bytes` の値による動作は次のとおりです。
+
+| 値 | 動作 |
+|---|---|
+| `< 0` | この制御を無効にし、従来のキャッシュミス時の書き込み動作を維持します |
+| `= 0` |
クエリ開始時から各BEでremote-only-on-miss状態になります。要求範囲がローカルキャッシュで完全にカバーされている場合はローカルから読み取れます。完全にカバーされていない範囲はリモートストレージから直接読み取り、キャッシュへ書き込みません
|
+| `> 0` |
累積の許可済みバイト数が閾値を超えないキャッシュブロックの書き込みを許可します。次のブロックで閾値を超える場合、そのブロックを拒否し、そのBE上の同一クエリによる後続のキャッシュミスはキャッシュへ書き込みません
|
+
+許可判定はキャッシュブロック単位で行われるため、実際の書き込み量が閾値と完全に一致するとは限りません。残りの容量が次のキャッシュブロックより小さい場合、そのブロック全体がスキップされ、残りの容量が後続の小さいブロックに使用されることはありません。クエリがBE上でremote-only-on-miss状態になると、そのBEではキャッシュ書き込みを再開しません。
+
+**リモートスキャンのキャッシュ書き込み量を制限する**
+
+次の例では、`large_table` がストレージ・コンピューティング分離クラスタにあり、すべてのBEでFile
Cacheが有効であることを前提とします。各BEで最大1 GiBのリモートスキャンキャッシュブロックを許可します。
+
+```sql
+SET enable_profile = true;
+SET profile_level = 2;
+SET file_cache_query_limit_bytes = 1073741824;
+
+SELECT COUNT(*) FROM large_table;
+```
+
+クエリ結果は変わりません。あるBEで次のキャッシュブロックによって許可済みバイト数が1
GiBを超える場合、そのBE上の同一クエリによる後続のキャッシュミスはリモートデータを読み取り、ローカルキャッシュへ追加で書き込みません。
+
+一時的なスキャンで最初からFile Cacheへ書き込みたくない場合は閾値を `0` に設定し、クエリ終了後にデフォルト値へ戻します。
+
+```sql
+SET file_cache_query_limit_bytes = 0;
+SELECT COUNT(*) FROM large_table;
+
+SET file_cache_query_limit_bytes = -1;
+```
+
+**Segmentメタデータを含めるかどうか**
+
+デフォルトでは、データページと転置インデックスのキャッシュ書き込みは閾値に含まれますが、Segment
footerとSegmentメタデータは含まれません。そのため、クエリがremote-only-on-miss状態になった後もSegment
footerとメタデータがFile Cacheへ書き込まれる可能性があり、Profileに表示される合計書き込み量が
`file_cache_query_limit_bytes` を超えることがあります。
+
+Segment footerとメタデータの書き込みも停止するには、同じCompute GroupのすべてのBEで次を設定します。
+
+```properties
+enable_file_cache_query_limit_segment_meta=true
+```
+
+このパラメータはBEの動的設定APIから即時に変更できます。再起動後も維持するには、`be.conf`
に追加するか、永続化オプション付きの動的設定を使用します。詳細は[BE設定](../../admin-manual/config/be-config.md)を参照してください。
+
+**Query Profileで確認する**
+
+Query Profileを有効にした後、Scanner配下の `FileCache` メトリックグループを確認します。
+
+| メトリック | 説明 |
+|---|---|
+| `RemoteOnlyOnMissTriggered` | 値が `1`
の場合、そのScannerがクエリのremote-only-on-miss状態への移行を確認したことを示します |
+| `RemoteOnlyOnMissThresholdBytes` | クエリに設定されたバイト閾値 |
+| `BytesWriteIntoCache` | File Cacheへ実際に書き込まれた合計バイト数 |
+| `InvertedIndexBytesWriteIntoCache` | File Cacheへ実際に書き込まれた転置インデックスのバイト数 |
+| `SegmentFooterIndexBytesWriteIntoCache` | File Cacheへ実際に書き込まれたSegment
footerとメタデータのバイト数 |
+| `NumSkipCacheIOTotal` |
キャッシュをスキップしたI/O回数です。他のキャッシュポリシーによってスキップされたI/Oも含まれるため、`RemoteOnlyOnMissTriggered`
と合わせて判断してください |
+
+許可済みバイト数が閾値と完全に一致し、クエリ終了までに閾値を超える新しいキャッシュブロックがない場合、`RemoteOnlyOnMissTriggered`
は `0` のままになることがあります。状態は、後続のブロックによって閾値を超える場合にのみ切り替わります。
+
+**推奨事項と注意事項**
+
+- 一時的なフルスキャン、再利用率の低いETL、またはアドホッククエリでは、小さい正の閾値または `0`
を使用してクエリ開始時からキャッシュへの書き込みを停止し、コールドデータによるホットデータの置き換えを防ぎます。
+- このパラメータが制限するのは、クエリ読み取り時のキャッシュミス後に行われるFile
Cacheへの書き込みです。リモート読み取り量を制限したり、クエリを終了したりするものではなく、ロード、Compaction、Schema
Change、または明示的なキャッシュウォームアップによる書き込みにも影響しません。
+-
remote-only-on-miss状態でも、要求範囲がローカルキャッシュで完全にカバーされている場合はローカルから読み取れます。完全にカバーされていない範囲はリモートストレージへ直接アクセスするため、オブジェクトストレージI/Oとクエリレイテンシが増加する可能性があります。
+- クエリが保持するキャッシュ占有率を制限しながら、後続のキャッシュミスによる書き込みを許可する場合は
`file_cache_query_limit_percent` を使用します。一定量を許可した後の書き込みを停止する場合は
`file_cache_query_limit_bytes` を使用します。
+- Segment
footerとメタデータをデフォルトで対象外にすることで、再利用率の高いメタデータのキャッシュ効果を維持できます。閾値到達後にこれらの書き込みも停止する必要がある場合のみ
`enable_file_cache_query_limit_segment_meta` を有効にし、Query Profileで結果を確認してください。
## Cache Warm Up
diff --git
a/ja-source/docusaurus-plugin-content-docs/version-4.x/lakehouse/data-cache.md
b/ja-source/docusaurus-plugin-content-docs/version-4.x/lakehouse/data-cache.md
index bfcc35be44d..bb4b132f016 100644
---
a/ja-source/docusaurus-plugin-content-docs/version-4.x/lakehouse/data-cache.md
+++
b/ja-source/docusaurus-plugin-content-docs/version-4.x/lakehouse/data-cache.md
@@ -2,7 +2,7 @@
{
"title": "データキャッシュ",
"language": "ja",
- "description":
"データキャッシュは、リモートストレージシステム（HDFSまたはオブジェクト）から最近アクセスされたデータファイルをキャッシュすることにより、同じデータの後続のクエリを高速化します。"
+ "description":
"データキャッシュは、HDFSまたはオブジェクトストレージのデータをローカルにキャッシュしてLakehouseクエリを高速化し、ウォームアップ、クエリ単位のキャッシュ書き込み制限、およびキャッシュアドミッション制御をサポートします。"
}
---
Data
Cacheは、リモートストレージシステム（HDFSまたはオブジェクトストレージ）から最近アクセスされたデータファイルをローカルディスクにキャッシュすることで、同じデータの後続クエリを高速化します。同じデータに頻繁にアクセスするシナリオでは、Data
Cacheは繰り返されるリモートデータアクセスのオーバーヘッドを回避し、ホットデータのクエリ分析のパフォーマンスと安定性を向上させることができます。
@@ -104,47 +104,98 @@ SET GLOBAL enable_file_cache = true;
## Cache Query Limit
-> この機能はバージョン4.0.3以降でサポートされています。
+Doris には、クエリ単位でData Cacheを制御する独立した2つの方式があります。
+
+| 制御方式 | 主なパラメータ | 制限到達後の動作 |
+|---|---|---|
+| キャッシュ占有率による制限 | `file_cache_query_limit_percent` |
キャッシュミス時の書き込みを継続しながら、BEはクエリ単位のLRU記録と他のキャッシュキューを使用して領域を解放します |
+| リモートスキャンの書き込みをバイト閾値で停止 | `file_cache_query_limit_bytes` |
次のキャッシュブロックによって許可済みバイト数が閾値を超える場合、後続のキャッシュミスはリモートストレージから読み取られ、ローカルキャッシュには書き込まれません
|
-Cache Query
Limit機能により、ユーザーは単一のクエリが使用できるファイルキャッシュの割合を制限できます。複数のユーザーや複雑なクエリがキャッシュリソースを共有するシナリオでは、単一の大きなクエリが過度にキャッシュ領域を占有し、他のクエリのホットデータが追い出される可能性があります。クエリ制限を設定することで、公正なリソース使用を確保し、キャッシュスラッシングを防ぐことができます。
+### キャッシュ占有率による制限
-クエリが占有するキャッシュ領域とは、キャッシュミスによりキャッシュに投入されたデータの総サイズを指します。クエリによって投入された総サイズがクォータ制限に達した場合、そのクエリによって後続に投入されるデータは、LRUアルゴリズムに基づいて以前に投入されたデータを置き換えます。
+> この機能はバージョン4.0.3以降でサポートされています。
-### 設定
+キャッシュ占有率による制限は、単一クエリが各File
Cacheインスタンスで使用できる最大割合を制御します。複数のユーザーや複雑なクエリがキャッシュリソースを共有する場合に、1つの大規模クエリが過剰なキャッシュを保持して他のホットデータを削除するリスクを軽減します。
-この機能には、BEとFEでの設定、およびセッション変数の設定が含まれます。
+この機能には、BE設定、FE設定、およびセッション変数が関係します。
**1. BE設定**
- `enable_file_cache_query_limit`:
- - タイプ: Boolean
- - デフォルト: `false`
- - 説明: BE側のファイルキャッシュクエリ制限機能のマスタースイッチ。有効にした場合のみ、BEはFEから渡されたクエリ制限パラメーターを処理します。
+ - 型: Boolean
+ - デフォルト値: `false`
+ - 説明: BE側のFile Cacheクエリ制限のマスタースイッチです。有効な場合のみ、BEはFEから渡されたクエリ制限パラメータを処理します。
**2. FE設定**
- `file_cache_query_limit_max_percent`:
- - タイプ: Integer
- - デフォルト: `100`
- - 説明: セッション変数の上限を検証するために使用される最大クエリ制限制約。ユーザーが設定したクエリ制限がこの値を超えないことを保証します。
+ - 型: Integer
+ - デフォルト値: `100`
+ - 説明: セッション変数の上限を検証するために使用されるクエリ制限の最大値です。
**3. セッション変数**
- `file_cache_query_limit_percent`:
- - タイプ: Integer (1-100)
- - 説明:
ファイルキャッシュクエリ制限割合。クエリが使用できるキャッシュの最大割合を設定します。この値は`file_cache_query_limit_max_percent`によって制約されます。計算されたキャッシュクォータが256MB未満にならないことを推奨します。この値より低い場合、BEはログに警告を出力します。
+ - 型: Integer (1-100)
+ - デフォルト値: `-1`
+ - 説明: クエリが使用できるキャッシュの最大割合です。この値は `file_cache_query_limit_max_percent`
によって制約されます。算出されたキャッシュクォータは256 MB以上を推奨します。これより小さい場合、BEはログに警告を出力します。
**使用例**
```sql
--- Set session variable to limit a query to use at most 50% of the cache
+-- 単一クエリが使用できるキャッシュを最大50%に制限する
SET file_cache_query_limit_percent = 50;
--- Execute query
+-- クエリを実行する
SELECT * FROM large_table;
```
-**注意:**
-1. 値は [0, `file_cache_query_limit_max_percent`] の範囲内である必要があります。
+
+**注意事項:**
+
+1. 値は `[1, file_cache_query_limit_max_percent]` の範囲内である必要があります。
+2. この制御を使用する前に、BEで `enable_file_cache` と `enable_file_cache_query_limit`
の両方を有効にし、クエリセッションの `enable_file_cache` が `true` であることを確認してください。
+3. キャッシュ占有率の上限に達した後も、キャッシュミスはData
Cacheへ書き込むことができます。この制御によって、クエリが「以降はキャッシュへ書き込まない」モードに切り替わることはありません。
+
+### リモートスキャンのキャッシュ書き込みをバイト閾値で停止する
+
+> この機能は Doris 4.1.x でのみサポートされます。Doris 4.0.x ではサポートされません。
+
+ストレージ・コンピューティング分離モードでは、セッション変数 `file_cache_query_limit_bytes`
により、Hive、Iceberg、Hudi、またはPaimonのデータファイルのキャッシュミスによってData
Cacheへの書き込みを許可された累積バイト数を、単一のSELECTクエリについて**各BE**で制限できます。この機能にはBEの
`enable_file_cache=true` が必要ですが、`enable_file_cache_query_limit` または
`file_cache_query_limit_max_percent` には依存しません。
+
+| パラメータ | 型 | デフォルト値 | 説明 |
+|---|---|---|---|
+| `file_cache_query_limit_bytes` | BigInt | `-1` |
単一クエリについて、各BEで許可するリモートスキャンのキャッシュ書き込み閾値です。単位はバイトです。`0`未満では無効、`0`ではクエリ開始時からキャッシュへ書き込まず、正の値ではキャッシュブロック単位で許可済みバイト数を累積します
|
+
+同一クエリの並列Scannerは、1つのBE上で同じ閾値を共有します。この閾値はクエリ全体またはクラスタ全体の合計値ではありません。次のキャッシュブロックによって許可済みバイト数が閾値を超える場合、そのBE上でクエリはremote-only-on-miss状態になります。要求範囲がローカルキャッシュで完全にカバーされている場合はローカルから読み取れます。完全にカバーされていない範囲はリモートストレージから直接読み取り、Data
Cacheへ書き込みません。クエリ結果は変わりません。
+
+次の例では、各BEのリモートスキャンキャッシュ書き込み閾値を1 GiBに設定します。
+
+```sql
+SET enable_profile = true;
+SET profile_level = 2;
+SET file_cache_query_limit_bytes = 1073741824;
+
+SELECT COUNT(*) FROM hive_catalog.sales.orders;
+```
+
+一時的なスキャンで最初からData Cacheへ書き込みたくない場合は閾値を `0` に設定し、クエリ終了後にデフォルト値へ戻します。
+
+```sql
+SET file_cache_query_limit_bytes = 0;
+SELECT COUNT(*) FROM hive_catalog.sales.orders;
+
+SET file_cache_query_limit_bytes = -1;
+```
+
+Query Profileを有効にした後、Scannerの `FileCache` メトリックグループで
`RemoteOnlyOnMissTriggered` と `RemoteOnlyOnMissThresholdBytes`
を確認します。`RemoteOnlyOnMissTriggered=1`
の場合、そのScannerがクエリのremote-only-on-miss状態への移行を確認したことを示します。`BytesWriteIntoCache` と
`NumSkipCacheIOTotal`
を使用して、実際の書き込みとキャッシュをスキップしたI/Oを確認できます。`NumSkipCacheIOTotal`
には他のキャッシュポリシーによってスキップされたI/Oも含まれるため、この値だけでは閾値が発動したことを判断できません。
+
+:::note
+
+- この制御は、ストレージ・コンピューティング分離モードのSELECTクエリで、キャッシュミス後にData
Cacheへ書き込む動作のみを制限します。リモート読み取り量を制限せず、明示的なキャッシュウォームアップにも影響しません。remote-only-on-miss状態では、リモートI/Oとクエリレイテンシが増加する可能性があります。
+-
許可判定はキャッシュブロック単位で行われます。残りの容量が次のブロックより小さい場合、そのブロック全体がスキップされます。`RemoteOnlyOnMissTriggered`
は、あるブロックによって閾値を超える場合にのみ `1` になります。
+- BEパラメータ `enable_file_cache_query_limit_segment_meta` は、Doris内部テーブルのSegment
footerとSegmentメタデータの書き込みを同じ閾値に含めるかどうかを制御します。Hive、Iceberg、Hudi、およびPaimonのデータファイルのキャッシュ書き込みは常に
`file_cache_query_limit_bytes`
の対象です。パラメータの完全な適用範囲と内部テーブルの動作については、[ファイルキャッシュの設定と使用ガイド](../compute-storage-decoupled/file-cache/file-cache.md)を参照してください。
+
+:::
## Cache Warmup
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 5f27b1ed124..fcc05a0522b 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
@@ -3,8 +3,8 @@
"title": "File Cache Configuration and Usage Guide (Compute-Storage
Decoupled)",
"sidebar_label": "File Cache Configuration",
"language": "en",
- "description": "Covers file cache configuration, index-only cache writes,
quota management, cache warmup and eviction, hit-rate monitoring, and TTL
policies for Doris in compute-storage decoupled mode to improve query
performance and reduce object storage costs.",
- "keywords": ["Doris file cache", "compute-storage decoupled cache", "file
cache", "index-only cache writes", "cache warmup", "cache quota", "TTL cache",
"LRU", "cache hit rate", "object storage acceleration"]
+ "description": "Covers file cache configuration, index-only cache writes,
query-level cache controls, cache warmup and eviction, hit-rate monitoring, and
TTL policies for Doris in compute-storage decoupled mode to improve query
performance and reduce object storage costs.",
+ "keywords": ["Doris file cache", "compute-storage decoupled cache", "file
cache", "index-only cache writes", "cache warmup", "cache quota",
"file_cache_query_limit_bytes", "TTL cache", "LRU", "cache hit rate", "object
storage acceleration"]
}
---
@@ -174,13 +174,18 @@ Proactive eviction actively frees space when cache
utilization reaches a thresho
<!-- Knowledge type: Configuration parameters -->
<!-- Applicable scenarios: Multi-user shared cache / Preventing large-query
cache thrashing -->
-> This feature is supported starting from version 4.0.3.
+Doris provides two independent query-level File Cache controls. Choose the
parameter according to whether you need to control the cache footprint already
held by a query or stop later cache fills:
+
+| Control | Primary parameter | Behavior after the limit | Use case |
+|---|---|---|---|
+| Limit by cache footprint percentage | `file_cache_query_limit_percent` | New
cache blocks can still be written. BE first evicts releasable blocks recorded
for the current query and then evicts from other cache queues when necessary |
Limit a query's cache footprint while allowing later cache fills |
+| Stop remote-scan cache writes by byte threshold |
`file_cache_query_limit_bytes` | When the next cache block would make the
admitted byte count exceed the threshold, the query enters remote-only-on-miss
mode on that BE. Later misses are read from remote storage without further File
Cache writes | Limit cache writes and churn caused by a large remote scan |
-The **Cache Query Limit** feature allows you to limit the proportion of the
file cache that a single query can fill. In scenarios where multiple users or
complex queries share cache resources, a single large query may occupy too much
cache and evict hot data belonging to other queries. Setting a query quota
ensures fair use of resources and prevents cache thrashing.
+### Limit by Cache Footprint Percentage
-The cache space occupied by a query refers to the total size of data that the
query fills into the cache due to cache misses. If the total fill reaches the
quota ceiling, subsequent data written by the query replaces data that the same
query wrote earlier, based on the LRU algorithm.
+> This feature is supported starting from version 4.0.3.
-### Configuration
+The cache-footprint percentage limit controls the maximum percentage of each
File Cache instance that a single query can use. When multiple users or complex
queries share cache resources, it reduces the risk that one large query retains
too much cache and evicts other hot data.
This feature involves three levels of configuration: BE configuration, FE
configuration, and session variables.
@@ -198,11 +203,13 @@ This feature involves three levels of configuration: BE
configuration, FE config
**Session Variables**
-| Variable | Type | Description |
-|---|---|---|
-| `file_cache_query_limit_percent` | Integer (1-100) | Maximum percentage of
cache that a single query may use. The upper bound is governed by
`file_cache_query_limit_max_percent`. The calculated cache quota should not be
lower than 256 MB; if it is, BE outputs a warning in the log |
+| Variable | Type | Default | Description |
+|---|---|---|---|
+| `file_cache_query_limit_percent` | Integer | `-1` | When explicitly set, the
value must be in `[1, file_cache_query_limit_max_percent]`. It specifies the
maximum percentage of cache that a single query may use. The calculated quota
should not be lower than 256 MB; otherwise, BE writes a warning to the log |
-### Usage Example
+Before using this control, enable both `enable_file_cache` and
`enable_file_cache_query_limit` on the BE, and ensure that `enable_file_cache`
is `true` in the query session.
+
+**Usage Example**
```sql
-- Limit a single query to using at most 50% of the cache
@@ -212,7 +219,90 @@ SET file_cache_query_limit_percent = 50;
SELECT * FROM large_table;
```
-> **Note:** The value must be within the range `[0,
file_cache_query_limit_max_percent]`.
+Later cache misses remain eligible for File Cache writes. When the query's
cache footprint exceeds the quota, BE releases space through the query-level
LRU record and other cache queues. This control does not switch the query into
a no-more-write mode.
+
+### Stop Remote-Scan Cache Writes by Byte Threshold
+
+> This feature is supported only in Doris 4.1.x. It is not supported in Doris
4.0.x.
+
+`file_cache_query_limit_bytes` limits the cumulative bytes admitted for
read-through File Cache writes caused by remote-scan cache misses for one
SELECT query on **each BE**. It takes effect only in compute-storage decoupled
mode when `enable_file_cache=true` on the BE. It does not depend on
`enable_file_cache_query_limit` or `file_cache_query_limit_max_percent`.
+
+Parallel scanners for the same query share one threshold on a BE, but the
threshold is not a query-wide or cluster-wide total. For example, if a query
runs on 10 BEs with a 1 GiB threshold, each BE can admit approximately 1 GiB
independently; the limit is not 1 GiB across all BEs.
+
+**Parameters**
+
+| Parameter | Location | Type | Default | Required | Description |
+|---|---|---|---|---|---|
+| `file_cache_query_limit_bytes` | Session Variable | BigInt | `-1` | Yes |
Remote-scan cache-fill threshold for one query on each BE, in bytes. A value
below `0` disables the control; `0` disables cache fills from the start of the
query; a positive value accumulates admitted bytes by cache block |
+| `enable_file_cache_query_limit_segment_meta` | BE configuration | Boolean |
`false` | No | Whether Segment footer and Segment metadata cache writes count
toward the same byte threshold. This parameter is dynamically configurable.
Data-page and inverted-index writes are subject to the byte threshold whenever
this control is active |
+
+`file_cache_query_limit_bytes` has the following behavior:
+
+| Value | Behavior |
+|---|---|
+| `< 0` | Disables this control and preserves the original cache-miss fill
behavior |
+| `= 0` | Places the query in remote-only-on-miss mode on every BE from the
start. A request range fully covered by local cache can still be read locally;
a range that is not fully covered is read directly from remote storage without
a cache fill |
+| `> 0` | Allows cache blocks while their cumulative admitted bytes do not
exceed the threshold. When the next block would exceed it, that block is
rejected and later misses for the query on that BE no longer fill the cache |
+
+Admission is evaluated by cache block, so actual writes are not guaranteed to
equal the threshold. If the remaining budget is smaller than the next cache
block, the entire block is skipped, and the remaining budget is not used for
smaller later blocks. After the query enters remote-only-on-miss mode on a BE,
cache filling does not resume there.
+
+**Limit Remote-Scan Cache Fills**
+
+The following example assumes that `large_table` is in a compute-storage
decoupled cluster and File Cache is enabled on every BE. It allows up to 1 GiB
of remote-scan cache blocks to be admitted on each BE:
+
+```sql
+SET enable_profile = true;
+SET profile_level = 2;
+SET file_cache_query_limit_bytes = 1073741824;
+
+SELECT COUNT(*) FROM large_table;
+```
+
+The query result is unchanged. When the next cache block on a BE would make
admitted bytes exceed 1 GiB, later cache misses for that query on the same BE
read remote data without additional local cache writes.
+
+To prevent a one-time scan from filling File Cache from the start, set the
threshold to `0`, and restore the default after the query:
+
+```sql
+SET file_cache_query_limit_bytes = 0;
+SELECT COUNT(*) FROM large_table;
+
+SET file_cache_query_limit_bytes = -1;
+```
+
+**Whether Segment Metadata Is Counted**
+
+By default, data-page and inverted-index cache writes count toward the
threshold, while Segment footer and Segment metadata writes do not. Segment
footer and metadata may therefore still be written after the query enters
remote-only-on-miss mode, and the total write volume shown in the Profile may
exceed `file_cache_query_limit_bytes`.
+
+To stop Segment footer and metadata fills as well, set the following
configuration on every BE in the same compute group:
+
+```properties
+enable_file_cache_query_limit_segment_meta=true
+```
+
+This parameter can be changed immediately through the BE dynamic configuration
API. To retain it across restarts, add it to `be.conf` or use persistent
dynamic configuration. For details, see [BE
Configuration](../../admin-manual/config/be-config.md).
+
+**Verify with Query Profile**
+
+After enabling Query Profile, inspect the `FileCache` metric group under the
Scanner:
+
+| Metric | Description |
+|---|---|
+| `RemoteOnlyOnMissTriggered` | A value of `1` means that the Scanner observed
the query entering remote-only-on-miss mode |
+| `RemoteOnlyOnMissThresholdBytes` | Byte threshold configured for the query |
+| `BytesWriteIntoCache` | Total bytes actually written to File Cache |
+| `InvertedIndexBytesWriteIntoCache` | Inverted-index bytes actually written
to File Cache |
+| `SegmentFooterIndexBytesWriteIntoCache` | Segment footer and metadata bytes
actually written to File Cache |
+| `NumSkipCacheIOTotal` | Number of I/O operations that skipped the cache.
This metric can also include I/O skipped by other cache policies, so evaluate
it together with `RemoteOnlyOnMissTriggered` |
+
+If admitted bytes equal the threshold exactly and no later cache block
attempts to exceed it before the query finishes, `RemoteOnlyOnMissTriggered`
can remain `0`. The state changes only when a subsequent block would exceed the
threshold.
+
+**Recommendations and Caveats**
+
+- For one-time full scans, low-reuse ETL, or ad hoc queries, use a small
positive threshold or `0` to disable cache fills from the start and avoid
replacing hot data with cold data.
+- This parameter limits File Cache fills after query-read misses. It does not
limit remote bytes read, terminate the query, or affect cache writes produced
by ingestion, Compaction, Schema Change, or explicit cache warmup.
+- In remote-only-on-miss mode, request ranges fully covered by local cache can
still be read locally. Ranges that are not fully covered access remote storage
directly, which may increase object-storage I/O and query latency.
+- Use `file_cache_query_limit_percent` when the goal is to limit the cache
footprint retained by a query while allowing later cache misses to fill the
cache. Use `file_cache_query_limit_bytes` when the goal is to stop later fills
after a specified amount has been admitted.
+- Excluding Segment footer and metadata by default preserves the cache benefit
of highly reusable metadata. Enable
`enable_file_cache_query_limit_segment_meta` only when those writes must also
stop after the threshold, and verify the result with Query Profile.
## Cache Warmup
diff --git a/versioned_docs/version-4.x/lakehouse/data-cache.md
b/versioned_docs/version-4.x/lakehouse/data-cache.md
index c7772bf552a..0ba7f6195f4 100644
--- a/versioned_docs/version-4.x/lakehouse/data-cache.md
+++ b/versioned_docs/version-4.x/lakehouse/data-cache.md
@@ -2,7 +2,7 @@
{
"title": "Data Cache",
"language": "en",
- "description": "Apache Doris Data Cache accelerates Lakehouse queries by
caching HDFS and object storage data locally. Supports cache warmup, quota
control, and admission control for Hive, Iceberg, Hudi, and Paimon tables."
+ "description": "Apache Doris Data Cache accelerates Lakehouse queries by
caching HDFS and object storage data locally. Supports cache warmup,
query-level cache-fill controls, and admission control for Hive, Iceberg, Hudi,
and Paimon tables."
}
---
@@ -109,13 +109,18 @@ Users can view cache statistics for each Backend node
through the system table [
## Cache Query Limit
-> This feature is supported since version 4.0.3.
+Doris provides two independent query-level Data Cache controls:
+
+| Control | Primary parameter | Behavior after the limit |
+|---|---|---|
+| Limit by cache footprint percentage | `file_cache_query_limit_percent` |
Cache-miss fills remain allowed, while BE releases space through the
query-level LRU record and other cache queues |
+| Stop remote-scan cache writes by byte threshold |
`file_cache_query_limit_bytes` | When the next cache block would make admitted
bytes exceed the threshold, later misses are read from remote storage without
filling the local cache |
-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.
+### Limit by Cache Footprint Percentage
-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.
+> This feature is supported since version 4.0.3.
-### Configuration
+The cache-footprint percentage limit controls the maximum percentage of each
File Cache instance that a single query can use. When multiple users or complex
queries share cache resources, it reduces the risk that one large query retains
too much cache and evicts other hot data.
This feature involves configuration on BE and FE, as well as session variable
settings.
@@ -131,26 +136,71 @@ This feature involves configuration on BE and FE, as well
as session variable se
- `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.
+ - Description: The maximum query limit constraint used to validate the upper
bound of the session variable.
**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.
+ - Default: `-1`
+ - Description: The maximum percentage of cache that a query can use. This
value is constrained by `file_cache_query_limit_max_percent`. The calculated
cache quota should be at least 256 MB; otherwise, BE writes a warning to the
log.
**Usage Example**
```sql
--- Set session variable to limit a query to use at most 50% of the cache
+-- Set the session variable to limit a query to at most 50% of the cache
SET file_cache_query_limit_percent = 50;
--- Execute query
+-- Execute the query
SELECT * FROM large_table;
```
-**Note:**
-1. The value must be within the range [0,
`file_cache_query_limit_max_percent`].
+**Notes:**
+
+1. The value must be in `[1, file_cache_query_limit_max_percent]`.
+2. Before using this control, enable both `enable_file_cache` and
`enable_file_cache_query_limit` on the BE, and ensure that `enable_file_cache`
is `true` in the query session.
+3. Cache misses remain eligible for Data Cache writes after the percentage
quota is reached. This control does not switch the query into a no-more-write
mode.
+
+### Stop Remote-Scan Cache Writes by Byte Threshold
+
+> This feature is supported only in Doris 4.1.x. It is not supported in Doris
4.0.x.
+
+In compute-storage decoupled mode, the `file_cache_query_limit_bytes` session
variable limits cumulative bytes admitted for Data Cache fills caused by Hive,
Iceberg, Hudi, or Paimon data-file cache misses for one SELECT query on **each
BE**. It requires `enable_file_cache=true` on the BE but does not depend on
`enable_file_cache_query_limit` or `file_cache_query_limit_max_percent`.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `file_cache_query_limit_bytes` | BigInt | `-1` | Remote-scan cache-fill
threshold for one query on each BE, in bytes. A value below `0` disables the
control; `0` disables cache fills from the start of the query; a positive value
accumulates admitted bytes by cache block |
+
+Parallel scanners for the same query share one threshold on a BE. The
threshold is not a query-wide or cluster-wide total. When the next cache block
would make admitted bytes exceed the threshold, the query enters
remote-only-on-miss mode on that BE: a request range fully covered by local
cache can still be read locally; a range that is not fully covered is read
directly from remote storage without filling Data Cache. The query result is
unchanged.
+
+The following example sets a 1 GiB remote-scan cache-fill threshold on each BE:
+
+```sql
+SET enable_profile = true;
+SET profile_level = 2;
+SET file_cache_query_limit_bytes = 1073741824;
+
+SELECT COUNT(*) FROM hive_catalog.sales.orders;
+```
+
+To prevent a one-time scan from writing Data Cache from the start, set the
threshold to `0`, and restore the default after the query:
+
+```sql
+SET file_cache_query_limit_bytes = 0;
+SELECT COUNT(*) FROM hive_catalog.sales.orders;
+
+SET file_cache_query_limit_bytes = -1;
+```
+
+After enabling Query Profile, inspect `RemoteOnlyOnMissTriggered` and
`RemoteOnlyOnMissThresholdBytes` in the Scanner's `FileCache` metric group.
When `RemoteOnlyOnMissTriggered=1`, the Scanner observed the query entering
remote-only-on-miss mode. Use `BytesWriteIntoCache` and `NumSkipCacheIOTotal`
to inspect actual writes and skipped-cache I/O. Because `NumSkipCacheIOTotal`
can also include I/O skipped by other cache policies, it is not sufficient by
itself to prove that the threshold w [...]
+
+:::note
+
+- This control applies only to Data Cache fills after SELECT query misses in
compute-storage decoupled mode. It does not limit remote bytes read or affect
explicit cache warmup. Remote-only-on-miss mode may increase remote I/O and
query latency.
+- Admission is evaluated by cache block. If the remaining budget is smaller
than the next block, the entire block is skipped. `RemoteOnlyOnMissTriggered`
changes to `1` only when a block would exceed the threshold.
+- The BE parameter `enable_file_cache_query_limit_segment_meta` controls
whether Doris internal-table Segment footer and Segment metadata writes count
toward the same threshold. Cache fills for Hive, Iceberg, Hudi, and Paimon data
files are always subject to `file_cache_query_limit_bytes`. For the complete
parameter scope and internal-table behavior, see [File Cache Configuration and
Usage Guide](../compute-storage-decoupled/file-cache/file-cache.md).
+
+:::
## Cache Warmup
@@ -368,4 +418,4 @@ Key fields and decision descriptions:
### Principle
-Data caching caches accessed remote data to the local BE node. The original
data file is split into Blocks based on the accessed IO size, and Blocks are
stored in the local file `cache_path/hash(filepath).substr(0,
3)/hash(filepath)/offset`, with Block metadata saved in the BE node. When
accessing the same remote file, Doris checks whether the cache data of the file
exists in the local cache and determines which data to read from the local
Block and which data to pull from the remote bas [...]
\ No newline at end of file
+Data caching caches accessed remote data to the local BE node. The original
data file is split into Blocks based on the accessed IO size, and Blocks are
stored in the local file `cache_path/hash(filepath).substr(0,
3)/hash(filepath)/offset`, with Block metadata saved in the BE node. When
accessing the same remote file, Doris checks whether the cache data of the file
exists in the local cache and determines which data to read from the local
Block and which data to pull from the remote bas [...]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
