Queries

The Queries page lists every query Query Doctor has captured for a project and what it found when it costed each one. Queries reach it two ways: the analyzer pushes what it reads from pg_stat_statements on a connected database, and CI runs contribute the queries your tests exercised. The source and branch filters separate the two.

This page covers what the numbers mean. The controls themselves are on screen.

Status

Every query lands in one of seven states.

Status	Meaning
Waiting	Captured, not yet costed
Optimizing	Being costed now
Improvements available	A set of new indexes or a rewrite of the query lowers its cost
No improvement found	Costed, and no candidate index or rewrite it tried beat the current plan
Not supported	Outside what the optimizer can cost (see below)
Timeout	Costing ran past its limit
Error	Costing failed

In a CI run and in optimize_query, a rewrite doesn’t wait on the index search. When the search runs past its limit, Query Doctor still costs the query’s rewrites against its current plan, and one that lowers the cost by 5% or more puts the query in Improvements available. That result says no index was costed, because none was.

Not supported is a statement about the query, not a failure. Three things trigger it:

• System queries — anything against pg_* or information_schema, and SET / SHOW statements.
• Non-SELECT queries. The optimizer costs reads. An INSERT or UPDATE never reaches it.
• SELECTs that read no table, such as SELECT 1. There is nothing to index.

Cost

Cost is PostgreSQL’s own plan cost, not milliseconds. It is what the planner used to choose this plan over the alternatives, so it compares two plans for the same query well and says nothing about wall-clock time on its own.

Only three states carry a cost: improvements available, no improvement found, and timeout. A waiting, optimizing, not supported or errored query has none.

Where an improvement exists, the reduction is the drop from the current plan’s cost to the cheapest improvement’s: the suggested indexes in place, or the rewritten query. An index reduction belongs to the whole recommended set, not to any one index in it. See how optimization works.

Why a query ranks where it does

The default sort is Relevance, a score rather than a single column. It adds three things:

1. The query’s Findings: 16 for each correctness Finding and 1 for each performance Finding.
2. Its best Improvement, on the same scale: 16 when it clears the high-value bar below, and 4 otherwise.
3. Its runtime impact — mean time times calls, log-scaled, and zero when the query has no runtime statistics.

Point 3 is why a CI-only query can sit below a live one with the same findings. CI queries carry no pg_stat_statements metrics, so their runtime impact is zero.

An Improvement clears the high-value bar only when it meets both thresholds: at least a 50% cost reduction and more than 100 cost units saved. A 90% reduction that saves 40 units weighs 4, because acting on it buys almost nothing.

Filters worth explaining

Most filters say what they do. Two don’t:

• Exclude targetless queries hides SELECTs with no FROM clause. They are already reported as not supported, so this mostly removes noise.
• Branch applies to queries that arrived from CI. Live queries from a connected database aren’t attached to a branch.