本文整理了数据湖 Data Cache 使用过程中的常见问题及处理方法。
使用Data Cache
Data Cache 支持哪些 Catalog 类型？
Data Cache 目前支持使用 StarRocks Native File Reader 的 External Catalog 类型（如 Parquet/ORC/CSV Reader），包括 Hive、Iceberg、Hudi、Delta Lake 和 Paimon。基于 JNI 访问数据的 Catalog（如 JDBC Catalog）暂不支持。
某些 Catalog 可能会根据特定条件（如文件类型和数据状态）使用不同的数据访问方法。例如，对于 Paimon Catalog，StarRocks 可能根据数据的 Compaction 状态自动选择 Native File Reader 或 JNI 访问。使用 JNI 访问时不支持 Data Cache 加速。
如何判断查询命中了缓存？
在查询对应的 Query Profile 中，查看以下指标：
DataCacheReadBytes：从本地缓存读取的数据量。DataCacheReadCounter：本地缓存命中次数。
若上述指标大于 0，则表明查询命中了本地缓存。
- DataCacheReadBytes: 518.73 MB
- __MAX_OF_DataCacheReadBytes: 4.73 MB
- __MIN_OF_DataCacheReadBytes: 16.00 KB
- DataCacheReadCounter: 684
- DataCacheWriteBytes: 7.65 GB
- DataCacheWriteCounter: 7.887K (7887)为什么启用Data Cache后查询未命中缓存？
请按以下步骤排查：
确认当前 Catalog 类型是否支持 Data Cache（需使用 StarRocks Native File Reader 的 Catalog，如 Hive、Iceberg、Hudi、Delta Lake、Paimon）。
检查查询是否符合缓存填充规则。可通过
EXPLAIN VERBOSE查看：
EXPLAIN VERBOSE SELECT col1 FROM hudi_table;若返回结果中包含 dataCacheOptions={populate: false}，表示该查询不填充缓存（如扫描了全部分区）。
若需强制对该类查询启用缓存填充，可设置：
SET populate_datacache_mode = 'always';Data Cache命中
为什么同一查询需要执行多次才能完全命中缓存？
当前版本中，Data Cache 默认使用异步填充模式，以减少对查询延迟的影响。异步填充下，单次查询只能缓存部分数据，需多次执行才能将查询所需数据全部缓存。
可选方案：
通过设置
enable_datacache_async_populate_mode=false切换为同步填充模式。通过
CACHE SELECT提前预热目标数据。
为什么所有数据已缓存，但仍有少量请求直接访问远端存储？
当前版本默认启用 I/O 自适应功能。当磁盘 I/O 负载较高时，系统会自动将少量缓存请求路由到远端存储，以避免磁盘长尾延迟影响整体性能，这是预期行为。
如需禁用 I/O 自适应，执行：
SET enable_datacache_io_adaptor = false;其他
如何清除缓存数据？
Data Cache 当前不提供直接清除缓存的接口，可选以下方案：
方案一（推荐）：删除 BE/CN 节点上 datacache 目录中的所有数据（包括块文件和元数据目录），然后重启节点。
方案二：通过运行时缩小缓存配额间接清理，无需重启节点。示例：将指定节点的磁盘缓存配额缩小至 0，系统自动清理后再恢复原值：
UPDATE be_configs SET VALUE="0" WHERE NAME="datacache_disk_size" AND BE_ID=10005;
UPDATE be_configs SET VALUE="2T" WHERE NAME="datacache_disk_size" AND BE_ID=10005;执行上述语句时，请仔细确认 WHERE 条件，避免误操作影响其他节点或参数。
如何提高Data Cache性能？
Data Cache 本质上是用本地内存或磁盘替代远端存储访问，因此性能直接取决于本地缓存介质的质量。若发现缓存访问延迟较高，可考虑以下优化措施：
优先使用高性能 NVMe 磁盘作为缓存磁盘。
若无高性能磁盘，增加磁盘数量以分散 I/O 压力。
适当增加 BE/CN 节点的服务器内存，利用操作系统 Page Cache 减少直接磁盘访问次数。