Reading the Cypher

You flagged Cypher as a gap, and forty lessons have quoted it at you. Here's the good news: the entire codebase's Cypher is built from about six recurring idioms. Learn to recognize them and you can read any hot-path query cold — and spot when one breaks a hard rule. This is a skills lesson: every query below is real, and you've already met most of them in context. Now we read them as Cypher.

Idiom 1 · Always anchored, always graph_id-scoped

Every single query starts by pinning a node by id and graph_id — never a bare MATCH (n). The read surface's point lookup (rules/node_lookup.go):

MATCH (n:Entity {id: $id, graph_id: $graph}) RETURN n.node_risk_score, n.symbol, …

Idiom 2 · Read many by id — UNWIND a list

To read N nodes in one round-trip, UNWIND a parameter list into rows and match each (the batched form of idiom 1, from the same file):

UNWIND $ids AS nid
MATCH (n:Entity {id: nid, graph_id: $graph}) RETURN …

UNWIND turns a list into rows — the inverse of collect(). You saw the write side of this everywhere (L41's coalescing produces exactly UNWIND $rows AS row <template>); here it's the read side. One idiom, both directions.

Idiom 3 · Bounded, both-directions traversal

The graph's signature query — the partial-graph spine walk that loads a focus token's neighborhood (L23/L38, risk/graph_partial.go):

MATCH (root:Entity {id: $root, graph_id: $graph})
OPTIONAL MATCH (root)-[r:<spine edge types>*1..6]-(n:Entity {graph_id: $graph})

Three things to read here, each a hard rule made concrete:

Idiom 4 · Aggregate with collect()

L32's conservation read gathers every holder balance into one list (risk/verify_balance_conservation.go):

MATCH (t:Entity {graph_id: $graph, id: $token})-[r:HOLDS]->(:Entity)
RETURN collect(r.quantity_raw) AS qtys

Here the arrow is directed (->): HOLDS has a known direction (token→holder), so reading it one way is correct. collect() folds the matched rows into a single list returned in one row — the read-side inverse of UNWIND. The target node is (:Entity) with no variable because we only need the edge property, not the holder.

Idiom 5 · Idempotent writes — MERGE, never CREATE; and the anti-join

Every write is idempotent because delivery is at-least-once (L7/L9). Two flavours. The batched SET (L38's node_risk_score):

UNWIND $updates AS u
MATCH (n:Entity {id: u.id, graph_id: $graph})
SET n.node_risk_score = u.nrs, n.governance_risk = u.gov

And the anti-join idempotent edge create (L27's oracle bridger) — create the edge only if it's missing:

MATCH (token)-[:LENDING_COLLATERAL]->(market), (token)-[:ORACLE_DEP]->(oracle)
WHERE NOT EXISTS { MATCH (market)-[:ORACLE_DEP]->(oracle) }
MERGE (market)-[:ORACLE_DEP]->(oracle)

Idiom 6 · Read a node's kind with coalesce (no APOC)

Memgraph has no APOC, and a node's kind can live under any of three properties, so the codebase reads it through a coalesce fallback chain (seen in chainref / rules scope):

WHERE coalesce(dep.type, dep.subcategory, dep.category) IN ['pool', 'vault', …]

coalesce(a, b, c) returns the first non-null — so "the node's kind" is "whichever of type / subcategory / category is set first." You'll also see the write-side don't-clobber idiom SET r.subcategory = coalesce(r.subcategory, $new) — "set it only if it isn't already set."

What you can now do

• Recognize the six idioms — anchored scope, UNWIND-by-id, bounded both-directions traversal, collect, MERGE/anti-join, coalesce-kind — in any query.
• Read a variable-length path (*1..6, undirected) and say what it traverses and how far.
• Explain UNWIND ↔ collect as the row/list inverses, on both read and write sides.
• Tell MERGE from CREATE from MATCH and explain the idempotency and no-stub reasons for each choice.
• Audit a hot-path query against CLAUDE.md's hard rules (graph_id, no full scan, bounded paths, both directions, coalesce-kind, MERGE).