From fa2c7eb56e1d39ee74c5e6527ebf2c90c7f159ed Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Tue, 19 May 2026 06:48:55 +0000
Subject: [PATCH] docs: document AI agent period-over-period comparisons

---
 guides/ai-agents/using-ai-agents.mdx | 25 +++++++++++++++++++++++++
 guides/period-over-period.mdx        |  4 ++++
 2 files changed, 29 insertions(+)

diff --git a/guides/ai-agents/using-ai-agents.mdx b/guides/ai-agents/using-ai-agents.mdx
index 525ad7a5..3c9af9d1 100644
--- a/guides/ai-agents/using-ai-agents.mdx
+++ b/guides/ai-agents/using-ai-agents.mdx
@@ -15,6 +15,7 @@ AI agents in Lightdash allow you to:
 - **Guide you to the right data** - Direct you to the most relevant explores or tables for your questions
 - **Discover existing content** - Find and share relevant charts and dashboards that have already been created in your project
 - **Generate complete dashboards** - Create multiple related visualizations at once that tell a cohesive story about your data, perfect for executive summaries or thematic analyses
+- **Compare across time periods** - Ask for month-over-month, year-over-year, or any custom period offset, and the agent adds a comparison column next to each metric automatically
 
 As mentioned earlier, Lightdash agents use the **semantic layer** defined in your dbt models to understand your data structure, relationships, and business logic.
 This ensures that the AI generates accurate queries and visualizations based on your specific data context.
@@ -51,6 +52,30 @@ If your agent has data access disabled, pinning still works — the agent sees t
 
 ## Example use cases
 
+### Period-over-period comparisons
+
+Agents can answer time-comparison questions directly — month-over-month, year-over-year, or any custom offset — without you having to set up the comparison in the Explorer first.
+
+When you ask a comparison question, the agent picks a base metric, a time dimension, a granularity (day, week, month, quarter, or year), and an offset (how many periods back). It then runs the query and adds a comparison column next to the base metric, labelled with the offset (for example, `Revenue (Previous month)`).
+
+**Prompts that work well**
+
+- *"Compare revenue to last month"*
+- *"Month-over-month new users"*
+- *"Year-over-year orders by week"*
+- *"Show revenue this quarter vs the previous quarter, and vs the same quarter last year"*
+
+You can stack multiple comparisons on the same metric (for example, MoM and YoY together) and you can use a [custom metric](/references/custom-fields) as the base.
+
+<Tip>
+  Period-over-period is for comparing whole prior periods (last month, last quarter, last year). For period-to-date questions like MTD or YTD, ask the agent for a filtered aggregation instead — for example, *"revenue so far this month vs the same point last month"*.
+</Tip>
+
+**Limitations**
+
+- The granularity must match the time dimension's interval — ask for *"monthly revenue vs last month"* (not *"daily revenue vs last month"*).
+- The agent can't yet sort or filter on the generated comparison column directly; sort or filter on the base metric or the time dimension instead.
+
 ### Advanced visualizations with window functions
 
 AI agents can handle complex analytical queries that would traditionally require writing intricate SQL or YAML configurations. In this example, we demonstrate building a 3-month rolling average visualization using nothing but natural language.
diff --git a/guides/period-over-period.mdx b/guides/period-over-period.mdx
index a21dd24f..5cac0c2f 100644
--- a/guides/period-over-period.mdx
+++ b/guides/period-over-period.mdx
@@ -22,6 +22,10 @@ To add a period comparison:
 4. Choose the time dimension and offset, then hit save
 5. Add the generated metric to your chart
 
+<Tip>
+  You can also ask an [AI agent](/guides/ai-agents/using-ai-agents#period-over-period-comparisons) for comparisons in natural language — for example, *"compare revenue to last month"* or *"year-over-year orders by week"*.
+</Tip>
+
 ---
 
 Period-over-period analysis is one of the most common ways to evaluate how metrics change over time. Whether you're looking at **month-over-month growth**, **year-over-year comparisons**, or **week-over-week performance**, Lightdash makes it easy to build these analyses directly in your dashboards.