Nudges Overview

Nudges are actionable suggestions that Query Doctor attaches to queries in the Live Queries view. Each nudge identifies a specific performance concern — from SQL anti-patterns to concrete index recommendations — and is assigned a severity level so you can prioritize what to fix first.

In the query detail view, nudges are grouped by severity in the Insights panel. Nudges that reference a specific location in the query are also highlighted inline in the formatted SQL view.

Severity levels

Severity	Meaning
Critical	High-impact issue that significantly degrades performance. Act on these first.
Warning	Issue that negatively impacts performance or correctness. Worth investigating.
Info	Best practice or minor inefficiency. Consider addressing when convenient.

The query list sorts by nudge severity by default, using a weighted score: critical counts for 16 points, warning for 4, and info for 1. This surfaces the queries with the most impactful issues at the top.

Nudge categories

Nudges come from two sources: query analysis (SQL anti-patterns detected by parsing the query AST) and optimization results (cost-based findings from the analyzer).

Optimization nudges

These are generated after the analyzer evaluates index configurations for a query.

Nudge	Severity	Description
Large improvement found	Critical	50%+ cost reduction with an absolute difference >100. Includes suggested CREATE INDEX statements.
Small improvement found	Warning	Cost reduction below 50%. Still worth reviewing, especially for high-call queries.

Query analysis nudges

These are detected by parsing the SQL and flagging common anti-patterns. Each can include a character offset pointing to the exact location in the query.

Nudge	Severity	Description
Function on column in WHERE	Warning	A function wrapping a column in a WHERE clause (e.g. WHERE lower(name) = 'bob') prevents the planner from using a plain B-tree index on that column.
Leading wildcard LIKE	Warning	A LIKE pattern starting with % (e.g. LIKE '%search') forces a sequential scan. Consider a trigram index or full-text search.
NULL comparison with = or !=	Warning	Comparing to NULL with = or != always yields unknown. Use IS NULL or IS NOT NULL.
DISTINCT without clear need	Warning	DISTINCT adds a sort or hash step. Use it only when duplicates are actually possible and unwanted.
Missing JOIN condition	Warning	A JOIN without an ON clause or multiple tables in FROM without an explicit join produce a cartesian product.
Many ORs instead of IN	Warning	Three or more OR conditions on the same column (e.g. id = 1 OR id = 2 OR id = 3) can be simplified to IN (1, 2, 3).
SELECT *	Info	Selecting all columns fetches more data than needed and prevents Index Only Scans. List only the columns you use.
Missing WHERE clause	Info	A top-level SELECT from a table with no WHERE clause reads every row.
Missing LIMIT clause	Info	A top-level SELECT from a table with no LIMIT may return more rows than the caller needs.
Large IN tuple	Info	An IN list with 10+ literal values can be replaced with = ANY($1) using a parameterized array for cleaner plans.