From ae719797ee94f51bd07ba6bb8b93b331791b4247 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 2 Apr 2026 11:45:22 +0000 Subject: [PATCH 1/2] Add pre-aggregate best practices: granularity, sizing, and semantic layer coverage Generated-By: mintlify-agent --- references/pre-aggregates/getting-started.mdx | 4 +++- references/pre-aggregates/overview.mdx | 6 ++++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/references/pre-aggregates/getting-started.mdx b/references/pre-aggregates/getting-started.mdx index 8cab50a9..4c430136 100644 --- a/references/pre-aggregates/getting-started.mdx +++ b/references/pre-aggregates/getting-started.mdx @@ -78,7 +78,9 @@ Pre-aggregates are defined under the `pre_aggregates` key in your model configur ## Multiple pre-aggregates per model -You can define multiple pre-aggregates on the same model, each targeting different query patterns. For example, you might want a fine-grained daily pre-aggregate for detailed dashboards and a coarser monthly one for summary views: +You can define multiple pre-aggregates on the same model, each targeting different query patterns. It is better to have **multiple small, focused pre-aggregates** rather than a single one containing all metrics and dimensions. Including too many dimensions increases the number of unique combinations, which generates large materialization files — this defeats the purpose of pre-aggregates, since they are meant to be smaller and faster than querying the warehouse directly. + +For example, you might want a fine-grained daily pre-aggregate for detailed dashboards and a coarser monthly one for summary views: ```yaml models: diff --git a/references/pre-aggregates/overview.mdx b/references/pre-aggregates/overview.mdx index 4e0f1ce6..4ce08a36 100644 --- a/references/pre-aggregates/overview.mdx +++ b/references/pre-aggregates/overview.mdx @@ -12,6 +12,8 @@ Pre-aggregates let you define materialized summaries of your data directly in yo This is especially useful for dashboards with high traffic or expensive aggregations that don't need real-time data. +Any query that goes through the Lightdash semantic layer can hit a pre-aggregate — this includes the Lightdash app, the API, [MCP](/references/integrations/lightdash-mcp), AI agents, the [Embed SDK](/references/embedding), and the [React SDK](/references/react-sdk). + Define pre-aggregates in your dbt project and configure scheduling. @@ -74,6 +76,10 @@ When a user runs a query, Lightdash automatically checks if a pre-aggregate can - The query does not contain custom dimensions, custom metrics, or table calculations - If the query uses a time dimension, the requested granularity is **equal to or coarser** than the pre-aggregate's granularity (for example, a `day` pre-aggregate can serve `day`, `week`, `month`, or `year` queries, but not `hour`) + + If you pre-aggregate at **day** granularity, the cache hits for `day`, `week`, `month`, `quarter`, and `year` queries. If you pre-aggregate at **month** granularity, the cache hits for `month`, `quarter`, and `year` — but **not** for `day` or `week`, since those require finer-grained data. + + When multiple pre-aggregates match a query, Lightdash picks the smallest one (fewest dimensions, then fewest metrics as tiebreaker). ### Dimensions from joined tables From da23f9e69359f119912034ccdde91c1e94207bcf Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 2 Apr 2026 11:47:52 +0000 Subject: [PATCH 2/2] Link AI agents and API reference in pre-aggregates overview Generated-By: mintlify-agent --- references/pre-aggregates/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/references/pre-aggregates/overview.mdx b/references/pre-aggregates/overview.mdx index 4ce08a36..a482355e 100644 --- a/references/pre-aggregates/overview.mdx +++ b/references/pre-aggregates/overview.mdx @@ -12,7 +12,7 @@ Pre-aggregates let you define materialized summaries of your data directly in yo This is especially useful for dashboards with high traffic or expensive aggregations that don't need real-time data. -Any query that goes through the Lightdash semantic layer can hit a pre-aggregate — this includes the Lightdash app, the API, [MCP](/references/integrations/lightdash-mcp), AI agents, the [Embed SDK](/references/embedding), and the [React SDK](/references/react-sdk). +Any query that goes through the Lightdash semantic layer can hit a pre-aggregate — this includes the Lightdash app, the [API](/api-reference/v1/introduction), [MCP](/references/integrations/lightdash-mcp), [AI agents](/guides/ai-agents), the [Embed SDK](/references/embedding), and the [React SDK](/references/react-sdk).