# Connect tables with joins

> Add and remove joins between tables so that agents join on the right columns, in a draft that reaches them when you publish it.

Updated: 2026-11-09

Each foreign key the database declares is a join from the start. On MySQL / MariaDB, Bonnard does not read foreign keys,
so add those joins yourself. 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.

## Add a join

Start from the table that holds the reference: refunds, for a join from refunds to orders. A join has up to 4 column
pairs, and each pair must have matching types. The two tables must be different.

### In your AI client

Ask:

```prompt
In <data source>, add a join from <table> to <other table> on <table>.<column> = <other table>.<column>.
```

### In the console

1. In the console at `app.bonnard.ai`, select **Context**, then **Tables**, then the table that holds the reference.
   With more than one data source, select one at the top right first.
2. Under **Joins**, select **Add join**.
3. Under **Joins to**, select **Pick a table**, then the other table.
4. Select a column on each side. For another pair, select **+ Add column**.
5. Select **Add join**. The join shows with the badge `edited`.

`These columns have different types.` means that the pair cannot be joined.
`The database already declares this join.` means that the join exists.

[Image: The Add join dialog: Joins to sessions, one column pair with session_id on each side, + Add column, Cancel, and Add join]

## Remove a join

AI clients keep a live join until you publish the draft. A join the database declares cannot be removed, so it is
hidden from AI clients instead.

### In your AI client

Ask:

```prompt
In <data source>, remove the join from <table> to <other table>.
```

Bonnard removes a join in the live version only after the agent sends `confirmed: true`. The agent is told to ask you first. The same request hides a join the database declares. If the two tables join more than one way, name the
columns in the request.

### In the console

1. On either table's page in **Context**, find the join under **Joins**.
2. Select **Remove**. For a join with the badge `database`, select **Hide from AI clients**.

**Undo** shows for 6 seconds after **Remove**. **Show to AI clients** brings back a hidden join.

## Accept a suggested join

Bonnard suggests a join when a column named `<name>_id` matches a table named `<name>` or `<name>s` with a single-column
key or an `id` column. Agents do not get suggestions.

### In the console

1. On the table's page in **Context**, find the join with the badge `Suggested` under **Joins**.
2. Select **Confirm** to add it to the draft, or **Dismiss** to add the dismissal to the draft.

After you publish a dismissal, only a [revert](https://bonnard.ai/docs/context/review-and-publish.md#revert-one-change) brings the suggestion back.

## Related

- [Describe your data](https://bonnard.ai/docs/context/descriptions-and-keys.md): set keys and descriptions on the tables you joined.
- [Define metrics](https://bonnard.ai/docs/context/metrics.md): name a calculation over the joined tables.
- [Publish context changes](https://bonnard.ai/docs/context/review-and-publish.md): review the draft and take it live.