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 ae7e312da5d [docs](file-cache) Document index-only write policies
(#4017)
ae7e312da5d is described below
commit ae7e312da5de6f99f197f58ec86a44e614a303f7
Author: bobhan1 <[email protected]>
AuthorDate: Tue Jul 28 15:05:01 2026 +0800
[docs](file-cache) Document index-only write policies (#4017)
## Summary
- document the global `enable_file_cache_write_index_file_only` policy,
including its scope, precedence, expected behavior, configuration
example, and operational trade-offs
- document the Base and Cumulative Compaction-specific index-only
policies and clarify that they refine existing cache-write decisions
- add the related index and Segment footer/index profile metrics
- update the File Cache internals page to keep the Compaction behavior
description consistent
## Related Doris PRs
- https://github.com/apache/doris/pull/60609
- https://github.com/apache/doris/pull/64995
## Scope
This PR updates the current and 4.x File Cache documentation in English,
Chinese, and Japanese. Japanese source pages are updated under
`ja-source`.
## Validation
- `git diff --check`
- reviewed the documented configuration names, precedence, and behavior
against the current Doris master implementation and the related PR
descriptions
- verified that the added current and 4.x content is aligned across all
three languages
- Docusaurus build not run, following the request to keep this round
limited to documentation content
## Versions
- [x] dev
- [x] 4.x
- [ ] 3.x
- [ ] 2.1 or older (not covered by version/language sync gate)
## Languages
- [x] Chinese
- [x] English
- [x] 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-internals.md | 7 ++
.../file-cache/file-cache.md | 81 +++++++++++++++++++++-
.../file-cache/file-cache-internals.md | 7 ++
.../file-cache/file-cache.md | 81 +++++++++++++++++++++-
.../file-cache/file-cache-internals.md | 7 ++
.../file-cache/file-cache.md | 81 +++++++++++++++++++++-
.../file-cache/file-cache-internals.md | 7 ++
.../file-cache/file-cache.md | 79 ++++++++++++++++++++-
.../file-cache/file-cache-internals.md | 7 ++
.../file-cache/file-cache.md | 79 ++++++++++++++++++++-
.../file-cache/file-cache-internals.md | 7 ++
.../file-cache/file-cache.md | 81 +++++++++++++++++++++-
12 files changed, 514 insertions(+), 10 deletions(-)
diff --git a/docs/compute-storage-decoupled/file-cache/file-cache-internals.md
b/docs/compute-storage-decoupled/file-cache/file-cache-internals.md
index f75f3298ba4..808f116b136 100644
--- a/docs/compute-storage-decoupled/file-cache/file-cache-internals.md
+++ b/docs/compute-storage-decoupled/file-cache/file-cache-internals.md
@@ -155,6 +155,13 @@ The two types of Compaction use different cache write
strategies:
| Cumulative Compaction | Output data is written to the file cache while being
uploaded to remote storage, consistent with the ingestion flow, to accelerate
subsequent queries. |
| Base Compaction | By default, data is written to the cache only when there
is sufficient cache space, to avoid cache pollution from large volumes of cold
data. You can force writes by setting the BE parameter
`enable_file_cache_keep_base_compaction_output = true`, but this may cause
other hot data to be evicted. |
+When local cache capacity is limited, you can enable an index-only write
policy to prevent Segment data from Compaction output from actively consuming a
large amount of cache space:
+
+- `enable_file_cache_write_index_file_only=true`: Applies to all rowset writes
in compute-storage decoupled mode, including Compaction. Segment data is not
actively cached, while Segment footer/internal-index ranges and independent
inverted-index files are still written to the cache.
+- `enable_file_cache_write_base_compaction_index_only=true` or
`enable_file_cache_write_cumu_compaction_index_only=true`: Only restricts
matching Compaction output that would otherwise be written to the cache.
Segment files are skipped and independent inverted-index files are retained,
but Segment footer/internal-index ranges are not preloaded.
+
+For parameter precedence, configuration examples, and limitations, see [File
Cache Configuration](./file-cache.md).
+
> **Planned:** A future version of Doris will provide an adaptive write
> strategy based on historical query statistics.
### Cache Loading After Restart
diff --git a/docs/compute-storage-decoupled/file-cache/file-cache.md
b/docs/compute-storage-decoupled/file-cache/file-cache.md
index a5104d3fdd4..5f27b1ed124 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, 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", "cache warmup", "cache quota", "TTL cache", "LRU", "cache hit rate",
"object storage acceleration"]
+ "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"]
}
---
@@ -49,6 +49,72 @@ Doris controls file cache behavior through the following
parameters in the BE co
|---|---|---|
| `enable_file_cache` | `false` | Whether to enable the file cache feature.
Set to `true` in compute-storage decoupled mode. |
+### Configuring Index-Only Cache Writes
+
+When local cache space is limited and query performance depends more heavily
on indexes and Segment metadata, you can enable the index-only write policy.
This policy limits what ingestion, Schema Change, Compaction, and other write
paths **actively write** to File Cache. It does not affect query-side cache
fill after a cache miss or cache warmup.
+
+Doris provides one global policy and two Compaction-specific policies:
+
+| Parameter | Type | Default | Scope | Description |
+|---|---|---|---|---|
+| `enable_file_cache_write_index_file_only` | Boolean | `false` | All rowset
writes in compute-storage decoupled mode, including ingestion, Schema Change,
Cumulative Compaction, and Base Compaction | When set to `true`, Segment data
is not actively cached. After a Segment is closed, its footer and internal
index ranges are synchronously preloaded, while independent inverted index
files are still written to File Cache. This parameter takes precedence over the
two Compaction-specific parameters |
+| `enable_file_cache_write_base_compaction_index_only` | Boolean | `false` |
Base Compaction | Only when the existing Base Compaction policy has already
decided to write output to File Cache, prevents the Segment file from being
actively cached while still caching independent inverted index files. This
parameter does not cause Base Compaction output that would otherwise bypass the
cache to be cached |
+| `enable_file_cache_write_cumu_compaction_index_only` | Boolean | `false` |
Cumulative Compaction | When Cumulative Compaction output is written to File
Cache, prevents the Segment file from being actively cached while still caching
independent inverted index files |
+
+The write path determines cache behavior in the following priority order:
+
+1. `enable_file_cache=false` has the highest priority and disables all File
Cache writes, including Segment footer/internal-index preload and independent
inverted-index writes.
+2. When `enable_file_cache=true` and
`enable_file_cache_write_index_file_only=true`, the global index-only policy is
enabled. The two Compaction-specific parameters no longer change the final
behavior. Adaptive writes, Compaction retention policies, cache-hit-ratio
thresholds, and request-level `write_file_cache` settings cannot cause Segment
data to be actively cached; index-related content is still written according to
the global policy described above.
+3. When the global index-only policy is disabled, the Base/Cumulative
Compaction-specific parameters only further restrict output of the matching
type that has **already been selected for caching**. They do not affect other
write scenarios or the query read path.
+4. When all three index-only parameters are `false`, existing active cache
writes, adaptive writes, and Compaction output retention behavior remain
unchanged.
+
+:::caution
+
+The two Compaction-specific parameters distinguish only between independent
inverted index files and Segment files. They do not trigger the Segment
footer/internal-index range preload used by the global index-only policy. To
actively preserve both independent inverted indexes and Segment internal
indexes and metadata, use `enable_file_cache_write_index_file_only`.
+
+:::
+
+#### Enabling the Global Index-Only Policy
+
+Configure the following settings in `be.conf` on every BE node:
+
+```properties
+enable_file_cache=true
+enable_file_cache_write_index_file_only=true
+enable_file_cache_write_base_compaction_index_only=false
+enable_file_cache_write_cumu_compaction_index_only=false
+```
+
+The expected behavior is as follows:
+
+| Scenario | Content Actively Written to File Cache |
+|---|---|
+| Ingestion, Schema Change, Cumulative Compaction, and Base Compaction |
Segment data is not actively written; Segment footer/internal-index ranges are
synchronously preloaded; independent inverted-index files are written |
+| Query data-page reads | Behavior is unchanged. After a cache miss, Segment
data can still be filled according to the existing read-path rules |
+| Cache warmup | Behavior is unchanged |
+| Packed File | Packed small Segment files are not cached as whole files;
packed independent small index files can still be cached as whole files |
+
+Under the global index-only policy, Segment footer/internal-index ranges are
written to the cache through synchronous reads and are not controlled by
`enable_flush_file_cache_async`. Independent inverted-index files continue to
use the existing direct-write and asynchronous-flush behavior.
+
+#### Restricting Only Compaction Output
+
+To reduce cache pressure from Compaction output without changing active cache
writes for ingestion and Schema Change, configure:
+
+```properties
+enable_file_cache=true
+enable_file_cache_write_index_file_only=false
+enable_file_cache_write_base_compaction_index_only=true
+enable_file_cache_write_cumu_compaction_index_only=true
+```
+
+Cumulative Compaction writes output to the cache by default, so enabling its
corresponding parameter skips Segment files and retains only independent
inverted-index files. Base Compaction still first uses
`enable_file_cache_keep_base_compaction_output` and the input-rowset cache hit
ratio to determine whether to cache its output. The Base Compaction index-only
parameter restricts the written content only after that decision is made.
+
+#### Recommendations
+
+- These three parameters are BE parameters. Keep them consistent across all BE
nodes in the same compute group to prevent nodes from using different
cache-write policies.
+- "Index-only" does not mean that File Cache never contains Segment data.
Query-side reads of cache-missed data pages can still fill Segment data into
the cache.
+- This policy can reduce cache pollution from ingestion and Compaction, but a
large data scan immediately after a write can increase remote-storage reads.
Benchmark it with the production query workload, and monitor Index queue
eviction and index-read metrics in the SQL Profile.
+
### Configuring Cache Paths and Size
```plaintext
@@ -309,6 +375,17 @@ Cache-related metrics in the SQL Profile are located under
the `SegmentIterator`
| `RemoteIOUseTimer` | Time spent reading from remote storage |
| `WriteCacheIOUseTimer` | Time spent writing into the file cache |
+After enabling index-only cache writes, monitor the following categorized
metrics to determine whether independent inverted indexes and Segment
footer/internal-index data are hitting the cache:
+
+| Metric | Description |
+|---|---|
+| `InvertedIndexBytesScannedFromCache` / `InvertedIndexBytesScannedFromRemote`
| Amount of independent inverted-index data read from File Cache / remote
storage |
+| `InvertedIndexNumLocalIOTotal` / `InvertedIndexNumRemoteIOTotal` | Number of
local / remote reads for independent inverted indexes |
+| `InvertedIndexLocalIOUseTimer` / `InvertedIndexRemoteIOUseTimer` | Time
spent on local / remote reads for independent inverted indexes |
+| `SegmentFooterIndexBytesScannedFromCache` /
`SegmentFooterIndexBytesScannedFromRemote` | Amount of Segment footer and
internal-index data read from File Cache / remote storage |
+| `SegmentFooterIndexNumLocalIOTotal` / `SegmentFooterIndexNumRemoteIOTotal` |
Number of local / remote reads for Segment footer and internal-index data |
+| `SegmentFooterIndexLocalIOUseTimer` / `SegmentFooterIndexRemoteIOUseTimer` |
Time spent on local / remote reads for Segment footer and internal-index data |
+
You can view the complete query performance report through [Query Performance
Analysis](../../query-acceleration/performance-tuning-overview/analysis-tools#doris-profile).
## TTL Cache Policy
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compute-storage-decoupled/file-cache/file-cache-internals.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compute-storage-decoupled/file-cache/file-cache-internals.md
index 703ab26e9ae..756f2d8026b 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compute-storage-decoupled/file-cache/file-cache-internals.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compute-storage-decoupled/file-cache/file-cache-internals.md
@@ -155,6 +155,13 @@ Doris 的 Compaction 分为两类：
| Cumulative Compaction | 输出数据上传远程存储的同时写入文件缓存，与导入流程一致，加速后续查询。 |
| Base Compaction | 默认仅在缓存空间充足时写入，避免大量冷数据造成缓存污染。可通过 BE 参数
`enable_file_cache_keep_base_compaction_output = true` 强制写入，但可能导致其他热数据被淘汰。 |
+当本地缓存容量有限时，可以启用索引优先写入策略，避免 Compaction 输出的 Segment 数据主动占用大量缓存空间：
+
+- `enable_file_cache_write_index_file_only=true`：对包括 Compaction 在内的所有存算分离
Rowset 写入生效。Segment 数据不主动写入缓存，Segment footer/内部索引范围和独立倒排索引文件仍写入缓存。
+- `enable_file_cache_write_base_compaction_index_only=true` 或
`enable_file_cache_write_cumu_compaction_index_only=true`：仅限制匹配类型中原本会写入缓存的
Compaction 输出，跳过 Segment 文件并保留独立倒排索引文件；不会预加载 Segment footer/内部索引范围。
+
+参数优先级、配置示例和使用限制详见[文件缓存配置](./file-cache.md)。
+
> **计划：** Doris 后续版本将提供基于历史查询统计信息的自适应写入策略。
### 重启后缓存加载
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 2fb320da231..beba5576faf 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", "索引优先缓存", "缓存预热",
"缓存配额", "TTL 缓存", "LRU", "缓存命中率", "对象存储加速"]
}
---
@@ -49,6 +49,72 @@ Doris 通过 BE 配置文件中的以下参数控制文件缓存行为。
|---|---|---|
| `enable_file_cache` | `false` | 是否启用文件缓存功能。存算分离模式下建议设置为 `true`。 |
+### 配置写入路径仅缓存索引
+
+当本地缓存空间有限，并且查询性能更依赖索引和 Segment 元数据时，可以启用索引优先（index-only）写入策略。该策略限制的是导入、Schema
Change 和 Compaction 等写入路径向 File Cache **主动写入**的内容，不影响查询读取未命中数据后的缓存回填，也不影响缓存预热。
+
+Doris 提供一个全局策略和两个 Compaction 专用策略：
+
+| 参数 | 类型 | 默认值 | 生效范围 | 说明 |
+|---|---|---|---|---|
+| `enable_file_cache_write_index_file_only` | Boolean | `false` | 所有存算分离
Rowset 写入，包括导入、Schema Change、Cumulative Compaction 和 Base Compaction | 设为
`true` 后，不主动缓存 Segment 数据；Segment 关闭后同步预加载其 footer 和内部索引范围，独立倒排索引文件仍写入 File
Cache。该参数的优先级高于两个 Compaction 专用参数 |
+| `enable_file_cache_write_base_compaction_index_only` | Boolean | `false` |
Base Compaction | 仅当 Base Compaction 按原有策略决定写入 File Cache 时，将其输出限制为不主动缓存
Segment 文件、仍缓存独立倒排索引文件。该参数不会使原本不写缓存的 Base Compaction 输出开始写入缓存 |
+| `enable_file_cache_write_cumu_compaction_index_only` | Boolean | `false` |
Cumulative Compaction | 当 Cumulative Compaction 输出写入 File Cache 时，将其限制为不主动缓存
Segment 文件、仍缓存独立倒排索引文件 |
+
+写入路径按以下优先级决定缓存行为：
+
+1. `enable_file_cache=false` 的优先级最高，禁止所有 File Cache 写入，包括 Segment
footer/内部索引预加载和独立倒排索引文件写入。
+2. `enable_file_cache=true` 且 `enable_file_cache_write_index_file_only=true`
时，启用全局索引优先写入。此时两个 Compaction 专用参数不再改变最终行为。Segment 数据不会因自适应写入、Compaction
保留策略、缓存命中率阈值或请求级 `write_file_cache` 设置而主动写入缓存；索引相关内容仍按上述全局策略写入。
+3. 全局索引优先写入关闭时，Base/Cumulative Compaction
专用参数只进一步限制匹配类型中**原本已决定写入缓存**的输出，不改变其他写入场景或查询读路径。
+4. 三个索引优先参数均为 `false` 时，保留现有的主动写缓存、自适应写入和 Compaction 输出保留逻辑。
+
+:::caution 注意
+
+两个 Compaction 专用参数只区分独立倒排索引文件与 Segment 文件，不会触发全局索引优先模式中的 Segment
footer/内部索引范围预加载。如果需要同时主动保留独立倒排索引和 Segment 内部索引、元数据，请使用
`enable_file_cache_write_index_file_only`。
+
+:::
+
+#### 全局启用索引优先写入
+
+在所有 BE 节点的 `be.conf` 中配置：
+
+```properties
+enable_file_cache=true
+enable_file_cache_write_index_file_only=true
+enable_file_cache_write_base_compaction_index_only=false
+enable_file_cache_write_cumu_compaction_index_only=false
+```
+
+预期行为如下：
+
+| 场景 | 主动写入 File Cache 的内容 |
+|---|---|
+| 导入、Schema Change、Cumulative Compaction、Base Compaction | 不主动写入 Segment
数据；同步预加载 Segment footer/内部索引范围；写入独立倒排索引文件 |
+| 查询读取数据页 | 行为不变；缓存未命中时仍可按现有读路径规则回填 Segment 数据 |
+| 缓存预热 | 行为不变 |
+| Packed File | 不对打包后的 Segment 小文件进行整文件缓存；打包后的独立索引小文件仍可整文件缓存 |
+
+全局索引优先模式下，Segment footer/内部索引范围通过同步读取写入缓存，不受 `enable_flush_file_cache_async`
控制；独立倒排索引文件仍沿用已有的直接写入和异步 flush 行为。
+
+#### 仅限制 Compaction 输出
+
+如果只希望减少 Compaction 输出造成的缓存压力，而不改变导入和 Schema Change 的主动写缓存行为，可以配置：
+
+```properties
+enable_file_cache=true
+enable_file_cache_write_index_file_only=false
+enable_file_cache_write_base_compaction_index_only=true
+enable_file_cache_write_cumu_compaction_index_only=true
+```
+
+Cumulative Compaction 默认会写入输出缓存，因此启用对应参数后会跳过 Segment 文件，仅保留独立倒排索引文件。Base
Compaction 仍先根据 `enable_file_cache_keep_base_compaction_output` 和输入 Rowset
缓存命中率决定是否写入输出；只有决定写入时，Base Compaction 的索引优先参数才进一步限制写入内容。
+
+#### 使用建议
+
+- 三个参数都是 BE 参数。应在同一计算组的所有 BE 节点上保持一致，避免不同节点采用不同的写缓存策略。
+- “仅缓存索引”不表示 File Cache 中永远不会出现 Segment 数据。查询读取未命中的数据页时，仍可能将数据写入缓存。
+- 该策略可以降低导入和 Compaction 对缓存的污染，但紧随写入发生的大范围数据扫描可能增加远程存储读取。建议结合业务查询负载进行压测，并持续观察
Index 队列淘汰量与 SQL Profile 中的索引读取指标。
+
### 配置缓存路径与大小
```plaintext
@@ -309,6 +375,17 @@ SQL Profile 中缓存相关指标位于 `SegmentIterator` 节点下：
| `RemoteIOUseTimer` | 读取远程存储的耗时 |
| `WriteCacheIOUseTimer` | 写入 File Cache 的耗时 |
+启用索引优先写入后，可以进一步关注以下分类指标，分别判断独立倒排索引和 Segment footer/内部索引是否命中缓存：
+
+| 指标名称 | 含义 |
+|---|---|
+| `InvertedIndexBytesScannedFromCache` / `InvertedIndexBytesScannedFromRemote`
| 从 File Cache / 远程存储读取的独立倒排索引数据量 |
+| `InvertedIndexNumLocalIOTotal` / `InvertedIndexNumRemoteIOTotal` | 独立倒排索引的本地
/ 远程读取次数 |
+| `InvertedIndexLocalIOUseTimer` / `InvertedIndexRemoteIOUseTimer` | 独立倒排索引的本地
/ 远程读取耗时 |
+| `SegmentFooterIndexBytesScannedFromCache` /
`SegmentFooterIndexBytesScannedFromRemote` | 从 File Cache / 远程存储读取的 Segment
footer 和内部索引数据量 |
+| `SegmentFooterIndexNumLocalIOTotal` / `SegmentFooterIndexNumRemoteIOTotal` |
Segment footer 和内部索引的本地 / 远程读取次数 |
+| `SegmentFooterIndexLocalIOUseTimer` / `SegmentFooterIndexRemoteIOUseTimer` |
Segment footer 和内部索引的本地 / 远程读取耗时 |
+
您可以通过[查询性能分析](../../query-acceleration/performance-tuning-overview/analysis-tools#doris-profile)查看完整的查询性能报告。
## TTL 缓存策略
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/compute-storage-decoupled/file-cache/file-cache-internals.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/compute-storage-decoupled/file-cache/file-cache-internals.md
index 703ab26e9ae..756f2d8026b 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/compute-storage-decoupled/file-cache/file-cache-internals.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/compute-storage-decoupled/file-cache/file-cache-internals.md
@@ -155,6 +155,13 @@ Doris 的 Compaction 分为两类：
| Cumulative Compaction | 输出数据上传远程存储的同时写入文件缓存，与导入流程一致，加速后续查询。 |
| Base Compaction | 默认仅在缓存空间充足时写入，避免大量冷数据造成缓存污染。可通过 BE 参数
`enable_file_cache_keep_base_compaction_output = true` 强制写入，但可能导致其他热数据被淘汰。 |
+当本地缓存容量有限时，可以启用索引优先写入策略，避免 Compaction 输出的 Segment 数据主动占用大量缓存空间：
+
+- `enable_file_cache_write_index_file_only=true`：对包括 Compaction 在内的所有存算分离
Rowset 写入生效。Segment 数据不主动写入缓存，Segment footer/内部索引范围和独立倒排索引文件仍写入缓存。
+- `enable_file_cache_write_base_compaction_index_only=true` 或
`enable_file_cache_write_cumu_compaction_index_only=true`：仅限制匹配类型中原本会写入缓存的
Compaction 输出，跳过 Segment 文件并保留独立倒排索引文件；不会预加载 Segment footer/内部索引范围。
+
+参数优先级、配置示例和使用限制详见[文件缓存配置](./file-cache.md)。
+
> **计划：** Doris 后续版本将提供基于历史查询统计信息的自适应写入策略。
### 重启后缓存加载
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 2fb320da231..beba5576faf 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", "索引优先缓存", "缓存预热",
"缓存配额", "TTL 缓存", "LRU", "缓存命中率", "对象存储加速"]
}
---
@@ -49,6 +49,72 @@ Doris 通过 BE 配置文件中的以下参数控制文件缓存行为。
|---|---|---|
| `enable_file_cache` | `false` | 是否启用文件缓存功能。存算分离模式下建议设置为 `true`。 |
+### 配置写入路径仅缓存索引
+
+当本地缓存空间有限，并且查询性能更依赖索引和 Segment 元数据时，可以启用索引优先（index-only）写入策略。该策略限制的是导入、Schema
Change 和 Compaction 等写入路径向 File Cache **主动写入**的内容，不影响查询读取未命中数据后的缓存回填，也不影响缓存预热。
+
+Doris 提供一个全局策略和两个 Compaction 专用策略：
+
+| 参数 | 类型 | 默认值 | 生效范围 | 说明 |
+|---|---|---|---|---|
+| `enable_file_cache_write_index_file_only` | Boolean | `false` | 所有存算分离
Rowset 写入，包括导入、Schema Change、Cumulative Compaction 和 Base Compaction | 设为
`true` 后，不主动缓存 Segment 数据；Segment 关闭后同步预加载其 footer 和内部索引范围，独立倒排索引文件仍写入 File
Cache。该参数的优先级高于两个 Compaction 专用参数 |
+| `enable_file_cache_write_base_compaction_index_only` | Boolean | `false` |
Base Compaction | 仅当 Base Compaction 按原有策略决定写入 File Cache 时，将其输出限制为不主动缓存
Segment 文件、仍缓存独立倒排索引文件。该参数不会使原本不写缓存的 Base Compaction 输出开始写入缓存 |
+| `enable_file_cache_write_cumu_compaction_index_only` | Boolean | `false` |
Cumulative Compaction | 当 Cumulative Compaction 输出写入 File Cache 时，将其限制为不主动缓存
Segment 文件、仍缓存独立倒排索引文件 |
+
+写入路径按以下优先级决定缓存行为：
+
+1. `enable_file_cache=false` 的优先级最高，禁止所有 File Cache 写入，包括 Segment
footer/内部索引预加载和独立倒排索引文件写入。
+2. `enable_file_cache=true` 且 `enable_file_cache_write_index_file_only=true`
时，启用全局索引优先写入。此时两个 Compaction 专用参数不再改变最终行为。Segment 数据不会因自适应写入、Compaction
保留策略、缓存命中率阈值或请求级 `write_file_cache` 设置而主动写入缓存；索引相关内容仍按上述全局策略写入。
+3. 全局索引优先写入关闭时，Base/Cumulative Compaction
专用参数只进一步限制匹配类型中**原本已决定写入缓存**的输出，不改变其他写入场景或查询读路径。
+4. 三个索引优先参数均为 `false` 时，保留现有的主动写缓存、自适应写入和 Compaction 输出保留逻辑。
+
+:::caution 注意
+
+两个 Compaction 专用参数只区分独立倒排索引文件与 Segment 文件，不会触发全局索引优先模式中的 Segment
footer/内部索引范围预加载。如果需要同时主动保留独立倒排索引和 Segment 内部索引、元数据，请使用
`enable_file_cache_write_index_file_only`。
+
+:::
+
+#### 全局启用索引优先写入
+
+在所有 BE 节点的 `be.conf` 中配置：
+
+```properties
+enable_file_cache=true
+enable_file_cache_write_index_file_only=true
+enable_file_cache_write_base_compaction_index_only=false
+enable_file_cache_write_cumu_compaction_index_only=false
+```
+
+预期行为如下：
+
+| 场景 | 主动写入 File Cache 的内容 |
+|---|---|
+| 导入、Schema Change、Cumulative Compaction、Base Compaction | 不主动写入 Segment
数据；同步预加载 Segment footer/内部索引范围；写入独立倒排索引文件 |
+| 查询读取数据页 | 行为不变；缓存未命中时仍可按现有读路径规则回填 Segment 数据 |
+| 缓存预热 | 行为不变 |
+| Packed File | 不对打包后的 Segment 小文件进行整文件缓存；打包后的独立索引小文件仍可整文件缓存 |
+
+全局索引优先模式下，Segment footer/内部索引范围通过同步读取写入缓存，不受 `enable_flush_file_cache_async`
控制；独立倒排索引文件仍沿用已有的直接写入和异步 flush 行为。
+
+#### 仅限制 Compaction 输出
+
+如果只希望减少 Compaction 输出造成的缓存压力，而不改变导入和 Schema Change 的主动写缓存行为，可以配置：
+
+```properties
+enable_file_cache=true
+enable_file_cache_write_index_file_only=false
+enable_file_cache_write_base_compaction_index_only=true
+enable_file_cache_write_cumu_compaction_index_only=true
+```
+
+Cumulative Compaction 默认会写入输出缓存，因此启用对应参数后会跳过 Segment 文件，仅保留独立倒排索引文件。Base
Compaction 仍先根据 `enable_file_cache_keep_base_compaction_output` 和输入 Rowset
缓存命中率决定是否写入输出；只有决定写入时，Base Compaction 的索引优先参数才进一步限制写入内容。
+
+#### 使用建议
+
+- 三个参数都是 BE 参数。应在同一计算组的所有 BE 节点上保持一致，避免不同节点采用不同的写缓存策略。
+- “仅缓存索引”不表示 File Cache 中永远不会出现 Segment 数据。查询读取未命中的数据页时，仍可能将数据写入缓存。
+- 该策略可以降低导入和 Compaction 对缓存的污染，但紧随写入发生的大范围数据扫描可能增加远程存储读取。建议结合业务查询负载进行压测，并持续观察
Index 队列淘汰量与 SQL Profile 中的索引读取指标。
+
### 配置缓存路径与大小
```plaintext
@@ -309,6 +375,17 @@ SQL Profile 中缓存相关指标位于 `SegmentIterator` 节点下：
| `RemoteIOUseTimer` | 读取远程存储的耗时 |
| `WriteCacheIOUseTimer` | 写入 File Cache 的耗时 |
+启用索引优先写入后，可以进一步关注以下分类指标，分别判断独立倒排索引和 Segment footer/内部索引是否命中缓存：
+
+| 指标名称 | 含义 |
+|---|---|
+| `InvertedIndexBytesScannedFromCache` / `InvertedIndexBytesScannedFromRemote`
| 从 File Cache / 远程存储读取的独立倒排索引数据量 |
+| `InvertedIndexNumLocalIOTotal` / `InvertedIndexNumRemoteIOTotal` | 独立倒排索引的本地
/ 远程读取次数 |
+| `InvertedIndexLocalIOUseTimer` / `InvertedIndexRemoteIOUseTimer` | 独立倒排索引的本地
/ 远程读取耗时 |
+| `SegmentFooterIndexBytesScannedFromCache` /
`SegmentFooterIndexBytesScannedFromRemote` | 从 File Cache / 远程存储读取的 Segment
footer 和内部索引数据量 |
+| `SegmentFooterIndexNumLocalIOTotal` / `SegmentFooterIndexNumRemoteIOTotal` |
Segment footer 和内部索引的本地 / 远程读取次数 |
+| `SegmentFooterIndexLocalIOUseTimer` / `SegmentFooterIndexRemoteIOUseTimer` |
Segment footer 和内部索引的本地 / 远程读取耗时 |
+
您可以通过[查询性能分析](../../query-acceleration/performance-tuning-overview/analysis-tools#doris-profile)查看完整的查询性能报告。
## TTL 缓存策略
diff --git
a/ja-source/docusaurus-plugin-content-docs/current/compute-storage-decoupled/file-cache/file-cache-internals.md
b/ja-source/docusaurus-plugin-content-docs/current/compute-storage-decoupled/file-cache/file-cache-internals.md
index b4068a776da..b1635329350 100644
---
a/ja-source/docusaurus-plugin-content-docs/current/compute-storage-decoupled/file-cache/file-cache-internals.md
+++
b/ja-source/docusaurus-plugin-content-docs/current/compute-storage-decoupled/file-cache/file-cache-internals.md
@@ -91,6 +91,13 @@ Dorisのファイルキャッシュは、マルチキューメカニズムを使
- Cumulative
Compaction：新しくマージされたデータは、リモートストレージアップロード後、インポートと同様にファイルキャッシュに入り、後続のクエリを高速化します。
- Base Compaction：Base
Compactionは通常大きなコールドデータを含むため、新しいデータは容量が許可する場合のみキャッシュに入ります。ユーザーはBE config
`enable_file_cache_keep_base_compaction_output =
true`を介してキャッシュ挿入を強制できますが、これは他のホットデータを削除する可能性があります。将来のバージョンでは、履歴クエリ統計を使用してキャッシュ挿入を決定する適応戦略を計画しています。
+ローカルキャッシュ容量が限られている場合は、インデックス優先書き込みポリシーを有効にして、Compaction出力のSegmentデータがキャッシュ領域を大量に消費することを防げます。
+
+-
`enable_file_cache_write_index_file_only=true`：Compactionを含む、ストレージ・コンピューティング分離モードのすべてのRowset書き込みに適用されます。Segmentデータは能動的にキャッシュされず、Segmentフッター/内部インデックス範囲と独立した転置インデックスファイルは引き続きキャッシュへ書き込まれます。
+-
`enable_file_cache_write_base_compaction_index_only=true`または`enable_file_cache_write_cumu_compaction_index_only=true`：該当する種類で、本来キャッシュへ書き込まれるCompaction出力だけを制限します。Segmentファイルをスキップして独立した転置インデックスファイルを保持しますが、Segmentフッター/内部インデックス範囲はプリロードされません。
+
+パラメータの優先順位、設定例、制限事項については、[ファイルキャッシュ設定](./file-cache.md)を参照してください。
+
### (4) 再起動後のキャッシュロード
再起動後のキャッシュロードは、キャッシュ状態の復旧と迅速なクエリ応答にとって重要です。v3.1以前では、保存されていないLRU情報により、一貫性のないキュー順序が発生し、ヒット率に影響していました。
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 450031bb4dc..80d6c6ac955 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": "疎結合アーキテクチャでは、データはリモートストレージに格納されます。"
+ "description":
"ストレージ・コンピューティング分離モードにおけるDorisファイルキャッシュの設定、インデックスのみの書き込み、クォータ、ウォームアップ、監視、およびTTL戦略について説明します。"
}
---
分離アーキテクチャでは、データはリモートストレージに保存されます。Dorisデータベースは、ローカルディスク上のキャッシュを利用してデータアクセスを高速化し、高度なマルチキューLRU（Least
Recently
Used）戦略を採用してキャッシュスペースを効率的に管理します。この戦略は特にインデックスとメタデータのアクセスパスを最適化し、頻繁にアクセスされるユーザーデータのキャッシュを最大化することを目的としています。マルチCompute
Group（Compute Group）シナリオでは、Dorisは新しいcompute
groupが確立された際に特定のデータ（テーブルやパーティションなど）をキャッシュに素早くロードするキャッシュウォーミング機能も提供し、それによりクエリパフォーマンスを向上させます。
@@ -32,6 +32,72 @@ enable_file_cache Default: "false"
```
パラメータの説明：この設定項目は、ファイルキャッシュ機能が有効かどうかを制御します。`true`に設定すると、ファイルキャッシュが有効になります。`false`に設定すると、ファイルキャッシュが無効になります。
+### 書き込みパスでインデックスのみをキャッシュする
+
+ローカルキャッシュ領域が限られており、クエリ性能がインデックスとSegmentメタデータにより強く依存する場合は、インデックス優先（index-only）書き込みポリシーを有効にできます。このポリシーは、データインポート、Schema
Change、Compactionなどの書き込みパスがFile
Cacheへ**能動的に書き込む**内容を制限します。クエリ時のキャッシュミス後のキャッシュ投入やキャッシュウォームアップには影響しません。
+
+Dorisは、1つのグローバルポリシーと2つのCompaction専用ポリシーを提供します。
+
+| パラメータ | 型 | デフォルト | 適用範囲 | 説明 |
+|---|---|---|---|---|
+| `enable_file_cache_write_index_file_only` | Boolean | `false` |
データインポート、Schema Change、Cumulative Compaction、Base
Compactionを含む、ストレージ・コンピューティング分離モードのすべてのRowset書き込み |
`true`に設定すると、Segmentデータは能動的にキャッシュされません。Segmentを閉じた後、そのフッターと内部インデックス範囲が同期的にプリロードされ、独立した転置インデックスファイルは引き続きFile
Cacheへ書き込まれます。このパラメータは2つのCompaction専用パラメータより優先されます |
+| `enable_file_cache_write_base_compaction_index_only` | Boolean | `false` |
Base Compaction | 既存のBase CompactionポリシーがFile
Cacheへの出力書き込みを決定した場合にのみ、Segmentファイルの能動的なキャッシュを停止し、独立した転置インデックスファイルをキャッシュします。このパラメータによって、本来キャッシュに書き込まれないBase
Compaction出力が新たにキャッシュされることはありません |
+| `enable_file_cache_write_cumu_compaction_index_only` | Boolean | `false` |
Cumulative Compaction | Cumulative Compaction出力がFile
Cacheへ書き込まれる場合、Segmentファイルの能動的なキャッシュを停止し、独立した転置インデックスファイルをキャッシュします |
+
+書き込みパスは、次の優先順位でキャッシュ動作を決定します。
+
+1.
`enable_file_cache=false`が最優先されます。Segmentフッター/内部インデックスのプリロードや独立した転置インデックスファイルの書き込みを含め、すべてのFile
Cache書き込みが無効になります。
+2.
`enable_file_cache=true`かつ`enable_file_cache_write_index_file_only=true`の場合、グローバルなインデックス優先書き込みが有効になります。このとき、2つのCompaction専用パラメータは最終的な動作を変更しません。適応型書き込み、Compaction出力保持ポリシー、キャッシュヒット率の閾値、リクエストレベルの`write_file_cache`設定によってSegmentデータが能動的にキャッシュされることはなく、インデックス関連コンテンツは前述のグローバルポリシーに従って書き込まれます。
+3. グローバルなインデックス優先書き込みが無効な場合、Base/Cumulative
Compaction専用パラメータは、該当する種類で**すでにキャッシュ書き込み対象と判断された**出力だけをさらに制限します。他の書き込みシナリオやクエリ読み取りパスには影響しません。
+4.
3つのインデックス優先パラメータがすべて`false`の場合、既存の能動的なキャッシュ書き込み、適応型書き込み、およびCompaction出力保持動作が維持されます。
+
+:::caution 注意
+
+2つのCompaction専用パラメータが区別するのは、独立した転置インデックスファイルとSegmentファイルだけです。グローバルなインデックス優先モードで行われるSegmentフッター/内部インデックス範囲のプリロードは実行されません。独立した転置インデックスとSegment内部のインデックスおよびメタデータの両方を能動的に保持するには、`enable_file_cache_write_index_file_only`を使用してください。
+
+:::
+
+#### グローバルなインデックス優先書き込みを有効にする
+
+すべてのBEノードの`be.conf`に次の設定を追加します。
+
+```properties
+enable_file_cache=true
+enable_file_cache_write_index_file_only=true
+enable_file_cache_write_base_compaction_index_only=false
+enable_file_cache_write_cumu_compaction_index_only=false
+```
+
+期待される動作は次のとおりです。
+
+| シナリオ | File Cacheへ能動的に書き込まれる内容 |
+|---|---|
+| データインポート、Schema Change、Cumulative Compaction、Base Compaction |
Segmentデータは能動的に書き込まれません。Segmentフッター/内部インデックス範囲が同期的にプリロードされ、独立した転置インデックスファイルが書き込まれます
|
+| クエリによるデータページ読み取り |
動作は変わりません。キャッシュミス後も、既存の読み取りパスのルールに従ってSegmentデータがキャッシュへ投入される場合があります |
+| キャッシュウォームアップ | 動作は変わりません |
+| Packed File |
パックされた小さなSegmentファイルはファイル全体としてキャッシュされません。パックされた独立した小さなインデックスファイルは、引き続きファイル全体としてキャッシュできます
|
+
+グローバルなインデックス優先モードでは、Segmentフッター/内部インデックス範囲は同期読み取りによってキャッシュへ書き込まれるため、`enable_flush_file_cache_async`の制御対象ではありません。独立した転置インデックスファイルは、既存の直接書き込みと非同期flushの動作を引き続き使用します。
+
+#### Compaction出力だけを制限する
+
+データインポートとSchema
Changeの能動的なキャッシュ書き込みを変更せず、Compaction出力によるキャッシュ負荷だけを減らす場合は、次のように設定します。
+
+```properties
+enable_file_cache=true
+enable_file_cache_write_index_file_only=false
+enable_file_cache_write_base_compaction_index_only=true
+enable_file_cache_write_cumu_compaction_index_only=true
+```
+
+Cumulative
Compactionはデフォルトで出力をキャッシュへ書き込むため、対応するパラメータを有効にするとSegmentファイルをスキップし、独立した転置インデックスファイルだけを保持します。Base
Compactionは、最初に`enable_file_cache_keep_base_compaction_output`と入力Rowsetのキャッシュヒット率に基づいて、出力をキャッシュするかどうかを決定します。Base
Compaction用のインデックス優先パラメータは、その決定後にのみ書き込み内容を制限します。
+
+#### 推奨事項
+
+- 3つのパラメータはいずれもBEパラメータです。同じCompute
Group内のすべてのBEノードで設定を統一し、ノードごとに異なるキャッシュ書き込みポリシーが適用されないようにしてください。
+- 「インデックスのみ」は、File
CacheにSegmentデータが一切存在しないことを意味しません。クエリがキャッシュミスしたデータページを読み取ると、Segmentデータがキャッシュへ投入される場合があります。
+-
このポリシーはデータインポートとCompactionによるキャッシュ汚染を抑制できますが、書き込み直後に大規模なデータスキャンを行うと、リモートストレージからの読み取りが増える可能性があります。実際のクエリ負荷で性能を検証し、Indexキューの退避量とSQL
Profileのインデックス読み取りメトリクスを継続的に監視してください。
+
2. ファイルキャッシュのパスとサイズの設定
```plaintext
@@ -297,6 +363,17 @@ SQLプロファイル内のキャッシュ関連メトリックは、SegmentIter
| RemoteIOUseTimer | リモートストレージからの読み取りにかかった時間 |
| WriteCacheIOUseTimer | File Cacheへの書き込みにかかった時間 |
+インデックス優先書き込みを有効にした後は、次の分類メトリクスを確認し、独立した転置インデックスとSegmentフッター/内部インデックスがキャッシュにヒットしているかを判断できます。
+
+| メトリクス名 | 意味 |
+|---|---|
+| `InvertedIndexBytesScannedFromCache` / `InvertedIndexBytesScannedFromRemote`
| File Cache / リモートストレージから読み取った独立した転置インデックスのデータ量 |
+| `InvertedIndexNumLocalIOTotal` / `InvertedIndexNumRemoteIOTotal` |
独立した転置インデックスのローカル / リモート読み取り回数 |
+| `InvertedIndexLocalIOUseTimer` / `InvertedIndexRemoteIOUseTimer` |
独立した転置インデックスのローカル / リモート読み取り時間 |
+| `SegmentFooterIndexBytesScannedFromCache` /
`SegmentFooterIndexBytesScannedFromRemote` | File Cache /
リモートストレージから読み取ったSegmentフッターおよび内部インデックスのデータ量 |
+| `SegmentFooterIndexNumLocalIOTotal` / `SegmentFooterIndexNumRemoteIOTotal` |
Segmentフッターおよび内部インデックスのローカル / リモート読み取り回数 |
+| `SegmentFooterIndexLocalIOUseTimer` / `SegmentFooterIndexRemoteIOUseTimer` |
Segmentフッターおよび内部インデックスのローカル / リモート読み取り時間 |
+
[Query Performance
Analysis](../../query-acceleration/performance-tuning-overview/analysis-tools#doris-profile)でクエリパフォーマンス分析を表示できます。
diff --git
a/ja-source/docusaurus-plugin-content-docs/version-4.x/compute-storage-decoupled/file-cache/file-cache-internals.md
b/ja-source/docusaurus-plugin-content-docs/version-4.x/compute-storage-decoupled/file-cache/file-cache-internals.md
index b0893bd82be..9afd60dd2b4 100644
---
a/ja-source/docusaurus-plugin-content-docs/version-4.x/compute-storage-decoupled/file-cache/file-cache-internals.md
+++
b/ja-source/docusaurus-plugin-content-docs/version-4.x/compute-storage-decoupled/file-cache/file-cache-internals.md
@@ -91,6 +91,13 @@ Dorisのファイルキャッシュは、異なるデータタイプを分離し
- Cumulative
Compaction：新しくマージされたデータは、リモートストレージアップロード後にファイルキャッシュに入り、インポートと同様に後続のクエリを加速します。
- Base Compaction：Base
Compactionは通常大きなコールドデータを含むため、新しいデータは領域が許可する場合のみキャッシュに入ります。ユーザーはBE設定`enable_file_cache_keep_base_compaction_output
=
true`経由で強制キャッシュ挿入が可能ですが、これは他のホットデータを退避する可能性があります。将来のバージョンでは、キャッシュ挿入を決定するために履歴クエリ統計を使用する適応戦略を計画しています。
+ローカルキャッシュ容量が限られている場合は、インデックス優先書き込みポリシーを有効にして、Compaction出力のSegmentデータがキャッシュ領域を大量に消費することを防げます。
+
+-
`enable_file_cache_write_index_file_only=true`：Compactionを含む、ストレージ・コンピューティング分離モードのすべてのRowset書き込みに適用されます。Segmentデータは能動的にキャッシュされず、Segmentフッター/内部インデックス範囲と独立した転置インデックスファイルは引き続きキャッシュへ書き込まれます。
+-
`enable_file_cache_write_base_compaction_index_only=true`または`enable_file_cache_write_cumu_compaction_index_only=true`：該当する種類で、本来キャッシュへ書き込まれるCompaction出力だけを制限します。Segmentファイルをスキップして独立した転置インデックスファイルを保持しますが、Segmentフッター/内部インデックス範囲はプリロードされません。
+
+パラメータの優先順位、設定例、制限事項については、[ファイルキャッシュ設定](./file-cache.md)を参照してください。
+
### (4) 再起動後のキャッシュロード
再起動後のキャッシュロードは、キャッシュ状態復旧と迅速なクエリ応答のために重要です。v3.1以前では、保持されないLRU情報がキューの順序不整合を引き起こし、ヒット率に影響していました。
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 db87e63391b..2bc798e5deb 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": "疎結合アーキテクチャでは、データはリモートストレージに格納されます。"
+ "description":
"ストレージ・コンピューティング分離モードにおけるDorisファイルキャッシュの設定、インデックスのみの書き込み、クォータ、ウォームアップ、監視、およびTTL戦略について説明します。"
}
---
分散アーキテクチャでは、データはリモートストレージに保存されます。Dorisデータベースは、ローカルディスク上のキャッシュを利用してデータアクセスを高速化し、高度なマルチキューLRU（Least
Recently
Used）戦略を採用してキャッシュ領域を効率的に管理します。この戦略は特にインデックスとメタデータのアクセスパスを最適化し、頻繁にアクセスされるユーザーデータのキャッシュを最大化することを目指しています。マルチCompute
Group（Compute Group）シナリオでは、Dorisは新しいcompute
groupが確立された際に特定のデータ（テーブルやパーティションなど）をキャッシュに素早くロードするキャッシュウォーミング機能も提供し、クエリパフォーマンスを向上させます。
@@ -32,6 +32,72 @@ enable_file_cache Default: "false"
```
パラメータ説明：この設定項目は、ファイルキャッシュ機能が有効かどうかを制御します。`true`に設定した場合、ファイルキャッシュが有効になります。`false`に設定した場合、ファイルキャッシュが無効になります。
+### 書き込みパスでインデックスのみをキャッシュする
+
+ローカルキャッシュ領域が限られており、クエリ性能がインデックスとSegmentメタデータにより強く依存する場合は、インデックス優先（index-only）書き込みポリシーを有効にできます。このポリシーは、データインポート、Schema
Change、Compactionなどの書き込みパスがFile
Cacheへ**能動的に書き込む**内容を制限します。クエリ時のキャッシュミス後のキャッシュ投入やキャッシュウォームアップには影響しません。
+
+Dorisは、1つのグローバルポリシーと2つのCompaction専用ポリシーを提供します。
+
+| パラメータ | 型 | デフォルト | 適用範囲 | 説明 |
+|---|---|---|---|---|
+| `enable_file_cache_write_index_file_only` | Boolean | `false` |
データインポート、Schema Change、Cumulative Compaction、Base
Compactionを含む、ストレージ・コンピューティング分離モードのすべてのRowset書き込み |
`true`に設定すると、Segmentデータは能動的にキャッシュされません。Segmentを閉じた後、そのフッターと内部インデックス範囲が同期的にプリロードされ、独立した転置インデックスファイルは引き続きFile
Cacheへ書き込まれます。このパラメータは2つのCompaction専用パラメータより優先されます |
+| `enable_file_cache_write_base_compaction_index_only` | Boolean | `false` |
Base Compaction | 既存のBase CompactionポリシーがFile
Cacheへの出力書き込みを決定した場合にのみ、Segmentファイルの能動的なキャッシュを停止し、独立した転置インデックスファイルをキャッシュします。このパラメータによって、本来キャッシュに書き込まれないBase
Compaction出力が新たにキャッシュされることはありません |
+| `enable_file_cache_write_cumu_compaction_index_only` | Boolean | `false` |
Cumulative Compaction | Cumulative Compaction出力がFile
Cacheへ書き込まれる場合、Segmentファイルの能動的なキャッシュを停止し、独立した転置インデックスファイルをキャッシュします |
+
+書き込みパスは、次の優先順位でキャッシュ動作を決定します。
+
+1.
`enable_file_cache=false`が最優先されます。Segmentフッター/内部インデックスのプリロードや独立した転置インデックスファイルの書き込みを含め、すべてのFile
Cache書き込みが無効になります。
+2.
`enable_file_cache=true`かつ`enable_file_cache_write_index_file_only=true`の場合、グローバルなインデックス優先書き込みが有効になります。このとき、2つのCompaction専用パラメータは最終的な動作を変更しません。適応型書き込み、Compaction出力保持ポリシー、キャッシュヒット率の閾値、リクエストレベルの`write_file_cache`設定によってSegmentデータが能動的にキャッシュされることはなく、インデックス関連コンテンツは前述のグローバルポリシーに従って書き込まれます。
+3. グローバルなインデックス優先書き込みが無効な場合、Base/Cumulative
Compaction専用パラメータは、該当する種類で**すでにキャッシュ書き込み対象と判断された**出力だけをさらに制限します。他の書き込みシナリオやクエリ読み取りパスには影響しません。
+4.
3つのインデックス優先パラメータがすべて`false`の場合、既存の能動的なキャッシュ書き込み、適応型書き込み、およびCompaction出力保持動作が維持されます。
+
+:::caution 注意
+
+2つのCompaction専用パラメータが区別するのは、独立した転置インデックスファイルとSegmentファイルだけです。グローバルなインデックス優先モードで行われるSegmentフッター/内部インデックス範囲のプリロードは実行されません。独立した転置インデックスとSegment内部のインデックスおよびメタデータの両方を能動的に保持するには、`enable_file_cache_write_index_file_only`を使用してください。
+
+:::
+
+#### グローバルなインデックス優先書き込みを有効にする
+
+すべてのBEノードの`be.conf`に次の設定を追加します。
+
+```properties
+enable_file_cache=true
+enable_file_cache_write_index_file_only=true
+enable_file_cache_write_base_compaction_index_only=false
+enable_file_cache_write_cumu_compaction_index_only=false
+```
+
+期待される動作は次のとおりです。
+
+| シナリオ | File Cacheへ能動的に書き込まれる内容 |
+|---|---|
+| データインポート、Schema Change、Cumulative Compaction、Base Compaction |
Segmentデータは能動的に書き込まれません。Segmentフッター/内部インデックス範囲が同期的にプリロードされ、独立した転置インデックスファイルが書き込まれます
|
+| クエリによるデータページ読み取り |
動作は変わりません。キャッシュミス後も、既存の読み取りパスのルールに従ってSegmentデータがキャッシュへ投入される場合があります |
+| キャッシュウォームアップ | 動作は変わりません |
+| Packed File |
パックされた小さなSegmentファイルはファイル全体としてキャッシュされません。パックされた独立した小さなインデックスファイルは、引き続きファイル全体としてキャッシュできます
|
+
+グローバルなインデックス優先モードでは、Segmentフッター/内部インデックス範囲は同期読み取りによってキャッシュへ書き込まれるため、`enable_flush_file_cache_async`の制御対象ではありません。独立した転置インデックスファイルは、既存の直接書き込みと非同期flushの動作を引き続き使用します。
+
+#### Compaction出力だけを制限する
+
+データインポートとSchema
Changeの能動的なキャッシュ書き込みを変更せず、Compaction出力によるキャッシュ負荷だけを減らす場合は、次のように設定します。
+
+```properties
+enable_file_cache=true
+enable_file_cache_write_index_file_only=false
+enable_file_cache_write_base_compaction_index_only=true
+enable_file_cache_write_cumu_compaction_index_only=true
+```
+
+Cumulative
Compactionはデフォルトで出力をキャッシュへ書き込むため、対応するパラメータを有効にするとSegmentファイルをスキップし、独立した転置インデックスファイルだけを保持します。Base
Compactionは、最初に`enable_file_cache_keep_base_compaction_output`と入力Rowsetのキャッシュヒット率に基づいて、出力をキャッシュするかどうかを決定します。Base
Compaction用のインデックス優先パラメータは、その決定後にのみ書き込み内容を制限します。
+
+#### 推奨事項
+
+- 3つのパラメータはいずれもBEパラメータです。同じCompute
Group内のすべてのBEノードで設定を統一し、ノードごとに異なるキャッシュ書き込みポリシーが適用されないようにしてください。
+- 「インデックスのみ」は、File
CacheにSegmentデータが一切存在しないことを意味しません。クエリがキャッシュミスしたデータページを読み取ると、Segmentデータがキャッシュへ投入される場合があります。
+-
このポリシーはデータインポートとCompactionによるキャッシュ汚染を抑制できますが、書き込み直後に大規模なデータスキャンを行うと、リモートストレージからの読み取りが増える可能性があります。実際のクエリ負荷で性能を検証し、Indexキューの退避量とSQL
Profileのインデックス読み取りメトリクスを継続的に監視してください。
+
2. ファイルキャッシュパスとサイズの設定
```plaintext
@@ -297,6 +363,17 @@ SQL profileのキャッシュ関連メトリクスはSegmentIterator下にあり
| RemoteIOUseTimer | リモートストレージからの読み取りにかかった時間 |
| WriteCacheIOUseTimer | File Cacheへの書き込みにかかった時間 |
+インデックス優先書き込みを有効にした後は、次の分類メトリクスを確認し、独立した転置インデックスとSegmentフッター/内部インデックスがキャッシュにヒットしているかを判断できます。
+
+| メトリクス名 | 意味 |
+|---|---|
+| `InvertedIndexBytesScannedFromCache` / `InvertedIndexBytesScannedFromRemote`
| File Cache / リモートストレージから読み取った独立した転置インデックスのデータ量 |
+| `InvertedIndexNumLocalIOTotal` / `InvertedIndexNumRemoteIOTotal` |
独立した転置インデックスのローカル / リモート読み取り回数 |
+| `InvertedIndexLocalIOUseTimer` / `InvertedIndexRemoteIOUseTimer` |
独立した転置インデックスのローカル / リモート読み取り時間 |
+| `SegmentFooterIndexBytesScannedFromCache` /
`SegmentFooterIndexBytesScannedFromRemote` | File Cache /
リモートストレージから読み取ったSegmentフッターおよび内部インデックスのデータ量 |
+| `SegmentFooterIndexNumLocalIOTotal` / `SegmentFooterIndexNumRemoteIOTotal` |
Segmentフッターおよび内部インデックスのローカル / リモート読み取り回数 |
+| `SegmentFooterIndexLocalIOUseTimer` / `SegmentFooterIndexRemoteIOUseTimer` |
Segmentフッターおよび内部インデックスのローカル / リモート読み取り時間 |
+
[Query Performance
Analysis](../../query-acceleration/performance-tuning-overview/analysis-tools#doris-profile)を通じてクエリパフォーマンス分析を表示できます。
diff --git
a/versioned_docs/version-4.x/compute-storage-decoupled/file-cache/file-cache-internals.md
b/versioned_docs/version-4.x/compute-storage-decoupled/file-cache/file-cache-internals.md
index f75f3298ba4..808f116b136 100644
---
a/versioned_docs/version-4.x/compute-storage-decoupled/file-cache/file-cache-internals.md
+++
b/versioned_docs/version-4.x/compute-storage-decoupled/file-cache/file-cache-internals.md
@@ -155,6 +155,13 @@ The two types of Compaction use different cache write
strategies:
| Cumulative Compaction | Output data is written to the file cache while being
uploaded to remote storage, consistent with the ingestion flow, to accelerate
subsequent queries. |
| Base Compaction | By default, data is written to the cache only when there
is sufficient cache space, to avoid cache pollution from large volumes of cold
data. You can force writes by setting the BE parameter
`enable_file_cache_keep_base_compaction_output = true`, but this may cause
other hot data to be evicted. |
+When local cache capacity is limited, you can enable an index-only write
policy to prevent Segment data from Compaction output from actively consuming a
large amount of cache space:
+
+- `enable_file_cache_write_index_file_only=true`: Applies to all rowset writes
in compute-storage decoupled mode, including Compaction. Segment data is not
actively cached, while Segment footer/internal-index ranges and independent
inverted-index files are still written to the cache.
+- `enable_file_cache_write_base_compaction_index_only=true` or
`enable_file_cache_write_cumu_compaction_index_only=true`: Only restricts
matching Compaction output that would otherwise be written to the cache.
Segment files are skipped and independent inverted-index files are retained,
but Segment footer/internal-index ranges are not preloaded.
+
+For parameter precedence, configuration examples, and limitations, see [File
Cache Configuration](./file-cache.md).
+
> **Planned:** A future version of Doris will provide an adaptive write
> strategy based on historical query statistics.
### Cache Loading After Restart
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 a5104d3fdd4..5f27b1ed124 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, 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", "cache warmup", "cache quota", "TTL cache", "LRU", "cache hit rate",
"object storage acceleration"]
+ "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"]
}
---
@@ -49,6 +49,72 @@ Doris controls file cache behavior through the following
parameters in the BE co
|---|---|---|
| `enable_file_cache` | `false` | Whether to enable the file cache feature.
Set to `true` in compute-storage decoupled mode. |
+### Configuring Index-Only Cache Writes
+
+When local cache space is limited and query performance depends more heavily
on indexes and Segment metadata, you can enable the index-only write policy.
This policy limits what ingestion, Schema Change, Compaction, and other write
paths **actively write** to File Cache. It does not affect query-side cache
fill after a cache miss or cache warmup.
+
+Doris provides one global policy and two Compaction-specific policies:
+
+| Parameter | Type | Default | Scope | Description |
+|---|---|---|---|---|
+| `enable_file_cache_write_index_file_only` | Boolean | `false` | All rowset
writes in compute-storage decoupled mode, including ingestion, Schema Change,
Cumulative Compaction, and Base Compaction | When set to `true`, Segment data
is not actively cached. After a Segment is closed, its footer and internal
index ranges are synchronously preloaded, while independent inverted index
files are still written to File Cache. This parameter takes precedence over the
two Compaction-specific parameters |
+| `enable_file_cache_write_base_compaction_index_only` | Boolean | `false` |
Base Compaction | Only when the existing Base Compaction policy has already
decided to write output to File Cache, prevents the Segment file from being
actively cached while still caching independent inverted index files. This
parameter does not cause Base Compaction output that would otherwise bypass the
cache to be cached |
+| `enable_file_cache_write_cumu_compaction_index_only` | Boolean | `false` |
Cumulative Compaction | When Cumulative Compaction output is written to File
Cache, prevents the Segment file from being actively cached while still caching
independent inverted index files |
+
+The write path determines cache behavior in the following priority order:
+
+1. `enable_file_cache=false` has the highest priority and disables all File
Cache writes, including Segment footer/internal-index preload and independent
inverted-index writes.
+2. When `enable_file_cache=true` and
`enable_file_cache_write_index_file_only=true`, the global index-only policy is
enabled. The two Compaction-specific parameters no longer change the final
behavior. Adaptive writes, Compaction retention policies, cache-hit-ratio
thresholds, and request-level `write_file_cache` settings cannot cause Segment
data to be actively cached; index-related content is still written according to
the global policy described above.
+3. When the global index-only policy is disabled, the Base/Cumulative
Compaction-specific parameters only further restrict output of the matching
type that has **already been selected for caching**. They do not affect other
write scenarios or the query read path.
+4. When all three index-only parameters are `false`, existing active cache
writes, adaptive writes, and Compaction output retention behavior remain
unchanged.
+
+:::caution
+
+The two Compaction-specific parameters distinguish only between independent
inverted index files and Segment files. They do not trigger the Segment
footer/internal-index range preload used by the global index-only policy. To
actively preserve both independent inverted indexes and Segment internal
indexes and metadata, use `enable_file_cache_write_index_file_only`.
+
+:::
+
+#### Enabling the Global Index-Only Policy
+
+Configure the following settings in `be.conf` on every BE node:
+
+```properties
+enable_file_cache=true
+enable_file_cache_write_index_file_only=true
+enable_file_cache_write_base_compaction_index_only=false
+enable_file_cache_write_cumu_compaction_index_only=false
+```
+
+The expected behavior is as follows:
+
+| Scenario | Content Actively Written to File Cache |
+|---|---|
+| Ingestion, Schema Change, Cumulative Compaction, and Base Compaction |
Segment data is not actively written; Segment footer/internal-index ranges are
synchronously preloaded; independent inverted-index files are written |
+| Query data-page reads | Behavior is unchanged. After a cache miss, Segment
data can still be filled according to the existing read-path rules |
+| Cache warmup | Behavior is unchanged |
+| Packed File | Packed small Segment files are not cached as whole files;
packed independent small index files can still be cached as whole files |
+
+Under the global index-only policy, Segment footer/internal-index ranges are
written to the cache through synchronous reads and are not controlled by
`enable_flush_file_cache_async`. Independent inverted-index files continue to
use the existing direct-write and asynchronous-flush behavior.
+
+#### Restricting Only Compaction Output
+
+To reduce cache pressure from Compaction output without changing active cache
writes for ingestion and Schema Change, configure:
+
+```properties
+enable_file_cache=true
+enable_file_cache_write_index_file_only=false
+enable_file_cache_write_base_compaction_index_only=true
+enable_file_cache_write_cumu_compaction_index_only=true
+```
+
+Cumulative Compaction writes output to the cache by default, so enabling its
corresponding parameter skips Segment files and retains only independent
inverted-index files. Base Compaction still first uses
`enable_file_cache_keep_base_compaction_output` and the input-rowset cache hit
ratio to determine whether to cache its output. The Base Compaction index-only
parameter restricts the written content only after that decision is made.
+
+#### Recommendations
+
+- These three parameters are BE parameters. Keep them consistent across all BE
nodes in the same compute group to prevent nodes from using different
cache-write policies.
+- "Index-only" does not mean that File Cache never contains Segment data.
Query-side reads of cache-missed data pages can still fill Segment data into
the cache.
+- This policy can reduce cache pollution from ingestion and Compaction, but a
large data scan immediately after a write can increase remote-storage reads.
Benchmark it with the production query workload, and monitor Index queue
eviction and index-read metrics in the SQL Profile.
+
### Configuring Cache Paths and Size
```plaintext
@@ -309,6 +375,17 @@ Cache-related metrics in the SQL Profile are located under
the `SegmentIterator`
| `RemoteIOUseTimer` | Time spent reading from remote storage |
| `WriteCacheIOUseTimer` | Time spent writing into the file cache |
+After enabling index-only cache writes, monitor the following categorized
metrics to determine whether independent inverted indexes and Segment
footer/internal-index data are hitting the cache:
+
+| Metric | Description |
+|---|---|
+| `InvertedIndexBytesScannedFromCache` / `InvertedIndexBytesScannedFromRemote`
| Amount of independent inverted-index data read from File Cache / remote
storage |
+| `InvertedIndexNumLocalIOTotal` / `InvertedIndexNumRemoteIOTotal` | Number of
local / remote reads for independent inverted indexes |
+| `InvertedIndexLocalIOUseTimer` / `InvertedIndexRemoteIOUseTimer` | Time
spent on local / remote reads for independent inverted indexes |
+| `SegmentFooterIndexBytesScannedFromCache` /
`SegmentFooterIndexBytesScannedFromRemote` | Amount of Segment footer and
internal-index data read from File Cache / remote storage |
+| `SegmentFooterIndexNumLocalIOTotal` / `SegmentFooterIndexNumRemoteIOTotal` |
Number of local / remote reads for Segment footer and internal-index data |
+| `SegmentFooterIndexLocalIOUseTimer` / `SegmentFooterIndexRemoteIOUseTimer` |
Time spent on local / remote reads for Segment footer and internal-index data |
+
You can view the complete query performance report through [Query Performance
Analysis](../../query-acceleration/performance-tuning-overview/analysis-tools#doris-profile).
## TTL Cache Policy
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
