Mechanism

Everything happens before the optimizer sees your query.

HyperQuery/PG is a planner-hook extension. It never touches your application, your connection pooler, or your ORM — it changes what the planner is handed, not how you talk to Postgres.

Green matrix-style code streaming across a dark screen

The pipeline

Parse → match → rewrite → verify → optimize.

Five stages, all inside a single PostgreSQL backend process, adding microseconds — not a network hop, not a sidecar, not a proxy.

Intercept at the planner hook

After Postgres parses and analyzes a query — once it has a fully resolved parse tree with real types and catalog OIDs — HyperQuery/PG's hook runs before planner() builds a plan. It sees exactly what the optimizer would have seen.

Match against the rule library

The parse tree is walked and checked against a compiled library of 300+ anti-pattern signatures. Rules are organized by category — predicates, subqueries, joins, pagination, aggregation, set operations — and many can match the same query independently.

Rewrite to the canonical form

Each match is replaced with the index-friendly, planner-friendly equivalent for that pattern — restructuring the tree, not generating new SQL text from scratch. The rewritten tree is handed back into the same query.

Verify equivalence

Every rule in the library ships with a proof of relational equivalence and a regression suite that checks the rewritten query returns identical rows, in identical order, across edge cases like NULLs, ties, and duplicates. A rule that can't be proven safe for a given shape simply doesn't fire — the original tree passes through unchanged.

Hand off to the optimizer

The (possibly rewritten) tree is passed to the standard PostgreSQL optimizer exactly as if it had arrived that way. Cost estimation, join ordering, and index selection all happen downstream, untouched by HyperQuery/PG.

Developer working at a dark monitor displaying code — the real-world context HyperQuery/PG operates in — No application code to change — the developer keeps shipping features, not query fixes

Rule library

The catalog, by category.

A representative cross-section of the 300+ rules HyperQuery/PG ships with. Figures are illustrative order-of-magnitude examples drawn from common schemas — not a benchmark of any single workload.

Predicates

PatternBeforeAfterΔ

text column = integer literal → typed literalimplicit cast 754,210888,570×

lower(email) = '…' → expression-index-safe formfunction-wrapped column 191,330412464×

date_trunc(created_at) = '…' → sargable rangefunction-wrapped column 276,310530521×

OR across two indexed columns → UNION ALL of branchespredicate restructuring 88,40296921×

Subqueries & joins

PatternBeforeAfterΔ

NOT IN (nullable) → NOT EXISTSnull-safe rewrite 482,9101,204401×

correlated scalar subquery in SELECT → LEFT JOIN LATERALjoin restructuring 1,208,5563,310365×

COUNT(*) > 0 existence check → EXISTSsubquery simplification 64,920411,583×

Pagination, aggregation & set operations

PatternBeforeAfterΔ

OFFSET 500000 pagination → keyset (seek) paginationpagination 940,4476121,537×

DISTINCT masking a JOIN fan-out → pre-aggregated subqueryaggregation 322,1081,855174×

UNION (duplicates impossible) → UNION ALLset operation 51,2069,8405×

Precisely organised network cables running into server ports — Each rule is a proven, deliberate connection — nothing fires unless relational equivalence is guaranteed

Questions

Before you install it

Will this change my query results?

No. Every rewrite is proven row-and-order equivalent before it ships in the rule library. If equivalence can't be proven for a given query shape — including edge cases like NULLs or duplicate rows — HyperQuery/PG leaves the query untouched.

Do I need to change my application or ORM?

No. HyperQuery/PG operates entirely inside Postgres, before the optimizer. Your application keeps sending exactly the SQL it already sends.

Which Postgres versions are supported?

Self-managed PostgreSQL 13 and later today. Support for managed/cloud Postgres providers is on the roadmap — ask us about your specific environment.

Can I see which rules are firing on my queries?

Yes. Every rewrite is logged with the rule that fired and a before/after of the query, so nothing happens silently.

What happens if a query doesn't match any rule?

It passes straight through to the optimizer, exactly as it would without HyperQuery/PG installed. The extension only ever acts on recognized patterns.

Ready to see your own queries through the rule library?

Send us a slow query. We'll tell you which rule catches it.

Request access