Add docs explaining MERGE + relationship uniqueness constraints (#507)

re-opening of #460

---------

Author: pontusmelke

modules/ROOT/pages/clauses/merge.adoc

@@ -415,12 +415,12 @@ This is in contrast to the example shown above in xref::clauses/merge.adoc#merge
 
 
 [[query-merge-using-unique-constraints]]
-== Using property uniqueness constraints with `MERGE`
+== Using node property uniqueness constraints with `MERGE`
 
 Cypher prevents getting conflicting results from `MERGE` when using patterns that involve property uniqueness constraints.
 In this case, there must be at most one node that matches that pattern.
 
-For example, given two property uniqueness constraints on `:Person(id)` and `:Person(ssn)`, a query such as `MERGE (n:Person {id: 12, ssn: 437})` will fail, if there are two different nodes (one with `id` 12 and one with `ssn` 437), or if there is only one node with only one of the properties.
+For example, given two property node uniqueness constraints on `:Person(id)` and `:Person(ssn)`, a query such as `MERGE (n:Person {id: 12, ssn: 437})` will fail, if there are two different nodes (one with `id` 12 and one with `ssn` 437), or if there is only one node with only one of the properties.
 In other words, there must be exactly one node that matches the pattern, or no matching nodes.
 
 Note that the following examples assume the existence of property uniqueness constraints that have been created using:
@@ -433,9 +433,9 @@ CREATE CONSTRAINT FOR (n:Person) REQUIRE n.role IS UNIQUE;
 
 
 [[merge-merge-using-unique-constraints-creates-a-new-node-if-no-node-is-found]]
-=== Merge using property uniqueness constraints creates a new node if no node is found
+=== Merge node using property uniqueness constraints creates a new node if no node is found
 
-Given the property uniqueness constraint on the `name` property for all `Person` nodes, the below query will create a new `Person` with the `name` property `'Laurence Fishburne'`.
+Given the node property uniqueness constraint on the `name` property for all `Person` nodes, the below query will create a new `Person` with the `name` property `'Laurence Fishburne'`.
 If a `'Laurence Fishburne'` node had already existed, `MERGE` would match the existing node instead.
 
 .Query
@@ -454,7 +454,7 @@ RETURN laurence.name
 
 
 [[merge-merge-using-unique-constraints-matches-an-existing-node]]
-=== Merge using property uniqueness constraints matches an existing node
+=== Merge using node property uniqueness constraints matches an existing node
 
 Given property uniqueness constraint on the `name` property for all `Person` nodes, the below query will match the pre-existing `Person` node with the `name` property `'Oliver Stone'`.
 
@@ -526,6 +526,37 @@ While there is a matching unique `Person` node with the name `'Oliver Stone'`, t
 Node already exists with label `Person` and property `name` = 'Oliver Stone'
 ----
 
+[[query-merge-using-relationship-unique-constraints]]
+== Using relationship property uniqueness constraints with `MERGE`
+
+All that has been said above about node uniqueness constraints also applies to relationship uniqueness constraints.
+However, for relationship uniqueness constraints there are some additional things to consider.
+
+For example, if there exists a relationship uniqueness constraint on `()-[:ACTED_IN(year)]-()`, then the following query,  in which not all nodes of the pattern are bound, would fail:
+
+.Query	
+[source, cypher, role=test-fail]
+----
+MERGE (charlie:Person {name: 'Charlie Sheen'})-[r:ACTED_IN {year: 1987}]->(wallStreet:Movie {title: 'Wall Street'})
+RETURN charlie.name, type(r), wallStreet.title
+----
+	
+This is due to the all-or-nothing semantics of `MERGE`, which causes the query to fail if there exists a relationship with the given `year` property but there is no match for the full pattern.
+In this example, since no match was found for the pattern, `MERGE` will try to create the full pattern including a relationship with `{year: 1987}`, which will lead to constraint violation error.
+
+Therefore, it is advised - especially when relationship uniqueness constraints exist - to always use bound nodes in the `MERGE` pattern.
+The following would, therefore, be a more appropriate composition of the query:
+
+.Query
+[source, cypher]
+----
+MATCH
+  (charlie:Person {name: 'Charlie Sheen'}),
+  (wallStreet:Movie {title: 'Wall Street'})
+MERGE (charlie)-[r:ACTED_IN {year: 1987}]->(wallStreet)
+RETURN charlie.name, type(r), wallStreet.title
+----
+
 [[merge-using-map-parameters-with-merge]]
 === Using map parameters with `MERGE`