> 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/build/charts/how-to/configure-a-chart-with-dimensions-and-metrics.md).

# Configure a chart with dimensions and metrics

{% hint style="info" %}
**Target Audience**: Makers using the semantic chart editor.
{% endhint %}

### Goal

Configure a chart manually using **dimensions** (what you slice by) and **metrics** (what you measure), instead of assigning plain column names to chart axes.

***

### Prerequisites

* A [connected and active database](/build/data-connections/how-to/add-a-database.md).

***

### Key concepts

| Term               | Role                                                                                                                         |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| **Dimension**      | A qualitative or time axis — a category column, or a date column with a granularity (year, month, day, …).                   |
| **Metric**         | A quantitative measure, defined by an **expression** such as `SUM(amount)` or `SUM(revenue) / COUNT_DISTINCT(customer_id)`.  |
| **Derived metric** | A metric whose expression references **other metrics by name** instead of columns, e.g. `` `male count` / `female count` ``. |
| **Data source**    | The database table (and optional **joins** to other tables) that dimensions and metrics draw columns from.                   |
| **Ordering**       | How result rows are sorted and optionally limited.                                                                           |

Dimensions reference a concrete **table column**. Metrics reference columns only inside their **expression**; every column must sit inside an aggregation (`SUM`, `AVG`, `COUNT`, …).

For field-level details on metric filters, normalization, time comparison, helper metrics, and chart slots, see the [Semantic chart reference](/references/semantic-chart-reference.md).

***

### Steps

#### 1. Open the manual semantic editor

The editor knows whether a chart is semantic, so two possibilities: a. Open a semantic chart from the **Library**; we provided a few examples. b. Create a new chart: it will be semantic chart.

Then switch to **Manual**.

#### 2. Choose the data source

* Under **Data**, pick the database and source table.
* Optionally add **joins** to bring in columns from related tables. Joined tables expand the column list available to dimensions and metrics.
* Data steps remain available for pre-processing the source table when needed.
* Data steps are used to transform the data upfront: filter rows, rename columns, or create derived columns, to prepare the output schema consumed by the semantic editor.
* When you use **data steps**, the semantic editor exposes the columns produced by the pipeline (including columns you create/rename in the steps). They become selectable for your **dimensions** and **metric expressions**.

#### 3. Pick a chart type

* Select the visual type (bar, line, table, value, …). Each type exposes its own dimension and metric slots — for example, a bar chart has **Bar category**, optional **Series**, and **Bar height**.

#### 4. Configure dimensions

* Open a **Dimension** block and set a **Label** (shown to end-users).
* Pick the backing **Column** from the grouped table/column picker.
* For **date** columns, choose a **Granularity** (year, quarter, month, week, day).
* Optional dimensions (e.g. **Series** on a bar chart) can be toggled on with the header switch; turning them off removes them from the saved config.
* Column selection: dimensions are bound to a specific table column via the picker, so they don't rely on “bare” column names to resolve ambiguity after `joins`.

#### 5. Configure metrics

Each metric has two definition modes:

* **Basic** — pick one column and one aggregation (`Sum`, `Average`, `Count`, …). Equivalent to writing `SUM(column_name)`.
* **Expression** — write a free-form formula combining aggregations and arithmetic.

Supported aggregations: `SUM`, `AVG`, `MIN`, `MAX`, `COUNT`, `COUNT_DISTINCT`.

