大网数据广告活动
数据库部署与 SQL 参考

数据缓存

· 52CE 我爱测

数据缓存(Data Cache)通过缓存最近访问的远端存储系统(HDFS 或对象存储)的数据文件到本地磁盘上,加速后续访问相同数据的查询。在频繁访问相同数据的查询场景中,Data Cache 可以避免重复的远端数据访问开销,提升热点数据的查询分析性能和稳定性。

数据缓存(Data Cache)通过缓存最近访问的远端存储系统(HDFS 或对象存储)的数据文件到本地磁盘上,加速后续访问相同数据的查询。在频繁访问相同数据的查询场景中,Data Cache 可以避免重复的远端数据访问开销,提升热点数据的查询分析性能和稳定性。

适用场景

数据缓存功能仅作用于 Hive、Iceberg、Hudi、Paimon 表的查询。对内表查询,或非文件的外表查询(如 JDBC、Elasticsearch)等无效果。

数据缓存是否能提升查询效率,取决于多方面因素,下面给出数据缓存的适用场景:

  • 高速本地磁盘

    建议使用高速本地磁盘,如 SSD 或 NVME 介质的本地磁盘作为数据缓存目录。不建议使用机械硬盘作为数据缓存目录。本质上,需确保本地磁盘的 IO 带宽和 IOPS 显著高于网络带宽、源端存储系统的 IO 带宽和 IOPS,才可能带来明显的性能提升。

  • 足够的缓存空间大小

    数据缓存使用 LRU 策略作为缓存淘汰策略。如果查询的数据并没有明显的冷热区分,则缓存数据有可能处于频繁的更新和汰换过程中,反而可能降低查询性能。推荐查询模式有明显冷热区分(如大部分查询只访问当天的数据,几乎不访问历史数据),并且缓存空间足够存储热数据的场景下开启数据缓存。

  • 远端存储的 IO 延迟不稳定

    这种情况通常出现在 HDFS 存储上。多数企业中不同的业务部门会共用同一套 HDFS,因此可能导致高峰期 HDFS 的 IO 延迟非常不稳定。这种情况下,如需确保 IO 延迟稳定,建议开启数据缓存。但仍需考虑前两种情况。

开启数据缓存

自 4.2 版本起,数据缓存功能默认开启:BE 配置项 enable_file_cache 和会话变量 enable_file_cache 的默认值均为 true。使用时配置 be.conf 中的缓存目录;并通过 FE 参数按会话或全局开启、关闭缓存。

BE 配置

首先,需要在 be.conf 中配置缓存路径信息,并重启 BE 节点让配置生效。

参数 必选项 说明
enable_file_cache 否 是否启用 Data Cache,自 4.2 版本起默认开启。
file_cache_path 是 缓存目录的相关配置,JSON 格式。
clear_file_cache 否 默认 false。如果为 true,则当 BE 节点重启时,会清空缓存目录。

file_cache_path 的配置示例:

file_cache_path=[{"path": "/path/to/file_cache1", "total_size":53687091200},{"path": "/path/to/file_cache2", "total_size":53687091200},{"path": "/path/to/file_cache3", "total_size":53687091200}]

path 是缓存的保存路径,可以配置一个或多个。建议同一块磁盘只配置一个路径。

total_size 是缓存的空间大小上限。单位是字节。超过缓存空间后,会通过 LRU 策略进行缓存数据的淘汰。

FE 配置

单个会话中开启 Data Cache:

SET enable_file_cache = true;

全局开启 Data Cache:

SET GLOBAL enable_file_cache = true;

外部文件扫描仅在 BE 配置项 enable_file_cache、会话变量 enable_file_cache 与缓存准入控制同时开启时才会走缓存。该会话变量对内部表无效。

  • 在存算一体的 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。

缓存可观测性

查看缓存命中情况

执行 set enable_profile=true 打开会话变量,可以在 FE 的 Web 页面的 Queries 标签中查看到作业的 Profile。数据缓存相关的指标如下:

-  FileCache:  0ns
    -  BytesScannedFromCache:  2.02  GB
    -  BytesScannedFromRemote:  0.00  
    -  BytesWriteIntoCache:  0.00  
    -  LocalIOUseTimer:  2s723ms
    -  NumLocalIOTotal:  444
    -  NumRemoteIOTotal:  0
    -  NumSkipCacheIOTotal:  0
    -  RemoteIOUseTimer:  0ns
    -  WriteCacheIOUseTimer:  0ns
  • BytesScannedFromCache:从本地缓存中读取的数据量。

  • BytesScannedFromRemote:从远端读取的数据量。

  • BytesWriteIntoCache:写入缓存的数据量。

  • LocalIOUseTimer:本地缓存的 IO 时间。

  • RemoteIOUseTimer:远端读取的 IO 时间。

  • NumLocalIOTotal:本地缓存的 IO 次数。

  • NumRemoteIOTotal:远端 IO 次数。

  • WriteCacheIOUseTimer:写入缓存的 IO 时间。

