Monitoring and debugging pre-aggregates

You can monitor pre-aggregates from Project Settings > Pre-aggregates. This section has two tabs: Materializations for tracking status and Analytics for query hit/miss statistics.

Materialization status

The Materializations tab shows all your pre-aggregates and their current state.

Each pre-aggregate has a materialization lifecycle:

Status	Meaning
Active	The materialization is live and serving matching queries. Only one materialization can be active per pre-aggregate at a time.
In progress	A new materialization is being built. The previous active materialization continues serving queries until the new one completes.
Superseded	A newer materialization replaced this one, or the pre-aggregate’s definition changed after Lightdash built it. Lightdash no longer serves queries from it.
Failed	The materialization encountered an error. Check the error message for details.

Two columns show how Lightdash refreshes each pre-aggregate:

Schedule shows the refresh.cron expression, if the pre-aggregate has one.
Triggers shows which triggers rebuild it: on change (dimmed when refresh.on_change is false), schedule when the pre-aggregate has a cron, and manual. Last materialized names the trigger that produced the active materialization. See Scheduling refreshes for how the triggers work.

Click any pre-aggregate to see its full details, including row count, file size, and duration. To refresh every managed pre-aggregate, click Rebuild managed at the top of the page. To refresh one, open its detail drawer and click the rebuild icon next to Last materialization.

Hit and miss statistics

The Analytics tab tracks how often queries hit or miss pre-aggregates on a daily basis. Lightdash records these stats automatically for every query it runs, with no setup, and the tab shows the last 3 days. Only queries on explores that have a pre_aggregates block are counted. Queries on other explores don’t appear, not even as misses, so Total Queries can be lower than your project’s overall query volume.

You can break down the statistics by:

Explore name — which explores are benefiting from pre-aggregates
Query context — whether the query came from a chart, dashboard, or the explorer
Chart or dashboard — which specific saved content is hitting or missing

Use these stats to identify opportunities for new pre-aggregates or to tune existing ones.

Why a query misses a pre-aggregate

When a query doesn’t match any pre-aggregate, Lightdash records the specific reason. Understanding these reasons helps you decide whether to adjust your pre-aggregate definition or accept the warehouse query.

Miss reason	What it means	How to fix it
No pre-aggregates defined	The explore has no pre-aggregates configured.	Add a `pre_aggregates` block to your dbt model.
Dimension not in pre-aggregate	The query includes a dimension not covered by any pre-aggregate.	Add the missing dimension to your pre-aggregate’s `dimensions` list.
Metric not in pre-aggregate	The query includes a metric not covered by any pre-aggregate.	Add the missing metric to your pre-aggregate’s `metrics` list.
Filter dimension not in pre-aggregate	A filter references a dimension not in the pre-aggregate, or a model `required_filters` target is missing from it.	Add the filter dimension to the `dimensions` list — even if it’s only used for filtering, not grouping.
`sql_filter` field not in pre-aggregate	The model’s `sql_filter` references a field (for example `${customers.segment}`) that isn’t a covered dimension of the pre-aggregate, so the filter cannot be rewritten onto the materialization.	Add every field referenced by `sql_filter` to the pre-aggregate’s `dimensions` list. See `sql_filter` and pre-aggregates.
Pre-aggregate filter not satisfied	The query’s filter doesn’t match the pre-aggregate’s, or the pre-aggregate’s `filters` block targets a required-filter field.	Narrow the query filter and match the pre-aggregate filter’s operator, remove any pre-aggregate `filters` on required-filter fields, or create another pre-aggregate for that query pattern.
Non-additive metric	The query includes a metric type that can’t be re-aggregated (for example, `count_distinct` or `median`) and it isn’t an exact match of any pre-aggregate.	Define a pre-aggregate whose dimensions and granularity match how the metric is queried, so the query can serve as an exact match. See supported metric types.
Non-additive metric: select exactly the pre-aggregate dimensions	The query includes a non-additive metric (`count_distinct`, `median`, `percentile`, etc.) and the pre-aggregate’s dimensions cover it, but the query didn’t select every pre-aggregate dimension at exactly its granularity — so no exact match.	Select every one of the pre-aggregate’s dimensions and use its exact granularity, or drop the non-additive metric.
Custom SQL metric	The query includes a custom SQL metric that can’t be re-aggregated. A `number` metric can be re-aggregated when every metric it references can be.	Build the metric only from re-aggregatable metrics and add it and the metrics it references to the pre-aggregate, or let the query run against the warehouse.
Granularity too fine	The query requests a finer time granularity than the pre-aggregate provides (for example, `hour` on a `day` pre-aggregate).	Either lower the pre-aggregate’s granularity or accept the warehouse query for this use case.
Time frame not derivable	The query’s time granularity can’t be safely rolled up from the pre-aggregate’s stored grain (for example, deriving calendar months from a week pre-aggregate — weeks cross month boundaries).	Store the pre-aggregate at a finer or aligned grain (day serves week, month, quarter, year).
Custom dimension present	The query uses a custom SQL dimension.	Custom SQL dimensions created in the UI are not supported. Write them back to the semantic layer.
Custom metric present	The query uses a custom metric.	Custom metrics defined in the Explorer are not supported. Write them back to the semantic layer.
SQL table calculation present	The query includes a raw SQL table calculation.	Use a formula table calculation instead, or let the query run against the warehouse.
Bypassed by user	The user explicitly bypassed the pre-aggregate cache for this query.	No action needed — this is intentional.
Materialized explore not found	Lightdash couldn’t resolve the pre-aggregate’s generated explore, usually because the source explore has changed shape since the pre-aggregate was last compiled.	Recompile or redeploy the project so the pre-aggregate explore is rebuilt.
No active materialization	A pre-aggregate matched the query, but no materialization is active yet — the first build hasn’t completed or the last one failed.	Wait for the running materialization to finish, or check the materialization status and re-run a failed build.

A query can also match a pre-aggregate and still run on the warehouse, because serving it from the materialization failed. The pre-aggregate icon next to Run query in the Explorer then reads “Pre-aggregate matched (<name>) but failed to serve. Results came from the warehouse”, without the cause. To see the error, turn off execution fallback so the query returns the error instead of running on the warehouse. On a self-hosted instance, the backend logs also record the cause as a warning, Pre-agg execution (duckdb) failed for <query uuid>: <error>. Falling back to warehouse, without turning fallback off. If the error is an S3 access error, check the bucket permissions in the self-hosting troubleshooting.

Dashboard pre-aggregate view

You can also monitor and manage pre-aggregates directly from any dashboard. Open the dashboard menu to access pre-aggregate options.

Pre-aggregate options in the dashboard menu

Pre-aggregation audit — Shows which tiles in the dashboard are hitting or missing pre-aggregates, and why. Available to editors, developers, and admins.
Rebuild pre-aggregates — Triggers a manual re-materialization for the pre-aggregates used by this dashboard. Available to developers and admins only.

Pre-aggregate audit view for a dashboard

The same audit data is available from the terminal via lightdash pre-aggregate-audit, which is useful for scripting, project-wide sweeps, and CI gates.

​Materialization status

​Hit and miss statistics

​Why a query misses a pre-aggregate

​Dashboard pre-aggregate view

Materialization status

Hit and miss statistics

Why a query misses a pre-aggregate

Dashboard pre-aggregate view