Cypher interface¶

The cypher feature gives a Cypher surface over the engine's native graph primitives (label index, VF2 subgraph matching, petgraph BFS) — not DataFusion. Reads run over a snapshot; writes mutate the graph.

Status snapshot: MATCH … WHERE … RETURN … LIMIT reads and writes (CREATE/MERGE/SET/DELETE +DETACH/REMOVE) are supported, along with ORDER BY/SKIP/WITH/OPTIONAL MATCH/UNWIND, the richer WHERE (OR/IN/STARTS WITH/CONTAINS/IS NULL), aggregation, DISTINCT, CALL {subquery} / CALL proc() YIELD, and the gds.* graph-data-science procedures (EG-KG.query.cypher-execution/062/063/141/142/143/144). A Bolt v4.4 wire (EG-KG.query.bolt-wire-protocol) lets Neo4j drivers connect directly. See the capability matrix.

Supported grammar¶

MATCH (a:Agent)-[:SUPERVISES*1..3]->(b:Agent)
WHERE a.region = 'us' AND b.active = true
RETURN a.id, b.id
LIMIT 100

Patterns: linear node (edge node)*. Nodes (var:Label) — both the variable and the label are optional. Edges -[:REL]->, <-[:REL]-, and variable-length -[:REL*m..n]-> (now combinable with surrounding fixed hops + path-variable binding, EG-KG.query.concept-2).
Quantified path patterns (Cypher 25, EG-KG.query.quantified-path-pattern): ((a)-[:REL]->(b)){m,n} repeats a WHOLE inner sub-pattern — not just one relationship — m..n times, e.g. MATCH (x)((a)-[:LIKES]->()-[:KNOWS]->(b)){1,3}(y) RETURN y. A single-hop group is exactly equivalent to -[:REL*m..n]->; the construct generalizes to multi-hop and (recursively) nested inner patterns. Deferred: only the group's overall reachability + the FINAL repetition's end node participate in the surrounding MATCH/WHERE/RETURN — per-iteration variable bindings inside the group are not exposed as Cypher 25's full list values. Not supported in CREATE.
WHERE (EG-KG.query.eg-extend-read-side): AND/OR, var.prop <op> literal with = <> != < <= > >=, plus IN, STARTS WITH, CONTAINS, IS NULL.
RETURN: var, var.prop, *, DISTINCT, comma-separated; aggregation (count/collect/sum/avg/min/max).
Pipeline: WITH, ORDER BY, SKIP, OPTIONAL MATCH, and UNWIND expr AS var (EG-KG.query.param-list-drives-unwind) compose as chained stages.
LIMIT: integer (an implicit cap of 50,000 rows protects the engine).

Writes¶

CREATE (a:Agent {id: 'AgentC', region: 'us'})
MERGE (b:Agent {id: 'AgentD'})
SET a.active = true
DELETE a            // DETACH DELETE to also drop incident edges; edge-var DELETE supported

CREATE/MERGE/SET/DELETE (+DETACH) and REMOVE (property/label removal, EG-KG.query.cypher-execution) map to native eg-core mutations (add_node/add_edge/compare_and_set_fields/remove_node/remove_edge). MERGE is idempotent (create-if-absent via the label index).

Procedures — `CALL` + GDS (EG-KG.query.cypher-planning/143/144)¶

CALL { subquery } and CALL proc(args) YIELD … invoke a procedure registry that dispatches to native (or WASM) procedures — the Neo4j-parity keystone. The registry ships an APOC-equivalent library plus the graph-data-science algorithms (a pure-Rust Neo4j-GDS-parity library in eg-compute, EG-144):

CALL gds.pageRank.stream('social') YIELD nodeId, score
RETURN nodeId, score ORDER BY score DESC LIMIT 10;

Available gds.*: PageRank, weakly/strongly-connected components, Louvain community detection, Label Propagation, betweenness + degree centrality, single-source weighted shortest path (Dijkstra), node similarity (Jaccard/cosine over neighborhoods, all-pairs gds.nodeSimilarity + per-node top-k gds.knn), density clustering (gds.dbscan, feature cypher-mining), and link prediction (gds.linkPrediction, a KAN classifier over structural pair features, feature cypher-graphlearn) — CONCEPT:EG-KG.query.gds-procedure-routing.

Remote drivers — Bolt v4.4 (EG-KG.query.bolt-wire-protocol, feature `bolt-wire`)¶

A native Bolt v4.4 listener (src/server/bolt_wire/, PackStream v2 chunked framing, HELLO/LOGON/RUN/PULL/DISCARD/BEGIN/COMMIT/ROLLBACK) lets Neo4j drivers (neo4j-python/js/go, cypher-shell) connect directly — RUN's Cypher goes straight to this engine, no SQL layer. Set EPISTEMIC_GRAPH_BOLT_ADDR (default 127.0.0.1:7687); see connecting.

Relationship to the other surfaces¶

The Cypher executor shares its edge-matching and snapshot model with the GraphQL resolver — the two produce byte-equal results for equivalent reads. For cross-modal queries that mix graph traversal with vector/text/SQL, use UQL.