一、问题背景:缓存命中率低下的日常困扰

很多团队在用Metabase做报表,明明数据量不大,但每次打开仪表盘都感觉慢半拍。数据库CPU经常飙高,DBA跑来问“你们是不是在反复跑同样的查询?”仔细一看,原来缓存根本没起作用。这就是一个典型的缓存命中率低迷的场景。

什么叫缓存命中率?简单说,如果你去餐厅点菜,厨师把做好的菜放在橱窗里,你每次点同样的菜,直接从橱窗拿走,不用重新做。这就是命中。如果厨师每次都重新做,那就是未命中,浪费燃料。Metabase的缓存就是那个橱窗,它把查询结果临时存起来,下一次同样的查询直接拿结果。

但现实中,这个橱窗常常是空的,或者里面的菜还没放多久就过期了,导致每次都要去数据库现查。

二、Metabase的缓存机制,你真的理解了吗?

Metabase的缓存核心是基于查询结果集的。当你运行一个查询,Metabase会计算查询的哈希值,如果哈希值匹配并且结果没有过期,就直接从缓存里返回,否则去数据库执行,然后把结果存起来。

2.1 缓存的关键参数

Metabase默认启用了查询缓存,但有几个参数直接影响命中率。

  • MB_QUERY_CACHING_ENABLED:是否开启缓存,默认true。
  • MB_QUERY_CACHING_TTL_MS:缓存有效期,默认5分钟(300000毫秒)。
  • MB_QUERY_CACHING_MIN_QUERY_DURATION_MS:只有查询耗时超过这个值才缓存,默认1000毫秒。这其实是避免把很快的查询也缓存起来,因为缓存本身有开销。
  • MB_QUERY_CACHING_MAX_CACHE_SIZE:限制缓存条数,防止内存溢出。

如果TTL设置太短,比如默认5分钟,而你的报表每小时才刷新一次,那么每次打开仪表盘,大概率缓存已经过期,又去查数据库。

2.2 缓存的粒度

Metabase的缓存是按查询文本和查询参数来识别的。也就是说,同样的SQL,同样的参数,会命中同一个缓存项。如果你在SQL里写了 NOW() 或者 CURRENT_TIMESTAMP,那么每次查询文本都会变化,因为 NOW() 在生成SQL文本时会被替换成具体时间,导致哈希值不同,永远不命中。

另外,如果查询使用了随机函数,比如 RANDOM(),也是一样的道理。

三、缓存命中率低迷的几个常见原因

从实践中看,命中率低通常有这几类原因。

3.1 TTL设置不合理

默认TTL是5分钟,但有些看板的数据源是每天凌晨才更新的,比如销售日报。白天的查询完全不需要每5分钟失效一次。如果把TTL设成1小时甚至1天,命中率会大幅上升。

3.2 查询语句不稳定

这是最容易被忽视的点。很多人在Metabase的SQL编辑器里写了带有动态时间条件的查询,比如:

-- 技术栈:Metabase
-- 这个查询每次执行时,NOW()都会被替换为当前时间,导致缓存永远不命中
SELECT 
  order_date,
  sum(amount) as total_amount
FROM orders
WHERE order_date >= now() - interval '1 day'
GROUP BY order_date

这里的 now() - interval '1 day' 是动态的,Metabase在执行前会把 now() 替换成具体的时间戳,比如 2025-04-01 12:00:00,这样查询文本每次都不同,缓存自然无法命中。解决办法是改用固定的时间参数,或者用Metabase的“仪表盘过滤器”传参数,而不是在SQL里写死。

3.3 缓存粒度太粗导致内存不足

如果一次查询返回几百万行,Metabase会把结果全放在内存里。当缓存项太多,内存不够时,Metabase可能会淘汰一些缓存项,导致后面再查又未命中。另外,如果单个缓存项太大,也会影响性能。

3.4 多实例部署但缓存不共享

如果你的Metabase是集群部署,比如用Docker Compose跑了多个副本,但没配置共享缓存,那么每个实例都有自己的本地缓存。用户请求被负载均衡到不同实例,同一查询可能在实例A命中,在实例B未命中,整体命中率就被拉低了。解决办法是使用Redis作为共享缓存,Metabase支持配置 MB_CACHE_REDIS_HOST 等参数。

