Add pre-aggregate best practices and semantic layer note (#527)

* Add pre-aggregate best practices: granularity, sizing, and semantic layer coverage

Generated-By: mintlify-agent

* Link AI agents and API reference in pre-aggregates overview

Generated-By: mintlify-agent

---------

Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>

Author: mintlify[bot]

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:

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](/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).
+
 <CardGroup cols={2}>
   <Card title="Getting started" icon="rocket" horizontal href="/references/pre-aggregates/getting-started">
     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`)
 
+<Tip>
+  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.
+</Tip>
+
 When multiple pre-aggregates match a query, Lightdash picks the smallest one (fewest dimensions, then fewest metrics as tiebreaker).
 
 ### Dimensions from joined tables