ViduraRedshift Tools
Query Performance Tools
The query performance tools give Vidura visibility into how SQL queries are executing on the Redshift cluster. They cover currently-executing queries, historical aggregates, disk spill, and WLM queue behavior. Together they account for 7 of the 19 Redshift tools.
Tool Reference
| Tool Name | Data Source | Description |
|---|---|---|
| long_running_queries() | stv_wlm_query_state | Returns currently executing queries with execution time greater than 300 seconds. Includes query ID, elapsed time, WLM queue, user, and truncated SQL text. Use when asked about slow or hung queries. |
| top_50_queries_by_runtime() | stl_query | Returns top 50 queries from the past 7 days aggregated by MD5 fingerprint, ordered by average runtime descending. Includes execution count, avg runtime, max runtime, and compile overhead. |
| top_50_queries_by_diskspill() | stl_query | Same aggregation as top_50_queries_by_runtime but ordered by total disk spill volume. Use when diagnosing memory pressure or high I/O queries. |
| query_spill() | sys_query_detail | Returns top 10 queries by disk spill volume using the formula: spill_gb = (spilled_block_count × 8.0) / (1024 × 1024). More granular than top_50 — includes per-step spill breakdown. |
| queue_time_query() | sys_query_history | Returns queries with queue_time > 0 from the past 7 days, indicating WLM queue contention. Shows queue wait time vs. execution time per query, ordered by queue_time descending. |
| daily_app_average() | sys_query_history + sys_connection_log | Returns daily average query execution time per application over a 7-day rolling window. Joins query history with connection log to resolve application names. Use for application-level performance trending. |
| run_sql(query) | Direct Redshift | Executes arbitrary read-only SQL against the connected Redshift cluster. Used for ad-hoc queries when no pre-built tool covers the needed data. The agent is instructed to keep queries read-only (SELECT only). |
WLM Queue Contention
WLM (Workload Management) assigns queries to queues with limited slot counts. When more queries arrive than available slots, queries wait. The queue_time_query() tool surfaces this contention:
- High queue_time / exec_time ratio — Indicates queue is frequently full. Consider increasing the slot count for that queue or creating a dedicated queue for long-running queries.
- Specific users or applications dominating queues — Use WLM query groups or user groups to route heavy users to a separate queue.
run_sql Safety
The
run_sql() tool uses a read-only database user and rejects statements that are not SELECT queries. The agent's system prompt reinforces read-only behavior, but the database-level restriction provides a hard guard against accidental writes.Disk Spill Formula
Both query_spill() and top_50_queries_by_diskspill() use the same formula to convert Redshift's block count metric to GB:
spill_gb = spilled_block_count × 8.0 / (1024 × 1024)
Each Redshift internal block is 8 KB. Dividing by 1,048,576 (1024 × 1024) converts KB to GB.