如果 BytesScannedFromRemote 为 0,表示全部命中缓存。

监控指标

用户可以通过系统表 file_cache_statistics 查看各个 Backend 节点的缓存统计指标。

缓存的配额

Doris 提供两种相互独立的查询级 Data Cache 限制机制:

机制 主要参数 达到限制后的行为
按缓存占用比例限制 file_cache_query_limit_percent 继续允许缓存未命中回填,并通过查询级 LRU 记录和其他缓存队列释放空间
按远端扫描回填字节数停止写入 file_cache_query_limit_bytes 当下一个缓存块会使累计准入字节数超过阈值时,后续未命中范围从远端读取但不再回填本地缓存

按缓存占用比例限制

该功能自 4.0.3 版本支持。

缓存占用比例限制用于控制单个查询在每个 File Cache 实例中可使用的最大缓存比例。在多用户或复杂查询共享缓存资源的场景下,该机制可以降低单个大查询长期占用过多缓存并淘汰其他热点数据的风险。

该功能涉及 BE 和 FE 两端的配置,以及会话变量(Session Variable)的设置。

1. BE 配置

  • enable_file_cache_query_limit:
    • 类型:Boolean
    • 默认值:false
    • 说明:BE 端文件缓存查询限制功能的主开关。只有开启此开关,BE 才会处理 FE 传递的查询限制参数。

2. FE 配置

  • file_cache_query_limit_max_percent:
    • 类型:Integer
    • 默认值:100
    • 说明:查询的最大配额约束,用于校验会话变量的上限。它确保用户设置的查询限制不会超过此值。

3. 会话变量 (Session Variables)

  • file_cache_query_limit_percent:
    • 类型:Integer (1-100)
    • 默认值:-1
    • 说明:文件缓存查询限制百分比。设置单个查询可使用的最大缓存比例。该值上限受 file_cache_query_limit_max_percent 约束。建议计算后的缓存配额不低于 256MB,如果低于该值,BE 会在日志中进行告警提示。

使用示例

-- 设置会话变量,限制单个查询最多使用 50% 的缓存
SET file_cache_query_limit_percent = 50;

-- 执行查询
SELECT * FROM large_table;

注意:

  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:

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;查询完成后恢复默认值:

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,不能单独作为阈值触发依据。

  • 该机制仅限制存算分离 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 约束。有关完整参数范围和内表行为,参见文件缓存配置与使用指南。

缓存预热

Data Cache 提供缓存“预热(Warmup)”功能,允许将外部数据提前加载到 BE 节点的本地缓存中,从而提升后续首次查询的命中率和查询性能。

该功能自 4.0.2 版本支持。

语法

WARM UP SELECT <select_expr_list>
FROM <table_reference>
[WHERE <boolean_expression>]

使用限制:

  • 支持:

    • 单表查询(仅允许一个 table_reference)
    • 指定列的简单 SELECT
    • WHERE 过滤(支持常规谓词)
  • 不支持:

    • JOIN、UNION、子查询、CTE
    • GROUP BY、HAVING、ORDER BY
    • LIMIT
    • INTO OUTFILE
    • 多表 / 复杂查询计划
    • 其它复杂语法

示例

  1. 预热整张表
WARM UP SELECT * FROM hive_db.tpch100_parquet.lineitem;
  1. 根据分区预热部分列
WARM UP SELECT l_orderkey, l_shipmode
FROM hive_db.tpch100_parquet.lineitem
WHERE dt = '2025-01-01';
  1. 根据过滤条件预热部分列
WARM UP SELECT l_shipmode, l_linestatus
FROM hive_db.tpch100_parquet.lineitem
WHERE l_orderkey = 123456;

执行返回结果

执行 WARM UP SELECT 后,FE 会下发任务至各 BE。BE 扫描远端数据并写入 Data Cache。

系统会直接返回各 BE 的扫描与缓存写入统计信息(注意:统计信息基本准确,但会有一定误差)。例如:

