Build charts with AI
Build charts with AI using dimensions, metrics, filters, and time comparisons.
Target Audience: Makers using Toucan AI to generate charts from natural language.
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 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 if you want to inspect or refine the generated chart manually.
Key concepts
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:
It identifies the relevant tables and columns in your connected database.
It chooses a chart type that matches your intent, such as a line chart for a trend or a bar chart for a ranking.
It builds a chart configuration with dimensions, metrics, filters, and ordering.
It can preview the resulting data before rendering the final chart.
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:
"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:
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:
Limits and verification tips
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.
For the field-by-field reference, see Semantic chart reference.
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 and Configure a chart with dimensions and metrics.
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 or When should I switch to manual editing?
Last updated
Was this helpful?