Query plan

The intermediate representation between the Wasm query compiler and the in-process query interpreter. Consumed by QueryInterpreter in packages/client-engine-runtime/src/interpreter/query-interpreter.ts. Type defined in packages/client-engine-runtime/src/query-plan.ts.

Why it exists

Prisma 7 separates plan compilation from plan execution:

• Compilation — done by @prisma/query-compiler-wasm (Rust → Wasm). Receives a JSON-protocol request, produces a query plan tree.
• Execution — done by QueryInterpreter in TypeScript. Receives a query plan and a SqlQueryable adapter, walks the tree, issues SQL.

Splitting these lets the same compiled plan run in multiple environments: in-process via LocalExecutor or remotely via RemoteExecutor and query-plan-executor. Both use the same interpreter code on the same plan shape.

Plan shape

QueryPlan is a discriminated union. Common node kinds:

Kind	What it represents
query	A single parameterized SQL execution
executeRaw	A user-supplied raw SQL command
queryRaw	A user-supplied raw SELECT
unique	Wrap a sub-plan to expect exactly one result
aggregate	Aggregation result shaping
group-by	GROUP BY result shaping
join	Hydrate a relation by joining child results onto parents
attach-children	Attach child rows to parents by foreign key
transform	Projection / typing transforms
transaction	Wrap a sub-plan in a transaction
concat / union	Combine results

(See packages/client-engine-runtime/src/query-plan.ts for the full union.)

Execution model

graph TD
    Plan[QueryPlan tree]
    Plan --> Walk[QueryInterpreter.run]
    Walk --> Issue[For 'query' nodes: queryRaw against adapter]
    Walk --> Apply[For 'transform' nodes: shape result]
    Walk --> Hydrate[For 'attach-children': fold children into parents]
    Walk --> Tx[For 'transaction': delegate to TransactionManager]

Plan walking is sequential per branch but exploits batching where possible — sibling queries inside a single tick can be coalesced via DataLoader upstream of the interpreter.

Parameterization

Query plans carry placeholders (positional or named) that resolve to actual parameter values at execution time. The parameterization/ directory in client-engine-runtime/src/ holds helpers for substitution. Helpers in param-graph and param-graph-builder track placeholder dependency graphs for query plans that reuse computed values.

Where plans are inspected

• Tests — packages/client-engine-runtime/bench/interpreter.bench.ts runs the interpreter against representative plans for performance tracking.
• Runtime — ClientEngine doesn't typically inspect plans; it delegates execution. But debug logging (via @prisma/debug) can dump them.
• Server-side execution — @prisma/query-plan-executor deserializes plans from HTTPS requests and runs the same interpreter.

See also

• @prisma/client-engine-runtime for the interpreter
• Query execution for the end-to-end flow
• @prisma/query-plan-executor for server-side execution