Datasets and metrics
OpenDash's semantic layer. Datasets describe your tables in small YAML files, metrics name the numbers that matter, and both compile to safe SQL.
Datasets and metrics are how you tell OpenDash what your numbers mean, once, so every answer agrees. A question that a metric covers takes the Metric path: it is built from definitions an admin approved, not from SQL the model wrote.
Find them under Knowledge → Datasets and Knowledge → Metrics.
Datasets
A dataset is a table or a query with a declared shape: what one row is, which columns exist, and what you can sum, count or filter.
ref: mrr_monthly
label: MRR snapshot by month
grain: one row per subscription item active at the end of each month
primary_key: [item_id, month]
time_column: month
sql: |
select ...
columns:
- { name: month, type: time, grain: month, description: The month (its first day) }
- { name: plan_id, type: string, dimension: true }
- { name: mrr_usd, type: number, format: usd }
- { name: is_test, type: boolean, dimension: true }
measures:
- { name: mrr, expr: "round(sum(mrr_usd), 2)", format: usd, description: MRR in USD }
- { name: paying_customers, expr: "count(distinct account_id)" }
segments:
- { name: exclude_test, where: "not is_test", default: true }
relationships:
- { to: plans, type: "n:1", on: { plan_id: id } }
snapshot: { at: month }| Field | Description |
|---|---|
ref | Identifier, lower_snake_case. |
label, description | How people and the analyst refer to it. |
sql | The query, in the source's own dialect. |
grain | What one row is, in words. Tested to be unique. |
primary_key, time_column | The key columns and the column periods filter on. |
columns | Each with a type (string, number, boolean, time), and optionally dimension, synonyms, grain and format (number, usd, percent). |
measures | Aggregations: name and expr, optionally format. |
segments | Named filters. A default: true segment always applies unless a question excludes it. |
relationships | Joins to other datasets: n:1, 1:1 or 1:n, with on columns. |
snapshot | For month-end style tables, the column that marks each snapshot. |
usage_guidance, ai_context | Notes and examples for the analyst. |
Why the compiler only joins many-to-one
Joining to the "many" side of a relationship silently multiplies rows, and every sum after it is wrong. OpenDash's compiler only joins many-to-one, so a fan-out can't happen in a metric query.
Metrics
A metric names a measure and how it should be read:
name: mrr
label: Monthly recurring revenue
description: MRR at the end of each month
dataset: mrr_monthly
measure: mrr
default_grain: month
format: usd
direction: higher_is_better
synonyms: [recurring revenue, run-rate revenue, MRR]| Field | Description |
|---|---|
name, label, description | Identifier and how it's shown. |
dataset, measure | Where the number comes from. |
segments | Filters always applied to this metric. |
time_column, default_grain | How it's bucketed over time (none for a point-in-time metric). |
format | number, usd or percent. |
direction | higher_is_better, lower_is_better or neutral. Used by insights and goals. |
synonyms | Other words people use for it. |
The analyst asks for metrics with up to five metrics, four dimensions and ten filters at a time, over ranges such as last_month, this_quarter, year_to_date or last_12_months, with an optional comparison to the previous period.
Create and change definitions
- Write one in the editor: YAML on the left with live checks, notes on the right.
- Draft them from tables. On a source's Overview, Draft definitions has helpers draft datasets and metrics from the tables you pick, each tested against your data. This uses the background budget.
- Make this a metric on an answer's query proposes a metric from it.
- Starter pack. The sample company comes with a proposed set of definitions and glossary terms to approve.
Tests and approval
Every definition is tested against your data before it's used:
- a dataset must run, return the columns it declares, have a unique grain, land its
n:1joins on unique keys, and fill its time column; - a metric must compile and run.
Results show as Tests passed, Needs a look or Tests failed.
Only owners and admins save, approve and release definitions. Editing a definition creates a new version: the Verified badge clears until it's approved again, and Ask keeps using the approved version meanwhile. Every version keeps its change note, so you can see who changed what and why.