> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clarityq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating and Editing Dashboards

> How to create dashboards with the AI agent, edit them, and work with filters.

## Artifacts vs Dashboards in Chat

Before diving into creation, it's important to understand the distinction between the two types of visual output in chat:

* **Artifacts** are static visualizations displayed **inline** in the conversation. They show the data as it was at the moment the agent generated them.
* **Dashboards** are interactive visualizations that appear as a **reference card** in the conversation. Clicking the card opens the dashboard in the **right panel**, where you can interact with filters, change date ranges, and see live data.

## Creating a Dashboard

### From an artifact in chat

The simplest way to create a dashboard is to turn an existing artifact into one. When the agent generates a visualization as part of an answer, click the **Make it a dashboard** button on the artifact. The agent converts the static visualization into an interactive dashboard — replacing hardcoded data with dynamic SQL queries and adding a date range picker and filters.

You can also ask the agent directly — for example, *"turn this into a dashboard"*.

### With the `/dashboard` command

For a dashboard built from scratch, use the `/dashboard add` command with a description of what you want:

* *"/dashboard add retention dashboard with main retention metrics and trends, with filters for country and platform"*
* *"/dashboard add weekly KPI overview showing installs, revenue, churn rate, and DAU with a date range picker and platform breakdown"*
* *"/dashboard add funnel dashboard showing signup to first purchase conversion with step-by-step drop-off rates"*

The agent builds the full dashboard — visualizations, date range picker, dynamic SQL queries, and semantic component tagging.

<Tip>
  Be specific about what you want to see. Mention the metrics, breakdowns, filters, and time ranges you care about. The more detail you give, the closer the first draft will be to what you need.
</Tip>

## Saving a Dashboard

When a dashboard is created in chat, it **only exists within that conversation**. To make it persistent and accessible from the Dashboards page, you need to save it.

Click the **Save Dashboard** button at the top of the dashboard panel. You'll be prompted to give the dashboard a name and an optional description. Once saved, the dashboard appears in your **My Dashboards** view as a **Private** dashboard.

<Note>
  Until you save, the dashboard lives only in the chat. If you close the conversation, you can still reopen it and save later — but the dashboard won't appear on the Dashboards page until you do.
</Note>

## Dashboard Versions in Chat

As you iterate on a dashboard in the same conversation — asking the agent to add charts, change filters, or restructure the layout — each update creates a **new version** in the chat. You'll see multiple dashboard reference cards in the conversation, one for each version.

* **Navigate between versions** by clicking different reference cards — each opens that version in the right panel
* **Only the latest version is interactive** — older versions are visible but their filters are locked
* **Save saves the version you're viewing** — whichever version you have open when you click **Save Dashboard** is the one that gets persisted and becomes accessible on the Dashboards page

## Editing a Dashboard

If a saved dashboard needs changes, use **Edit in Chat** from the dashboard's action bar. This opens a chat where the agent has the full context of the dashboard. Describe what you want to change:

* *"Add a table showing the top 10 countries by revenue"*
* *"Change the bar chart to a line chart"*
* *"Add a platform filter dropdown"*
* *"Remove the KPI card for churn rate"*

The agent modifies the dashboard and you can preview the result in the right panel. Click **Save Dashboard** again to persist the updated version.

## Filters

### Date Range (Required)

Every dashboard has a date range picker with a **default preset** that the agent selects based on the dashboard's content:

* **Trend and time series dashboards** default to a range like Last 7 days, Last 14 days, or Last 28 days
* **Single-day snapshot dashboards** default to Yesterday

Available presets include: Today, Yesterday, This Week, Last Week, Last 7/14/28/90/180 days, This Calendar Month, Last Calendar Month, and a Custom date range.

Changing the date range re-runs all queries and updates every visualization.

### Additional Filters (Optional)

The agent adds filters based on the data and your request. If you don't specify which filters to include, the agent uses its judgment — if the data groups by a categorical column (like country or platform), it becomes a filter candidate.

Filter types include:

* **Dropdown filters** — Select from a list of values (e.g., country, platform)
* **Multi-select filters** — Choose multiple values at once
* **Cascading filters** — A child filter's options depend on the parent's selection (e.g., selecting a country updates the available cities)

Additional filters default to **"All"**, meaning no filtering is applied until you make a selection.

Filters can have their options **hardcoded** (queried once when the dashboard is built, faster to load) or **dynamic** (queried at runtime whenever a parent filter changes, always current).

### Breakdown Filters

Breakdown filters let you choose what dimension to group all the metrics in the dashboard by. Instead of filtering *out* data, a breakdown filter splits it — adding a row for each value of the selected dimension.

For example, a KPI table showing installs, revenue, and churn could have a breakdown filter with options like **Country**, **Platform**, or **Install Date**. Selecting "Country" adds a row for each country, showing all metrics per country. Switching to "Platform" regroups the same metrics by platform.

Breakdown filters are especially useful for tables where you want to explore the same set of metrics across different slices without creating a separate dashboard for each one.

### Changing Filter Defaults

You can change the default date range preset and filter values by asking the agent in **Edit in Chat** — for example, *"change the default date range to last 28 days"* or *"default the platform filter to iOS"*.

<Note>
  You cannot change the set of available date range presets — those are fixed. But you can change which preset is selected by default, and you can add, remove, or restructure additional filters through Edit in Chat.
</Note>

## Advanced Tips

### Performance

ClarityQ optimizes dashboard queries for efficiency and caches results to minimize warehouse load. If a dashboard still feels slow:

* **Use a shorter default date range** — A dashboard defaulting to Last 180 days will query much more data than one defaulting to Last 7 days. Ask the agent to change the default if you don't need the full range on every load.
* **Keep dashboards focused** — The agent optimizes queries so that multiple components can share data from fewer queries, but fewer components still means fewer queries overall. Consider splitting large dashboards into multiple smaller ones.

### Pagination

For tables with many rows, the agent adds pagination automatically. Be aware that larger page sizes mean more data transferred per query. If a table feels slow, consider reducing the page size or adding filters to narrow the result set.

### Filters

* **Cascading filters support up to 2 levels** — A parent filter can drive one child filter, but you can't chain three or more levels
* **Hardcoded filter options load faster** than dynamic ones — For stable lists like countries or platforms, hardcoded options avoid an extra query on every load
* **Changing a parent filter resets its child** — If you change the country, the city filter resets to "All"

### Error Handling

If a SQL query fails inside a dashboard — for example, because a table was renamed or a column was removed — that specific component shows an error state. The rest of the dashboard continues to work. Use **Edit in Chat** to fix the broken query.

### Iterating with the Agent

Dashboards rarely come out perfect on the first try. Use **Edit in Chat** to refine rather than starting over. Describe what's wrong — *"the revenue chart is showing gross instead of net"* or *"the table needs a column for percentage change"* — and the agent adjusts the existing dashboard rather than rebuilding from scratch.