Configure a chart with dimensions and metrics
Configure charts with dimensions and metric expressions in the semantic manual editor.
Target Audience: Makers using the semantic chart editor.
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
Key concepts
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.
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 writingSUM(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.
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) + 100Legacy: 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; useSUM(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:
Literals and math operators (Expression)
The Expression field supports:
Numeric literals:
42,3.14,0Binary operators:
+,-,*,/,%Unary negation:
-SUM(loss)Parentheses for grouping:
(SUM(a) + SUM(b)) / COUNT(*)
Examples:
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:
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")orSUM(\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
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 or Add filters to a dashboard
Last updated
Was this helpful?