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 dialog, which you can edit, run, save, or discard like any other query.

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.
• The Allow LLM credentials setting enabled in your Validio Workspace. See Configuring Global Settings.
• 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.
• Permissions in the namespace as follows. See Managing Roles.

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:

-- 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:

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

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.
• Discard it if it is not useful. Nothing was stored, so there is no confirmation step.

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.

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.
• Related incidents and lineage — what else is firing nearby, and whether the cause looks upstream. See Root Cause Analysis.
• 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. 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. Cancelling 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
• Debug Query Syntax
• Root Cause Analysis
• LLM Credentials
• AI Data Transparency
• About Validio AI Features