QueryDeck Docs
AI Assistant

Explain, optimize, and fix

The three power features of the AI Assistant for queries you already have.

For: developers.

When you have a query already, the AI can do three things with it. Each has a button next to the editor and a right-click menu entry. All three are also available by asking in plain English.

Explain

Take a SQL query and get a plain-language description of what it does and what each part is for.

How to use

Way to triggerBehavior
Right-click in editor → "Explain"Sends the query (or selection) to the AI for a written explanation
Cmd+I, type "Explain this"Same
Toolbar → AI sparkle → "Explain"Same

What you get

A short prose explanation, broken into the logical parts of the query. Example for:

SELECT u.country, COUNT(DISTINCT o.user_id) AS active_users
FROM users u
LEFT JOIN orders o ON o.user_id = u.id AND o.created_at >= NOW() - INTERVAL '30 days'
GROUP BY u.country
HAVING COUNT(DISTINCT o.user_id) > 10;

Returns something like:

This query counts unique users who placed at least one order in the last 30 days, grouped by their country.

  • The LEFT JOIN keeps users who haven't ordered, but the predicate on o.created_at means only orders from the last 30 days are joined. A user with no recent order joins to NULL.
  • COUNT(DISTINCT o.user_id) counts the active users per country, ignoring NULLs.
  • HAVING filters out countries with 10 or fewer active users.

Note: because the date filter is in the ON clause and not in the WHERE, users with no orders at all are still included in the country count (with active_users = 0).

The explanation is conversational and points out subtle behavior (the ON vs WHERE difference here is exactly the kind of thing that catches people).

When to use it

  • Reading code written by a teammate.
  • Reviewing your own old query before changing it.
  • Teaching someone who's learning SQL.

Optimize

Take a SQL query and get a faster equivalent (or a suggestion for an index).

How to use

Way to triggerBehavior
Right-click in editor → "Optimize"Sends the query + the database's planner output to the AI
Cmd+I, type "How can I make this faster"Same
Toolbar → AI sparkle → "Optimize"Same

The optimize action includes EXPLAIN ANALYZE results in the AI prompt when possible — that gives the model the actual plan rather than guessing.

What you get

Either a rewritten query, an index suggestion, or both. Examples:

Rewrite suggestion:

Your query uses SELECT * with a DISTINCT. Replacing DISTINCT with GROUP BY on the columns you actually need cuts the sort cost in half on your data size.

SELECT u.id, u.email, COUNT(o.id)
FROM users u JOIN orders o ON ...
GROUP BY u.id, u.email;

Index suggestion:

Your query scans orders filtering on (user_id, created_at). The current plan shows a Seq Scan with 800ms cost. Adding a composite index would let the planner use an Index Scan:

CREATE INDEX idx_orders_user_created ON orders (user_id, created_at DESC);

Expected speedup: 50–200x on this query.

The model knows about common patterns: N+1 in disguise (correlated subqueries that should be joins), missing indexes on FK columns, ORDER BY ... LIMIT without a matching index, OR clauses that prevent index use.

Verify before you apply

The optimize feature is opinionated. Some of its suggestions are wins; some don't help on your specific data; some change query semantics in subtle ways. Always:

  1. Read the rewritten query carefully.
  2. Run EXPLAIN ANALYZE on the suggestion before and after.
  3. For index suggestions, weigh the cost (index size, write slowdown) against the speedup.

The AI cannot see your data distribution, only your schema and the plan output. Sometimes it suggests an index that helps cold queries but slows down high-volume writes.

Fix error

You ran a query, the database returned an error, and the AI suggests the change to make it work.

How to use

When a query errors in the editor, the error banner has a "Fix with AI" button. Click it. The AI sees the query, the error, and the schema.

You can also right-click the error in the result tab → "Fix with AI".

What you get

The corrected SQL with a short note on what changed:

The error column "createdAt" does not exist occurs because PostgreSQL folds unquoted identifiers to lowercase. Your column is named created_at. Replacing createdAt with created_at fixes it.

SELECT * FROM users WHERE created_at > NOW() - INTERVAL '7 days';

Common errors the assistant handles well:

ErrorTypical fix
Column doesn't existCasing, snake_case vs camelCase, missing alias
Ambiguous columnAdd table prefix
GROUP BY clauseAdd missing columns or wrap in aggregates
Type mismatchAdd cast
FK constraint violationSuggest the parent row that's missing
Syntax errorIdentify the malformed clause

The fix is generated against your live schema, so column suggestions are real, not guesses.

When the fix isn't right

If the AI fixes one error but the corrected query has a different bug, reply in the chat:

That works but now it returns no rows. The user might be in a sub-schema.

The conversation continues from there.

All three together

A common workflow:

  1. Write a query (yourself or with NL → SQL).
  2. Run it. If error, click "Fix with AI".
  3. Run the fixed version. If slow, click "Optimize".
  4. If a teammate will read it, click "Explain" and paste the explanation as a SQL comment.

The whole loop takes a minute or two with a fast model and saves you the back-and-forth of trial-and-error.

What's next