Verified Queries

Verified Queries are curator-approved, reusable SQL examples - each paired with the business question it answers and the datasource it runs on. When a question matches one, Colrows AI and agents run the stored, governed query by ID and version instead of generating SQL from scratch. It's how you turn "the query we trust for revenue by region" into a first-class, reusable asset.

Why verified queries

Generated SQL is right most of the time. For the questions your business asks constantly - board metrics, regulatory reports, the numbers a room will argue over - "most of the time" isn't enough. A verified query pins the exact, reviewed SQL for a known question, so the answer is identical every time and traceable to a human who approved it.

How curators manage them

Curators work in the Verified Queries workspace in the Curator Space:

• Add a verified query - the business question (as a description), the SQL, and the datasource it targets.
• Bulk import - upload a CSV of questions and SQL, with a preview step before you commit.
• Per-row actions - view, edit, delete, and inspect the full version and lineage history of any query.

How agents use them at runtime

Verified queries are exposed to AI agents and MCP clients as two read-only tools (see the MCP Tool Reference):

• searchVerifiedQueries - find valid queries for a question. Returns matches (query ID, version, question, datasource) - never SQL text, and it never runs anything. It searches only datasources the caller may access.
• executeVerifiedQuery - run a match by queryId and version. The server loads the stored SQL; the caller cannot submit SQL. The result carries columns, rows, row count, and a truncated flag.

The Excel add-in uses these same two tools to search and load results into a workbook.

Governance, versioning & validity

• Verified queries follow the same rules as every other semantic entity: immutable versions, lineage, and a validity lifecycle (Active, Invalid, Deleted). Only active, valid queries are searchable and executable.
• A query whose values change (this month vs. last month) needs a new version - verified queries take no runtime SQL parameters. If a caller asks for a stale version, it gets the VERSION_CHANGED signal and searches again.
• Execution checks semantic validity and the caller's data access at run time, and applies row and column policies - the same governance as the rest of Colrows.

Manage via API

Verified queries are managed from the console, and the same operations are available to administrators and curators on the platform API: