Before you begin
Before you start, make sure you have:- Access: Access to Metrics Studio and a workspace you can write to. A metric stays in the workspace you choose and cannot move later.
- Permission: Permission to save revisions in that workspace. Without it, Save definition is disabled when you revise an existing metric.
- Metric app: An administrator has installed the Metric app in your account.
- Your SQL or table: The formula, the warehouse it runs on, and either a source table or the source SQL.
1
Start new metric
Open Metrics in the sidebar and choose New metric. The page opens with the note “Saved as an unreleased revision. SQL is stored as text, never run or checked here.”To start from existing SQL instead of an empty form, choose Paste SQL or a dbt model under Start from SQL or a dbt model. You can paste SQL or a dbt manifest with compiled models, up to 16 MiB and 5,000 models. Nothing is fetched, compiled, or run. Applying the import with Use source and reset definition replaces the definition in the form. It does not save the metric.
2
Name metric
Under Name and workspace, fill in:
- Destination workspace (required): where the metric lives. Existing items cannot move between workspaces.
- Name (required): the display name.
- Identifier (required): lowercase with underscores, unique in the workspace, for example
average_order_value. It cannot change after saving. - Description: optional.
3
Define calculation
Under Definition, choose Fields for the guided form or JSON to edit the full definition, including optional fields. If the JSON is invalid, Fields stays shut until you fix it.In Fields, set:
- Formula, Warehouse, and Aggregation type (all required).
- Output name and Output data type (required). Output unit and Granularity are optional.
- Source type: Table or SQL. Then Source entity, Source alias, and exactly one non-empty Source table or Source SQL. Switching the type clears the other field.
- Dimensions, filters, joins and parameters: open this section to add Dimensions, Filters, Mandatory filters, Joins, and Parameters. Each is a JSON array, and
[]means none. - Definition version (required, at least 1): raise it when the formula, source, joins, dimensions, or filters change. It is separate from revision numbers and release versions.
- Where it came from: optional provenance, such as Source location, Source revision, and Source metadata. Studio preserves it with the revision and does not fetch or run the source.
4
Review and save
Choose Review changes. Studio shows the definition as it will be saved, and nothing is sent yet. Choose Back to editing to change it, or Save definition to save. A blank required field blocks the save with “Complete the required fields.”
5
Verify revision
The result reads “Definition saved” with a Revision N badge and “Saved. Agents get it only once you release it.” Choose Open saved item to open the metric, then open History. Confirm that the new revision is listed and that the catalog shows Not released for a first revision.
6
Revise metric (optional)
Open the metric and choose Edit from its action menu. The same form opens on the current revision. Destination workspace, Name, Identifier, and Description are locked, and Studio raises Definition version by 1 on each metric revision. Saving creates revision N+1, still unreleased.
- “This item has changed. Copy your edits, then reopen the current revision.” means someone saved a newer revision while you edited. The save is refused, so copy your edits and reopen the current one.
- “Restore this archived item before revising it.” means the metric is archived. See Release metrics.
Next steps
- Release metrics: Make your revision what agents get.
See also
- Find and read metrics: Read a metric’s calculation and release state.
- Metrics Studio: How revisions and releases relate.