Skip to main content

relate_model/
plan_keys.rs

1//! The plan wire form's key vocabulary (ADR-0344/0345): the names
2//! `PlanNode::to_value` produces and every consumer reads, single-sourced
3//! so drift between producer and consumer is a compile error, not a silent
4//! mismatch. Its own module (the plan-node types and decoder stay in
5//! `plan_wire`); the public path is `wire::plan_keys`.
6
7use crate::wire::KernelRungWire;
8
9pub const OPERATOR_TYPE: &str = "operatorType";
10pub const ARGS: &str = "args";
11pub const IDENTIFIERS: &str = "identifiers";
12pub const CHILDREN: &str = "children";
13pub const ID: &str = "Id";
14pub const DETAILS: &str = "Details";
15pub const ESTIMATED_ROWS: &str = "EstimatedRows";
16/// PROFILE metrics (ADR-0344 phase 2).
17pub const ROWS: &str = "Rows";
18pub const TIME_NS: &str = "TimeNs";
19/// PROFILE metric fields (ADR-0344 metric fields).
20pub const DB_HITS: &str = "DbHits";
21pub const MEMORY_BYTES: &str = "MemoryBytes";
22/// The expression allocation bytes a profiled clause charged against the
23/// ADR-0463 statement budget, emitted with the metric block.
24pub const EXPRESSION_BUILT_BYTES: &str = "ExpressionBuiltBytes";
25/// The store-read mix behind `DbHits` (LABS-369): the kinds the one
26/// total blends — relationship hops, neighbor walks, node-store reads.
27pub const HOPS: &str = "Hops";
28pub const NEIGHBOR_WALKS: &str = "NeighborWalks";
29pub const NODE_READS: &str = "NodeReads";
30/// The phase times the read kinds' store work spent (LABS-448): the
31/// seek (candidate resolution and admission — the `Nodes` kind's
32/// work) and the walk (relationship traversal — the `Rels`/`Degree`
33/// kinds' work), inclusive of a multi-element pattern's nested
34/// phases. Emitted together with the metric block and the kinds.
35pub const SEEK_TIME_NS: &str = "SeekTimeNs";
36/// See [`SEEK_TIME_NS`].
37pub const WALK_TIME_NS: &str = "WalkTimeNs";
38/// The walk's chosen start (LABS-369): the pattern element index, its
39/// direction, and the reason class (`bound-pivot`, `cheapest`,
40/// `seek-anchored`, `index-0`) — the fact an opaque `Expand` hid.
41pub const START_ELEMENT: &str = "StartElement";
42pub const START_BACKWARD: &str = "StartBackward";
43pub const START_REASON: &str = "StartReason";
44/// Which rung served the clause's `MATCH` walk (LABS-1117), one of the
45/// `KERNEL_RUNGS` vocabulary — emitted only when a rung served the
46/// clause, with the metric set (a non-`MATCH` clause and a batch-chain
47/// `MATCH` emit no key).
48pub const KERNEL_RUNG: &str = "KernelRung";
49/// The chain rung's hop count (LABS-1117) — emitted with `KernelRung`
50/// when the rung is the chain, never for another rung.
51pub const KERNEL_HOPS: &str = "KernelHops";
52/// The store's active pattern-engine rung (LABS-1117): `auto`, `nfa`,
53/// or `walk`, emitted on every `MATCH` operator of an EXPLAIN and
54/// PROFILE tree — the one static rung fact the plan can state.
55pub const PATTERN_ENGINE: &str = "PatternEngine";
56/// The kernel-rung vocabulary (LABS-1117), the typed [`KernelRungWire`]'s
57/// name list — one spelling, never a second list and never a fabricated
58/// variant value. The executor's `KernelRung::as_str` reads the same name
59/// constants, and the mapping is pinned by `relate`'s
60/// `decline_and_start_reason_names_match_the_wire_tables`, like the start
61/// reasons and the run-time declines.
62pub const KERNEL_RUNGS: [&str; 4] = KernelRungWire::NAMES;
63/// Whether the clause ran ADR-0468's batch scan/filter/project chain
64/// over `Chunk` (LABS-359) — emitted only when true (like the start
65/// trio's presence-only-when-walked), with the metric set.
66pub const BATCHED: &str = "Batched";
67/// The batch filter's zone skips (LABS-645): conjunct-batch
68/// evaluations the chunk's derived min/max zone metadata provably
69/// replaced with the correct empty survivor set — emitted only when
70/// nonzero (a count's presence-only shape), with the metric set.
71pub const ZONE_SKIPS: &str = "ZoneSkips";
72/// The frontier family's run counters (ADR-0478): the BFS's edge
73/// visits, completed levels, and accepted endpoints — emitted only
74/// when the family ran the clause (`levels > 0`), the three together
75/// (a half-present trio is a wire-contract break), with the metric
76/// set.
77pub const FRONTIER_EDGES: &str = "FrontierEdges";
78pub const FRONTIER_LEVELS: &str = "FrontierLevels";
79pub const FRONTIER_ENDPOINTS: &str = "FrontierEndpoints";
80/// The frontier-NFA rung's own PROFILE facts (ADR-0478 §3, ADR-0516),
81/// riding the frontier trio's presence-only-when-engaged group: the
82/// (node, state) cells the runs created, the re-arrival rule memo's
83/// hits and misses, the admission asks by verdict
84/// (representative-proof / search-proven / search-disproven /
85/// declined-exhausted), and the budget fraction the rule's work
86/// spent — the seven integers and the one float emitted together
87/// with the trio, a half-present set a wire-contract break.
88pub const FRONTIER_CELLS: &str = "FrontierCells";
89pub const FRONTIER_MEMO_HITS: &str = "FrontierMemoHits";
90pub const FRONTIER_MEMO_MISSES: &str = "FrontierMemoMisses";
91pub const FRONTIER_REPRESENTATIVE_PROOFS: &str = "FrontierRepresentativeProofs";
92pub const FRONTIER_SEARCH_PROVEN: &str = "FrontierSearchProven";
93pub const FRONTIER_SEARCH_DISPROVEN: &str = "FrontierSearchDisproven";
94pub const FRONTIER_DECLINED_EXHAUSTED: &str = "FrontierDeclinedExhausted";
95pub const FRONTIER_BUDGET_FRACTION: &str = "FrontierBudgetFraction";
96/// Why the frontier rung did not serve the clause, one of the
97/// `DECLINE_REASONS` vocabulary — emitted with the metric set when the
98/// rung declined at plan time (counters absent: it never ran) or engaged,
99/// ran, and fell through (ADR-0516, counters beside it).
100pub const FRONTIER_DECLINE_REASON: &str = "FrontierDeclineReason";
101/// The decline vocabulary: first the run-time declines (ADR-0516), the
102/// executor's `FrontierRunDecline::as_str` names, then the plan-time
103/// gates' (ADR-0478), `FrontierDecline::as_str` — single-sourced here so
104/// a renamed decline fails loudly at the wire boundary, like the start
105/// reasons. Each name is its own constant, read by the executor's
106/// vocabulary macros and by the table below.
107pub const DECLINE_REARRIVAL_BUDGET: &str = "rearrival-budget";
108pub const DECLINE_TABLE_BUDGET: &str = "table-budget";
109pub const DECLINE_MULTIPLE_PATTERNS: &str = "multiple-patterns";
110pub const DECLINE_CARRYING_ROW: &str = "carrying-row";
111pub const DECLINE_MODE: &str = "mode";
112pub const DECLINE_NESTED_SPINE: &str = "nested-spine";
113pub const DECLINE_ALL_REDUCE_GROUP: &str = "all-reduce-group";
114pub const DECLINE_PINNED_BINDING: &str = "pinned-binding";
115pub const DECLINE_CONJUNCT: &str = "conjunct";
116pub const DECLINE_NFA_SHAPE: &str = "nfa-shape";
117pub const DECLINE_GUARDED_GROUP: &str = "guarded-group";
118pub const DECLINE_FULL_ENUMERATION: &str = "full-enumeration";
119pub const DECLINE_ORDERED_CAP: &str = "ordered-cap";
120pub const DECLINE_PATH_COUNT: &str = "path-count";
121pub const DECLINE_PATH_CONSUMER: &str = "path-consumer";
122pub const DECLINE_COST: &str = "cost";
123/// The decline names, in the vocabulary's own order.
124pub const DECLINE_REASONS: [&str; 16] = [
125    DECLINE_REARRIVAL_BUDGET,
126    DECLINE_TABLE_BUDGET,
127    DECLINE_MULTIPLE_PATTERNS,
128    DECLINE_CARRYING_ROW,
129    DECLINE_MODE,
130    DECLINE_NESTED_SPINE,
131    DECLINE_ALL_REDUCE_GROUP,
132    DECLINE_PINNED_BINDING,
133    DECLINE_CONJUNCT,
134    DECLINE_NFA_SHAPE,
135    DECLINE_GUARDED_GROUP,
136    DECLINE_FULL_ENUMERATION,
137    DECLINE_ORDERED_CAP,
138    DECLINE_PATH_COUNT,
139    DECLINE_PATH_CONSUMER,
140    DECLINE_COST,
141];
142/// The start-reason vocabulary (LABS-369), the executor's
143/// `StartReason::as_str` names — single-sourced here so a renamed
144/// reason fails loudly at the wire boundary, like the warning names.
145/// Each name is its own constant, so the variant↔name mapping reads the
146/// same spelling this table does (the shape [`KernelRungWire`] takes for
147/// the rungs).
148pub const REASONS: [&str; 4] = [
149    START_REASON_BOUND_PIVOT,
150    START_REASON_CHEAPEST,
151    START_REASON_SEEK_ANCHORED,
152    START_REASON_INDEX_ZERO,
153];
154/// The bound-pivot start reason: see [`REASONS`].
155pub const START_REASON_BOUND_PIVOT: &str = "bound-pivot";
156/// The cheapest-start reason: see [`REASONS`].
157pub const START_REASON_CHEAPEST: &str = "cheapest";
158/// The seek-anchored start reason: see [`REASONS`].
159pub const START_REASON_SEEK_ANCHORED: &str = "seek-anchored";
160/// The first-element (un-optimised) start reason: see [`REASONS`].
161pub const START_REASON_INDEX_ZERO: &str = "index-0";
162/// The typed warnings the node carries (typed node warnings): a list
163/// of warning maps from the [`PlanWarning`](crate::wire::PlanWarning)
164/// vocabulary, present only when the node carries one. Each map
165/// carries the warning's name and, when the warning has a payload
166/// (the `LabelDisjunctionScan` warning's index pairs), that payload —
167/// one spelling for the producer and every consumer.
168pub const WARNINGS: &str = "warnings";
169/// The warning map's name field (typed node warnings).
170pub const WARNING_NAME: &str = "name";
171/// The warning map's payload field (typed node warnings): the
172/// `LabelDisjunctionScan` warning's index-pair text.
173pub const WARNING_INDEX: &str = "index";
174/// The Neo4j-facing root args (ADR-0357): the plan's rendered text —
175/// Neo4j's plan root carries it and tooling (Browser's Code tab,
176/// strict clients) renders from it. The engine's own args stay as
177/// they are; the one decoration lives on `PlanNode` (the
178/// `relate` crate's `to_neo4j_value`, this vocabulary's only
179/// writer) and each surface calls it at its boundary.
180pub const STRING_REPRESENTATION: &str = "string-representation";
181/// The planner and runtime identity args (ADR-0357): `planner` names
182/// the planner, `planner-impl`/`planner-version` its implementation
183/// and version; `runtime`/`runtime-impl`/`runtime-version` the same
184/// for the runtime; `version` is the Cypher language version — Neo4j's
185/// plan root carries all of them and tooling (cypher-shell's summary
186/// block, Browser's footer) reads them.
187pub const PLANNER_IMPL: &str = "planner-impl";
188/// See [`PLANNER_IMPL`].
189pub const PLANNER: &str = "planner";
190/// See [`PLANNER_IMPL`].
191pub const PLANNER_VERSION: &str = "planner-version";
192/// See [`PLANNER_IMPL`].
193pub const RUNTIME: &str = "runtime";
194/// See [`PLANNER_IMPL`].
195pub const RUNTIME_IMPL: &str = "runtime-impl";
196/// See [`PLANNER_IMPL`].
197pub const RUNTIME_VERSION: &str = "runtime-version";
198/// See [`PLANNER_IMPL`]: the Cypher language version the plan ran
199/// under.
200pub const VERSION: &str = "version";
201/// See [`PLANNER_IMPL`]: Neo4j's `Memory` arg — the root mirrors this
202/// engine's row-materialization bytes under it (ADR-0357).
203pub const MEMORY: &str = "Memory";