You may use quotes `"` or backticks \`\`\` to delimit a column name with spaces or special characters.

If you want the full semantic reference for `where`, `having`, `timeShift`, formatting, and hidden helper metrics, see [Semantic chart reference](/references/semantic-chart-reference.md).

#### Legacy vs Expression (calculations)

* **Legacy** (NonSemantic): advanced calculations typically require multiple **data steps** to produce intermediate columns (numerator/denominator, derived amounts, etc.), and then measure those columns.
* **Expression (semantic)**: you can combine multiple aggregations and math operations directly inside the metric.

Ratio example:

* Legacy: prepare intermediate columns via `data steps`, then build the metric.
* Expression: `SUM(revenue) / COUNT_DISTINCT(order_id)`

Literal example:

* Expression: `SUM(revenue) + 100`
* Legacy: for this kind of calculation (addition, division, etc.), you would use **data steps** to create one or more intermediate columns, and then measure the result.

{% hint style="warning" %} **Expression rules**

* Every **column** reference must appear inside an aggregation: a bare column (`amount`) is invalid; use `SUM(amount)`. (A bare reference to another **metric** by name is allowed — that's how derived metrics work; see below.)
* Nested aggregations are not supported: for example `AVG(SUM(amount))` is rejected.
* Columns sharing the same name across multiple joined tables cannot be picked in Basic; use distinct column names (or rename in `data steps`). In Expression, if needed, use quoted identifiers for names containing spaces/special characters (e.g. `SUM("unit price")`). {% endhint %}

**Expression examples:**

```
SUM(revenue)
SUM(quantity * unit_price)
SUM(revenue) / COUNT_DISTINCT(order_id)
```

#### Literals and math operators (Expression)

The **Expression** field supports:

* Numeric literals: `42`, `3.14`, `0`
* Binary operators: `+`, `-`, `*`, `/`, `%`
* Unary negation: `-SUM(loss)`
* Parentheses for grouping: `(SUM(a) + SUM(b)) / COUNT(*)`

Examples:

```
(SUM(revenue) + 10) / COUNT_DISTINCT(customer_id)
SUM(revenue) - SUM(discount)
```

#### Deriving metrics (referencing other metrics)

An expression can reference **another metric by its name** instead of a column. This lets you build a metric out of other metrics — for example a ratio of two counts:

```
male count          → COUNT(account_id)        (filtered to gender = Male)
female count        → COUNT(account_id)        (filtered to gender = Female)
male to female ratio → `male count` / `female count`
```

Use quotes or backticks around the metric name when it contains spaces (e.g. `` `male count` ``). Each referenced metric is computed per the chart's dimensions and the results are combined, so the derived metric is evaluated at the same grain as the rest of the chart.

This makes every metric one of two kinds:

* **Simple metric** — its expression uses only columns and aggregations (`COUNT(account_id)`, `SUM(amount) / 2`). It can use the full set of options (filter, having, share-of-total, time comparison).
* **Derived metric** — its expression uses only references to other metrics plus numbers and operators (`` `male count` / `female count` ``). It can carry a **having** filter on its computed value, but **not** a row filter (`where`), share-of-total, or time comparison.

{% hint style="warning" %} **Derivation rules**

* A single expression is **either** simple **or** derived — you cannot mix a metric reference with a raw aggregation (e.g. `` `helper` + SUM(amount) `` is rejected).
* A metric referenced by another metric may carry a row **filter**, but not share-of-total, having, or time comparison.
* References must not form a **cycle** (A → B → A), and a name cannot be used by both a metric and a table column. {% endhint %}

#### Column selection in metrics

* **Basic**: column picker + aggregation. If a column has the same name in multiple joined tables, Basic selection may be disabled to avoid ambiguity.
* **Expression**: you reference columns via identifiers inside the formula. For names containing spaces or special characters, use quoted identifiers, e.g. `SUM("unit price")` or `SUM(\`unit price\`)\`.

Switching between Basic and Expression preserves separate drafts, so you do not lose your work when exploring both modes.

#### 6. Set ordering (optional)

* Enable **Ordering** to sort results by any configured dimension or metric.
* Add one or more sort predicates, drag to reorder priority, and optionally set a row **limit**.

#### 7. Preview and save

* The chart preview updates as you edit.
* Incomplete required fields are highlighted; fix them before publishing.
* Save when the status badge shows the chart is persisted.

***

### Chart-type cheat sheet

| Chart type      | Typical dimensions            | Typical metrics                                   |
| --------------- | ----------------------------- | ------------------------------------------------- |
| **Bar**         | Bar category; optional series | Bar height; optional line overlay (vertical bars) |
| **Stacked bar** | Category; stack series        | Stack value                                       |
| **Line**        | X axis; optional series       | Line value                                        |
| **Circular**    | Slice label                   | Slice value                                       |
| **Heatmap**     | X axis; Y axis                | Cell value                                        |
| **Value**       | —                             | Main value; optional comparison                   |
| **Table**       | One dimension per column      | One metric per column                             |

***

### Conclusion

The chart is configured with explicit dimensions and metric expressions. The semantic layer executes the config against your tables and joins.

**Suggested next steps:** [Semantic chart reference](/references/semantic-chart-reference.md) or [Add filters to a dashboard](/build/dashboards-and-layouts/how-to/add-filters-to-a-dashboard.md)