Clauses

In a Cypher query, clauses state what needs to happen with the pattern specified after the clause. For an exhaustive list of clauses, we refer to the Neo4j Cypher manual. Here, we will explain what a clause looks like and what the most common clauses do.

In the Cypher queries below, MATCH, RETURN and LIMIT are all clauses. While it is not mandatory to use capital letters, we usually do this for clarity so that it becomes easier to see which parts of the Cypher query are clauses.

MATCH (n) RETURN n LIMIT 25

MATCH
The MATCH clause finds the pattern described after the clause. In the example above, the MATCH clause will find any node n.

RETURN
The RETURN clause returns the pattern described after the clause. In the example above, the RETURN clause will return the previously identified node n.

LIMIT
The LIMIT clause limits the number of returned results. In the example above, the LIMIT clause will ensure that no more than 25 nodes are returned.

CREATE
The CREATE clause creates a node or a relationship. In the following examples, the CREATE clause creates an unnamed node, a node with a label, a node with a label and a name and a relationship. Note that, to create a relationship, the nodes need to be matched first.

CREATE (n) RETURN n
CREATE (n:Experiment) RETURN n
CREATE (n:Experiment {name: "Test"}) RETURN n
MATCH (a:Experiment), (b:Specimen) CREATE (a)-[r:PART_OF]-(b) RETURN r

MERGE
The MERGE clause matches or creates a node or a relationship. If the specified pattern already exists, it is matched, and if it does not exist, it is created. It is possible to specify nodes with labels and/or properties, so nodes are only created if a node with the exact same label and properties does not yet exist.

DELETE
The DELETE clause deletes the node or relationship specified after the clause. Nodes that have relationships, cannot be deleted. To delete a node and all its relationships, use DETACH DELETE. For exammple, the query below deletes all nodes and relationships in a database.

MATCH (n) DETACH DELETE n

WHERE
The WHERE clause extends constraints to the patterns previously described after a MATCH or WITH clause. In the example below, the WHERE clause is used to state that the the node in the MATCH clause should have a specific name. WHERE clauses are particularly helpful when used with operators like AND, OR, NOT and IN. They can also be used to filter on properties using the < and > operators.

MATCH (n) WHERE n.name = ‘g__Escherischia’ RETURN n

WITH
The WITH clause allows queries to be chained together. Often, the WITH clause refers to a pattern matched before the clause and subsets this pattern to be used in the next part of the query. In the example below, the WITH clause is used to select a single node from a query and connect this node to another node. In this case, the clause finds any Taxon node connected to at least two edges and then finds part of its taxonomy.

MATCH (a:Edge)–(x:Taxon)–(b:Edge) WITH x MATCH p=(x)–(:Family)–(:Order)–(:Class)–(:Phylum)–(:Kingdom) RETURN p