Query planning and execution

A ShrikeDB query passes through language parsing, semantic eligibility checks, logical and physical planning, snapshot binding, execution, and result serialization. Understanding these boundaries makes plans easier to inspect and performance changes easier to measure.

Execution lifecycle

Stage Work Useful evidence

Parse

Build a Cypher or SPARQL syntax tree and resolve parameters.

Syntax diagnostics and source location

Validate

Check clause combinations, semantic preconditions, write gates, path bounds, and procedure arguments.

Explicit rejection reason

Logical plan

Represent scans, expansions, joins, filters, aggregation, projection, sorting, and procedures.

Logical operator tree

Physical selection

Choose an eligible general executor or specialized exact implementation.

Implementation identity and fallback reason

Snapshot binding

Pin published graph, vector, KV, RDF, SpaceKey, or lakehouse facts needed by the plan.

Snapshot and source versions

Execute

Produce and transform rows while recording work.

Intermediate rows, seeks, expansions, candidates, elapsed time

Return

Serialize projected fields and stream or package the response.

Output row count, bytes, result hash

General and specialized execution

The ordinary physical executor handles plans assembled from general operators. ShrikeDB also contains exact implementations for eligible structural counts, transfer patterns, finite paths, motifs, graph analytics, vector search, and lakehouse views.

Eligibility is semantic. A specialized implementation must support the query’s labels, directions, multiplicity, distinctness, filters, path rules, clause boundaries, and output projection. Statistics may influence which eligible implementation is attractive; they cannot make an ineligible implementation correct.

When a specialized path is not eligible, the dispatcher retains its established precedence and fallback behavior. A diagnostic should identify the rejected candidate or unsupported shape rather than silently change query meaning.

Snapshot binding

Execution reads one published view of the database. Structural facts used during planning belong to the database identity and snapshot version. Named vector indexes, graph projections, catalog state, and other resources are pinned for the request so a concurrent publication does not mix versions inside one plan.

For direct multi-RPC workflows, an application can pass supported snapshot fields or record the versions observed by each call. See Transactions, durability, and snapshots for commits and publication.

Cardinality and work

Cardinality is the number of rows at a point in the plan. A query can return ten rows after producing millions of intermediate rows, so output size alone does not describe the work.

Common sources of growth include:

  • a broad node scan before a selective predicate;

  • expanding high-degree nodes;

  • joining two streams without a selective key;

  • applying a lateral vector search once per input row;

  • variable-length paths with a high upper bound;

  • aggregation or sorting after a large expansion.

Use PROFILE and operator traces to find where rows grow. Add the earliest semantically equivalent filter, relationship type, endpoint label, time bound, candidate limit, or source partition that reduces that stage.

EXPLAIN and PROFILE

EXPLAIN plans a supported query without running the child query:

EXPLAIN
MATCH (person:Person)-[:WORKS_FOR]->(company:Company)
WHERE company.country = $country
RETURN person.id, company.name

PROFILE executes and returns fields including operator count, row count, elapsed time, plan text, and a result hash:

PROFILE
MATCH (person:Person)-[:WORKS_FOR]->(company:Company)
WHERE company.country = $country
RETURN person.id, company.name

The profile row_count is the number of output rows. A scalar aggregate normally has one output row even if its child operators examine a large graph.

Query optimizer modes

The production dispatcher selects among existing execution implementations. The experimental learned selector operates in offline and shadow workflows: it describes eligible candidates, scores them, and records a recommendation while the established dispatcher serves the request. Shadow observation does not execute the recommended alternative.

Missing models, incompatible model versions, unavailable facts, an out-of-support feature vector, or exhausted preparation budget return the deterministic baseline recommendation. Learned estimates do not satisfy semantic preconditions.

This separation distinguishes two performance cases:

  • an eligible existing implementation is efficient, but dispatch did not select it;

  • no existing implementation completes efficiently, indicating a missing execution capability.

Plan stable application queries

For a latency-sensitive request:

  1. Preserve one parameterized query template.

  2. Record database and snapshot, parameters, concurrency, result count, and cache condition.

  3. Run a cold request separately from repeated requests.

  4. Compare completion and errors before comparing latency.

  5. Inspect planning time separately from execution and result transfer.

  6. Confirm result values and multiplicities after every rewrite.

Avoid optimizing a single literal if production values select very different graph regions. Use a parameter set that covers sparse, typical, dense, empty, and high-degree cases.

Fallback and rejection

A fallback is safe when another executor supports the same semantics. An explicit rejection is appropriate when the server cannot preserve them. Examples include unsupported unbounded path materialization, an invalid vector option, a disabled write gate, a missing lakehouse mapping, or a procedure whose required facts are unavailable.

Read the diagnostic, locate the unsupported shape, and choose an equivalent formulation only after verifying results on a small fixture.

Related chapters