Expand description
Canonical JSON wire encoding shared by every Relate surface.
This module is the single source of truth for how a CypherValue, a set
of mutation counters, and a query response are rendered as JSON on the wire
(the C FFI, the CLI, and the shapes the language bindings derive from
those). Every surface is expected to route its serialization
through here so that a drift in one surface becomes a failing golden test
(see the golden submodule).
It is deliberately distinct from the persistence encoding in
crate::serde_value (the __type-tagged format used for on-disk
round-tripping and for CypherValue’s serde::Serialize impl). The wire
encoding is self-describing and stable: it never falls through to a
Display string for a structured value, and is documented field-by-field
below. Entity values (nodes and relationships) carry an explicit
"kind" discriminator so clients dispatch on a
documented field instead of sniffing key sets (ADR-0223, a breaking wire
change recorded in the CHANGELOG); the __type-tagged persistence
format remains a separate encoding.
§Value encoding (value_to_wire_json)
| Variant | Wire JSON |
|---|---|
Null | null |
Bool | true / false |
Int | JSON integer |
Float | JSON number (non-finite NaN/±Inf → "NaN"/"Inf"/"-Inf", see below) |
Str | JSON string |
List | JSON array (elements recursively encoded) |
Map | JSON object (values recursively encoded) |
Node | {"kind":"node","id","labels","properties"} |
Relationship | {"kind":"relationship","id","type","start_node","end_node","properties"} |
Path | JSON array alternating [node, rel, node, rel, …, node] (no tag of its own; elements carry their kind, ADR-0223) |
Date | ISO-8601 date string YYYY-MM-DD |
Time | ISO-8601 time string HH:MM[:SS[.fff]][±HH:MM[:SS] or Z] |
DateTime | ISO-8601 YYYY-MM-DDTHH:MM:SS[.fff]±HH:MM[[Zone/Id]] |
LocalDateTime | ISO-8601 YYYY-MM-DDTHH:MM:SS[.fff] |
Duration | ISO-8601 duration PnYnMnDTnHnMnS |
Point | coordinate-key object + srid/crs marker (below) |
Geometry | GeoJSON-style {"type", "coordinates" or "geometries"} |
Vector | {"type","dim","values"} (structured, not a string) |
The five temporal renderings are exactly the canonical ISO-8601 Display
forms of the corresponding CypherValue (trailing-zero-trimmed fractional
seconds, compact offsets, Z for UTC, [IANA/Zone] suffix on a zoned
DateTime). They are unambiguous and parseable, and — unlike the
persistence format — carry no type tag.
§Point (Point)
A coordinate-key object carrying an explicit CRS marker so the reader never has to guess the coordinate space:
- geographic (
srid4326 / 4979):{"srid","crs","longitude","latitude"[,"height"]} - cartesian (all other srids):
{"srid","crs","x","y"[,"z"]}
crs is the Neo4j CRS name (wgs-84, wgs-84-3d, cartesian,
cartesian-3d; unknown srids fall back to cartesian keys/name). The
srid/crs marker is new relative to the historical CLI/WASM point output,
which emitted the coordinate keys alone.
§Vector (Vector)
{"type": <coordinate-type name>, "dim": <usize>, "values": [<number>, …]}.
type is the canonical coordinate-type name (INTEGER8, INTEGER16,
INTEGER32, INTEGER, FLOAT32, FLOAT); integer-kind vectors carry JSON
integers, float-kind vectors carry JSON numbers. This replaces the previous
bug where every surface stringified a vector via Display
(vector([…], 3, FLOAT32 NOT NULL)).
§Non-finite floats
NaN, +Inf, and -Inf are not representable as standard JSON numbers
and are encoded as the JSON strings "NaN", "Inf", and "-Inf" —
exactly the CypherValue Display spellings, so the JSON surfaces agree
with the table/CSV modes and a non-finite float is never
indistinguishable from a genuine null (ADR-0280; a breaking wire
change from the previous null encoding, acceptable pre-1.0/alpha per
the precedent below, recorded in the CHANGELOG).
§Stats encoding (stats_to_wire_json)
All 11 mutation counters, snake_case, zeros included:
nodes_created, nodes_deleted, relationships_created,
relationships_deleted, properties_set, labels_added, labels_removed,
indexes_added, indexes_removed, constraints_added,
constraints_removed.
stats_from_wire_json is the inverse: it decodes that object back into
a WireStatsSnapshot, naming the first canonical counter that is
missing or not an unsigned integer.
These are the canonical names (they match the engine’s Stats field names
and Neo4j’s Added/Removed semantics). The historical JSONL server
renamed four of them (indexes_added→indexes_created,
indexes_removed→indexes_dropped, and the two constraints_*
equivalents); the WASM surface used camelCase and omitted zeros; the FFI
surface emitted only six. Unifying on this set is a breaking wire change
(documented in the CHANGELOG; acceptable pre-1.0/alpha).
§Response envelope (response_envelope / error_envelope)
{ "columns": [ … ], "columnTypes": [ … ], "rows": [ { … }, … ], "stats": { … }, "notifications": [ … ], "elapsed_ms": 1.25, "parse_ms": 0.4, "plan_ms": 1.1, "execute_ms": 10.8, "plan": { … } | null, "error": null }notifications is always present and empty on a plain run (ADR-0363
decision 9); its entries are the engine-native notification objects
(notification_to_wire_json). plan is always present too — the
relate.plan/v1 document (LABS-418, ADR-0381), null on a plain
run.
The row container key is rows. The historical JSONL server and FFI
used data; migrating them to rows is part of the same unification.
elapsed_ms is the engine-reported statement elapsed in wall-clock
milliseconds (ADR-0221). parse_ms/plan_ms/execute_ms are that
window’s PARSE / PLAN / EXECUTE split (ADR-0491): always-on, disjoint
sub-windows whose sum never exceeds elapsed_ms (the inter-stage gaps
stay in the total alone). The total and its split ride the builder
together as one TimingStampMs — an envelope construction site
cannot carry the total without its split.
columnTypes carries the engine-stamped
per-column type names of ADR-0224 (one of the 18 canonical names, beside
columns, same length and order; a column whose first-row value is
Null, or a result with no rows, stamps ANY, so a write-only envelope
carries "columnTypes": []). On error: columns: [], rows: [],
stats: {}, error: <message string> (no elapsed_ms: no statement
ran).
Modules§
- golden
- Shared golden fixtures: the cross-surface anti-drift substrate.
- notification_
keys - The engine-native notification keys (ADR-0363 decision 9) — the
vocabulary
notification_to_wire_jsonemits and every consumer reads, single-sourced likesuper::plan_keys. - plan_
keys - The plan wire form’s key vocabulary (ADR-0344/0345): the names
PlanNode::to_valueproduces and every consumer reads, single-sourced so drift between producer and consumer is a compile error, not a silent mismatch. Its own module (the plan-node types and decoder stay inplan_wire); the public path iswire::plan_keys.
Structs§
- Notification
- One query notification (ADR-0363 decision 1): the record
{ kind, description, remedy, operator_id }. - Plan
Metrics Wire - The PROFILE metric set (ADR-0344 phase 2 + metric fields) as named fields: which number is rows, nanoseconds, store accesses, or row-materialization bytes is stated by the names, not by a position convention.
- Plan
Node Wire - The typed view of one structured-plan wire node (ADR-0344/0345): the
producer (
relate’sPlanNode::to_value) emits exactly this shape, so this accessor states the invariants instead of tolerating misses — a malformed plan fails loudly rather than silently dropping a row or shifting cells into the wrong column. - Plan
Phases Wire - The phase times a PROFILE node reports (LABS-448): the elapsed time
the read kinds’ store work spent — the seek (candidate resolution and
admission, the
Nodeskind’s work) and the walk (relationship traversal, theRels/Degreekinds’ work), inclusive of a multi-element pattern’s nested phases. - Plan
Profiled Facts - A metrics-carrying node’s presentation bundle (cumulative vs self): the PROFILE metric set and its subtree total — the derived total travels with the metrics it sums, present together or not at all, so no presentation can render a total beside unavailable metrics or a metric set without one.
- Plan
Reads Wire - The store-read mix a PROFILE node reports (LABS-369): the kinds the
one
Db Hitstotal blends — relationship hops, neighbor walks, and node-store reads. - Stat
Counter - A mutation counter: its key in an envelope’s
statsobject, its key on the Bolt wire (derived byStatCounter::bolt_key), and theWireStatsaccessor it encodes — with that accessor’s inverse, sostats_to_wire_jsonandstats_from_wire_jsonread one table. - Timing
Stamp Ms - The statement’s timing block as one wire value — the wire-side spelling
of the engine’s result-header timing stamp: the ADR-0221 wall-clock
total (
elapsed_ms) together with its always-on PARSE / PLAN / EXECUTE split (ADR-0491) and the fine sub-split plus the plan-cache outcome (LABS-1120), flattened to the envelope keys’ own milliseconds. Bundled like the engine bundles its stamp, so an envelope construction site cannot carry the total without its split — and the canonical builder stays underclippy::too_many_arguments. - Wire
Stats Snapshot - A plain, model-owned carrier of the 11 counters — a
WireStatsvalue that does not require the engine crate (used by the golden fixtures and by any surface that already has counts in hand).
Enums§
- Column
Type Kind - The ADR-0224 per-column type classification: the closed 18-kind set the
engine stamps result columns with, one kind per first-row value. This
enum is the single source of the canonical name spellings — both value
taxonomies (the wire-side
CypherValuehere, the engine’s coreValueinrelate-core’sconvertmodule) classify into it, so a renamed or extended kind fails to compile at every mapping site instead of drifting into a second hand-maintained table. - Kernel
Rung Wire - The traversal rung a PROFILE node reports (LABS-1117), typed from the
wire vocabulary: the chain carries its hop count, so a chain without
one — the half-state the parser rejects — is unrepresentable.
Self::as_stris the vocabulary’s one spelling;plan_keys::KERNEL_RUNGSis derived from it. - Notification
Category - The category spellings (ADR-0363 decision 1): the categories in scope.
- Notification
Kind - The notification kinds (ADR-0363 decision 1) — the row identities of the one vocabulary below, generated from its single table.
- Notification
Severity - The severity spellings (ADR-0363 decision 1): Neo4j’s two severities.
- Plan
Warning - One typed warning a plan node carries (ADR-0344, typed node warnings): the vocabulary’s one definition — the wire name it serializes by, the message text that renders beside the affected operator and in the warnings footer, the payload variant that names the property index, and the notification kind it projects to (ADR-0363 decision 1) — each owned here once, beside the notification vocabulary it projects into, so the engine’s detection, the wire parse, and every surface’s rendering cannot drift (LABS-461: one warning type, not three coordinated layers).
Constants§
- CYPHER_
VERSION - The Cypher language version the plan’s
versionarg reports (ADR-0357): this engine’s front-end is openCypher 5-compatible (ADR-0046), so the Neo4j-shapedversionarg says5— the language version, not a product version. - NEO4J_
PLANNER_ IMPL - The
planner-implvalue every surface sends (ADR-0357): this engine’s own planner, named honestly — never Neo4j’sIDP/COST, which would claim a planner this engine does not run. - PLAN_
SCHEMA - The schema identifier every projected document carries.
- PLAN_
UNAVAILABLE - The one spelling of a plan column’s unavailable value, shared by every presentation of the plan table (the engine renderer and the surfaces’ table layout) so “column not produced” renders identically everywhere.
- STAT_
COUNTERS - The mutation counters of an envelope’s
statsobject, in canonical order. - WIRE_
KIND_ NODE - The
kinddiscriminator of a wire node object (ADR-0223). Decoder sides match on these constants instead of re-typing the literals. - WIRE_
KIND_ RELATIONSHIP - The
kinddiscriminator of a wire relationship object (ADR-0223).
Traits§
- Wire
Stats - The 11 canonical mutation counters, read as
u64.
Functions§
- column_
type_ kind - Classify a first-row value into its canonical ADR-0224 kind.
- column_
type_ name - One canonical ADR-0224 per-column type name for a first-row value — the
name spelling of
column_type_kind, for callers that want the string directly. The engine stamps each result column with one of the 18 canonical names at result construction, from the first row only — Cypher columns are heterogeneous, and the name makes no claim about later rows. This mapping is the wire-side spelling of the engine’sQueryResult::column_typesstamp. - crs_
name - The Neo4j CRS name for an SRID (used as the
crspoint marker) — the canonical mapping every surface shares (ADR-0280 wire shape). - error_
envelope - Build the canonical error response envelope: empty
columns/rows, emptystats, and the error message string undererror. - estimation_
miss - The one estimated-vs-actual overshoot policy (ADR-0344 metric
fields + typed node warnings): the estimate misses when it
overshoots the actual rows by 10x or more and the operator
produced rows (an estimate over zero actual rows has no ratio).
Both the ratio cell’s warning marker and the
EstimationMisswarning derive from this one policy, never a second computation. - json_
f64 - Encode an
f64as wire JSON: a JSON number when finite, otherwise the JSON string of itsCypherValueDisplayspelling ("NaN"/"Inf"/"-Inf", ADR-0280). - metric_
i64 - The wire form’s one width policy for metric integers: saturate at
i64::MAX— one policy for every metric field (rows and time alike), never an unchecked cast on one and a clamp on the other. - metric_
u64 - The consumer side of the metric width policy: a wire metric is
non-negative when present (the producer saturates), so the
one conversion every metric cell reads goes through here — never a
bare
ascast at a call site. - notification_
to_ neo4j_ entries - One notification’s Neo4j-shaped entries (ADR-0363 decisions 11/12), in
Bolt’s entry order:
code,title,description,severity,category. The effective remedy is folded intodescriptionas(remedy: <remedy>); noremedyand nopositionentry is ever emitted. This is the ordered form Bolt packs directly, without building or re-reading a JSON object;notification_to_neo4j_jsonis the JSON projection of the same entries. - notification_
to_ neo4j_ json - One notification’s Neo4j-shaped wire object (ADR-0363 decisions 11/12):
exactly
code,title,description,severity,category, with the remedy folded intodescriptionas(remedy: <remedy>)and noremedyorpositionkey. Built fromnotification_to_neo4j_entries. - notification_
to_ wire_ json - One notification’s engine-native wire object (ADR-0363 decision 9):
code,gql_status,severity,category,title,description,remedyand — on operator-scoped kinds —operator_id. - notifications_
to_ wire_ json - A notification list in the engine-native form — the array the shared success envelope always carries (empty on a plain run).
- plan_
document - Project a plan wire tree (the engine’s
PlanNode::to_value()form) into the agent-native document, as aserde_json::Value— the surface serializes it, exactly as it does the sibling wire documents (stats_to_wire_json,notifications_to_wire_json). - plan_
node_ wire - Read one plan wire node (ADR-0344/0345). Panics on a malformed node — the wire form is engine-produced and invariant-bound, so a deviation is an engine contract break, kept loud like every other boundary here.
- plan_
subtree_ totals - The one subtree-total pass (cumulative vs self): every node’s own elapsed time plus every descendant’s, saturated through the metric width policy — ONE walk over the tree, keyed by the node’s pre-order id, so the table’s walk and the agent document’s walk read the same map instead of each re-folding its subtree (one policy, one spelling). Reads the typed accessor (the same validation every other consumer takes), so a malformed tree fails loudly here rather than silently summing partial subtrees.
- profiled_
facts - A metrics-carrying node’s presentation bundle, read from the totals map — the ONE spelling of the pairing’s contract (“the map covers every walked node”), so the table’s walk and the agent document’s walk cannot each re-state the lookup, and a third consumer inherits it instead of cloning the panic.
- ratio_
defined - Whether the estimated-vs-actual ratio is defined (ADR-0344 metric
fields): the operator produced rows. The one predicate both the
ratio cell and the overshoot policy read — never a second
actual > 0spelling at either site. - response_
envelope - Build the canonical success response envelope (ADR-0491): the one
construction every JSON surface renders — the pre-0491 envelope plus
the statement’s per-phase timing split beside
elapsed_ms. - row_
to_ wire_ json - Encode one result row (an ordered column→value map) as a JSON object.
- rows_
for_ result - Build the canonical wire
rowsarray for a query result. - stats_
from_ wire_ json - Decode an envelope’s
statsobject into the 11 canonical counters — the inverse ofstats_to_wire_json, reading the sameSTAT_COUNTERStable the encoder writes. - stats_
to_ wire_ json - Encode the 11 canonical mutation counters as a JSON object: snake_case keys, zeros included. See the module docs for the canonical name set.
- time_
ns_ ms - The one nanoseconds-to-milliseconds conversion, as a float: every
millisecond presentation reads it — the table cell’s
{:.3}render, the HTTP v2 node’stimefield, the agent document’stime_msandtotal_time_ms— so the spellings cannot drift (and none truncates a sub-millisecond operator to 0). - value_
to_ wire_ json - Encode a
CypherValueas its canonical wire JSON. - warning_
wire_ json - The wire shape of one typed warning:
{name, index?}, built from the onePlanWarningvocabulary — the spelling the plan-wire warning projections read (the HTTP v2 plan), never a re-assembled{name, index}at each site. The agent-native document does not read it: per ADR-0381 its nodewarningsderive from the result’s remedy-bearing notifications.