Caching
Source: docs/guide/06-caching.md at origin/main (3688d236), synced 2026-11-05. Do not edit this page here; change the source and run yarn sync:semantic.
A metric can be served from a cube: a table of the metric already totalled by a few dimensions and a time bucket, kept up to date on a schedule. A question the cube can answer is read from it in milliseconds and costs the warehouse nothing. One it cannot answer goes to the warehouse, or asks you first. Either way the answer says which happened (Answers).
The warehouse stays the source of record. A cube is a copy of what the warehouse would compute, found by an exact fingerprint of the metric's definition, so it can only ever serve the same computation.
Turning it on
Add a cache directive to the metric and save it. That means a metric write on the catalog,
PUT /metrics/{id} with the whole metric. Studio's model_change edits fields and time axes but
not metrics.
name: revenue
anchor: orders
agg: sum
operand: amount
filters:
- {field: is_test, op: equals, value: false}
cache:
- dimensions: [region, channel]
time_grain: {unit: hour}
from: "2024-01-01T00:00:00Z"
tiers:
- {name: recent, cron: "0 * * * *", time_zone: UTC}
| Key | Says |
|---|---|
dimensions | the fields the cube is broken down by. A query may group or filter by any of them, and by no others. Write them as the metric's filters are written: a bare field of the anchor, a shorthand, or a path. |
time_grain | the cube's bucket, {unit, multiple}. The cube answers that grain and any coarser one it divides into. |
from | where the cube starts, a UTC instant. Required. |
to | optional. With it, the cube fills [from, to) once and is never refreshed. Without it, the cube fills up to now and keeps refreshing. |
tiers | refresh schedules, each a name and a five-field cron. The fastest one sets how often the cube refreshes: every 1, 5, 15 or 30 minutes, 1 or 6 hours, or a day. |
time_grain must be on the grain ladder:
1m → 5m → 15m → 30m → 1h → 3h → 6h → 12h → 1d ─┬→ 1w
└→ month → quarter → year
{unit: minute} takes multiple 1, 5, 15 or 30. {unit: hour} takes 1, 3, 6 or 12. Every other
unit takes 1. A month, quarter or year cube is refused (CACHE_DIRECTIVE_REFUSED): cache at
{unit: day} instead, and month, quarter and year questions are answered from it. A grain finer
than the metric's time axis offers (an hourly cube over a Date axis) is refused the same way.
Saving the metric registers the cube, which then fills in the background. Registration runs after the write and cannot undo it, so a directive can be saved even when no cube was made, for example when the cache service is down. The metric then answers from the warehouse.
What cannot be cached
A cube is built for an aggregation metric with a declared time axis in a domain whose time zone is UTC. These are not built:
avg,medianandpercentilemetrics- derived metrics. Cache their components instead, and the derived metric is served from those cubes.
count_distinctcoarser than a day, because distinct counts cannot be added across days- metrics owned by a domain whose
timezoneis not UTC - a directive with no
from, or whose fastest tier is not one of the cadences above
Sync and hand-written caches
Today a sync rewrites every metric it owns from its KPI, and a KPI carries no cache directive. So
a cache added by hand to a synced metric is removed by the next sync. A cache on a metric a
person wrote (one with no KPI behind it) is kept.
When a cube answers
A cube answers a question only when it holds exactly what the question needs:
- Dimensions. Every field the question groups or filters by is one of the cube's dimensions.
- Grain. The question's bucket is the cube's or a coarser one it divides into. A
1dcube answersweek,month,quarterandyear. A1wcube never answersmonth, because weeks do not fit into months. A total with no time bucket reads any grain. - Window edges. The window starts where one of the cube's buckets starts: an hourly cube cannot answer from 09:10. The end must be on a bucket edge too, unless it is now or later.
- Coverage. The cube holds every UTC day the window touches.
- Time zone. Cube buckets are UTC. A question in another zone is answered from a cube whose
buckets line up with that zone's offset: an hourly question in
Asia/Kolkata(+05:30) reads a30mcube, never a1hone. ADateaxis has no zone and is exempt. - Distinct counts need exactly the cube's dimensions and exactly its grain.
All or nothing. If any metric in a statement cannot be served from a cube, the whole statement runs on the warehouse. Answers never mix sources.
A miss is never silent. The plan, and semantics.cache on a warehouse answer, list each reason the
cube could not serve, such as a dimension it lacks, a grain it is too coarse for, or the days it
does not hold.
When the cache cannot answer: the serving policy
serving:
on_miss: ask # ask (default) | warehouse | reject
on_stale: disclose # disclose (default) | ask
| Setting | On a miss or a stale cube |
|---|---|
on_miss: ask | On a metered warehouse (Snowflake, BigQuery), the query stops and asks for consent, carrying the plan and its price. Resend it with consent: {warehouse: true} to run it. |
on_miss: warehouse | It runs on the warehouse without asking. |
on_miss: reject | It is refused (CACHE_MISS_REJECTED); consent cannot help. |
on_stale: disclose | A cube past its refresh cadence still answers, and the answer says how stale it is. |
on_stale: ask | It asks: consent: {stale: true} to accept the cube, or {warehouse: true} to run live. |
On an unmetered warehouse, such as your own DuckDB, nothing asks for consent, though
on_miss: reject still refuses. A query sent with from_cache: true on a metered warehouse is
answered from cubes or refused (CACHE_CANNOT_SERVE, with every reason), never run on the
warehouse.
Fresh as of the last refresh
A window that ends now runs past the cube's last refresh, so the cube answers with what it holds and says so:
includes data up to 2026-09-29T14:00:00Z (the cube's last refresh);
the last 37 minutes of the window are not in the cache
The same moment is in each metric's routing entry as cache_through. A cube past its own
refresh cadence is also stale, and on_stale decides what happens then.