版本: 最新版本-3.5

数据缓存常见问题

本文档介绍数据缓存的一些常见问题 (FAQ) 和常见问题，并提供这些问题的故障排除步骤和解决方案。

启用数据缓存

如何确认数据缓存是否成功启用？

大多数情况下，您可以通过以下任何一种方法检查数据缓存是否成功启用

从 SQL 客户端执行 SHOW BACKENDS (或 SHOW COMPUTE NODES)，并检查 DataCacheMetrics 的值。如果磁盘或内存缓存配额大于 0，则可以确认已启用数据缓存。

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)

在上面的示例中，数据缓存的磁盘缓存配额为 1TB，当前使用了 44MB；而内存缓存配额为 0B，因此未启用内存缓存。

您可以访问 BE Web 控制台 (http://${BE_HOST}:${BE_HTTP_PORT}/api/datacache/stat) 以检查当前数据缓存配额、命中率和其他指标。如果 disk_quota_bytes 或 mem_quota_bytes 大于 0，则可以确认已启用数据缓存。

Data Cache FAQ - Web Console

为什么默认情况下不启用数据缓存？

从 v3.3 开始，BE 会尝试在启动时启用数据缓存。但是，如果当前磁盘上的可用空间不足，则不会自动启用数据缓存。

这可能是由以下情况引起的

百分比：当前磁盘使用率很高。
剩余空间：剩余磁盘空间大小相对较低。

因此，如果默认情况下未启用数据缓存，您可以首先检查当前磁盘使用情况，并在必要时增加磁盘容量。

或者，您可以根据当前可用磁盘空间通过配置缓存配额来手动启用数据缓存。

# disable Data Cache Automatic Adjustment
datacache_auto_adjust_enable = false
# Set Data Cache disk quota manually
datacache_disk_size = 1T

使用数据缓存

数据缓存支持哪些 catalog 类型？

数据缓存当前支持使用 StarRocks Native File Reader（例如 Parquet/ORC/CSV Reader）的外部 catalog 类型，包括 Hive、Iceberg、Hudi、Delta Lake 和 Paimon。尚不支持基于 JNI 访问数据的 Catalog（例如 JDBC Catalog）。

注意

某些 catalog 可能会根据特定条件（例如文件类型和数据状态）使用不同的数据访问方法。例如，对于 Paimon catalog，StarRocks 可能会自动选择是使用 Native File Reader 还是 JNI 来访问数据，具体取决于当前数据的压缩状态。当使用 JNI 访问 Paimon 数据时，不支持数据缓存加速。

如何知道查询命中了缓存？

您可以在相应的查询 profile 中检查与数据缓存相关的指标。指标 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

为什么启用数据缓存后查询会错过缓存？

请按照以下步骤进行故障排除

检查数据缓存是否支持当前的 catalog 类型。
确认查询语句是否满足缓存填充条件。在某些情况下，数据缓存会拒绝某些查询的缓存填充。有关详细信息，请参阅数据缓存填充规则。

可以使用 EXPLAIN VERBOSE 命令检查查询是否触发缓存填充。例子

mysql> EXPLAIN VERBOSE SELECT col1 FROM hudi_table;
|   0:HudiScanNode                        |
|      TABLE: hudi_table                  |
|      partitions=3/3                     |
|      cardinality=9084                   |
|      avgRowSize=2.0                     |
|      dataCacheOptions={populate: false} |
|      cardinality: 9084                  |
+-----------------------------------------+

在上面的示例中，dataCacheOptions 部分的 populate 字段为 false，表示不会为此查询填充缓存。

要为此类查询启用数据缓存，您可以通过将系统变量 populate_datacache_mode 设置为 always 来修改默认填充行为。

数据缓存命中

为什么有时需要多次执行同一查询才能完全命中缓存？

在当前版本中，数据缓存默认使用异步填充，以减少其对查询性能的影响。使用异步填充时，系统会尝试在后台缓存访问的数据，而不会尽可能地影响读取性能。因此，单次执行查询只能缓存一部分数据。您需要多次运行查询才能缓存查询所需的所有数据。

您还可以通过设置 enable_datacache_async_populate_mode=false 来使用同步缓存填充，或者通过 CACHE SELECT 提前预热目标数据。

为什么当前查询中的所有数据都已缓存，但仍有少量数据从远程访问？

在当前版本中，默认启用 I/O 适配以优化磁盘 I/O 负载较高时的缓存性能，这可能导致在某些情况下少量请求直接访问远程存储。

您可以通过将 enable_datacache_io-adapter 设置为 false 来禁用 I/O 适配功能。

其他

如何清除缓存的数据？

目前，数据缓存不提供直接清除缓存数据的接口，但您可以选择以下方法之一来清除它

您可以通过删除 BE/CN 节点上 datacache 目录中的所有数据（包括块文件和元数据目录）来清理缓存的数据，然后重新启动节点。（推荐）
如果您想避免重新启动 BE/CN 节点，您还可以通过在运行时缩减缓存配额来间接清理缓存的数据。例如，如果您之前已将磁盘缓存配额设置为 2TB，您可以先将其缩减为 0（系统将自动清理缓存的数据），然后将其重置为 2TB。

示例

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 条件，以避免意外损坏其他无关的参数或节点。

如何提高数据缓存性能？

使用数据缓存，StarRocks 本质上访问本地内存或磁盘，而不是远程存储。因此，性能与本地缓存介质直接相关。如果您发现由于磁盘负载较高而导致缓存访问延迟较高，您可以考虑提高本地缓存介质的性能

优先使用高性能 NVME 磁盘作为缓存磁盘。
如果没有高性能磁盘，您还可以增加磁盘数量以分担 I/O 压力。
增加 BE/CN 节点的服务器内存（而不是数据缓存内存配额），使用操作系统的页面缓存来减少直接磁盘访问的次数和磁盘 I/O 压力。

启用数据缓存​

如何确认数据缓存是否成功启用？​

为什么默认情况下不启用数据缓存？​

使用数据缓存​

数据缓存支持哪些 catalog 类型？​

如何知道查询命中了缓存？​

为什么启用数据缓存后查询会错过缓存？​

数据缓存命中​

为什么有时需要多次执行同一查询才能完全命中缓存？​

为什么当前查询中的所有数据都已缓存，但仍有少量数据从远程访问？​

其他​

如何清除缓存的数据？​

如何提高数据缓存性能？​

您觉得这篇文档怎么样？