四、合理设置缓存策略:几种典型方案

4.1 按数据更新频率调整TTL

对于每天只更新一次的数据,TTL可以设成24小时。对于每分钟都在更新的实时数据,TTL可以设成30秒甚至更短。关键是让TTL和真实数据更新周期匹配。

例如,你的订单表每天晚上10点跑批更新,那么TTL设为12小时就够用了。这样白天所有查询都命中缓存,晚上跑批后第一次查询会回源,之后又进入缓存。

4.2 使用查询级别覆盖

Metabase允许对单个查询或仪表盘卡片设置单独的缓存时长。在仪表盘编辑界面,点击卡片右上角的“选项”,可以设置“缓存TTL”为“自定义”。这比全局设置更灵活。

4.3 缓存预热

对于重要的看板,可以写一个定时任务,在数据更新后立即触发一次查询,让缓存提前填充。比如用cron在每天凌晨跑批结束后,调用Metabase的API执行关键查询,这样早晨用户打开看板时,直接命中缓存。

五、详细示例:从配置到监控

下面通过完整示例演示如何优化。

5.1 通过环境变量配置缓存(Docker Compose示例)

假设你的Metabase部署在Docker中,可以通过环境变量调整缓存参数。

# 技术栈:Metabase(Docker Compose)
# 这是一个docker-compose.yml的片段,展示了缓存相关配置
services:
  metabase:
    image: metabase/metabase:v0.50.0
    container_name: metabase
    environment:
      # 开启缓存
      MB_QUERY_CACHING_ENABLED: "true"
      # 缓存有效期设置为30分钟,适合每小时刷新一次的数据
      MB_QUERY_CACHING_TTL_MS: "1800000"
      # 只有查询耗时超过2秒才缓存,避免缓存大量轻量查询造成内存浪费
      MB_QUERY_CACHING_MIN_QUERY_DURATION_MS: "2000"
      # 设置内存上限,防止缓存占用过多内存
      MB_QUERY_CACHING_MAX_CACHE_SIZE: "1000"
      # 如果使用Redis共享缓存,可以配置如下
      # MB_CACHE_REDIS_HOST: "redis"
      # MB_CACHE_REDIS_PORT: "6379"
    ports:
      - "3000:3000"
    depends_on:
      - db

这段配置里,TTL设成30分钟,但如果你知道数据是每天更新,完全可以设成 86400000 毫秒(24小时)。

5.2 通过REST API动态修改缓存设置

如果不想重启Metabase,也可以通过管理API修改设置。

# 技术栈:Metabase REST API
# 获取当前缓存TTL设置
curl -s -X GET \
  -H "X-Metabase-Session: <你的session token>" \
  http://localhost:3000/api/setting/query-caching-ttl-ms

# 将TTL设置为1小时(3600000毫秒)
curl -s -X PUT \
  -H "Content-Type: application/json" \
  -H "X-Metabase-Session: <你的session token>" \
  -d '{"value": 3600000}' \
  http://localhost:3000/api/setting/query-caching-ttl-ms

需要注意的是,X-Metabase-Session 需要从登录API获取,一般是用 POST /api/session 得到。这里为了方便,假设你已经有了session。

5.3 编写可缓存的查询SQL

正确的写法是避免动态函数,使用固定参数或仪表盘过滤器。

-- 技术栈:Metabase
-- 正确的写法:使用Metabase的仪表盘变量,比如{{date}}
-- 假设仪表盘上有一个过滤器,用户选择日期范围
SELECT 
  category,
  sum(amount) as total_sales
FROM orders
WHERE order_date >= {{start_date}} 
  AND order_date <= {{end_date}}
GROUP BY category

注意这里的 {{start_date}} 是Metabase的模板变量,当用户选择日期后,Metabase会把具体日期填入SQL,并生成一个固定的查询哈希。如果用户没有改变日期,再次运行同样的过滤器,就能命中缓存。

5.4 监控缓存命中率

