MERGE ensures that a specified Cypher graph pattern exists. It first looks for the complete inline pattern; if no match exists, it creates that pattern. In that sense, it combines the roles of MATCH and CREATE, but it is designed for “find or create” work rather than for filtering an existing result set. MERGE describes its pattern inline and cannot be combined with WHERE. section 3.1.7
A query such as MERGE (a:Person {name:'Alicia'}) can be rerun without creating another identical Person pattern. This makes the statement idempotent: repeated execution produces the same stored result. That behavior is especially useful when importing data that may contain duplicates or when an import must be safely rerun. section 3.1.7 section 3.4
Listing 3.29 Cypher query that uses the MERGE clause to ensure a Person node with a name Alicia exists in the database
MERGE (a:Person {name:'Alicia'})
This minimal pattern ensures that a Person node identified by the supplied name exists. section 3.1.7
MERGE matches the full pattern written in its braces, not merely part of it. If a Person with name Alicia already exists, but no node has both name Alicia and location Chicago, MERGE (t:Person {name:'Alicia', location:'Chicago'}) creates a second Person node. Avoid treating every property as an identity field: merge on a chosen unique identifier, then set other properties separately. section 3.1.7
Listing 3.31 Cypher query that merges a node on its unique identifier property and then adds additional properties to the node
MERGE (t:Person{name:"Amy"})
ON CREATE SET t.location = "Taj Mahal", t.createdAt = datetime()
ON MATCH SET t.updatedAt = datetime()
Merge on the identifying name, then use ON CREATE SET for initial properties and ON MATCH SET to record later matches. section 3.1.7
MERGE is commonly applied in imports in three steps:
- Merge each node by a stable identifier, then use ON CREATE SET to populate properties only when that node is new. section 3.2.5
- MATCH nodes that must already exist, then MERGE the relationship between them to prevent duplicate connections. section 3.2.5
- Batch large CSV work with a Cypher subquery and IN TRANSACTIONS when a single transaction could exhaust memory. section 3.2.5
Importing a social graph safely
For user rows, merge a User by id and set name, username, and registration time only on creation. For follower rows, match the source and target User nodes by id, then merge a FOLLOWS relationship. The same approach supports Tweet nodes and PUBLISH, MENTIONS, RETWEETS, and IN_REPLY_TO relationships while allowing the import to be rerun without duplicating the intended graph patterns. section 3.2.5
Relationships can also be merged after their endpoint nodes are ensured. Separate MERGE clauses can create two Person nodes and then a directed FRIEND relationship. An undirected relationship pattern can likewise ensure that a FRIEND connection exists between two nodes. For data quality and performance, import nodes and relationships separately. section 3.1.7 section 3.4
