StarRocks Data Cache 故障排查完全指南启用确认、命中率分析与性能调优【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocksData Cache 是 StarRocks 将远端存储HDFS、对象存储中的数据按块缓存到本地内存与磁盘从而加速数据湖分析查询的核心特性。本文围绕 Data Cache 常见问题展开覆盖「如何确认缓存是否启用、为何默认未启用、如何判断查询是否命中缓存、缓存未命中如何排查、命中率上不去怎么办、如何清理缓存与提升性能」等高频问题并结合仓库源码BE 配置定义、缓存模块实现给出可验证的排查步骤与配置依据。读完本文你可以独立定位大多数 Data Cache 相关的故障并掌握从SHOW BACKENDS到查询 Profile、再到 BE HTTP 接口的完整排查链路。快速确认 Data Cache 是否成功启用通过 SHOW BACKENDS / SHOW COMPUTE NODES 查看配额在 SQL 客户端执行SHOW BACKENDS共享数据集群中执行SHOW COMPUTE NODES检查输出中的DataCacheMetrics字段。只要磁盘缓存配额或内存缓存配额大于 0即可确认 Data Cache 已启用。mysql show backends \G *************************** 1. row *************************** BackendId: 89041 IP: X.X.X.X HeartbeatPort: 9050 BePort: 9060 HttpPort: 8040 BrpcPort: 8060 LastStartTime: 2025-05-29 14:45:37 LastHeartbeat: 2025-05-29 19:20:32 Alive: true SystemDecommissioned: false ClusterDecommissioned: false TabletNum: 10 DataUsedCapacity: 0.000 B AvailCapacity: 1.438 TB TotalCapacity: 1.718 TB UsedPct: 16.27 % MaxDiskUsedPct: 16.27 % ErrMsg: Version: main-c15b412 Status: {lastSuccessReportTabletsTime:2025-05-29 19:20:30} DataTotalCapacity: 1.438 TB DataUsedPct: 0.00 % CpuCores: 8 MemLimit: 50.559GB NumRunningQueries: 0 MemUsedPct: 0.50 % CpuUsedPct: 0.2 % DataCacheMetrics: Status: Normal, DiskUsage: 44MB/1TB, MemUsage: 0B/0B Location: StatusCode: OK 1 row in set (0.00 sec)上例中DiskUsage: 44MB/1TB表示磁盘缓存配额为 1TB、当前已使用 44MBMemUsage: 0B/0B表示内存缓存配额为 0即内存缓存未启用。Status: Normal表示缓存实例运行正常其他取值见下文 BE HTTP 接口一节包括ABNORMAL与UPDATING。如需查看每个 BE 更细粒度的缓存容量与用量还可以查询information_schema.be_datacache_metrics视图其中DISK_QUOTA_BYTES、DISK_USED_BYTES、MEM_QUOTA_BYTES、MEM_USED_BYTES、META_USED_BYTES分别对应磁盘缓存配额、磁盘缓存已用空间、内存缓存配额、内存缓存已用空间与元数据缓存占用DIR_SPACES则给出缓存路径及每个路径的配额详见 Data Cache 观测指南。通过 BE Web Console 查看运行指标访问 BE 的 Web Console 地址http://${BE_HOST}:${BE_HTTP_PORT}/api/datacache/stat可查看当前 Data Cache 的配额、命中率等底层执行指标。若disk_quota_bytes或mem_quota_bytes大于 0即说明 Data Cache 已启用。该接口返回的字段与SHOW BACKENDS互补例如block_cache_disk_quota_bytes/block_cache_disk_used_bytes反映磁盘块缓存配额与用量block_cache_hit_rate给出累计命中率block_cache_status表示缓存实例状态NORMAL正常、ABNORMAL数据读写异常需结合日志定位、UPDATING表示实例正在更新例如在线扩缩容过程。注意该接口展示的是 Data Cache 底层执行状态并不直接等于查询层的实际命中率查询层命中率请优先使用下文「如何判断查询命中缓存」一节的方法。为什么 Data Cache 默认未启用从 v3.3 起BE 启动时会尝试自动启用Data Cache但如果当前磁盘可用空间不足则不会自动启用。常见诱因有两类磁盘使用率过高Percentage当前磁盘占用比例已很高剩余空间不足Remaining space磁盘剩余可用空间偏少。排查时先检查当前磁盘使用情况必要时扩容磁盘也可以根据当前可用磁盘空间手动配置缓存配额来启用 Data Cache# 关闭 Data Cache 自动调整 datacache_auto_adjust_enable false # 手动设置 Data Cache 磁盘配额 datacache_disk_size 1T从源码角度理解这一行为Data Cache 的磁盘配额默认值为100%见 be/src/common/config.h#L1822 中CONF_mString(datacache_disk_size, 100%)即默认按磁盘总容量的一定百分比分配。当 BE 启动解析该配额时若磁盘余量不足以支撑缓存初始化就会放弃自动启用。此外BE 还提供自动扩容机制当磁盘用量持续低于disk_low_level阈值默认 60%且缓存已写满时系统会自动将缓存容量扩张到disk_safe_level默认 80%对应的水位当磁盘用量超过disk_high_level默认 90%时自动驱逐缓存数据释放空间。这三个阈值同样定义在 be/src/common/config.h#L97-L104并由磁盘空间监控线程在运行时读取计算参见 be/src/cache/disk_space_monitor.cpp#L124-L126。因此当遇到缓存没有按预期自动启用时本质是磁盘水位与这些阈值共同作用的结果优先检查磁盘剩余空间是最直接的切入点。Data Cache 支持哪些 Catalog 类型Data Cache 当前支持使用 StarRocks 原生文件读取器Native File Reader访问数据的外部 Catalog例如 Parquet/ORC/CSV Reader 对应的 Hive、Iceberg、Hudi、Delta Lake 与 Paimon Catalog。基于 JNI 方式访问数据的 Catalog如 JDBC Catalog暂不支持Data Cache。部分 Catalog 会根据具体条件文件类型、数据状态等动态切换访问方式。例如 Paimon Catalog 会根据当前数据的合并compaction状态自动选择使用 Native File Reader 还是 JNI 读取当走 JNI 路径访问 Paimon 数据时Data Cache 加速不生效。这一点在源码中同样有迹可循缓存填充的入口逻辑会根据表类型与读取路径决定是否写入缓存例如 Hive Connector 与 Paimon 文件系统在访问数据时会携带 Data Cache 选项见 be/src/connector/hive/hive_connector.cpp 与 be/src/connector/hive/paimon/paimon_file_system.cpp而DataCacheOptions结构体be/src/cache/cache_options.h#L19-L29中的enable_datacache等字段则决定了当前读取路径是否真正启用缓存。若查询的表类型不在支持列表内Data Cache 自然不会参与。如何判断一次查询是否命中缓存在查询对应的Query Profile中查看 Data Cache 相关指标其中DataCacheReadBytes与DataCacheReadCounter直接反映本地缓存命中情况- DataCacheReadBytes: 518.73 MB - __MAX_OF_DataCacheReadBytes: 4.73 MB - __MIN_OF_DataCacheReadBytes: 16.00 KB - DataCacheReadCounter: 684 - __MAX_OF_DataCacheReadCounter: 4 - __MIN_OF_DataCacheReadCounter: 0 - DataCacheReadTimer: 737.357us - DataCacheWriteBytes: 7.65 GB - __MAX_OF_DataCacheWriteBytes: 64.39 MB - __MIN_OF_DataCacheWriteBytes: 0.00 - DataCacheWriteCounter: 7.887K (7887) - __MAX_OF_DataCacheWriteCounter: 65 - __MIN_OF_DataCacheWriteCounter: 0 - DataCacheWriteTimer: 23.467ms - __MAX_OF_DataCacheWriteTimer: 62.280ms - __MIN_OF_DataCacheWriteTimer: 0ns各指标含义如下完整解读与示例对比可参考 Data Cache 核心原理文档DataCacheReadBytes/DataCacheReadCounter直接从本地内存与磁盘缓存读取的数据量 / 读取次数越大说明命中越多DataCacheWriteBytes/DataCacheWriteCounter从远端存储加载并写入缓存的数据量 / 次数DataCacheReadTimer/DataCacheWriteTimer缓存读 / 写耗时BytesRead查询总读取量远端 本地缓存。对比示例某查询DataCacheReadBytes仅 518.73 MB 而DataCacheWriteBytes达 7.65 GB说明大量数据刚从远端拉取并写入缓存Block Cache 命中率较低而另一个查询DataCacheReadBytes达 46.08 GB、DataCacheWriteBytes为 0且BytesRead也恰为 46.08 GB说明全部数据都来自本地缓存详见 data_cache.md 中的完整示例。缓存未命中时如何排查若 Data Cache 已启用但查询仍未命中按以下两步排查确认 Catalog 类型是否受支持见上文「支持的 Catalog 类型」一节确认查询语句是否满足缓存填充population条件。某些场景下 Data Cache 会主动拒绝为该查询填充缓存。使用EXPLAIN VERBOSE可以查看当前查询是否会触发缓存填充mysql EXPLAIN VERBOSE SELECT col1 FROM hudi_table; | 0:HudiScanNode | | TABLE: hudi_table | | partitions3/3 | | cardinality9084 | | avgRowSize2.0 | | dataCacheOptions{populate: false} | | cardinality: 9084 | -----------------------------------------上例中dataCacheOptions的populate字段为false说明该查询不会填充缓存。要让这类查询也写入缓存可将系统变量populate_datacache_mode设置为always。缓存填充规则Population Rules自 v3.3.2 起为提升 Block Cache 命中率系统默认按以下规则决定是否填充缓存完整规则见 data_cache.md非 SELECT 语句不填充缓存例如ANALYZE TABLE、INSERT INTO SELECT扫描表全分区的查询不填充缓存但若表只有一个分区则默认填充扫描表全列的查询不填充缓存但若表只有一列则默认填充非 Hive / Paimon / Delta Lake / Hudi / Iceberg 表不填充缓存。populate_datacache_mode会话/全局变量的取值与默认行为定义于 docs/en/sql-reference/System_variable.md#populate_datacache_mode取值行为auto默认系统基于填充规则有选择性地缓存数据always总是缓存数据never永不缓存数据例如全分区扫描是默认不填充的典型场景如果你确认该表热点集中、希望强制缓存可以SET GLOBAL populate_datacache_modealways后重跑查询。为什么相同查询要执行多次才能完全命中缓存当前版本 Data Cache默认采用异步填充asynchronous population以尽量降低对查询性能的影响查询先完成数据读取缓存写入在后台异步执行不阻塞当前查询。因此单次查询通常只能缓存到部分数据需要多次执行才能把查询所需数据逐步全部缓存。如果希望一次查询即完成缓存有两种方式改为同步填充设置系统变量enable_datacache_async_populate_modefalse。同步模式下首次查询读取远端数据时立即写入本地缓存后续查询可直接复用缓存效率高但首次查询的延迟会有所增加该变量默认值见 System_variable.md#enable_datacache_async_populate_mode提前预热目标数据使用CACHE SELECT主动将目标数据写入缓存参见 Data Cache 预热CACHE SELECT文档。从源码看同步/异步两种模式正是通过DataCacheOptions中的enable_datacache_async_populate_mode字段be/src/cache/cache_options.h#L23在读取链路中传递并生效的与文档描述完全对应。数据已全部缓存为什么仍有少量远程访问当前版本默认开启了I/O AdaptorI/O 自适应功能当缓存磁盘 I/O 负载较高时系统会将部分缓存请求动态路由到远端存储利用本地缓存与远端存储并行提升整体吞吐避免磁盘高负载导致尾部延迟放大、缓存反而负优化。因此即使查询所需数据已全部缓存在磁盘负载高峰时段仍可能出现少量请求直接访问远端存储的现象这属于该机制的正常表现。若业务对远程访问零容忍可将enable_datacache_io_adaptor设置为false关闭该功能该变量默认开启true参见 System_variable.md#enable_datacache_io_adaptor。:::note 注意变量名拼写排障文档中曾写作enable_datacache_io-adapter请以系统变量参考文档中的enable_datacache_io_adaptor为准下划线连接否则设置不会生效。 :::如何清理 Data Cache 缓存数据Data Cache 目前不提供直接清理缓存的接口但可以选择以下两种方式方式一删除缓存目录后重启节点推荐删除 BE/CN 节点上datacache目录下的全部数据包括块文件与元数据目录然后重启节点。缓存目录通常位于 BE 的存储路径下例如storage_root_path对应的datacache子目录路径及配额可通过information_schema.be_datacache_metrics的DIR_SPACES字段确认。磁盘上的缓存数据默认持久化重启后会被重新加载BE 配置datacache_persistence_enable默认true因此必须删除文件后再重启才能彻底清空。方式二运行时动态缩容触发自动清理免重启通过动态修改配置把缓存配额临时降为 0系统会自动清理缓存数据再恢复原配额即可全程无需重启UPDATE be_configs SET VALUE0 WHERE NAMEdatacache_disk_size and BE_ID10005; UPDATE be_configs SET VALUE2T WHERE NAMEdatacache_disk_size and BE_ID10005;:::warning 运行时清理缓存数据时务必小心语句中的WHERE条件避免误伤其他无关参数或节点。建议始终显式指定BE_ID或明确的目标条件不要省略WHERE子句。 :::此外需要注意通过UPDATE be_configs方式做出的容量调整不会被持久化BE/CN 进程重启后会丢失。如果希望改动在重启后继续生效应在动态调整的同时手工修改 BE/CN 配置文件中的对应参数详见 data_cache.md 的 Dynamic scaling 一节。如何提升 Data Cache 性能Data Cache 的本质是用本地内存或磁盘替代远端存储因此查询性能直接取决于本地缓存介质的性能。若因磁盘负载高导致缓存访问延迟偏大可从以下三方面优化优先使用高性能 NVMe 磁盘作为缓存盘降低缓存读写的单次延迟增加磁盘数量分摊 I/O 压力多盘并行读写可显著降低单盘负载Block Cache 支持配置多个缓存路径block_cache_disk_spaces中即可看到多个路径与其配额提升 BE/CN 节点服务器内存注意是机器物理内存而非 Data Cache 内存配额借助操作系统 Page Cache 减少直接磁盘访问次数、降低磁盘 I/O 压力。因为 Page Cache 由 OS 统一管理更大的物理内存意味着更多热点数据停留在内存层间接提升缓存读取速度。从架构上看这也是 Block Cache 设计文档中反复强调的缓存介质选型原则——缓存加速效果与磁盘性能直接相关选用高性能磁盘与合理规划多盘是数据湖查询场景下最立竿见影的调优手段参见 data_cache.md。附Data Cache 核心配置速查以下参数是排查与调优中最常涉及的 Data Cache 配置默认值均取自 be/src/common/config.h#L1820-L1896 与 System_variable.md配置/变量默认值作用datacache_enableBEtrueData Cache 总开关关闭后 Page Cache 与 Block Cache 一并停用datacache_mem_sizeBE20%内存缓存Page Cache配额上限支持绝对大小与百分比datacache_disk_sizeBE100%磁盘缓存Block Cache配额上限datacache_eviction_policyBEslru缓存淘汰策略可选lru/slrudatacache_block_sizeBE262144256K磁盘缓存块大小datacache_persistence_enableBEtrue磁盘缓存数据是否持久化重启后复用enable_datacache_disk_auto_adjustBEtrue磁盘配额自动调整开关disk_high_level/disk_safe_level/disk_low_levelBE90/80/60磁盘水位阈值百分比驱动缓存自动驱逐与扩容populate_datacache_mode系统变量auto缓存填充行为auto/always/neverenable_datacache_async_populate_mode系统变量false是否异步填充缓存true时单次查询可能只缓存部分数据enable_datacache_io_adaptor系统变量true磁盘负载高时将部分缓存请求路由到远端降低磁盘压力完整的系统变量与 BE 配置清单请参见 Data Cache 配置与变量一览 的「Configurations and variables」小节。结合这些默认值与排障文档中给出的排查路径即可系统性地完成从缓存没生效到命中率不达标再到延迟偏高的完整闭环调优。【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
StarRocks Data Cache 故障排查完全指南启用确认、命中率分析与性能调优【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocksData Cache 是 StarRocks 将远端存储HDFS、对象存储中的数据按块缓存到本地内存与磁盘从而加速数据湖分析查询的核心特性。本文围绕 Data Cache 常见问题展开覆盖「如何确认缓存是否启用、为何默认未启用、如何判断查询是否命中缓存、缓存未命中如何排查、命中率上不去怎么办、如何清理缓存与提升性能」等高频问题并结合仓库源码BE 配置定义、缓存模块实现给出可验证的排查步骤与配置依据。读完本文你可以独立定位大多数 Data Cache 相关的故障并掌握从SHOW BACKENDS到查询 Profile、再到 BE HTTP 接口的完整排查链路。快速确认 Data Cache 是否成功启用通过 SHOW BACKENDS / SHOW COMPUTE NODES 查看配额在 SQL 客户端执行SHOW BACKENDS共享数据集群中执行SHOW COMPUTE NODES检查输出中的DataCacheMetrics字段。只要磁盘缓存配额或内存缓存配额大于 0即可确认 Data Cache 已启用。mysql show backends \G *************************** 1. row *************************** BackendId: 89041 IP: X.X.X.X HeartbeatPort: 9050 BePort: 9060 HttpPort: 8040 BrpcPort: 8060 LastStartTime: 2025-05-29 14:45:37 LastHeartbeat: 2025-05-29 19:20:32 Alive: true SystemDecommissioned: false ClusterDecommissioned: false TabletNum: 10 DataUsedCapacity: 0.000 B AvailCapacity: 1.438 TB TotalCapacity: 1.718 TB UsedPct: 16.27 % MaxDiskUsedPct: 16.27 % ErrMsg: Version: main-c15b412 Status: {lastSuccessReportTabletsTime:2025-05-29 19:20:30} DataTotalCapacity: 1.438 TB DataUsedPct: 0.00 % CpuCores: 8 MemLimit: 50.559GB NumRunningQueries: 0 MemUsedPct: 0.50 % CpuUsedPct: 0.2 % DataCacheMetrics: Status: Normal, DiskUsage: 44MB/1TB, MemUsage: 0B/0B Location: StatusCode: OK 1 row in set (0.00 sec)上例中DiskUsage: 44MB/1TB表示磁盘缓存配额为 1TB、当前已使用 44MBMemUsage: 0B/0B表示内存缓存配额为 0即内存缓存未启用。Status: Normal表示缓存实例运行正常其他取值见下文 BE HTTP 接口一节包括ABNORMAL与UPDATING。如需查看每个 BE 更细粒度的缓存容量与用量还可以查询information_schema.be_datacache_metrics视图其中DISK_QUOTA_BYTES、DISK_USED_BYTES、MEM_QUOTA_BYTES、MEM_USED_BYTES、META_USED_BYTES分别对应磁盘缓存配额、磁盘缓存已用空间、内存缓存配额、内存缓存已用空间与元数据缓存占用DIR_SPACES则给出缓存路径及每个路径的配额详见 Data Cache 观测指南。通过 BE Web Console 查看运行指标访问 BE 的 Web Console 地址http://${BE_HOST}:${BE_HTTP_PORT}/api/datacache/stat可查看当前 Data Cache 的配额、命中率等底层执行指标。若disk_quota_bytes或mem_quota_bytes大于 0即说明 Data Cache 已启用。该接口返回的字段与SHOW BACKENDS互补例如block_cache_disk_quota_bytes/block_cache_disk_used_bytes反映磁盘块缓存配额与用量block_cache_hit_rate给出累计命中率block_cache_status表示缓存实例状态NORMAL正常、ABNORMAL数据读写异常需结合日志定位、UPDATING表示实例正在更新例如在线扩缩容过程。注意该接口展示的是 Data Cache 底层执行状态并不直接等于查询层的实际命中率查询层命中率请优先使用下文「如何判断查询命中缓存」一节的方法。为什么 Data Cache 默认未启用从 v3.3 起BE 启动时会尝试自动启用Data Cache但如果当前磁盘可用空间不足则不会自动启用。常见诱因有两类磁盘使用率过高Percentage当前磁盘占用比例已很高剩余空间不足Remaining space磁盘剩余可用空间偏少。排查时先检查当前磁盘使用情况必要时扩容磁盘也可以根据当前可用磁盘空间手动配置缓存配额来启用 Data Cache# 关闭 Data Cache 自动调整 datacache_auto_adjust_enable false # 手动设置 Data Cache 磁盘配额 datacache_disk_size 1T从源码角度理解这一行为Data Cache 的磁盘配额默认值为100%见 be/src/common/config.h#L1822 中CONF_mString(datacache_disk_size, 100%)即默认按磁盘总容量的一定百分比分配。当 BE 启动解析该配额时若磁盘余量不足以支撑缓存初始化就会放弃自动启用。此外BE 还提供自动扩容机制当磁盘用量持续低于disk_low_level阈值默认 60%且缓存已写满时系统会自动将缓存容量扩张到disk_safe_level默认 80%对应的水位当磁盘用量超过disk_high_level默认 90%时自动驱逐缓存数据释放空间。这三个阈值同样定义在 be/src/common/config.h#L97-L104并由磁盘空间监控线程在运行时读取计算参见 be/src/cache/disk_space_monitor.cpp#L124-L126。因此当遇到缓存没有按预期自动启用时本质是磁盘水位与这些阈值共同作用的结果优先检查磁盘剩余空间是最直接的切入点。Data Cache 支持哪些 Catalog 类型Data Cache 当前支持使用 StarRocks 原生文件读取器Native File Reader访问数据的外部 Catalog例如 Parquet/ORC/CSV Reader 对应的 Hive、Iceberg、Hudi、Delta Lake 与 Paimon Catalog。基于 JNI 方式访问数据的 Catalog如 JDBC Catalog暂不支持Data Cache。部分 Catalog 会根据具体条件文件类型、数据状态等动态切换访问方式。例如 Paimon Catalog 会根据当前数据的合并compaction状态自动选择使用 Native File Reader 还是 JNI 读取当走 JNI 路径访问 Paimon 数据时Data Cache 加速不生效。这一点在源码中同样有迹可循缓存填充的入口逻辑会根据表类型与读取路径决定是否写入缓存例如 Hive Connector 与 Paimon 文件系统在访问数据时会携带 Data Cache 选项见 be/src/connector/hive/hive_connector.cpp 与 be/src/connector/hive/paimon/paimon_file_system.cpp而DataCacheOptions结构体be/src/cache/cache_options.h#L19-L29中的enable_datacache等字段则决定了当前读取路径是否真正启用缓存。若查询的表类型不在支持列表内Data Cache 自然不会参与。如何判断一次查询是否命中缓存在查询对应的Query Profile中查看 Data Cache 相关指标其中DataCacheReadBytes与DataCacheReadCounter直接反映本地缓存命中情况- DataCacheReadBytes: 518.73 MB - __MAX_OF_DataCacheReadBytes: 4.73 MB - __MIN_OF_DataCacheReadBytes: 16.00 KB - DataCacheReadCounter: 684 - __MAX_OF_DataCacheReadCounter: 4 - __MIN_OF_DataCacheReadCounter: 0 - DataCacheReadTimer: 737.357us - DataCacheWriteBytes: 7.65 GB - __MAX_OF_DataCacheWriteBytes: 64.39 MB - __MIN_OF_DataCacheWriteBytes: 0.00 - DataCacheWriteCounter: 7.887K (7887) - __MAX_OF_DataCacheWriteCounter: 65 - __MIN_OF_DataCacheWriteCounter: 0 - DataCacheWriteTimer: 23.467ms - __MAX_OF_DataCacheWriteTimer: 62.280ms - __MIN_OF_DataCacheWriteTimer: 0ns各指标含义如下完整解读与示例对比可参考 Data Cache 核心原理文档DataCacheReadBytes/DataCacheReadCounter直接从本地内存与磁盘缓存读取的数据量 / 读取次数越大说明命中越多DataCacheWriteBytes/DataCacheWriteCounter从远端存储加载并写入缓存的数据量 / 次数DataCacheReadTimer/DataCacheWriteTimer缓存读 / 写耗时BytesRead查询总读取量远端 本地缓存。对比示例某查询DataCacheReadBytes仅 518.73 MB 而DataCacheWriteBytes达 7.65 GB说明大量数据刚从远端拉取并写入缓存Block Cache 命中率较低而另一个查询DataCacheReadBytes达 46.08 GB、DataCacheWriteBytes为 0且BytesRead也恰为 46.08 GB说明全部数据都来自本地缓存详见 data_cache.md 中的完整示例。缓存未命中时如何排查若 Data Cache 已启用但查询仍未命中按以下两步排查确认 Catalog 类型是否受支持见上文「支持的 Catalog 类型」一节确认查询语句是否满足缓存填充population条件。某些场景下 Data Cache 会主动拒绝为该查询填充缓存。使用EXPLAIN VERBOSE可以查看当前查询是否会触发缓存填充mysql EXPLAIN VERBOSE SELECT col1 FROM hudi_table; | 0:HudiScanNode | | TABLE: hudi_table | | partitions3/3 | | cardinality9084 | | avgRowSize2.0 | | dataCacheOptions{populate: false} | | cardinality: 9084 | -----------------------------------------上例中dataCacheOptions的populate字段为false说明该查询不会填充缓存。要让这类查询也写入缓存可将系统变量populate_datacache_mode设置为always。缓存填充规则Population Rules自 v3.3.2 起为提升 Block Cache 命中率系统默认按以下规则决定是否填充缓存完整规则见 data_cache.md非 SELECT 语句不填充缓存例如ANALYZE TABLE、INSERT INTO SELECT扫描表全分区的查询不填充缓存但若表只有一个分区则默认填充扫描表全列的查询不填充缓存但若表只有一列则默认填充非 Hive / Paimon / Delta Lake / Hudi / Iceberg 表不填充缓存。populate_datacache_mode会话/全局变量的取值与默认行为定义于 docs/en/sql-reference/System_variable.md#populate_datacache_mode取值行为auto默认系统基于填充规则有选择性地缓存数据always总是缓存数据never永不缓存数据例如全分区扫描是默认不填充的典型场景如果你确认该表热点集中、希望强制缓存可以SET GLOBAL populate_datacache_modealways后重跑查询。为什么相同查询要执行多次才能完全命中缓存当前版本 Data Cache默认采用异步填充asynchronous population以尽量降低对查询性能的影响查询先完成数据读取缓存写入在后台异步执行不阻塞当前查询。因此单次查询通常只能缓存到部分数据需要多次执行才能把查询所需数据逐步全部缓存。如果希望一次查询即完成缓存有两种方式改为同步填充设置系统变量enable_datacache_async_populate_modefalse。同步模式下首次查询读取远端数据时立即写入本地缓存后续查询可直接复用缓存效率高但首次查询的延迟会有所增加该变量默认值见 System_variable.md#enable_datacache_async_populate_mode提前预热目标数据使用CACHE SELECT主动将目标数据写入缓存参见 Data Cache 预热CACHE SELECT文档。从源码看同步/异步两种模式正是通过DataCacheOptions中的enable_datacache_async_populate_mode字段be/src/cache/cache_options.h#L23在读取链路中传递并生效的与文档描述完全对应。数据已全部缓存为什么仍有少量远程访问当前版本默认开启了I/O AdaptorI/O 自适应功能当缓存磁盘 I/O 负载较高时系统会将部分缓存请求动态路由到远端存储利用本地缓存与远端存储并行提升整体吞吐避免磁盘高负载导致尾部延迟放大、缓存反而负优化。因此即使查询所需数据已全部缓存在磁盘负载高峰时段仍可能出现少量请求直接访问远端存储的现象这属于该机制的正常表现。若业务对远程访问零容忍可将enable_datacache_io_adaptor设置为false关闭该功能该变量默认开启true参见 System_variable.md#enable_datacache_io_adaptor。:::note 注意变量名拼写排障文档中曾写作enable_datacache_io-adapter请以系统变量参考文档中的enable_datacache_io_adaptor为准下划线连接否则设置不会生效。 :::如何清理 Data Cache 缓存数据Data Cache 目前不提供直接清理缓存的接口但可以选择以下两种方式方式一删除缓存目录后重启节点推荐删除 BE/CN 节点上datacache目录下的全部数据包括块文件与元数据目录然后重启节点。缓存目录通常位于 BE 的存储路径下例如storage_root_path对应的datacache子目录路径及配额可通过information_schema.be_datacache_metrics的DIR_SPACES字段确认。磁盘上的缓存数据默认持久化重启后会被重新加载BE 配置datacache_persistence_enable默认true因此必须删除文件后再重启才能彻底清空。方式二运行时动态缩容触发自动清理免重启通过动态修改配置把缓存配额临时降为 0系统会自动清理缓存数据再恢复原配额即可全程无需重启UPDATE be_configs SET VALUE0 WHERE NAMEdatacache_disk_size and BE_ID10005; UPDATE be_configs SET VALUE2T WHERE NAMEdatacache_disk_size and BE_ID10005;:::warning 运行时清理缓存数据时务必小心语句中的WHERE条件避免误伤其他无关参数或节点。建议始终显式指定BE_ID或明确的目标条件不要省略WHERE子句。 :::此外需要注意通过UPDATE be_configs方式做出的容量调整不会被持久化BE/CN 进程重启后会丢失。如果希望改动在重启后继续生效应在动态调整的同时手工修改 BE/CN 配置文件中的对应参数详见 data_cache.md 的 Dynamic scaling 一节。如何提升 Data Cache 性能Data Cache 的本质是用本地内存或磁盘替代远端存储因此查询性能直接取决于本地缓存介质的性能。若因磁盘负载高导致缓存访问延迟偏大可从以下三方面优化优先使用高性能 NVMe 磁盘作为缓存盘降低缓存读写的单次延迟增加磁盘数量分摊 I/O 压力多盘并行读写可显著降低单盘负载Block Cache 支持配置多个缓存路径block_cache_disk_spaces中即可看到多个路径与其配额提升 BE/CN 节点服务器内存注意是机器物理内存而非 Data Cache 内存配额借助操作系统 Page Cache 减少直接磁盘访问次数、降低磁盘 I/O 压力。因为 Page Cache 由 OS 统一管理更大的物理内存意味着更多热点数据停留在内存层间接提升缓存读取速度。从架构上看这也是 Block Cache 设计文档中反复强调的缓存介质选型原则——缓存加速效果与磁盘性能直接相关选用高性能磁盘与合理规划多盘是数据湖查询场景下最立竿见影的调优手段参见 data_cache.md。附Data Cache 核心配置速查以下参数是排查与调优中最常涉及的 Data Cache 配置默认值均取自 be/src/common/config.h#L1820-L1896 与 System_variable.md配置/变量默认值作用datacache_enableBEtrueData Cache 总开关关闭后 Page Cache 与 Block Cache 一并停用datacache_mem_sizeBE20%内存缓存Page Cache配额上限支持绝对大小与百分比datacache_disk_sizeBE100%磁盘缓存Block Cache配额上限datacache_eviction_policyBEslru缓存淘汰策略可选lru/slrudatacache_block_sizeBE262144256K磁盘缓存块大小datacache_persistence_enableBEtrue磁盘缓存数据是否持久化重启后复用enable_datacache_disk_auto_adjustBEtrue磁盘配额自动调整开关disk_high_level/disk_safe_level/disk_low_levelBE90/80/60磁盘水位阈值百分比驱动缓存自动驱逐与扩容populate_datacache_mode系统变量auto缓存填充行为auto/always/neverenable_datacache_async_populate_mode系统变量false是否异步填充缓存true时单次查询可能只缓存部分数据enable_datacache_io_adaptor系统变量true磁盘负载高时将部分缓存请求路由到远端降低磁盘压力完整的系统变量与 BE 配置清单请参见 Data Cache 配置与变量一览 的「Configurations and variables」小节。结合这些默认值与排障文档中给出的排查路径即可系统性地完成从缓存没生效到命中率不达标再到延迟偏高的完整闭环调优。【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
 构建与运行 LLM Agent)
