> ## Documentation Index
> Fetch the complete documentation index at: https://docs.validio.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Debug Query Suggestions

> Ask an AI agent to write an investigation query for an incident, then edit, run, save, or discard the suggestion it drafts.

The debug query agent writes investigation SQL for an incident you are looking at. You describe what you want to know in plain language, and the agent reads the incident's context — the validator and its deviation, the source schema, catalog metadata — then drafts a query for that source's SQL dialect. The suggestion arrives as an unsaved draft in the [Debug](https://docs.validio.io/docs/incidents-and-errors/incidents/debugging-an-incident.md) dialog, which you can edit, run, save, or discard like any other query.

![The Debug incident dialog with a suggested query selected in the Queries picker, the ask above the editor, the agent's reasoning as a comment block above the SQL, and the results preview alongside](https://mintcdn.com/validio/30m58lWK6Ph-vklQ/images/docs/ai-features/1030-debug-suggestions.png?fit=max\&auto=format\&n=30m58lWK6Ph-vklQ\&q=85\&s=24b4eb1af6e71ef28edd66f366e522b6)

Generated debug query with comments and preview

The agent only writes SQL — it never runs it. Running a suggestion goes through the same debug query path as any other query, and still requires the `sqlExecution:WRITE` permission.

## Prerequisites

To ask the agent for a query, ensure that you have the following:

* A source where **Debug** is available — a data warehouse or query engine source that Validio validates through SQL pushdown. See [Debugging an Incident](https://docs.validio.io/docs/incidents-and-errors/incidents/debugging-an-incident.md).
* The **Allow LLM credentials** setting enabled in your Validio Workspace. See [Managing Workspace Settings](https://docs.validio.io/docs/access-and-settings/settings/workspace-settings.md).
* At least one LLM credential configured in your environment. Validio runs no model of its own, so the **Suggest query** button stays disabled until you configure one. See [LLM Credentials](https://docs.validio.io/docs/integrations/llm-credentials.md).
* Permissions in the namespace as follows. See [Managing Roles](https://docs.validio.io/docs/access-and-settings/settings/managing-roles.md).

| Permission | What it allows |
| :- | :- |
| `incidents:WRITE` | Asking the agent for a suggestion |
| `sqlExecution:READ` | Asking the agent for a suggestion |
| `sqlExecution:WRITE` | Running the suggested query and loading sample records |
| `validators:WRITE` | Saving a suggestion as a reusable debug query |

Anyone who can already open **Debug** and run a query can ask the agent — it adds no permission of its own.

## Ask for a suggestion

1. Open **Debug** on an incident, from an incident group details page or anywhere individual incidents are listed.
2. Select **Suggest query** in the toolbar above the editor. A prompt slides in beneath the toolbar.
3. Describe what you want the query to show — for example, `break the drop down by region and channel` or `compare this window against the same day last week`.
4. (Optional) Choose which LLM credential to ask with, from the menu on the send button. Validio uses the first configured credential by default.
5. Send the ask. **Suggest query** becomes a progress indicator while the agent works; hover or select it to see the per-step detail:

   | Step | What happens |
   | :- | :- |
   | Gathering incident context | Validio gathers context about the incident |
   | Designing the debug query | The model writes the query and Validio runs its own checks on it |

## Read the suggestion

Each suggestion arrives as its own unsaved draft named `<name> (unsaved #N)`, where `<name>` is the agent's own name for the query. The draft opens in the editor, selected in the **Queries** picker, with the agent's reasoning above the SQL as a `--` comment block:

```sql title="SQL" theme={null}
-- Wholesale channel volume by region
-- ROW_COUNT fell 38% below the lower bound. Broken down by region and
-- channel to find where the rows went; built on the saved query "Daily
-- volume by region".
SELECT
  region,
  channel,
  COUNT(*) AS row_count
FROM "analytics"."orders"
WHERE CAST("created_at" AS TIMESTAMPTZ) >= {{ validio_incident_window_start() }}
  AND CAST("created_at" AS TIMESTAMPTZ) < {{ validio_incident_window_end() }}
GROUP BY region, channel
ORDER BY row_count ASC
LIMIT 50
```

The comment block is part of the query text, so it stays with the query when you save it.

Whatever query you had selected before keeps its own working copy, so nothing needs restoring — you can move between the suggestion and what you were looking at without losing either.

### Remaining checks

Before showing you a suggestion, Validio checks it against the `{{ validio_* }}` placeholder grammar and gives the agent a chance to correct what it finds. Anything left over appears in the comment block as a `-- Check:` line, so you see it before you run the query:

```sql title="SQL" theme={null}
-- Check: validio_incident_window_start: was in the generated base query and
-- is gone, so the suggestion no longer re-binds to a later incident.
```

A check line is a flag, not a fault. The query above runs and answers this incident; it just will not re-bind to a later one if you save it. See [Debug Query Syntax](https://docs.validio.io/docs/incidents-and-errors/incidents/debug-query-syntax.md) for the placeholder grammar.

Validio does not check column names, so a query naming a column that does not exist fails at your warehouse. Validio carries that error into your next ask for you — see [Iterate on a query](#iterate-on-a-query).

### Edit, run, save, or discard

A suggested draft behaves like any other unsaved query:

* **Run** it to load sample records, as with the generated query.
* **Edit** the SQL freely. **Reset** returns the draft to the SQL the agent wrote.
* **Save** it to keep it against the validator for future incidents, under a name of your choosing. See [Saving and reusing a debug query](https://docs.validio.io/docs/incidents-and-errors/incidents/debugging-an-incident.md#saving-and-reusing-a-debug-query).
* **Discard** it if it is not useful. Nothing was stored, so there is no confirmation step.

> [!TIP]
>
> **Recommendation**
>
> Save a suggestion once it works. The agent sees a validator's saved queries as worked examples on later asks, so each one improves what the agent writes next.

## Iterate on a query

Asking again refines the query in front of you rather than starting over. Each ask carries:

* The SQL currently in the editor, including any edits you made.
* Whether that SQL is still the agent's own last suggestion, unchanged.
* Your warehouse's error message, if the last run of that query failed.

> [!WARNING]
>
> **Result rows are never sent**
>
> The agent never sees the records a query returned — only the query text. A follow-up that depends on what you saw in the results has to name it. Ask `drill into the WHOLESALE channel`, not `drill into the worst one`.

Each new suggestion arrives as its own draft, so earlier suggestions stay in the **Queries** picker and you can compare them.

## What the agent reads

So that the query it writes is specific to what actually went wrong, the agent reads context about the incident and its surroundings. That includes, among other things:

* **Incident details** — the validator's configuration, the window that fired, and how far the value deviated from its threshold.
* **Catalog metadata** — names, data types, and descriptions for the source's columns. See [Catalog Assets](https://docs.validio.io/docs/catalog/catalog-assets.md).
* **Related incidents and lineage** — what else is firing nearby, and whether the cause looks upstream. See [Root Cause Analysis](https://docs.validio.io/docs/incidents-and-errors/root-cause-analysis.md).
* **Previously saved queries** — the validator's saved debug queries, as worked examples of how your team investigates this check.
* **Your ask** — what you typed, passed to the model verbatim.

Validio sends only the most relevant information, narrowing each of these to what bears on this particular incident rather than sending everything available, so a wide source or a busy lineage graph does not crowd out the detail that matters.

For what this means in data transparency terms, see [AI Data Transparency](https://docs.validio.io/docs/other/llm-data-transparency.md). The agent sends metadata, configuration, and query text; it does not send rows, record samples, or query results.

## Cancel a run

While a run is in flight, open the progress detail from the **Suggest query** button and cancel it. Canceling stops the run without drafting anything.

If a run fails — a credential problem, a provider error, or a failed step — the panel reports why on the step that failed and leaves the query in the editor untouched.

## Related resources

* [Debugging an Incident](https://docs.validio.io/docs/incidents-and-errors/incidents/debugging-an-incident.md)
* [Debug Query Syntax](https://docs.validio.io/docs/incidents-and-errors/incidents/debug-query-syntax.md)
* [Root Cause Analysis](https://docs.validio.io/docs/incidents-and-errors/root-cause-analysis.md)
* [LLM Credentials](https://docs.validio.io/docs/integrations/llm-credentials.md)
* [AI Data Transparency](https://docs.validio.io/docs/other/llm-data-transparency.md)
* [About Validio AI Features](https://docs.validio.io/docs/ai-features.md)