Module query 

The runner (spec/surface/README.md §1.4): parse the source, rewrite the row functions to $self methods, run it through the engine over the store context, and shape the engine’s result into the surface’s OqxResult (lean { id, path, … } hits, keyset paging, the consumer scalars). Port of packages/core/src/oqx-js/run.ts.

By default the tier-3 planner (crate::planner) pre-filters the scan in SQL and the in-memory engine finishes the residual over the produced rows; QueryOptions::in_memory forces the pure in-memory engine (the differential gate runs every case both ways — a planner must be invisible).

Structs

OqxResult

§1.4 OqxResult.

QueryOptions

query’s options.

Constants

BARE_NEEDS_SELECT_MESSAGE

The bare refusals (4.2): the same text in both engines.

BARE_WITH_VALUES_MESSAGE

DEFAULT_LIMIT

The default page size.

REPO_REMOVED_MESSAGE

The $repo error (removed in surface 2.0): the same text in both engines.

RESERVED_ALIAS_PREFIXES

The runner’s own projection names (__oqx_id, __oqx_path, __oqx_self, __oqx_value) and the selector compiler’s slots (__omg_sel_<t>_<slot>, crate::select) share two reserved prefixes. A user alias under either would shadow an injected item (select __oqx_id: 1 overwrote the hit’s id through 4.0) or collide with a slot, so it is refused before anything runs (4.1) — over the query’s own top-level items, the only ones the runner injects beside. The reference’s reservedAlias.

Functions

bare_target_message

The bare-target error. depth is the scope depth the name was read at when known statically (the carets in the hint count it); None when raised at read time by the context, where the hint spells out the rule instead.

check_bare

bare: true needs a projection and is not the values form (§1.4, 4.2): without a projection a hit is only its envelope, and values is already the bare-values form. Checked over the resolved query where hits are built (the scalar consumers have no hits and ignore bare), before the engine runs, so the error never depends on the rows and the planned and in-memory paths agree trivially. The reference’s bareMisuse.

check_reserved_aliases

Refuse a top-level select alias under a reserved prefix.

check_root_spellings

The repository is OQX’s root row (spec/oqx 0.18): from a top-level row ^docs reaches the documents (one caret per enclosing block, or the absolute 0^docs) and ^id the repository id. Two spellings are refused before evaluation, by one walk over the parsed tree, so the error does not depend on which rows the data holds and the planned and in-memory paths agree trivially: $repo anywhere (bare, as a member head, ^$repo, 0^$repo), and a bare docs/links at scope depth ≥ 1 — a property read of a row that has none. blocks/nodes are relations of some rows (docs.blocks, docs.nodes, blocks.nodes, section.blocks) and are judged by the context at read time with the same message. A ^<target> with more carets than enclosing scopes (^docs count { } at the top level) would read absent and count 0: refused too, naming the bare spelling. Port of the reference’s checkRootSpellings.

collect_semantic_phrases

The distinct phrases semantic("…") names (free calls in the raw parse); empty when the source does not parse.

embed_phrases

Embed the query’s phrases through the provider: the vectors semantic(...) ranks by. Without a provider the phrases stay unembedded and the context reports filter_invalid (“needs an embedding provider”) when one is reached — after its target check, so semantic() on nodes names the targets (§9; the query tool’s pre-check is what reports semantic_unavailable).

past_root_message

The past-the-root error: ^docs at the root scope (more carets than there are enclosing scopes) would read absent and count 0 — refused, naming the bare spelling. levels is the caret count written.

query

Run an OQX query against repo_id (§1.4).

query_ast

Run an already-parsed query (§1.4) — the AST entry the selector compile uses (spec/mutate §11.8: the selector’s tree with the templates’ slot projections appended runs as any query does; the reserved-alias check is the source entry’s, so the appended __omg_sel_* items pass). semantic holds the embedded phrases (embed_phrases); opts.provider is not read here. Unknown names (4.6) default to UnknownNames::Refuse here: this entry’s caller is the write selector, where a name no row carries would select every row; the source entry passes Hint.

rewrite_query

Rewrite every row function in a parsed query to a $self method call, and root every string literal compared with a path intrinsic — one transform over the AST (spec/oqx/AST.md §5), every block included.

root_path_literals

The literal-rooting rewrite of one expression (see rewrite_query).

semantic_phrases_of

collect_semantic_phrases over a parsed tree.

unknown_target_message

The unknown-target error (3.0 name pass): a top-level from <name> whose name is not one of the five collections would read an absent root and return an empty result — refused instead, naming the collections (in the root object’s order, revisions the fifth since 4.7); edges, the links target’s name before 3.0, gets its new name spelled out.