Merge
The MERGE clause tries to match the query pattern in the database or, if not present, create the pattern in the database. MERGE <pattern> can be interpreted as If MATCH <pattern> then RETURN <pattern> ELSE CREATE <pattern>. Note that there is no notion of partially matching the pattern and creating the remaining parts. That is, either the whole pattern is matched or the whole pattern is created.
Similar to INSERT ON CONFLICT in SQL, the MERGE clause comes with ON CREATE and ON MATCH set operations, allowing you to specify additional update logic if the pattern is found or not found.
We will use the example database for demonstration, whose schema and data import commands are given here.
Merge Nodes
Merge existing nodes
The following query tries to merge a user with the name “Adam”. Since “Adam” exists in the database, no user is created.
MERGE (n:User {name : 'Adam'}) RETURN n.*;┌────────┬───────┐│ n.name │ n.age ││ STRING │ INT64 │├────────┼───────┤│ Adam │ 30 │└────────┴───────┘MATCH (:User) RETURN COUNT(*);┌──────────────┐│ COUNT_STAR() ││ INT64 │├──────────────┤│ 4 │└──────────────┘Merge non-existing nodes
The following query tries to merge a user with the name “Bob”. Since “Bob” does not exist in the database, a new user with the name “Bob” is created.
MERGE (n:User {name : 'Bob', age: 45}) RETURN n.*;┌────────┬───────┐│ n.name │ n.age ││ STRING │ INT64 │├────────┼───────┤│ Bob │ │└────────┴───────┘MATCH (:User) RETURN COUNT(*);┌──────────────┐│ COUNT_STAR() ││ INT64 │├──────────────┤│ 5 │└──────────────┘Merge with ON MATCH
ON MATCH specifies the SET operation once a match is found. The following query updates age property if pattern is matched.
MERGE (n:User {name : 'Adam'}) ON MATCH SET n.age = 35 RETURN n.*;┌────────┬───────┐│ n.name │ n.age ││ STRING │ INT64 │├────────┼───────┤│ Adam │ 35 │└────────┴───────┘Merge with ON CREATE
ON CREATE specifies the SET operation if no match is found. The following query updates age property if pattern is not matched.
MERGE (n:User {name : 'Bob'}) ON CREATE SET n.age = 60 RETURN n.*;┌────────┬───────┐│ n.name │ n.age ││ STRING │ INT64 │├────────┼───────┤│ Bob │ 60 │└────────┴───────┘Merge relationships
Merge existing relationships
The following query tries to merge a follows edge since 2020 between “Adam” and “Zhang”. A match is found in this case.
MATCH (a:User), (b:User)WHERE a.name = 'Adam' AND b.name = 'Zhang'MERGE (a)-[e:Follows {since:2020}]->(b) RETURN e;┌───────────────────────────────────────────────────────┐│ e ││ REL │├───────────────────────────────────────────────────────┤│ (0:0)-{_LABEL: Follows, _ID: 2:1, since: 2020}->(0:2) │└───────────────────────────────────────────────────────┘MATCH (a:User)-[e:Follows]->(b:User)WHERE a.name = 'Adam' AND b.name = 'Zhang'RETURN e;┌───────────────────────────────────────────────────────┐│ e ││ REL │├───────────────────────────────────────────────────────┤│ (0:0)-{_LABEL: Follows, _ID: 2:1, since: 2020}->(0:2) │└───────────────────────────────────────────────────────┘Merge non-existing relationships
The following query tries to merge a follows edge since 2022 between “Adam” and “Zhang”. No match is found and an edge is created.
MATCH (a:User), (b:User)WHERE a.name = 'Adam' AND b.name = 'Zhang'MERGE (a)-[e:Follows {since:2022}]->(b) RETURN e;┌───────────────────────────────────────────────────────┐│ e │├───────────────────────────────────────────────────────┤│ (0:0)-{_LABEL: Follows, _ID: 0:4, since: 2022}->(0:2) │└───────────────────────────────────────────────────────┘MATCH (a:User)-[e:Follows]->(b:User)WHERE a.name = 'Adam' AND b.name = 'Zhang'RETURN e;┌───────────────────────────────────────────────────────┐│ e │├───────────────────────────────────────────────────────┤│ (0:0)-{_LABEL: Follows, _ID: 2:1, since: 2020}->(0:2) ││ (0:0)-{_LABEL: Follows, _ID: 2:4, since: 2022}->(0:2) │└───────────────────────────────────────────────────────┘Merge with ON MATCH
Similar to merge nodes, the following query updates edge since property if the pattern is found.
MATCH (a:User), (b:User)WHERE a.name = 'Adam' AND b.name = 'Karissa'MERGE (a)-[e:Follows {since:2020}]->(b)ON MATCH SET e.since = 2021RETURN e;┌───────────────────────────────────────────────────────┐│ e │├───────────────────────────────────────────────────────┤│ (0:0)-{_LABEL: Follows, _ID: 2:0, since: 2021}->(0:1) │└───────────────────────────────────────────────────────┘Merge with ON CREATE
Similar to merge nodes, the following query updates edge since property if the pattern is not found.
MATCH (a:User), (b:User)WHERE a.name = 'Adam' AND b.name = 'Karissa'MERGE (a)-[e:Follows {since:2022}]->(b)ON CREATE SET e.since = 1999RETURN e;┌───────────────────────────────────────────────────────┐│ e │├───────────────────────────────────────────────────────┤│ (0:0)-{_LABEL: Follows, _ID: 0:5, since: 1999}->(0:1) │└───────────────────────────────────────────────────────┘Merge complex patterns
Previous examples have shown how to merge single node and relationship patterns. It is also possible to merge complex patterns involving multiple nodes and relationships.
MERGE (:User {name:'A'})-[:Follows]->(:User {name:'B'})-[:LivesIn]->(:City {name:'Toronto'});MATCH (a:User)-[:Follows]->(b:User)-[:LivesIn]->(c:City)RETURN a.name, b.name, c.name;┌─────────┬─────────┬───────────┐│ a.name │ b.name │ c.name │├─────────┼─────────┼───────────┤│ Adam │ Karissa │ Waterloo ││ Karissa │ Zhang │ Kitchener ││ Adam │ Zhang │ Kitchener ││ Zhang │ Noura │ Guelph ││ A │ B │ Toronto │└─────────┴─────────┴───────────┘