Metabase内置了审计功能,可以通过SQL查询它的内部表来监控缓存使用情况。

-- 技术栈:Metabase
-- 查看最近查询的缓存命中情况
-- 注意:metabase的审计日志表名可能因版本不同而有差异,下面以通用版本为例
SELECT 
  q.context,
  q.execution_time,
  q.cache_hit,
  q.query_hash
FROM metabase.audit_query_execution q
WHERE q.created_at > now() - interval '7 day'
ORDER BY q.created_at DESC
LIMIT 100;

这里的 cache_hit 字段如果是true,说明这次查询命中了缓存。通过统计 cache_hit = true 的比例,就能算出命中率。如果发现很多false,就需要按照前面讲的原因去排查。

六、应用场景:不同业务形态下的缓存选择

6.1 报表展示场景

典型的报表是销售日报、库存汇总等,数据一般每天或每小时更新一次。这类场景适合长TTL,比如24小时。因为用户主要看昨天的数据,今天的数据还没出来,缓存完全够用。即使数据更新了,也可以在跑批后手动清缓存。

6.2 实时仪表盘场景

监控类的仪表盘,比如服务器CPU使用率、订单实时数量,这类数据每分钟都在变。如果TTL太长,用户看到的都是旧数据。此时需要短TTL,比如30秒或1分钟。但要注意,短TTL可能导致数据库压力大,可以考虑用“短TTL+查询结果小”的组合,或者使用Redis缓存。

6.3 批量分析场景

数据分析师经常在Metabase里跑复杂的关联查询,比如跨表聚合。这类查询往往耗时长,但结果变化不大。建议设置较长的TTL,并且在数据更新后主动触发缓存预热,这样后续的探索性分析都能命中缓存。

七、技术优缺点分析

7.1 缓存带来的好处

最明显的好处是数据库压力下降。查询走缓存,不再占用数据库连接和CPU。其次是响应速度提升,因为缓存是内存读取,比数据库查询快几个数量级。另外,对数据库的稳定运行也有好处,避免突发查询把数据库打挂。

7.2 缓存的短板

缓存必然带来数据延迟。你看到的数据可能是几分钟甚至几小时前的,对于需要即时性的场景,这就是个问题。另外,缓存占用内存,如果查询结果集很大,可能影响Metabase自身性能。还有一个风险是缓存雪崩,如果TTL同时过期,大量查询会同时回源到数据库,反而造成压力高峰。

八、注意事项与避坑指南

8.1 避免缓存雪崩

尽量让不同的查询设置不同的TTL,或者给TTL加上随机偏移量。比如基础TTL是1小时,可以设置成60分钟、61分钟、62分钟这样,分散过期时间。这在Metabase里可以通过对每个查询单独设置来实现。

8.2 注意内存限制

如果你的查询结果集很大,一定要设置 MB_QUERY_CACHING_MAX_CACHE_SIZE,否则Metabase可能因为缓存占用过多内存而崩溃。这个参数限制缓存条数,超过后会淘汰最旧的。

8.3 查询参数化

一定要用Metabase的模板变量,而不是在SQL里拼接字符串。模板变量不仅安全,还能让缓存正常工作。如果直接拼接,比如 WHERE date = '2025-04-01',那每次改日期都会生成新的查询哈希,缓存无法复用。

8.4 时区问题

如果数据库和Metabase时区不一致,now() 的结果可能不稳定,导致缓存失效。建议统一设置 MB_JVM_TIMEZONE 和数据库连接时区,让查询结果稳定。

九、总结

缓存命中率低迷,大多数时候不是Metabase的问题,而是配置和使用方式没跟上。核心要抓住三点:第一,TTL要和数据更新频率匹配,不能一刀切;第二,查询语句要稳定,避免在SQL里写动态函数;第三,如果有多实例,一定要用共享缓存。做到这三点,命中率通常就能从低谷升到80%以上。另外,善用查询级别覆盖和缓存预热,可以进一步精细化控制。

最后,要养成监控的习惯。定期查看缓存命中率,如果发现下降,及时排查原因。缓存用好了,Metabase会变得非常顺畅,数据库也会轻松很多。