# Add filters to a dashboard

> Add filters to a dashboard by declaring params in your AI client or the console, with optional filters, a value viewers must select, and a starting value.

Updated: 2026-11-09

A param is what the dashboard declares, and a filter is the control a viewer changes.

## Requirements

- A dashboard you can change.
- To work from your AI client: [Bonnard connected](https://bonnard.ai/docs/ai-clients/connect-your-ai-client.md) and the **Dashboards** switch on in **Settings**, **AI tools**.

## Declare a param

### In your AI client

Ask:

```prompt
On <dashboard>, add a <label> filter with values from <column> in <table>. Use it in each tile.
```

### In the console

1. In the console at `app.bonnard.ai`, open the dashboard, then select **Edit**.
2. Select **Params**, then **Add param**.
3. Enter a name, then select **Text**, **Number**, or **Date**.
4. Set **Shown as**, **Values from**, and **Starting value**.
5. Put `{{name}}` in each tile's SQL, with no quotes.
6. Select **Save**, or **Publish changes** on a verified dashboard.

In the console, **Values from** takes a plain `table` or `schema.table`. Declare any other name from your AI client, for example `project.dataset.table`, and change that dashboard there, because the editor then blocks **Save**:

```text
The table must be a plain name (letters, digits, underscores), optionally schema.table.
```

The two paths set the same fields:

Table: Console labels and the param fields they set

| Console label | Field | What it sets |
| --- | --- | --- |
| **Shown as** | `label` | The filter name viewers read |
| **Values from** | `valuesFrom` | The table and column that hold the values |
| **Order** | `sortBy` | The order of those values |
| **Starting value** | `default`, `required` | What the filter opens on |
| **Description for AI clients** | `description` | How an agent gets a valid value |

`{{name}}` works in tile SQL, titles, and KPI captions:

```sql
SELECT COUNT(*) AS orders FROM <table> WHERE <column> = {{name}}
```

[Image: The Params panel for the month param: Shown as, Values from, Order, Starting value, Description for AI clients, and Delete param]

## Make a filter optional

Put `[[ AND ... ]]` around each condition on the param, in each tile. The filter then offers All, and with no value the condition is dropped.

### In your AI client

Ask:

```prompt
Make the <label> filter on <dashboard> optional, so viewers can select All.
```

### In the console

1. In the dashboard editor, select **Edit**. In each tile that uses the param, put `[[ ]]` around the condition:

   ```sql
   SELECT COUNT(*) AS orders FROM <table> WHERE 1=1 [[ AND <column> = {{name}} ]]
   ```

2. Select **Params**, the param, then **Starting value**.
3. Select the option that starts with **All**.
4. Select **Save**, or **Publish changes** on a verified dashboard.

## Make viewers select a value first

With **People choose first** set, no tile loads until a viewer selects a value.

### In your AI client

Ask:

```prompt
On <dashboard>, make viewers select a <label> before anything loads.
```

### In the console

1. In the dashboard editor, select **Edit**, **Params**, the param, then **Starting value**.
2. Select **People choose first**.
3. Select **Save**, or **Publish changes** on a verified dashboard.

The option reads `Not available: this filter can be cleared, so it cannot require a value.` while the condition is inside `[[ ]]`. Remove the brackets first.

## Open on the latest value

With **Starting value** set to **First in the list**, the filter opens on the first value in its order, so sort newest first.

### In your AI client

Ask:

```prompt
On <dashboard>, make the <label> filter open on the newest value, ordered by <column>.
```

### In the console

1. In the dashboard editor, select **Edit**, **Params**, the param, then **Order**.
2. Select the column, then **Newest first**.
3. Select **Starting value**, then **First in the list**.
4. Select **Save**, or **Publish changes** on a verified dashboard.

## Make sure that the filter shows

### In your AI client

Ask:

```prompt
Show the <dashboard> dashboard.
```

The agent's reply names each filter's starting value, for example `Channels: All`. A param with no description warns when saved: `param "<name>" has no description, so a caller in a later session sees only its name.`

### In the console

In the dashboard editor, select **Preview**. The filter shows above the tiles with its starting value.

## Change or delete a param

Changing a param's name changes `{{name}}` in each tile, and links or saved calls that use the old name fail. Changing **Shown as** changes only the filter name viewers read.

### In your AI client

To change it, ask:

```prompt
Rename the <label> filter on <dashboard> to <new label>.
```

To delete it, ask:

```prompt
Remove the <label> filter and its conditions from <dashboard>.
```

### In the console

1. In the dashboard editor, select **Edit**, **Params**, then the param.
2. Change its name or another field, or select **Delete param**. First remove `{{name}}` from each tile, because Bonnard refuses a tile that names a deleted param.
3. Select **Save**, or **Publish changes** on a verified dashboard.

## Related

- [Dashboard operations](https://bonnard.ai/docs/for-ai-agents/dashboard-operations.md): the operations an agent uses for params.
- [Share dialog](https://bonnard.ai/docs/dashboards/share.md): give the dashboard to viewers.