Query Intelligence Tools
7 tools for writing, validating, and executing SQL queries with governance.
Schema-link, join-path, ERD, join-type comparison, and date-boundary tools moved to the Schema & Exploration reference.
query_database
Execute governed, read-only SQL against a registered connection.
Governance applied automatically:
- DDL/DML blocked at parse time
- 79+ dangerous functions denied
- LIMIT auto-injected if missing (default: 1000 rows)
- INTO clause blocked
- Multi-statement rejected
- Full audit log written (SQL string literals PII-redacted)
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
connection | string | Yes | Connection name (from list_database_connections) |
sql | string | Yes | SQL query to execute |
limit | integer | No | Override auto-LIMIT (cannot exceed the gateway max) |
Returns: Array of rows, column names, row count, governance decisions applied.
Example:
Use query_database with connection="my-postgres" to run:SELECT order_date, COUNT(*) as orders FROM orders GROUP BY 1 ORDER BY 1
validate_sql
Validate SQL syntax and semantics via EXPLAIN. No data is read, no budget is consumed.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
connection | string | Yes | Connection name |
sql | string | Yes | SQL to validate |
Returns: valid: true/false, error message if invalid, governance flags if blocked.
When to use: Before any non-trivial query_database call. Catches syntax errors and governance violations without touching data.
explain_query
Get the execution plan for a query with row estimates and cost warnings.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
connection | string | Yes | Connection name |
sql | string | Yes | SQL to explain |
Returns: Execution plan, estimated rows per step, cost warning if applicable.
estimate_query_cost
Dry-run cost estimate before executing. For BigQuery, returns exact bytes that will be billed.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
connection | string | Yes | Connection name |
sql | string | Yes | SQL to estimate |
Returns: Estimated cost in USD, bytes processed (BigQuery), row estimate, recommendation if cost is high.
When to use: Before any full-table scan on BigQuery or Snowflake.
debug_cte_query
Break a CTE query into steps and validate each CTE independently.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
connection | string | Yes | Connection name |
sql | string | Yes | CTE query to debug |
Returns: Per-CTE validation result, row count, fan-out detection for each step.
check_budget
Remaining query budget for the current session.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
connection | string | Yes | Connection name |
Returns: Budget cap (USD), amount spent this session, amount remaining. Applies to warehouses that report scan cost (BigQuery, Snowflake).
query_history
Retrieve recent successful queries for a connection (session memory).
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
connection | string | Yes | Connection name |
limit | integer | No | Number of queries to return (default: 20) |
Returns: Recent queries with timestamp, SQL, row count, execution time.