UNION

Generic Description

Combine multiple query branches into one result set.

Simple example:

MATCH (a) RETURN a UNION MATCH (b) RETURN b

Consumer-Level Explanation

Use UNION when the query must combine multiple query branches into one result set 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

UNION is useful when several logically different graph patterns should contribute to one output shape. In practice it is common in search-like queries, heterogeneous feeds, or combined procedural result sets.

What this clause is really for:

• it defines one concrete stage in the Cypher row pipeline, so variables available before and after UNION 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 UNION inside a complete query pipeline so the clause boundary, visible variables, and returned row shape are clear to planner tooling.

PROFILE 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, d, cosine_similarity(vector(properties(d).embedding), vector([0.22, 0.18, 0.44])) AS score
RETURN u.user_id, d.title, score
ORDER BY score DESC
LIMIT 10

Real Use Cases

• combining multiple discovery strategies
• mixed feed construction from several entity classes
• merging semantic and symbolic result branches

Real Limitations And Tradeoffs

• all branches must align in output shape
• UNION DISTINCT removes duplicates, which may or may not be desirable
• complex UNION trees can be harder to optimize and reason about