Read Graph Patterns with MATCH and Understand Variable Binding Across Nodes and Relationships

Learning outcomes

AtlasMart needs a read API that answers “which products did a customer buy?” without treating Cypher as SQL with arrows pasted into the FROM clause. The key mental model is a stream of rows: MATCH finds graph patterns and binds variables in each successful match; later clauses transform or project those bindings.

1. MATCH binds variables to successful graph patterns

In MATCH (c:Customer)-[r:PLACED]->(o:Order), c, r, and o are variables. Each row is one binding combination that satisfies the whole pattern. If Ava placed two orders, the same customer node can appear in two rows because the relationship/order bindings differ. The row count therefore follows matching paths, not the number of distinct starting nodes.

2. Build a deterministic fixture and count bindings

CYPHER 25CREATE CONSTRAINT customer_id IF NOT EXISTS FOR (c:Customer) REQUIRE c.customerId IS UNIQUE;CREATE CONSTRAINT product_id IF NOT EXISTS FOR (p:Product) REQUIRE p.productId IS UNIQUE;CREATE CONSTRAINT order_id IF NOT EXISTS FOR (o:Order) REQUIRE o.orderId IS UNIQUE;CREATE CONSTRAINT category_id IF NOT EXISTS FOR (c:Category) REQUIRE c.categoryId IS UNIQUE;MERGE (c1:Customer {customerId:'C-1001'}) SET c1.name='Ava Chen', c1.tier='gold', c1.region='eu'MERGE (c2:Customer {customerId:'C-1002'}) SET c2.name='Noah Smith', c2.tier='silver', c2.region='us'MERGE (c3:Customer {customerId:'C-1003'}) SET c3.name='Mina Rahimi', c3.tier='gold', c3.region='me'MERGE (c4:Customer {customerId:'C-1004'}) SET c4.name='Leo Martin', c4.region='eu'MERGE (cat1:Category {categoryId:'CAT-CAMERAS'}) SET cat1.name='Cameras'MERGE (cat2:Category {categoryId:'CAT-AUDIO'}) SET cat2.name='Audio'MERGE (p1:Product {productId:'P-1001'}) SET p1.name='Trail Camera', p1.price=129.90, p1.rating=4.7MERGE (p2:Product {productId:'P-1002'}) SET p2.name='Studio Headphones', p2.price=89.00, p2.rating=4.7MERGE (p3:Product {productId:'P-1003'}) SET p3.name='Action Camera', p3.price=219.00, p3.rating=4.5MERGE (p4:Product {productId:'P-1004'}) SET p4.name='USB Microphone', p4.price=75.00MERGE (p1)-[:IN_CATEGORY]->(cat1)MERGE (p3)-[:IN_CATEGORY]->(cat1)MERGE (p2)-[:IN_CATEGORY]->(cat2)MERGE (p4)-[:IN_CATEGORY]->(cat2)MERGE (o1:Order {orderId:'O-2001'}) SET o1.placedAt=datetime('2026-08-01T09:00:00Z'), o1.status='paid', o1.total=218.90MERGE (o2:Order {orderId:'O-2002'}) SET o2.placedAt=datetime('2026-08-02T10:30:00Z'), o2.status='paid', o2.total=219.00MERGE (o3:Order {orderId:'O-2003'}) SET o3.placedAt=datetime('2026-08-03T12:00:00Z'), o3.status='shipped', o3.total=129.90MERGE (o4:Order {orderId:'O-2004'}) SET o4.placedAt=datetime('2026-08-04T14:15:00Z'), o4.status='paid', o4.total=164.00MERGE (o5:Order {orderId:'O-2005'}) SET o5.placedAt=datetime('2026-08-04T14:15:00Z'), o5.status='paid', o5.total=75.00MERGE (c1)-[:PLACED]->(o1)MERGE (c2)-[:PLACED]->(o2)MERGE (c1)-[:PLACED]->(o3)MERGE (c3)-[:PLACED]->(o4)MERGE (c4)-[:PLACED]->(o5)MERGE (o1)-[:CONTAINS {quantity:1}]->(p1)MERGE (o1)-[:CONTAINS {quantity:1}]->(p2)MERGE (o2)-[:CONTAINS {quantity:1}]->(p3)MERGE (o3)-[:CONTAINS {quantity:1}]->(p1)MERGE (o4)-[:CONTAINS {quantity:1}]->(p2)MERGE (o4)-[:CONTAINS {quantity:1}]->(p4)MERGE (o5)-[:CONTAINS {quantity:1}]->(p4);

CYPHER 25MATCH (c:Customer {customerId:$customerId})-[r:PLACED]->(o:Order)RETURN c.customerId AS customerId,       type(r) AS relationshipType,       o.orderId AS orderIdORDER BY o.orderId;

