> For the complete documentation index, see [llms.txt](https://docs.smaq.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.smaq.io/documentation/features/datablocks/custom-metrics.md).

# Custom metrics

Define calculated KPIs — ROAS, AOV, CPA, retention rate — using formulas on top of your existing datablock columns. Custom metrics work everywhere a regular metric works.

A custom metric is a formula that produces a number from other numbers. Use them to define your business's KPIs once and reuse them across every dashboard, chart, automation, and chat session.

### When to create a custom metric

* The metric isn't returned natively by your connection (ROAS isn't a Meta metric — you derive it from `purchase_value / spend`).
* You want a custom version of a standard metric (e.g. "Profit-adjusted ROAS" subtracting COGS).
* You want to blend across connections — `(GA4 organic_sessions) / (Google Ads spend)`.

### Where to find custom metrics

In any project, click **Custom metrics** in the side menu (or open a chart's settings, scroll to the **Custom columns** section — see [Add custom column to table](/documentation/features/dashboard/add-custom-column-to-table.md) for the chart-level version).

> **\[Screenshot needed]** Custom metrics list page with three saved metrics: ROAS, Blended ROAS, AOV.

### Two scopes

#### Project-level custom metric

* Created from the Custom metrics page.
* Available across every dashboard in the project.
* Best for KPIs that recur (ROAS, AOV, CPA, profit-adjusted versions).

#### Chart-level custom column

* Created from inside a single chart's settings.
* Only visible on that chart.
* Best for one-off calculations specific to one analysis.

See [Add custom column to table](/documentation/features/dashboard/add-custom-column-to-table.md) for the chart-level workflow.

### Creating a project-level custom metric

#### Step 1 — Pick the base datablock(s)

A custom metric references columns from one or more datablocks. Pick the datablock(s) that contain the inputs you need.

#### Step 2 — Write the formula

Formulas use bracketed column names and standard arithmetic operators:

```
[purchase_value] / [spend]
```

```
([revenue] - [cogs]) / [spend]
```

```
SUM([sessions]) / SUM([users])
```

Available operators: `+ - * /` Functions: `SUM`, `AVG`, `MIN`, `MAX`, `COUNT`, `IF`, `CASE WHEN ... THEN ... ELSE ... END`

> **\[Screenshot needed]** Custom metric formula editor with `[purchase_value] / [spend]` typed in and the column picker visible.

#### Step 3 — Name and format

* **Name**: human-readable (e.g. "ROAS"). No spaces in the underlying identifier — SMAQ converts `ROAS` to display correctly and accepts underscores.
* **Format**: pick how it renders — Currency, Percentage, Number, Ratio. Custom metrics with the Currency format automatically participate in [currency conversion](/documentation/features/dashboard/currency-conversion-for-tables.md).
* **Description**: the AI uses this when picking metrics during chat.

#### Step 4 — Save and use

Once saved, your custom metric appears in the Metrics picker of every chart, datablock builder, and report — alongside the platform-native metrics. Use it just like any other metric.

> **\[Screen video needed]** From creating a "ROAS" custom metric on a Google Ads + Meta blended datablock through using it in a new dashboard chart. \~90 seconds.

### Blending metrics across connections

To blend across connections (e.g. organic GA4 sessions against paid Google Ads spend), you need a datablock that joins or unions the two sources. SQL connections support this natively. For API connections, use a [merged table](/documentation/features/dashboard/merge-table.md) — then build the custom metric on top.

### Tips

* **Pick the format carefully.** A ratio formatted as a percentage shows `30.5%` instead of `0.305`. A ratio formatted as a number shows `0.305`. They're the same value — pick what your audience reads more easily.
* **Use parentheses generously.** Operator precedence does what you'd expect, but parentheses make intent obvious and prevent mistakes.
* **Don't divide by zero.** Use `IF([spend] = 0, NULL, [revenue] / [spend])` to avoid `NaN` or `Inf` showing up in dashboards.
* **Test against a known dataset.** Build the metric, render it on a dashboard, and compare to a number you know is right.

### What's next

* [Add custom column to table](/documentation/features/dashboard/add-custom-column-to-table.md) — chart-level alternative.
* [Currency conversion for tables](/documentation/features/dashboard/currency-conversion-for-tables.md) — applies to custom currency metrics too.
* [Datablocks overview](/documentation/features/datablocks.md).