> For the complete documentation index, see [llms.txt](https://docs.toucanai.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toucanai.cloud/faq-and-troubleshooting/ai-assisted-creation/build-charts-with-semantic-ai.md).

# Build charts with AI

{% hint style="info" %}
**Target Audience**: Makers using Toucan AI to generate charts from natural language.
{% endhint %}

### Goal

Understand what the AI assistant can build with Toucan AI's chart operations, and how to phrase requests that lead to reliable chart configurations.

***

### Prerequisites

* A [connected and active database](/build/data-connections/how-to/add-a-database.md).
* A clear business question, such as "show monthly revenue growth" or "compare women share by team".
* Basic familiarity with [Configure a chart with dimensions and metrics](/build/charts/how-to/configure-a-chart-with-dimensions-and-metrics.md) if you want to inspect or refine the generated chart manually.

***

### Key concepts

| Term                      | Role                                                                                                                 |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Semantic chart config** | A chart definition that declares its tables, joins, dimensions, metrics, and ordering directly.                      |
| **Simple metric**         | A metric written from columns and aggregations, such as `SUM(revenue)` or `SUM(revenue) / COUNT_DISTINCT(order_id)`. |
| **Derived metric**        | A metric written from other metrics by name, such as `` `men count` / `women count` ``.                              |
| **Metric helper**         | A chart-scoped helper metric that is not exposed as a persisted, reusable metric.                                    |
| **Normalization**         | A share calculation such as "share of total" or "share within each group".                                           |
| **Time comparison**       | A comparison against a previous period, such as month-over-month or year-over-year.                                  |
| **Ordering**              | Sorting and limiting the result, globally or within each group.                                                      |

In this model, the AI builds the builds the chart configuration directly, instead of building a separate aggregation query first. It's possible thanks to the fact we can now entirely deduce the query from the configuration.

***

### How the AI builds a chart

When you ask for a chart, the assistant follows a predictable workflow:

1. It identifies the relevant tables and columns in your connected database.
2. It chooses a chart type that matches your intent, such as a line chart for a trend or a bar chart for a ranking.
3. It builds a chart configuration with dimensions, metrics, filters, and ordering.
4. It can preview the resulting data before rendering the final chart.
5. It shows the chart, or adds it to a dashboard depending on the flow you are using.

This matters because many advanced requests are now expressed as chart operations, not as manual SQL logic.

***

### What you can ask for

The assistant works best when your request describes the business meaning you want to see. Here are typical patterns:

| You ask for...                                        | The assistant typically configures...                                                   |
| ----------------------------------------------------- | --------------------------------------------------------------------------------------- |
| "Monthly revenue trend"                               | A datetime dimension with monthly granularity and a simple metric such as `SUM(amount)` |
| "Top 5 product categories by revenue"                 | A category dimension, a revenue metric, and ordering with a descending limit            |
| "Gross margin percentage by category"                 | A formula metric such as `SUM(revenue - discount) / SUM(revenue)`                       |
| "Average monthly base salary by team"                 | A metric combining aggregation and division, often across joined tables                 |
| "Each category's share of total revenue"              | A normalized metric with `share-of-total`                                               |
| "Share of women employees within each team"           | A filtered metric plus `share-of-group`                                                 |
| "Top 3 sellers by revenue share within each region"   | Per-group normalization plus per-group ordering and limit                               |
| "Revenue by region and product category as a heatmap" | Two dimensions plus one metric                                                          |
| "Month-over-month revenue change"                     | A metric with a time comparison against the previous month                              |
| "Year-over-year revenue growth %"                     | A metric with a time comparison in percentage mode                                      |
| "Ratio of men to women employees"                     | Two helper metrics with different filters plus one derived metric                       |
| "Salary per employee last year by department"         | A helper metric with a time comparison, then a visible derived or aliased metric        |
| "Each category's share of the month's total growth"   | A time-shifted helper metric plus a visible normalized alias                            |

The same idea can lead to different chart configurations depending on your wording. For example, "growth of share" and "share of growth" are not the same calculation.

***

### Advanced concepts the AI can handle

#### Filters before or after aggregation

The chart model distinguishes two kinds of filtering:

* **Row filter**: restricts which rows contribute to a metric before aggregation.
* **Post-aggregation filter**: keeps only result rows that match a condition after the metric is computed.

This distinction is important for percentages and thresholds. For example, filtering to only "USA" before computing a share does not mean the same thing as computing all shares first and then keeping only the USA row.

#### Shares and percentages

The assistant can compute:

* **Share of total**: each row's contribution to the chart's grand total.
* **Share of group**: each row's contribution within a partition such as a month, team, or region.

If a metric is already a ratio, such as margin rate or conversion rate, it should usually stay as-is. Reapplying a share calculation would distort the meaning.

#### Time comparisons

The assistant can compare a metric with a previous period when the chart includes a date dimension. Common cases include:

* previous month's value
* month-over-month change
* year-over-year growth percentage

These comparisons are chart time operations, not arithmetic on a manually selected "previous period" column.

#### Helper metrics and derived metrics

Some requests need intermediate metrics that the user does not want to display directly. A common example is a ratio between two filtered populations:

```
men count
women count
men to women ratio
```

The visible metric is derived from chart-level helper metrics, which are scoped to a single chart and are not exposed as persisted, reusable metrics. This is also how the assistant handles more advanced cases such as "share of growth".

***

### Writing prompts that work well

Good prompts usually mention:

* the business measure: revenue, salary, employee count, discount, margin
* the breakdown: by month, by team, by category, by region
* the comparison: top 5, share, ratio, previous month, previous year
* the expected output: bar chart, line chart, value chart, heatmap, table

Examples:

```
Show the monthly revenue trend.
```

```
Show the top 3 sellers by revenue share within each region.
```

```
Show year-over-year revenue growth percentage by quarter.
```

```
Show the ratio of total offered salary to total expected salary by department.
```

***

### Limits and verification tips

{% hint style="warning" %}
**What to keep in mind**

* The assistant does not use free-form SQL inside metric expressions. Conditional logic belongs in chart filters, shares, and time comparisons.
* A metric is either **simple** or **derived**. It cannot mix raw aggregations with references to other metrics in the same expression.
* A ratio is already a proportion. Do not expect an additional share calculation on top unless you explicitly want a second normalization.
* Time comparisons depend on a date dimension already present in the chart.
* You should still verify important business results before publishing them to end-users.
  {% endhint %}

For the field-by-field reference, see [Semantic chart reference](/references/semantic-chart-reference.md).

***

The assistant chooses the chart type based on your intent and data shape. For the exact slots and fields used by each chart type, see [Semantic chart reference](/references/semantic-chart-reference.md) and [Configure a chart with dimensions and metrics](/build/charts/how-to/configure-a-chart-with-dimensions-and-metrics.md).

***

### Conclusion

AI chart generation lets you ask for business concepts such as shares, ratios, top-N, and period-over-period changes without manually assembling the chart logic yourself.

**Suggested next steps:** [Semantic chart reference](/references/semantic-chart-reference.md) or [When should I switch to manual editing?](/faq-and-troubleshooting/ai-assisted-creation/when-should-i-switch-to-manual-editing.md)