With $customerId='C-1001', the fixture should yield exactly two rows: O-2001 and O-2003. That proves two matching PLACED relationships exist for Ava; it does not mean the Customer node was duplicated.

CYPHER 25MATCH (c:Customer {customerId:$customerId})-[:PLACED]->(o:Order)-[:CONTAINS]->(p:Product)RETURN c.customerId, o.orderId, p.productIdORDER BY o.orderId, p.productId;

For Ava, the first order has two CONTAINS relationships and the second has one, so the pattern yields three rows. Thinking in rows makes later DISTINCT, aggregation, pagination and accidental fan-out understandable.

3. EXPLAIN proves planned operators, not returned data

CYPHER 25 EXPLAINMATCH (c:Customer {customerId:$customerId})-[:PLACED]->(o:Order)RETURN o.orderIdORDER BY o.orderId;

EXPLAIN asks Neo4j to plan without executing. Operator names and estimated rows are release/runtime dependent, so the lesson uses them as evidence of access-path and expansion shape rather than as constants to memorize. Later Chapter 10 will use PROFILE, which does execute and collects actual runtime counters.

4. Wrong approach: assume matching a customer returns one row

A developer writes a query that starts from one customer and returns c.name after expanding orders/products, then is surprised that “Ava Chen” repeats. The repetition is not a duplicate Customer record; it is one value projected from multiple binding rows. Fix the requirement, not the symptom: if the API wants unique customers, project DISTINCT c; if it wants orders or products, keep the expanded rows or aggregate intentionally.

CYPHER 25MATCH (c:Customer)-[:PLACED]->(:Order)-[:CONTAINS]->(:Product)RETURN c.customerId AS customerIdORDER BY customerId;CYPHER 25MATCH (c:Customer)-[:PLACED]->(:Order)-[:CONTAINS]->(:Product)RETURN DISTINCT c.customerId AS customerIdORDER BY customerId;

The second query removes duplicate projected rows; it does not delete, merge, or otherwise alter graph entities.

Lab: build the first read-query contract

:param {customerId: 'C-1001'};CYPHER 25MATCH (c:Customer {customerId:$customerId})-[:PLACED]->(o:Order)-[line:CONTAINS]->(p:Product)RETURN o.orderId, o.placedAt, p.productId, p.name, line.quantityORDER BY o.placedAt, o.orderId, p.productId;

Verification checklist: the parameter is bound separately from query text; the row count is three for C-1001; every row has one order/product binding; order direction is Customer→Order; the sort uses explicit stable keys; and changing the parameter to an unknown customer returns zero rows rather than an error.

Production judgment

Row cardinality is both a correctness surface and a cost surface. A query that accidentally expands from Customer→Order→Product before applying the intended business restriction may return correct-looking final columns while doing far more work than expected. Treat each pattern hop as a possible multiplier, keep domain direction explicit, and make API result cardinality part of tests. Next, we place predicates correctly and make null/parameter semantics observable.

Summary and next step

Read Graph Patterns with MATCH and Understand Variable Binding Across Nodes and Relationships is useful only when its assumptions and observed evidence stay attached to the decision. The examples above establish a reproducible mechanism and boundary; they do not turn one lab result into a universal production rule.

Next, continue to Filter with WHERE, Predicates, Labels, Types, Property Access, Null Semantics, and Parameters. Carry forward the verified assumptions, fixture state, version/edition boundaries, and measurements from this lesson instead of treating the next topic as an isolated recipe.

Authoritative references

• Current Neo4j versions — Official current-release and 5.26 LTS patch snapshot.
• Cypher Manual introduction — Current Cypher 25 baseline and Cypher 5 compatibility framing.
• MATCH — Pattern matching and variable-binding semantics.
• Variables — Variable naming and scope across query parts.
• WHERE — Pattern constraints and post-WITH filtering semantics.
• Predicates — Boolean/comparison/string/list/type predicates and three-valued results.
• Working with null — Null propagation and missing-property semantics.
• RETURN — Projection, aliases, expressions and DISTINCT semantics.
• List expressions and pattern comprehension — Current fixed/variable pattern-comprehension syntax and behavior.
• ORDER BY — Only ORDER BY guarantees result ordering; sort semantics and index-backed ordering.
• SKIP / OFFSET — Offset semantics and OFFSET synonym.
• LIMIT — Row limiting semantics and the absence of ordering guarantees without ORDER BY.
• Cypher Shell — Bolt CLI, parameter support, script/file execution and output modes.
• Query tuning and plans — EXPLAIN/PROFILE and execution-plan evidence.