MERGE

Generic Description

Match existing structure or create it if missing.

Simple example:

MERGE (p:Person {email: 'alix@example.com'})
RETURN p.email AS email

Consumer-Level Explanation

Use MERGE when the query must match existing structure or create it if missing 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

MERGE is the upsert-like clause most people reach for first, but it has graph semantics rather than SQL UPSERT semantics. It tries to match the described pattern, and if no match exists it creates it. That makes it very useful for identity anchors and canonical relationship creation.

What this clause is really for:

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

UNWIND [{user_id: 'u-1', doc_id: 'd-1', ts: '2025-01-02T10:00:00Z', payload: {kind: 'view'}, doc_metadata: {kind: 'report'}, embedding: [0.22, 0.18, 0.44]}] AS evt
MERGE (u:User {user_id: evt.user_id})
MERGE (d:Document {doc_id: evt.doc_id})
CREATE (u)-[e:VIEWED]->(d)
SET e.ts = toDateTime(evt.ts),
    e.payload = evt.payload,
    d.metadata = evt.doc_metadata,
    d.embedding = vector(evt.embedding)
WITH u, d, e, date_trunc('day', e.ts) AS day_bucket
RETURN u.user_id, d.doc_id, day_bucket, keys(properties(d)) AS doc_keys

Real Use Cases

• identity-safe entity creation around business keys
• idempotent relationship creation
• incremental sync pipelines

Real Limitations And Tradeoffs

• pattern shape matters; over-broad MERGE patterns can create unexpected structures
• MERGE is not magic deduplication for bad data models
• you still need clear stable properties for identity