> Documentation index: https://docs.beetl.io/llms.txt

# Result charts

> Plotting a result as a bar, line, area, scatter or pie chart.

Source: https://docs.beetl.io/query/charts/
Last updated: 2026-10-03

Any [query result](https://docs.beetl.io/concepts/query-results) can be drawn as a chart if it has something to plot.
Use the **Table** and **Chart** buttons in the result toolbar to switch views. Chart stays disabled
unless the result has a numeric column plus either a text or date column or a second numeric
column. **Expand** opens the chart full screen.

## How Beetl reads your columns

Beetl gives each column a role from its type, and the role decides where the column can go.

| Column                                                                     | Role     | Where it can go                              |
| -------------------------------------------------------------------------- | -------- | -------------------------------------------- |
| Integer, float or decimal                                                  | Numeric  | Y values; X axis of a scatter chart          |
| Date or timestamp, or text whose values are ISO dates such as `2026-10-03` | Temporal | X axis of a bar, line or area chart          |
| Any other text                                                             | Category | X axis of any chart except scatter; Split by |

Booleans, lists, structs and other types can't be charted. To plot a boolean as a category, cast it
in SQL: `CAST(is_active AS VARCHAR)`.

## The chart Beetl proposes

When a result opens, Beetl prepares a first chart from the column roles:

1. If there is a temporal column, a line chart over the first one, with the first numeric column as
   Y. If that is the only numeric column, the first category column splits it into one line per
   value.
2. Otherwise, if there is a category column, a bar chart over the first one with the first numeric
   column. If that is the only numeric column and a second category column exists, the second one
   splits the bars.
3. Otherwise, with 2 or more numeric columns, a scatter chart of the first against the second.

"First" means first in your `SELECT` list, so put the column you want on the X axis ahead of others
of the same kind.

## Choosing type and axes

The controls above the chart are **Chart**, **X axis**, **Y values** and **Split by**. Change them
and select **Build chart**. Y values accepts several numeric columns at once.

| Chart           | X axis                      | Y values                            | Split by                                               |
| --------------- | --------------------------- | ----------------------------------- | ------------------------------------------------------ |
| bar, line, area | Category or temporal        | 1 or more numeric                   | A category column other than X, with exactly 1 Y value |
| scatter         | Numeric                     | Exactly 1 numeric, different from X | A category column, optional                            |
| pie             | Category, one slice per row | Exactly 1 numeric                   | Not available                                          |

If you pick a combination these rules don't allow, Beetl names the problem and draws nothing. Two
more checks apply to the rows themselves. In a pie chart, each category value may appear only once.
With Split by, each pair of X value and split value may appear only once. If either check fails,
aggregate in SQL first, for example with `GROUP BY region, month`.

Rows with a null in any column the chart uses are left out, and the chart says how many, for example
"Skipped 12 rows with null values." X values are plotted in the order the rows come back, without
sorting, so add `ORDER BY` to a time series.

## Limits

Charts draw from the stored rows of the result, at most 1,000. When the query returned more, the
chart says how many it used, for example "Chart uses 1000 of 48210 rows." To chart all of the data,
aggregate in SQL until the result fits in 1,000 rows.

Chart settings are not saved with the result. When you reopen a result it starts on the table, and
Chart shows the proposed chart again. The result itself expires after 7 days, as described in
[Query results](https://docs.beetl.io/concepts/query-results).

## Charts in chat

When the assistant runs a query on the AI Chat page, the latest result opens in the panel next to
the conversation with the same Table and Chart views (in the sidebar it opens as a card that leads
to the Query page), so you can plot it without leaving the conversation. **Open full page** opens the
same result on the Query page.

## Saved and shared charts

A chart on a query result is private to you, like the result it draws from. For a chart you want to
keep, share or place next to others, build it in [Dashboards](https://docs.beetl.io/dashboards).

- [Lineage and drill-down](https://docs.beetl.io/query/lineage): Check where a value in the result came from.

- [Export](https://docs.beetl.io/query/export): Download the stored rows as CSV.