apoc.merge.relationship

Procedure APOC Core

apoc.merge.relationship(startNode, relType, identProps:{key:value, …}, onCreateProps:{key:value, …}, endNode, onMatchProps:{key:value, …}) - merge relationship with dynamic type, with support for setting properties ON CREATE or ON MATCH

Signature

apoc.merge.relationship(startNode :: NODE?, relationshipType :: STRING?, identProps :: MAP?, props :: MAP?, endNode :: NODE?, onMatchProps = {} :: MAP?) :: (rel :: RELATIONSHIP?)

Input parameters

Name	Type	Default
startNode	NODE?	null
relationshipType	STRING?	null
identProps	MAP?	null
props	MAP?	null
endNode	NODE?	null
onMatchProps	MAP?	{}

Name

Type

Default

startNode

NODE?

null

relationshipType

STRING?

null

identProps

MAP?

null

props

MAP?

null

endNode

NODE?

null

onMatchProps

MAP?

{}

Output parameters

Name	Type
rel	RELATIONSHIP?

Usage Examples

The examples in this section are based on the following graph:

CREATE (p:Person {name: "Tom Hanks"})
CREATE (m:Movie {title:"You've Got Mail"});

This procedure provides a more flexible way of merging relationships than Cypher’s MERGE clause.

The example below shows equivalent ways of merging an ACTED_IN relationship between the Tom Hanks and You’ve Got Mail nodes:

apoc.merge.relationship

MATCH (p:Person {name: "Tom Hanks"})
MATCH (m:Movie {title:"You've Got Mail"})
CALL apoc.merge.relationship(p, "ACTED_IN",
  {roles:['Joe Fox']},
  {created: datetime()},
  m,
  {lastSeen: datetime()}
)
YIELD rel
RETURN rel;

MERGE clause

MATCH (p:Person {name: "Tom Hanks"})
MATCH (m:Movie {title:"You've Got Mail"})
MERGE (p)-[rel:ACTED_IN {roles:['Joe Fox']}]->(m)
ON CREATE SET rel.created = datetime()
ON MATCH SET rel.lastSeen = datetime()
RETURN rel;

If we run these queries a few times, we’ll see output as shown below:

Table 1. Results
rel
[:ACTED_IN {lastSeen: 2020-11-03T11:02:00.261Z, created: 2020-11-03T11:00:56.849Z, roles: ["Joe Fox"]}]

But this procedure is mostly useful for merging relationships that have a dynamic relationship type or dynamic properties. For example, we might want to merge a relationship with a relationship type or properties passed in as parameters.

The following creates relationshipType and properties parameters:

:param relType =>  ("ACTED_IN");
:param properties => ({roles: ["Joe Fox"]});

The following merges a relationship with a relationship type and properties based on the previously defined parameters:

MATCH (p:Person {name: "Tom Hanks"})
MATCH (m:Movie {title:"You've Got Mail"})
CALL apoc.merge.relationship(p, $relType, $properties, {}, m, {})
YIELD rel
RETURN rel;

Table 2. Results
rel
[:ACTED_IN {roles: ["Joe Fox"]}]

More documentation of apoc.merge.relationship