Debugging an Incident

When investigating individual incident groups, the Debug feature generates sample SQL queries from captured incidents, allowing you to investigate the exact data causing quality issues directly in your database. Queries you find useful can be saved against the validator and reused on future incidents. You can also ask an AI agent to write an investigation query for you — see Debug Query Suggestions. For AI-assisted analysis of the incident itself, see Root Cause Analysis.

​

Prerequisites for debug

To use the Debug feature, ensure the following requirements are met:

• Source type: Debug is available for data warehouse and query engine sources where Validio uses SQL pushdown for validation.
• Permissions: Your role must have the following permissions in the namespace. See Managing Roles.

​

How debug works

The Debug feature is available where individual incidents are listed, such as in a details page for incident groups, and provides:

• Automatically generated SQL: Validio generates a SQL query that reproduces the data quality incidents. The query,
  • Filters data down to the specific Window and Segment where the incident occurred. It does this using placeholders — the time range and segment appear as {{ validio_... }} rather than as fixed values, and Validio fills them in when the query runs. See Debug Query Syntax.
  • Orders records based on how far away they are from being allowed, returning the most prominent outliers at the top.

• Sample data generation: Use Run for Validio to automatically generate sample rows from the detected incidents to help you troubleshoot.
• Query customization: Modify the generated query to explore different aspects of the problem. The query actions sit above the editor. If needed, Reset removes your edits and returns to the original generated SQL.
• Copy support: Copy the query to run in your preferred database tools for deeper analysis.
• Reusable queries: Save a query you want to run again, and pick it up on any future incident for the same validator. See Saving and Reusing a Debug Query.
• AI-suggested queries: Select Suggest query to have an agent write an investigation query from the incident’s context, arriving as an unsaved draft you can edit, run, save, or discard. See Debug Query Suggestions.

​

Saving and reusing a debug query

A saved debug query belongs to the validator, not to the incident you saved it from. Once saved, it is available on every incident for that validator, to anyone with validators:READ in the namespace. To save a query:

1. Open Debug on an incident and edit the SQL until it returns what you need.
2. Select Save and give the query a name.

A query keeping its window placeholders re-binds to whichever incident you open it from; one with the timestamps written in returns the same range every time. Validio saves either kind — see Debug Query Syntax. If Save is unavailable, hover it to see why. To reuse a saved query:

1. Open Debug on any incident for the same validator.
2. Choose the query from the Queries picker above the editor.
3. Select Run. Any placeholders bind to the incident you are currently viewing.

To change a saved query, select it, edit the SQL, and choose Save again. The name field is pre-filled with the query’s current name, so saving over a query and renaming it are the same step. Save is unavailable until you have actually changed something.

​

Setting a default query

One of a validator’s saved queries can be its default. When a validator has a default query, opening Debug on any of its incidents loads that query instead of the freshly generated one — useful when a validator has a known investigation path you want everyone to start from. To set one, open the Queries picker and choose the bookmark action on that query’s row. Setting a new default clears the previous one, so a validator never has more than one.

​

Renaming and deleting

To rename a saved query, select it and choose Save — the name field opens pre-filled, and the new name replaces the old one. To delete one, open the Queries picker and choose the delete action on that query’s row. Deleting asks for confirmation first, then removes the query for everyone in the namespace. A validator’s saved queries are deleted along with the validator itself.

​

Viewing the executed SQL

Sample records are produced by the query with its placeholders expanded, which is not quite the SQL shown in the editor. To see what actually ran, expand Executed SQL beneath the sample records. The panel reflects the samples currently on screen rather than what is in the editor. If you edit the query after loading samples, both the records and the executed SQL are dimmed to show they are out of date, and running the query again refreshes them.