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. For AI-assisted investigation, see Root Cause Analysis.

[TODO: re-capture screenshot - UI changed]

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.

    📘

    Troubleshooting Outliers

    Although outliers are not the only cause of incidents, they are a good starting point for troubleshooting.

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

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.

[TODO: screenshot needed] Queries picker with a query selected, showing the row's default and delete actions.

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.