+---------------+-----------+-------------+---------------------------+----------------------------+---------------------+
| BackendId     | ScanRows  | ScanBytes   | ScanBytesFromLocalStorage | ScanBytesFromRemoteStorage | BytesWriteIntoCache |
+---------------+-----------+-------------+---------------------------+----------------------------+---------------------+
| 1755134092928 | 294744184 | 11821864798 | 538154009                 | 11283717130                | 11899799492         |
| 1755134092929 | 305293718 | 12244439301 | 560970435                 | 11683475207                | 12332861380         |
| TOTAL         | 600037902 | 24066304099 | 1099124444                | 22967192337                | 24232660872         |
+---------------+-----------+-------------+---------------------------+----------------------------+---------------------+

字段解释

  • ScanRows:扫描读取行数。
  • ScanBytes:扫描读取数据量。
  • ScanBytesFromLocalStorage:从本地缓存扫描读取的数据量。
  • ScanBytesFromRemoteStorage:从远端存储扫描读取的数据量。
  • BytesWriteIntoCache:本次预热写入 Data Cache 的数据量。

缓存准入控制

该功能为实验性功能,自 4.1.0 版本起支持。

通过缓存准入控制功能,用户可以基于操作用户、Catalog、Database 以及 Table 等维度配置规则,精细化管理查询产生的数据是否允许写入 Data Cache。

在某些业务场景(如全表扫描的大规模 ETL 作业或不可预期的 Ad-hoc 分析)中,大量的冷数据读取可能会迅速填满缓存空间,导致高频访问的“热数据”被频繁置换(即缓存污染问题)。此时系统整体的缓存命中率和查询性能将出现严重下滑。通过配置缓存准入规则拒绝此类作业的数据进入缓存,可以有效保护热数据,确保整个系统的 Data Cache 命中率维持在稳定水平。

缓存准入控制功能默认关闭,需要在 FE 节点上配置相关参数来开启。

FE 配置

需要在 FE 节点的配置文件 fe.conf 中新增如下参数以开启缓存准入控制。开启及配置目录路径需要重启 FE 节点生效,但目录下规则文件的修改支持动态加载。

参数 必选项 说明
enable_file_cache_admission_control 是 是否启用缓存准入控制功能。默认为 false(不启用)。
file_cache_admission_control_json_dir 是 存放缓存准入规则 JSON 文件的目录路径。该目录下的所有 .json 文件均会被自动加载并实时监听修改,规则更替动态生效无需重启节点。

准入控制规则配置

规则文件应存放于 file_cache_admission_control_json_dir 所配置的目录下,且后缀需为 .json。

参数说明

规则以 JSON 数组形式提供,每个 JSON Object 代表一条规则,各字段及说明如下:

字段名 类型 说明 示例
id Long 规则 ID,供用户区分不同的规则。 1
user_identity String 用户标识(格式为 user@host,其中 % 表示匹配所有 IP)。留空 ("") 表示匹配全局所有用户。 "root@%"
catalog_name String Catalog 名称。留空 ("") 表示匹配所有 Catalog。 "hive_cat"
database_name String Database 名称。留空 ("") 表示匹配所有 Database。 "db1"
table_name String Table 名称。留空 ("") 表示匹配所有表。 "tbl1"
partition_pattern String (当前版本暂未实现)分区正则表达式。留空表示匹配所有分区。 ""
rule_type Integer 规则类型。0 表示禁止缓存(黑名单);1 表示允许缓存(白名单)。 0
enabled Integer 该规则是否生效启用。0 表示停用;1 表示启用。 1
created_time Long 记录的创建时间(UNIX 时间戳,秒)。 1766557246
updated_time Long 记录的最新更新时间(UNIX 时间戳,秒)。 1766557246

JSON 文件样例

[
  {
    "id": 1,
    "user_identity": "root@%",
    "catalog_name": "hive_cat",
    "database_name": "db1",
    "table_name": "table1",
    "partition_pattern": "",
    "rule_type": 0,
    "enabled": 1,
    "created_time": 1766557246,
    "updated_time": 1766557246
  },
  {
    "id": 2,
    "user_identity": "",
    "catalog_name": "hive_cat",
    "database_name": "",
    "table_name": "",
    "partition_pattern": "",
    "rule_type": 1,
    "enabled": 1,
    "created_time": 1766557246,
    "updated_time": 1766557246
  }
]

从 MySQL 导入规则

对于有自动化系统对接需求的用户,在 Doris 源码库 tools/export_mysql_rule_to_json.sh 路径下提供了辅助脚本。可以使用该脚本将预先存储在 MySQL 数据库表中的缓存准入规则导出为符合上述格式的 JSON 配置文件。

规则匹配原理

规则作用域分类

根据填写的字段明确程度,规则支持以下几种层级和形式的生效范围:

