---
title: L6 - Query Engine
description: Admit operations, compile portable queries, and execute provider statements
icon: database
---

The query engine lives in `src/query-engine/`. Its public input is an operation
on a registered model; its output is a parsed result or a typed failure. The
compiler and its intermediate objects are private implementation details.

## Admission and execution

A client operation returns a lazy `PendingOperation`. Awaiting it runs the
operation lifecycle once; subsequent Promise consumers share that execution.
Extension `call` parts patch or refuse its arguments before validation. The
schema registry then admits the operation against the registered model graph.
`around` parts surround execution, and a `unit` part declared
`{ rewrites: true }` rewrites each logical statement. Observation (`unit`
parts) has separate operation and statement boundaries.

The current implementation is under `raptor3/`:

- `commands/index.ts` admits an operation and runs it: on the client's own
  driver, or inside the transaction an owner lends it.
- `shared/sql-operation-context.ts` binds the schema, the driver and the call
  for one execution.
- `shared/query.ts` prepares reads, filters, projections and aggregates, and
  decodes provider rows into the public scalar and relation domains;
  `shared/sql-queries.ts` lowers what was prepared to SQL.
- `write/` runs writes, nested relation work included: the verbs say what a
  write means, the store holds what the call believes of its rows, and the
  transports send its statements one unit at a time.

Those paths describe the installed implementation. They are not package entry
points, supported extension hooks, or APIs applications should import.

## SQL belongs to adapters

The engine decides which rows and relationships an operation addresses. The
adapter owns the SQL spelling: identifier qualification, JSON aggregation,
comparisons, storage conversions, returning clauses, and provider differences.
Both layers compose parameterized `Sql` fragments. The engine does not recover
semantic facts by parsing generated SQL.

A relation's topology is resolved once by schema validation. Query and write
consumers use that same resolved index. They do not scan for inverse relations
or independently decide which side owns a foreign key.

## Atomicity is a driver capability

An interactive transaction keeps an operation on one reserved session. A native
batch can atomically execute a prepared statement group, but cannot generally
branch in JavaScript on an earlier result. A driver offering neither facility
cannot make several statements atomic merely because the caller issued one
nested ORM operation.

The compiler refuses a shape when its required guarantees cannot be preserved.
For example, relation-bearing `skipDuplicates` requires a supported savepoint or
native strategy; unsupported combinations fail before writing rather than
silently dropping the option. See [transactions](/docs/client/transactions) and
the [driver matrix](/docs/drivers) for the concrete guarantees.

Prepared array transactions admit their members before dispatch. They preserve
member order and statement attribution. Callback transactions execute against
the callback's bound client. A failed savepoint or transaction poisons further
work on that scope until its owning cleanup boundary completes.

## Result and storage boundaries

Input validation establishes the logical scalar domain. Provider parsers and
the compiled row parser establish the returned domain. Invalid provider data
raises an error; a missing or malformed value is not replaced with a plausible
zero, empty object, or empty list.

Typed operations never inspect physical storage. A schema VibORM pushed or
migrated is correct by construction; a foreign SQLite decimal column or
noncanonical temporal text is found by `viborm check --db`, not per statement.
Raw SQL stays physical and does not receive model-aware decoding.

## Inspection and verification

`PendingOperation.buildStatement()` is an inspection facility for supported
read shapes; it is not a general prepared-query API. Use the official
[instrumentation extension](/docs/extensions/instrumentation) to inspect
executed statement events under its disclosure settings.

`pnpm test:layer:query-engine` runs the layer's fast checks. `pnpm test:core`
runs the complete core selection in sequential bounded shards. Extended,
provider, and coverage selections are documented in `tests/README.md` and
owned by the CI manifests. A local compiler test does not establish a hosted
provider contract.
