Query Cost Guardrails

A governed layer shouldn't let an innocent question turn into a warehouse-melting scan. Before any generated query runs, Colrows estimates its cost, classifies it into a tier, and can block the runaway ones - so a badly-shaped question fails fast instead of running up a bill.

How it works

Colrows estimates a query's cost immediately before it runs. The estimate runs on the AI Data Analyst path, the MCP askData and executeVerifiedQuery tools, and governed executions submitted through the agent API (POST /api/agents/v1/queries). The estimate is row-oriented ("how many rows would this touch"), classified into tiers, and logged. There's nothing to configure per query.

• Low - small; recorded.
• Moderate - larger than typical; recorded.
• High - unusually large; recorded and flagged.
• Blocked - beyond the block ceiling, or an unbounded result with no limit.

Each estimate carries a confidence level and a plain-language list of the assumptions it made - for example, a table with no profiled row count, or a join with no statistics. A query the platform can't estimate is marked Unknown and always passes.

Report-only by default

Out of the box, guardrails are report-only: every query is estimated and logged, but nothing is refused. An operator turns on enforcement per deployment once the estimates are trusted. With enforcement on, a query classified blocked fails the request and the caller receives the estimate's summary; everything below the ceiling runs normally.

Thresholds (the warn level, the block level, the unbounded-result cap) and the enforcement toggle are deployment configuration, set by an operator - not per-user settings.

Check cost before running

An agent can check a query's cost without running it. The agent API's SQL validation operation (POST /api/agents/v1/queries/validate, scope sql:execute) returns the estimate with its tier, confidence, and the enforced limits. With enforcement on, a query that would be blocked returns a COST_LIMIT error. Otherwise, a query that would be blocked, or whose cost is unknown, returns a COST_WARNING warning.

Row caps on data tools

Independently of the cost estimate, the data tools cap how many rows come back. The row limit defaults to 1,000 on both the MCP tools and the agent API. The ceiling differs by surface - the MCP maxRows argument cannot exceed 5,000 rows, and the agent API's limits.maxRows on POST /api/agents/v1/queries cannot exceed 10,000. Any capped result is marked truncated: true so a caller never mistakes a partial set for the whole answer.