Summary: Metrics are reusable KPI definitions — a measure or custom SQL calculation tied to a data source — that power your charts, Insights, forecasts, goals, and scheduled deliveries. This article shows you how to create a metric and manage it from the Metrics page.
Who this is for: Anyone who builds dashboards or tracks KPIs in Alta and wants consistent, reusable metric definitions across the workspace.
Before you start
You need at least one connected data source (Settings → Connectors) so a data model is available to build on.
Some actions are restricted on public (shared) metrics if you don't have model access — for example, public metrics can't be deleted without it.
Where to find Metrics
In the left sidebar, open the Build section and click Metrics. You'll see a list of your metrics with their data model and sources. Two controls sit above the list:
Search metric — fuzzy search by name, key, or model name.
Show Tracked — a toggle that is on by default, so the list only shows tracked metrics. If a metric seems to be missing, switch this off to see everything.
How to create a metric
On the Metrics page, click + Add Metric. The Metric Calculation dialog opens, with a live preview of your metric on the right side.
Under Metric name, enter a Name (required — letters, numbers, spaces, hyphens, and underscores only; special characters are rejected with "Name can not contain special characters"). Optionally add a Description (up to 200 characters).
Under Define metric, pick a Data source. Choose carefully — the data source is locked after the metric is created, and changing it while creating resets your measure, filters, date field, and breakdowns.
Define the calculation using one of the two tabs:
Measure — click Choose measure and pick a measure from your model. Optionally click Add filter to narrow the data with the filter builder (filter groups are supported).
Custom SQL — write a SQL formula in the editor (it autocompletes fields from your model), then click Apply Formula. Using custom SQL clears any measure and filters you had set.
You must provide one or the other — saving without either shows "Please select a measure or enter a custom SQL".
Set the Default date field (required). This is the date used by default for time-based calculations. Alta pre-fills it from the model's default date field when one exists.
Optionally add Breakdowns — dimension fields the metric can be split by (for example, source, region, or owner). You can save a group of breakdown fields as a reusable field set.
Optionally expand Additional settings (Optional):
Additional fields — extra dimensions available for customizing and filtering visualizations built on this metric.
Metric type — Simple for single-value metrics, Cumulative for metrics that aggregate values over time, or Rolling for averages/sums over a moving time window.
Metric value type — Amount for monetary values, Entity Count for counting entities, or Conversion for rates and percentages.
Value format — a display format string such as
$#.00;($#.00). Click View value formatters for the full reference.
Click Save. You'll see "Successfully saved metric" and the metric appears in the list.
Managing metrics from the list
Hover over any metric row to reveal its actions:
Track metric to receive AI insights notifications — tracking a metric feeds it into Alta's Insights engine, which analyzes changes and notifies you. Click again to Disable AI insights notifications.
Hide metric / Show metric — hidden metrics stay in the workspace but are dimmed and sorted to the bottom.
Duplicate metric — opens the creation dialog pre-filled with the metric's definition and " - Copy" appended to the name. This is the way to move a definition to a different data source, since the source is locked on existing metrics.
Edit metric — reopens the Metric Calculation dialog.
Delete metric — permanently removes the metric. On shared metrics you may see "Cannot delete public metrics" if you don't have model access.
Click a metric's name to open its detail page with the full definition and related entities.
Tips and common pitfalls
Can't find a metric you just created? The Show Tracked toggle is on by default and new metrics start untracked. Turn the toggle off.
Data source is greyed out when editing. That's by design — the source can't change after creation. Duplicate the metric instead.
Type and value type locked? On public metrics you don't own, Metric type and Metric value type are read-only unless you have model access.
Save button disabled? The dialog only enables Save after you've changed something, and requires a name, data source, a measure or custom SQL, and a default date field.
Track the metrics that matter. Only tracked metrics generate AI Insights — track your core KPIs and leave exploratory metrics untracked to keep Insights focused.
Related