user_identity catalog_name database_name table_name 级别与作用域
非空 非空 非空 非空 指定用户・Table 级规则
空缺或留空 非空 非空 非空 全体用户・Table 级规则
非空 非空 非空 空缺或留空 指定用户・Database 级规则
空缺或留空 非空 非空 空缺或留空 全体用户・Database 级规则
非空 非空 空缺或留空 空缺或留空 指定用户・Catalog 级规则
空缺或留空 非空 空缺或留空 空缺或留空 全体用户・Catalog 级规则
非空 空缺或留空 空缺或留空 空缺或留空 指定用户・全局规则

说明:

  • 空缺或留空:表示该字段在 JSON 中配置为空字符串 "" 或者是直接省略不配置(效果等同于空字符串 "")。
  • 非空:表示对应字段必须是一个明确的值(如 "hive_cat")。
  • 任何跳跃或不符合层级依赖关系的规则配置均视为无效规则,不会被解析生效。例如:配置了 database_name 但 catalog_name 为空。

匹配及优先级顺序

判定某个查询访问目标表数据时是否写入缓存,受配置的多条规则综合影响。匹配原则如下:

  1. 精确优先原则:按层级由明细到宽泛的顺序(Table → Database → Catalog → 全局)进行匹配,优先匹配精确度更高的规则。
  2. 拒绝优先(安全优先):在同一个规则内或同级别(如既存在指定用户的黑名单规则,又存在全局的白名单规则),禁止缓存(黑名单)规则的优先级永远高于允许缓存(白名单)规则。拒绝访问的决策最先被识别生效。

完整的决策推导链路如下:

1. Table 级规则匹配
   a) 命中黑名单 (rule_type=0) -> 拒绝
   b) 命中白名单 (rule_type=1) -> 允许
2. Database 级规则匹配
   ...
3. Catalog 级规则匹配
   ...
4. 全局规则匹配 (仅匹配 user_identity)
   ...
5. 兜底默认决策:如果所有的层级也没有匹配上,系统默认【拒绝】写入缓存操作(等同全局黑名单)。

提示:由于系统默认兜底为拒绝准入,因此在实际部署该功能时,最佳实践通常是建立一条广泛的全局允许规则(如全员白名单,或某个重要业务 Catalog 的白名单),然后再针对已知会进行全表扫描的大表配置针对性的 Table 级黑名单,由此实现精细化的冷热数据剥离。

缓存决策可观测性

当开启规则并在系统中生效起作用后,用户可以通过向目标表发送 EXPLAIN 命令,审查其 File Cache 准入控制决策情况(聚焦关注节点下方的 file cache request 决策输出信息)。

|   0:VHIVE_SCAN_NODE(74)                                                                                          |
|      table: test_file_cache_features.tpch1_parquet.lineitem                                                      |
|      inputSplitNum=10, totalFileSize=205792918, scanRanges=10                                                    |
|      partition=1/1                                                                                               |
|      cardinality=1469949, numNodes=1                                                                             |
|      pushdown agg=NONE                                                                                           |
|      file cache request ADMITTED: user_identity:root@%, reason:user table-level whitelist rule, cost:0.058 ms    |
|      limit: 1                                                                                                    |

重点字段与判定说明:

  • ADMITTED / DENIED:代表请求被允许写入缓存(ADMITTED)或被直接拒绝(DENIED)。如果被拒绝,数据访问直接击穿至远端底层存储。
  • user_identity:执行本次查询鉴别出的用户凭证身份。
  • reason:命中判定策略的具体原因说明。常见的输出原因如:user table-level whitelist rule(当前示例:指定用户 Table 级白名单规则);common table-level blacklist rule(全体用户 Table 级黑名单规则)。此类原因格式一般为 [作用范围] [规则级别] [规则类型] rule。
  • cost:完成整个准入匹配计算过程的耗时开销(以毫秒 ms 为单位)。如果开销过大,可通过简化规则层级数进行调整。

附录

原理

数据缓存将访问的远程数据缓存到本地的 BE 节点。原始的数据文件会根据访问的 IO 大小切分为 Block,Block 被存储到本地文件 cache_path/hash(filepath).substr(0, 3)/hash(filepath)/offset 中,并在 BE 节点中保存 Block 的元信息。当访问相同的远程文件时,Doris 会检查本地缓存中是否存在该文件的缓存数据,并根据 Block 的 offset 和 size,确认哪些数据从本地 Block 读取,哪些数据从远程拉取,并缓存远程拉取的新数据。BE 节点重启的时候,扫描 cache_path 目录,恢复 Block 的元信息。当缓存大小达到阈值上限的时候,按照 LRU 原则清理长久未访问的 Block。

本文来自 Apache Doris 文档贡献者,按 Apache 2.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
Apache Doris 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
Apache 2.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。