This is an automated email from the ASF dual-hosted git repository.
morningman 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 e778825270c [docs](file-cache) Document file cache enabled by default
since 4.2 (#4202)
e778825270c is described below
commit e778825270c19405ae64c69e36bafc73fd606ead
Author: daidai <[email protected]>
AuthorDate: Sat Oct 10 12:18:00 2026 +0800
[docs](file-cache) Document file cache enabled by default since 4.2 (#4202)
### What problem does this PR solve?
Apache Doris enables the block file cache by default since 4.2: both the
BE config `enable_file_cache` and the session variable
`enable_file_cache` default to `true` (apache/doris#66684,
apache/doris#68797). The docs still described the old behavior (`false`
for non-cloud mode, and "disabled by default" for Data Cache).
### What is changed?
- `enable_file_cache` default updated from `false` to `true` in the BE
config reference, the Data Cache page, and the compute-storage-decoupled
File Cache page.
- Clarified that an external file scan reads through the cache only when
the BE config, the session variable, and cache admission control are all
enabled; the session variable has no effect on internal tables.
- Added caveats for the new default: the default cache path
`${DORIS_HOME}/file_cache` may grow until the disk is 85%–88% full
(bound it with `total_size`, or set `enable_file_cache = false` to keep
the old behavior); BE configs are not persisted while session variables
are persisted in the FE image, so a cluster upgraded from an older
version keeps its previous value and needs `SET GLOBAL enable_file_cache
= true` to cache external tables.
- Applied to `docs/` (dev) and `versioned_docs/version-4.x/`, English
and Chinese.
## Versions
- [x] dev
- [x] 4.x
- [ ] 3.x
- [ ] 2.1 or older (not covered by version/language sync gate)
## Languages
- [x] Chinese
- [x] English
## 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
---
docs/admin-manual/config/be-config.md | 2 +-
docs/compute-storage-decoupled/file-cache/file-cache.md | 8 +++++++-
docs/key-features/data-cache-page-cache.mdx | 2 +-
docs/lakehouse/data-cache.md | 13 ++++++++++---
.../current/admin-manual/config/be-config.md | 2 +-
.../compute-storage-decoupled/file-cache/file-cache.md | 8 +++++++-
.../current/lakehouse/data-cache.md | 13 ++++++++++---
.../version-4.x/admin-manual/config/be-config.md | 2 +-
.../compute-storage-decoupled/file-cache/file-cache.md | 8 +++++++-
.../version-4.x/lakehouse/data-cache.md | 13 ++++++++++---
versioned_docs/version-4.x/admin-manual/config/be-config.md | 2 +-
.../compute-storage-decoupled/file-cache/file-cache.md | 8 +++++++-
.../version-4.x/key-features/data-cache-page-cache.mdx | 2 +-
versioned_docs/version-4.x/lakehouse/data-cache.md | 13 ++++++++++---
14 files changed, 74 insertions(+), 22 deletions(-)
diff --git a/docs/admin-manual/config/be-config.md
b/docs/admin-manual/config/be-config.md
index 6ecfc456939..451125c8d4a 100644
--- a/docs/admin-manual/config/be-config.md
+++ b/docs/admin-manual/config/be-config.md
@@ -1406,7 +1406,7 @@ Default: ""
#### `enable_file_cache`
-Default: true for cloud mode, false for non-cloud mode.
+Default: true (enabled by default since Doris 4.2; always on in cloud mode).
* Description: Whether to use file cache.
#### `file_cache_path`
diff --git a/docs/compute-storage-decoupled/file-cache/file-cache.md
b/docs/compute-storage-decoupled/file-cache/file-cache.md
index b9400fa5207..8df568956a4 100644
--- a/docs/compute-storage-decoupled/file-cache/file-cache.md
+++ b/docs/compute-storage-decoupled/file-cache/file-cache.md
@@ -47,7 +47,13 @@ Doris controls file cache behavior through the following
parameters in the BE co
| Parameter | Default | Description |
|---|---|---|
-| `enable_file_cache` | `false` | Whether to enable the file cache feature.
Set to `true` in compute-storage decoupled mode. |
+| `enable_file_cache` | `true` | Whether to enable the file cache feature.
Enabled by default since Doris 4.2. In compute-storage decoupled mode, BE
always forces it on. |
+
+:::caution
+
+`file_cache_path` defaults to the storage directory under the BE deployment
path. Without a `total_size`, the cache may grow until the disk is 85%–88%
full; set a `total_size` to bound it.
+
+:::
### Configuring Index-Only Cache Writes
diff --git a/docs/key-features/data-cache-page-cache.mdx
b/docs/key-features/data-cache-page-cache.mdx
index 762702f23d1..50c05e4e3c0 100644
--- a/docs/key-features/data-cache-page-cache.mdx
+++ b/docs/key-features/data-cache-page-cache.mdx
@@ -67,7 +67,7 @@ Apache Doris funnels every lakehouse scan through the Page
Cache first, then the
```sql
-- One-time setup on each BE: configure a cache directory.
--- be.conf:
+-- be.conf (enable_file_cache is enabled by default since Doris 4.2):
-- enable_file_cache = true
-- file_cache_path = [{"path":"/data/file_cache","total_size":107374182400}]
diff --git a/docs/lakehouse/data-cache.md b/docs/lakehouse/data-cache.md
index 7cdd83c1137..9544176d89e 100644
--- a/docs/lakehouse/data-cache.md
+++ b/docs/lakehouse/data-cache.md
@@ -28,7 +28,7 @@ Whether data caching can improve query efficiency depends on
multiple factors. B
## Enabling Data Cache
-The data cache function is disabled by default and needs to be enabled by
setting relevant parameters in FE and BE.
+Data Cache is enabled by default since Doris 4.2: both the BE config
`enable_file_cache` and the session variable `enable_file_cache` default to
`true`. To use it, configure the cache directory in `be.conf`; use the FE
parameter to enable or disable caching for a session or globally.
### BE Configuration
@@ -36,7 +36,7 @@ First, configure the cache path information in `be.conf` and
restart the BE node
| Parameter | Required | Description |
| ------------------- | --- | -------------------------------------- |
-| `enable_file_cache` | Yes | Whether to enable Data Cache, default is false
|
+| `enable_file_cache` | No | Whether to enable Data Cache, enabled by
default since Doris 4.2. |
| `file_cache_path` | Yes | Configuration related to the cache directory,
in JSON format. |
| `clear_file_cache` | No | Default is false. If true, the cache directory
will be cleared when the BE node restarts. |
@@ -64,7 +64,14 @@ Enable Data Cache globally:
SET GLOBAL enable_file_cache = true;
```
-Note that if `enable_file_cache` is not enabled, the cache will not be used
even if the BE is configured with a cache directory. Similarly, if the BE is
not configured with a cache directory, the cache will not be used even if
`enable_file_cache` is enabled.
+An external file scan reads through the cache only when the BE config
`enable_file_cache`, the session variable `enable_file_cache`, and cache
admission control are all enabled. The session variable has no effect on
internal tables.
+
+:::caution[File Cache is enabled by default since Doris 4.2]
+
+- On a storage-compute-coupled BE that does not set `file_cache_path`, the
cache is created under `${DORIS_HOME}/file_cache` and, without a `total_size`,
may grow until the disk is 85%–88% full. Set `file_cache_path` with a
`total_size` to bound it, or set `enable_file_cache = false` in `be.conf` to
keep the previous behavior.
+- BE configs are not persisted, so an upgraded BE uses the default compiled
into its binary unless `be.conf` sets the key. Session variables are persisted
in the FE image, so a cluster upgraded from an older version keeps its previous
value; to cache external tables after upgrading, run `SET GLOBAL
enable_file_cache = true`.
+
+:::
## Cache Observability
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/config/be-config.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/config/be-config.md
index 76c76e16fae..896ad40be96 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/config/be-config.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/config/be-config.md
@@ -1381,7 +1381,7 @@ load tablets from header failed, failed tablets size:
xxx, path=xxx
#### `enable_file_cache`
-* 默认值：在存算分离模式下为 true，在非存算分离模式下为 false。
+* 默认值：true（自 4.2 版本起默认开启；存算分离模式下始终开启）。
* 描述：是否使用文件缓存。
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 184e4d77170..3c4cc897679 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
@@ -47,7 +47,13 @@ Doris 通过 BE 配置文件中的以下参数控制文件缓存行为。
| 参数 | 默认值 | 说明 |
|---|---|---|
-| `enable_file_cache` | `false` | 是否启用文件缓存功能。存算分离模式下建议设置为 `true`。 |
+| `enable_file_cache` | `true` | 是否启用文件缓存功能。自 4.2 版本起默认开启；存算分离模式下 BE 会强制开启。 |
+
+:::caution
+
+`file_cache_path` 默认使用 BE 部署目录下的存储目录。未设置 `total_size` 时，缓存可能增长到磁盘的
85%–88%，建议设置 `total_size` 加以限制。
+
+:::
### 配置写入路径仅缓存索引
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 74df8a7263f..084993bab26 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
@@ -28,7 +28,7 @@
## 开启数据缓存
-数据缓存功能是默认关闭的，需要在 FE 和 BE 中设置相关参数进行开启。
+自 4.2 版本起，数据缓存功能默认开启：BE 配置项 `enable_file_cache` 和会话变量 `enable_file_cache`
的默认值均为 `true`。使用时配置 `be.conf` 中的缓存目录；并通过 FE 参数按会话或全局开启、关闭缓存。
### BE 配置
@@ -36,7 +36,7 @@
| 参数 | 必选项 | 说明 |
| ------------------- | --- | -------------------------------------- |
-| `enable_file_cache` | 是 | 是否启用 Data Cache，默认 false |
+| `enable_file_cache` | 否 | 是否启用 Data Cache，自 4.2 版本起默认开启。 |
| `file_cache_path` | 是 | 缓存目录的相关配置，JSON 格式。 |
| `clear_file_cache` | 否 | 默认 false。如果为 true，则当 BE 节点重启时，会清空缓存目录。 |
@@ -64,7 +64,14 @@ SET enable_file_cache = true;
SET GLOBAL enable_file_cache = true;
```
-注意，如果没有开启 `enable_file_cache`，即使 BE 配置了缓存目录，也不会使用缓存。同样，如果 BE 没有配置缓存目录，即使开启
`enable_file_cache`，也不会使用缓存。
+外部文件扫描仅在 BE 配置项 `enable_file_cache`、会话变量 `enable_file_cache`
与缓存准入控制同时开启时才会走缓存。该会话变量对内部表无效。
+
+:::caution[自 4.2 版本起文件缓存默认开启]
+
+- 在存算一体的 BE 上，如果没有设置 `file_cache_path`，缓存会创建在 `${DORIS_HOME}/file_cache` 下；未设置
`total_size` 时，缓存可能增长到磁盘的 85%–88%。建议为 `file_cache_path` 设置 `total_size` 加以限制，或在
`be.conf` 中设置 `enable_file_cache = false` 以保持原有行为。
+- BE 配置不会持久化：升级后的 BE 在没有显式配置该项时，使用二进制内置的默认值。会话变量会持久化到 FE
image，因此从旧版本升级的集群会保留原有取值；升级后如需让外部表走缓存，请执行 `SET GLOBAL enable_file_cache = true`。
+
+:::
## 缓存可观测性
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/admin-manual/config/be-config.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/admin-manual/config/be-config.md
index a99c7f66b43..0a92e0cfefd 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/admin-manual/config/be-config.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/admin-manual/config/be-config.md
@@ -1375,7 +1375,7 @@ load tablets from header failed, failed tablets size:
xxx, path=xxx
#### `enable_file_cache`
-* 默认值：在存算分离模式下为 true，在非存算分离模式下为 false。
+* 默认值：true（自 4.2 版本起默认开启；存算分离模式下始终开启）。
* 描述：是否使用文件缓存。
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 618dfa9d310..e3c1e7fc2d8 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
@@ -47,7 +47,13 @@ Doris 通过 BE 配置文件中的以下参数控制文件缓存行为。
| 参数 | 默认值 | 说明 |
|---|---|---|
-| `enable_file_cache` | `false` | 是否启用文件缓存功能。存算分离模式下建议设置为 `true`。 |
+| `enable_file_cache` | `true` | 是否启用文件缓存功能。自 4.2 版本起默认开启；存算分离模式下 BE 会强制开启。 |
+
+:::caution
+
+`file_cache_path` 默认使用 BE 部署目录下的存储目录。未设置 `total_size` 时，缓存可能增长到磁盘的
85%–88%，建议设置 `total_size` 加以限制。
+
+:::
### 配置写入路径仅缓存索引
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 b1d74a0d4c5..1ad85938af9 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
@@ -28,7 +28,7 @@
## 开启数据缓存
-数据缓存功能是默认关闭的，需要在 FE 和 BE 中设置相关参数进行开启。
+自 4.2 版本起，数据缓存功能默认开启：BE 配置项 `enable_file_cache` 和会话变量 `enable_file_cache`
的默认值均为 `true`。使用时配置 `be.conf` 中的缓存目录；并通过 FE 参数按会话或全局开启、关闭缓存。
### BE 配置
@@ -36,7 +36,7 @@
| 参数 | 必选项 | 说明 |
| ------------------- | --- | -------------------------------------- |
-| `enable_file_cache` | 是 | 是否启用 Data Cache，默认 false |
+| `enable_file_cache` | 否 | 是否启用 Data Cache，自 4.2 版本起默认开启。 |
| `file_cache_path` | 是 | 缓存目录的相关配置，JSON 格式。 |
| `clear_file_cache` | 否 | 默认 false。如果为 true，则当 BE 节点重启时，会清空缓存目录。 |
@@ -64,7 +64,14 @@ SET enable_file_cache = true;
SET GLOBAL enable_file_cache = true;
```
-注意，如果没有开启 `enable_file_cache`，即使 BE 配置了缓存目录，也不会使用缓存。同样，如果 BE 没有配置缓存目录，即使开启
`enable_file_cache`，也不会使用缓存。
+外部文件扫描仅在 BE 配置项 `enable_file_cache`、会话变量 `enable_file_cache`
与缓存准入控制同时开启时才会走缓存。该会话变量对内部表无效。
+
+:::caution[自 4.2 版本起文件缓存默认开启]
+
+- 在存算一体的 BE 上，如果没有设置 `file_cache_path`，缓存会创建在 `${DORIS_HOME}/file_cache` 下；未设置
`total_size` 时，缓存可能增长到磁盘的 85%–88%。建议为 `file_cache_path` 设置 `total_size` 加以限制，或在
`be.conf` 中设置 `enable_file_cache = false` 以保持原有行为。
+- BE 配置不会持久化：升级后的 BE 在没有显式配置该项时，使用二进制内置的默认值。会话变量会持久化到 FE
image，因此从旧版本升级的集群会保留原有取值；升级后如需让外部表走缓存，请执行 `SET GLOBAL enable_file_cache = true`。
+
+:::
## 缓存可观测性
diff --git a/versioned_docs/version-4.x/admin-manual/config/be-config.md
b/versioned_docs/version-4.x/admin-manual/config/be-config.md
index 97b71187533..4650cddd4da 100644
--- a/versioned_docs/version-4.x/admin-manual/config/be-config.md
+++ b/versioned_docs/version-4.x/admin-manual/config/be-config.md
@@ -1400,7 +1400,7 @@ Default: ""
#### `enable_file_cache`
-Default: true for cloud mode, false for non-cloud mode.
+Default: true (enabled by default since Doris 4.2; always on in cloud mode).
* Description: Whether to use file cache.
#### `file_cache_path`
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 2b1bb6bb4c5..18b6eb63d33 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
@@ -47,7 +47,13 @@ Doris controls file cache behavior through the following
parameters in the BE co
| Parameter | Default | Description |
|---|---|---|
-| `enable_file_cache` | `false` | Whether to enable the file cache feature.
Set to `true` in compute-storage decoupled mode. |
+| `enable_file_cache` | `true` | Whether to enable the file cache feature.
Enabled by default since Doris 4.2. In compute-storage decoupled mode, BE
always forces it on. |
+
+:::caution
+
+`file_cache_path` defaults to the storage directory under the BE deployment
path. Without a `total_size`, the cache may grow until the disk is 85%–88%
full; set a `total_size` to bound it.
+
+:::
### Configuring Index-Only Cache Writes
diff --git a/versioned_docs/version-4.x/key-features/data-cache-page-cache.mdx
b/versioned_docs/version-4.x/key-features/data-cache-page-cache.mdx
index 762702f23d1..50c05e4e3c0 100644
--- a/versioned_docs/version-4.x/key-features/data-cache-page-cache.mdx
+++ b/versioned_docs/version-4.x/key-features/data-cache-page-cache.mdx
@@ -67,7 +67,7 @@ Apache Doris funnels every lakehouse scan through the Page
Cache first, then the
```sql
-- One-time setup on each BE: configure a cache directory.
--- be.conf:
+-- be.conf (enable_file_cache is enabled by default since Doris 4.2):
-- enable_file_cache = true
-- file_cache_path = [{"path":"/data/file_cache","total_size":107374182400}]
diff --git a/versioned_docs/version-4.x/lakehouse/data-cache.md
b/versioned_docs/version-4.x/lakehouse/data-cache.md
index 0ba7f6195f4..555ea7f7da2 100644
--- a/versioned_docs/version-4.x/lakehouse/data-cache.md
+++ b/versioned_docs/version-4.x/lakehouse/data-cache.md
@@ -28,7 +28,7 @@ Whether data caching can improve query efficiency depends on
multiple factors. B
## Enabling Data Cache
-The data cache function is disabled by default and needs to be enabled by
setting relevant parameters in FE and BE.
+Data Cache is enabled by default since Doris 4.2: both the BE config
`enable_file_cache` and the session variable `enable_file_cache` default to
`true`. To use it, configure the cache directory in `be.conf`; use the FE
parameter to enable or disable caching for a session or globally.
### BE Configuration
@@ -36,7 +36,7 @@ First, configure the cache path information in `be.conf` and
restart the BE node
| Parameter | Required | Description |
| ------------------- | --- | -------------------------------------- |
-| `enable_file_cache` | Yes | Whether to enable Data Cache, default is false
|
+| `enable_file_cache` | No | Whether to enable Data Cache, enabled by
default since Doris 4.2. |
| `file_cache_path` | Yes | Configuration related to the cache directory,
in JSON format. |
| `clear_file_cache` | No | Default is false. If true, the cache directory
will be cleared when the BE node restarts. |
@@ -64,7 +64,14 @@ Enable Data Cache globally:
SET GLOBAL enable_file_cache = true;
```
-Note that if `enable_file_cache` is not enabled, the cache will not be used
even if the BE is configured with a cache directory. Similarly, if the BE is
not configured with a cache directory, the cache will not be used even if
`enable_file_cache` is enabled.
+An external file scan reads through the cache only when the BE config
`enable_file_cache`, the session variable `enable_file_cache`, and cache
admission control are all enabled. The session variable has no effect on
internal tables.
+
+:::caution[File Cache is enabled by default since Doris 4.2]
+
+- On a storage-compute-coupled BE that does not set `file_cache_path`, the
cache is created under `${DORIS_HOME}/file_cache` and, without a `total_size`,
may grow until the disk is 85%–88% full. Set `file_cache_path` with a
`total_size` to bound it, or set `enable_file_cache = false` in `be.conf` to
keep the previous behavior.
+- BE configs are not persisted, so an upgraded BE uses the default compiled
into its binary unless `be.conf` sets the key. Session variables are persisted
in the FE image, so a cluster upgraded from an older version keeps its previous
value; to cache external tables after upgrading, run `SET GLOBAL
enable_file_cache = true`.
+
+:::
## Cache Observability
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
