OPTIONAL MATCH

Generic Description

Null-preserving graph match for patterns that may be absent.

Simple example:

MATCH (p:Person) OPTIONAL MATCH (p)-[:KNOWS]->(q) RETURN p, q

Consumer-Level Explanation

Use OPTIONAL MATCH when the query must null-preserving graph match for patterns that may be absent and the planner needs to see that operation as part of the Cypher row pipeline. Keep the clause explicit because it controls row grain, variable scope, and what later clauses are allowed to reference.

More Detailed Explanation

OPTIONAL MATCH behaves like a graph-aware outer join. It keeps the left-side row even if the optional pattern does not exist, filling the optional variables with null. This is crucial when you want enrichment without accidentally dropping the primary entity set.

What this clause is really for:

• it defines one concrete stage in the Cypher row pipeline, so variables available before and after OPTIONAL MATCH must be clear
• it should make graph structure, temporal filters, document payload shaping, or procedure output explicit instead of relying on client-side interpretation
• planner tooling depends on this clause boundary to know row grain, variable scope, and whether later expressions are reads, writes, schema operations, or projections

Advanced Example

This example keeps OPTIONAL MATCH inside a complete query pipeline so the clause boundary, visible variables, and returned row shape are clear to planner tooling.

MATCH (u:User)-[e:VIEWED]->(d:Document)
TIME e.ts BETWEEN datetime('2025-01-01T00:00:00Z') AND datetime('2025-02-01T00:00:00Z')
WITH u, e, d,
     date_trunc('day', e.ts) AS day_bucket,
     properties(d) AS doc_map,
     unpivot(properties(d.metadata)) AS metadata_rows,
     cosine_similarity(vector(properties(d).embedding), vector([0.22, 0.18, 0.44])) AS score
RETURN u.user_id, d.title, day_bucket, keys(doc_map) AS doc_keys, metadata_rows, score
ORDER BY score DESC
LIMIT 15

Real Use Cases

• enriching user or document rows with optional metadata relations
• UI result assembly where partial graph context is acceptable
• reporting queries where absence of a relationship is itself meaningful

Real Limitations And Tradeoffs

• null propagation must be handled carefully in later expressions
• stacking many OPTIONAL MATCH clauses can make the query harder to reason about
• it is not a substitute for selective initial MATCH design