# Define metrics

> Create, change, and remove named calculations for agents to use, in a draft that reaches them when you publish it.

Updated: 2026-11-09

A metric names the calculation for a number, for example revenue or refund rate. Agents read it and use it in their SQL:
Bonnard does not apply it for them. Changes wait in a draft until you [publish it](https://bonnard.ai/docs/context/review-and-publish.md#publish). To make sure that a change saved, [review the draft](https://bonnard.ai/docs/context/review-and-publish.md#review-the-draft).

## Requirements

- The Editor role or higher in your workspace.
- To work from your AI client: [Bonnard connected](https://bonnard.ai/docs/ai-clients/connect-your-ai-client.md) and access to the data source.

## Create a metric

Only a name is needed to start, with at least one letter a to z or digit. The calculation is SQL that names each column with its table, for example
`SUM(orders.amount)`. Instructions say when to use the metric and when not to. Names take up to 120 characters,
descriptions 2,000, and calculations and instructions 4,000.

### In your AI client

Ask:

```prompt
In <data source>, create a metric called Refund rate, calculated as SUM(refunds.amount) / SUM(orders.amount). Tell AI clients to exclude test orders.
```

### In the console

1. In the console at `app.bonnard.ai`, select **Context**, then **Metrics**. With more than one data source, select one at
   the top right first.
2. Select **New metric**, enter a **Name**, and select **Create**. The metric's page opens.
3. Select the value in the **Description**, **Calculation**, or **Instructions** row, type, then select outside the
   field. `Saved to draft` shows under the label.

`A metric called <name> already exists.` means that the name is taken. Select **Open it** to change that metric.

[Image: The page of a new metric called Revenue in Context, with the badge Incomplete and empty Description, Calculation, and Instructions rows]

## Change or remove a metric

AI clients keep the published metric until you publish the draft.

### In your AI client

Ask:

```prompt
In <data source>, change the calculation of <metric> to <calculation>.
```

To remove it, ask:

```prompt
In <data source>, remove the <metric> metric.
```

Bonnard removes a metric in the live version only after the agent sends `confirmed: true`. The agent is told to ask you first.

### In the console

1. In the console, select **Context**, then **Metrics**, then the metric.
2. To change it, select its name or a field, type, then select outside the field.
3. To remove it, open the **Metric actions** menu at the top right, select **Remove metric**, then accept with
   **Remove metric**.

**Undo** shows for 6 seconds after a removal.

## Incomplete metrics

A metric is incomplete when it has no calculation. It is also incomplete when its calculation names a hidden table or a
column the data source does not have. Bonnard does a check only on `table.column` references and does not run the calculation.
Publishing the draft holds it back and publishes the rest.

To find them from your AI client, ask:

```prompt
Which metrics in the context draft for <data source> are incomplete?
```

In the console, incomplete metrics have the badge `Incomplete`. On the **Context** page, select **Review** in the banner
to list them.

## Related

- [Connect tables with joins](https://bonnard.ai/docs/context/joins.md): tell agents how the tables in a metric connect.
- [Hide tables from AI clients](https://bonnard.ai/docs/context/hide-tables.md): hiding a table withholds the metrics that name it.
- [Publish context changes](https://bonnard.ai/docs/context/review-and-publish.md): review the draft and take it live.