# Custom metrics

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).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.smaq.io/documentation/features/datablocks/custom-metrics.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.