12.7. Create Unique

The CREATE UNIQUE clause is a mix of MATCH and CREATE — it will match what it can, and create what is missing.

Introduction

[Tip]Tip

MERGE might be what you want to use instead of CREATE UNIQUE. Note however, that MERGE doesn’t give as strong guarantees for relationships being unique.

CREATE UNIQUE is in the middle of MATCH and CREATE — it will match what it can, and create what is missing. CREATE UNIQUE will always make the least change possible to the graph — if it can use parts of the existing graph, it will.

Another difference to MATCH is that CREATE UNIQUE assumes the pattern to be unique. If multiple matching subgraphs are found an error will be generated.

[Tip]Tip

In the CREATE UNIQUE clause, patterns are used a lot. Read Section 9.6, “Patterns” for an introduction.

The examples start out with the following data set:

cypher-createunique-graph.svg

Create unique nodes

Create node if missing

If the pattern described needs a node, and it can’t be matched, a new node will be created.

Query  

MATCH (root { name: 'root' })
CREATE UNIQUE (root)-[:LOVES]-(someone)
RETURN someone

The root node doesn’t have any LOVES relationships, and so a node is created, and also a relationship to that node.

Result

someone
1 row
Nodes created: 1
Relationships created: 1

Node[4]{}

Try this query live create (_0 {`name`:"A"}) create (_1 {`name`:"B"}) create (_2 {`name`:"C"}) create (_3 {`name`:"root"}) create (_0)-[:`KNOWS`]->(_2) create (_3)-[:`X`]->(_2) create (_3)-[:`X`]->(_1) create (_3)-[:`X`]->(_0) ; match (root {name: 'root'}) create unique (root)-[:LOVES]-(someone) return someone

Create nodes with values

The pattern described can also contain values on the node. These are given using the following syntax: prop : <expression>.

Query  

MATCH (root { name: 'root' })
CREATE UNIQUE (root)-[:X]-(leaf { name:'D' })
RETURN leaf

No node connected with the root node has the name D, and so a new node is created to match the pattern.

Result

leaf
1 row
Nodes created: 1
Relationships created: 1
Properties set: 1

Node[4]{name:"D"}

Try this query live create (_0 {`name`:"A"}) create (_1 {`name`:"B"}) create (_2 {`name`:"C"}) create (_3 {`name`:"root"}) create (_0)-[:`KNOWS`]->(_2) create (_3)-[:`X`]->(_2) create (_3)-[:`X`]->(_1) create (_3)-[:`X`]->(_0) ; match (root {name: 'root'}) create unique (root)-[:X]-(leaf {name:'D'} ) return leaf

Create labeled node if missing

If the pattern described needs a labeled node and there is none with the given labels, Cypher will create a new one.

Query  

MATCH (a { name: 'A' })
CREATE UNIQUE (a)-[:KNOWS]-(c:blue)
RETURN c

The A node is connected in a KNOWS relationship to the c node, but since C doesn’t have the :blue label, a new node labeled as :blue is created along with a KNOWS relationship from A to it.

Result

c
1 row
Nodes created: 1
Relationships created: 1
Labels added: 1

Node[4]{}

Try this query live create (_0 {`name`:"A"}) create (_1 {`name`:"B"}) create (_2 {`name`:"C"}) create (_3 {`name`:"root"}) create (_0)-[:`KNOWS`]->(_2) create (_3)-[:`X`]->(_2) create (_3)-[:`X`]->(_1) create (_3)-[:`X`]->(_0) ; match (a {name: 'A'}) create unique (a)-[:KNOWS]-(c:blue) return c

Create unique relationships

Create relationship if it is missing

CREATE UNIQUE is used to describe the pattern that should be found or created.

Query  

MATCH (lft { name: 'A' }),(rgt)
WHERE rgt.name IN ['B', 'C']
CREATE UNIQUE (lft)-[r:KNOWS]->(rgt)
RETURN r

The left node is matched agains the two right nodes. One relationship already exists and can be matched, and the other relationship is created before it is returned.

Result

r
2 rows
Relationships created: 1

:KNOWS[4]{}

:KNOWS[3]{}

Try this query live create (_0 {`name`:"A"}) create (_1 {`name`:"B"}) create (_2 {`name`:"C"}) create (_3 {`name`:"root"}) create (_0)-[:`KNOWS`]->(_2) create (_3)-[:`X`]->(_2) create (_3)-[:`X`]->(_1) create (_3)-[:`X`]->(_0) ; match (lft {name: 'A'}), (rgt) where rgt.name in ['B','C'] create unique (lft)-[r:KNOWS]->(rgt) return r

Create relationship with values

Relationships to be created can also be matched on values.

Query  

MATCH (root { name: 'root' })
CREATE UNIQUE (root)-[r:X { since:'forever' }]-()
RETURN r

In this example, we want the relationship to have a value, and since no such relationship can be found, a new node and relationship are created. Note that since we are not interested in the created node, we don’t name it.

Result

r
1 row
Nodes created: 1
Relationships created: 1
Properties set: 1

:X[4]{since:"forever"}

Try this query live create (_0 {`name`:"A"}) create (_1 {`name`:"B"}) create (_2 {`name`:"C"}) create (_3 {`name`:"root"}) create (_0)-[:`KNOWS`]->(_2) create (_3)-[:`X`]->(_2) create (_3)-[:`X`]->(_1) create (_3)-[:`X`]->(_0) ; match (root {name: 'root'}) create unique (root)-[r:X {since:'forever'}]-() return r

Describe complex pattern

The pattern described by CREATE UNIQUE can be separated by commas, just like in MATCH and CREATE.

Query  

MATCH (root { name: 'root' })
CREATE UNIQUE (root)-[:FOO]->(x),(root)-[:BAR]->(x)
RETURN x

This example pattern uses two paths, separated by a comma.

Result

x
1 row
Nodes created: 1
Relationships created: 2

Node[4]{}

Try this query live create (_0 {`name`:"A"}) create (_1 {`name`:"B"}) create (_2 {`name`:"C"}) create (_3 {`name`:"root"}) create (_0)-[:`KNOWS`]->(_2) create (_3)-[:`X`]->(_2) create (_3)-[:`X`]->(_1) create (_3)-[:`X`]->(_0) ; match (root {name: 'root'}) create unique (root)-[:FOO]->(x), (root)-[:BAR]->(x) return x