Cypher Clauses

This section describes AnzoGraph compatibility with Cypher command clauses based on the Cypher Query Language Reference:

• MATCH (Partially Supported)
• OPTIONAL MATCH (Partially Supported)
• MANDATORY MATCH (Not Supported)
• RETURN (Supported)
• WITH (Supported)
• UNWIND (Partially Supported)
• WHERE (Partially Supported)
• ORDER BY (Partially Supported)
• SKIP (Partially Supported)
• LIMIT (Partially Supported)
• CREATE (Partially Supported)
• DELETE (Supported)
• SET (Partially Supported)
• REMOVE (Supported)
• MERGE (Not supported)
• CALL[…YIELD] (Not Supported)
• UNION and UNION ALL (Supported)
• State Visibility and Behavior between Clauses (Partially Supported)

MATCH (Partially Supported)

The Cypher MATCH clause allows you to specify the patterns that Cypher will search for in data. The MATCH clause is often used with a WHERE clause that adds restrictions or predicates to the MATCH pattern. In that case, the predicates are part of the pattern description, and should not be considered just a filter applied only after the matching is done.

The MATCH clause can be included at the beginning of a query or later, for example, as part of a WITH clause. If it is the first clause in a statement, no data will have been bound yet to the result, and Cypher will search to find the results matching the pattern in the MATCH clause and any associated predicates specified in any WHERE clause. This could involve a scan of the database, a search for nodes of a certain label, or a search of an index to find starting points for the pattern matching. Nodes and relationships found by this search are available as bound pattern elements, and can be used for pattern matching of sub-graphs. They can also be used in any further MATCH clauses, where Cypher will use the known elements, and find further unknown elements from there. Predicates in a WHERE clause can be evaluated before pattern matching, during pattern matching, or after finding matches.

Finding All Nodes (Supported)

By specifying a MATCH pattern with just a single node and no labels, all nodes in the graph will be returned. For example:

MATCH (n)
RETURN n

This example returns all nodes in the database.

Finding All Nodes with a Label (Supported)

To return all nodes with a label, you can specify a single node pattern where the node has a label

on it. For example:

MATCH (movie:Movie)
RETURN movie.title

This example returns all the movies in the database.

Finding Related Nodes (Supported)

You can use the notation ( -[ ]- ) to find related nodes, without regard to the type or direction of their relationship. For example:

MATCH (director {name: 'Oliver Stone'})-[]-(movie)
RETURN movie.title

This example returns all the movies directed by 'Oliver Stone'.

Finding Matches with Labels (Supported)

To specify a pattern to return only nodes with labels, you can add the label syntax to your node match pattern. For example:

MATCH (:Person {name: 'Oliver Stone'})-[]-(movie:Movie)
RETURN movie.title

This example returns only those nodes connected with the Person 'Oliver' that are labeled Movie.

Finding Matches Based on the Direction of Relationships (Supported)

When you want to specify the direction of a relationship in a pattern match, you can use the directional notation, (->) or (<-). For example:

MATCH (:Person {name: 'Oliver Stone'})-[]->(movie)
RETURN movie.title

This example returns any nodes connected with the Person 'Oliver' by an outgoing relationship.

Directed Relationships and Variables (Supported)

Cypher allows you to use variables in MATCH queries, either for filtering on properties of a relationship, or to return the relationship. For example:

MATCH (:Person {name: 'Oliver Stone'})-[r]->(movie)
RETURN type(r)

This example returns the type of each outgoing relationship from 'Oliver'.

Specifying Matches Based on Relationship Type (Supported)

You can specify matches based on the relationship type by entering a colon followed by the relationship type. For example:

MATCH (wallstreet:Movie {title: 'Wall Street'})<-[:ACTED_IN]-(actor)
RETURN actor.name

This example returns all actors that ACTED_IN 'Wall Street'.

Specifying Matches Based on Multiple Relationship Types (Supported)

To specify a match based on multiple relationship types, you can combine the different relationship types with the pipe ( | ) symbol. For example:

MATCH (wallstreet {title: 'Wall Street'})<-[:ACTED_IN|:DIRECTED]-(person)
RETURN person.name

This example returns nodes with an ACTED_IN or DIRECTED relationship to 'Wall Street'.

Specifying Matches on the Relationship Types Using Variables (Supported)

Cypher also allows you to used a variable in pattern matches based on the relationship type and then return the relationship in the variable. For example:

MATCH (wallstreet {title: 'Wall Street'})<-[r:ACTED_IN]-(actor)
RETURN r.role

This example returns the ACTED_IN roles for the movie 'Wall Street'.

Specifying Matches for Relationship Types That Contain Non-letter Characters (Supported)

If your database contains relationship types that include non-letter characters or spaces, you can use the single back quote ( ` ) character to escape the type. For example, to demonstrate this, you could add an additional relationship between 'Charlie Sheen' and 'Rob Reiner':

MATCH (charlie:Person {name: 'Charlie Sheen'}),
  (rob:Person {name: 'Rob Reiner'})
CREATE (rob)-[:`TYPE WITH SPACE`]->(charlie)

This example returns a relationship type with a space in it:

type(r)
"TYPE WITH SPACE"

1 row

Finding Matches with Multiple Relationships (Supported)

To find matches for multiple relationships, you can specify the relationship match pattern using the form:

 (- [ ] -) 

You could then string them together in a single MATCH statement. For example:

MATCH (charlie {name: 'Charlie Sheen'})-[:ACTED_IN]->(movie)<-[:DIRECTED]-(director)
RETURN movie.title, director.name

This example returns the movie that 'Charlie Sheen' acted in and also returns its director's name.

Variable-length relationships (Partially Supported)

Based on the Cypher Language specification, nodes that are a variable number of relationship -> node hops away can be found using the following syntax:

-[:TYPE*minHops..maxHops]→. 

In this case, minHops and maxHops are optional and default to 1 and infinity respectively. When no bounds are given, the dots may be omitted. The dots may also be omitted when setting only one bound and this implies a fixed-length pattern.

Using Relationship Variable in Variable-length Relationships (Supported)

When the connection between two nodes is of variable length, the list of relationships comprising

the connection can be returned using the following syntax:

MATCH p = (actor {name: 'Charlie Sheen'})-[:ACTED_IN*2]-(co_actor)
RETURN relationships(p)

This example returns a list of relationships.

Match with Properties on a Variable-length Path (Supported)

A variable-length relationship with properties defined on in it means that all relationships in the

path must have the property set to the given value.

Zero-length Paths (Supported)

Using variable-length paths that have the lower bound set to zero means that two variables can point to

the same node. If the path length between two nodes is zero, they are, by definition, the same node.

Note that when matching zero-length paths, the result may contain a match even when matching on

a relationship type that is not in use. For example:

MATCH (wallstreet:Movie {title: 'Wall Street'})-[*0..1]-(x)
RETURN x

This example returns the movie itself as well as actors and directors one relationship away.

Named Paths (Supported)

If you want to return or specify a filter on a path in your pattern graph, you can introduce a named path. For example:

MATCH p = (michael {name: 'Michael Douglas'})-[]->()
RETURN p

This example returns the two paths starting from 'Michael Douglas'.

Matching on a Bound Relationship (Supported)

When a pattern contains a bound relationship, and that relationship pattern does not specify direction, Cypher will attempt to match the relationship in both directions. For example:

MATCH (a)-[r]-(b)
WHERE id(r)= 0
RETURN a,b

This example returns the two connected nodes, the start node, and the end node.

Finding the Single Shortest Path (Not Supported)

You can use the shortestPath() function to find a single shortest path between two nodes. For example:

MATCH (martin:Person {name: 'Martin Sheen'}), (oliver:Person {name: 'Oliver Stone'}),
p = shortestPath((martin)-[*..15]-(oliver))
RETURN p

Finding All Shortest Paths (Not Supported)

You can use the allShortestPaths() function to find all the shortest paths between two nodes. For example:

MATCH (martin:Person {name: 'Martin Sheen'}), (michael:Person {name: 'Michael
Douglas'}), p = allShortestPaths((martin)-[*]-(michael))
RETURN p

Finding Nodes by ID (Supported)

You can use the id() function in a predicate to search for nodes. For example

MATCH (n)
WHERE id(n)= 0
RETURN n

This example returns the corresponding node.

Finding a Relationship by ID (Not Supported)

Based on the Cypher language specification, you can use the id() function in a predicate to search for relationships. For example:

MATCH ()-[r]->()
WHERE id(r)= 0
RETURN r

Finding Multiple Nodes by ID (Supported)

You can use the id() function with the IN clause in a predicate to find multiple nodes by ID. For example:

MATCH (n)
WHERE id(n) IN [0, 3, 5]
RETURN n

This example returns the nodes listed in the IN expression.

OPTIONAL MATCH (Partially Supported)

This clause is used to specify the patterns to search for, while using nulls for missing parts of the pattern.

Optional Relationships (Supported)

If a relationship is optional, you can use the OPTIONAL MATCH clause to find relationships, similar to how an outer join works in SQL. Cypher returns the relationship if it is found; otherwise a null is returned.

MATCH (a:Movie {title: 'Wall Street'})
OPTIONAL MATCH (a)-[]->(x)
RETURN x

This example returns null, since the node has no outgoing relationships.

Returning Null for Null Properties on Optional Elements (Supported)

Returning a property from an optional element that is null will also return null. For example:

MATCH (a:Movie {title: 'Wall Street'})
OPTIONAL MATCH (a)-[]->(x)
RETURN x, x.name

This example will return the x element (null in this query), and null as its name.

Optional Typed and Named Relationships (Not Supported)

Just as with a normal relationship, you can decide which variable a relationship goes into, and what relationship type you want to return. For example:

MATCH (a:Movie {title: 'Wall Street'}) 
OPTIONAL MATCH (a)-[r:ACTS_IN]->()
RETURN a.title, r

This example returns the title of the node, that is, 'Wall Street'. If the node has no outgoing ACTS_IN relationships, null is returned for the relationship denoted by r.

MANDATORY MATCH (Not Supported)

The Cypher MANDATORY MATCH clause lets you specify the patterns to search for.

RETURN (Supported)

The RETURN clause specifies what to include in a query result set. Based on the Cypher language specification, any expression, literals, predicates, properties, and functions, can be used as a return item. For example

MATCH (a {name: 'A'})

RETURN a.age > 30, "I'm a literal", (a)-[]->()

WITH (Supported)

The WITH clause allows queries to be chained together, piping the results from one query to be used as the starting point or search criteria for the next query.

UNWIND (Partially Supported)

The UNWIND clause expands a list into a sequence of records.

UNWIND [1, 2, 3] AS xRETURN x

WHERE (Partially Supported)

The WHERE clause adds constraints to the patterns in a MATCH or OPTIONAL MATCH clause or used to filter the results of a WITH clause.

Filter on Dynamically-computed Node Property (Not Supported)

Based on the Cypher language specification, you can use square bracket syntax to filter on a property using a dynamically-computed name. For example:

WITH 'AGE' AS propname 
MATCH (n)
WHERE n[toLower(propname)]< 30 
RETURN n.name, n.age

Checking for the Existence of a Property (Not Supported)

Based on the Cypher language specification, you can use the exists() function to only include in results the nodes or relationships in which a property exists.. For example:

MATCH (n)
WHERE exists(n.belt) 
RETURN n.name, n.belt

Filter on Patterns with Properties (Not Supported)

Based on the Cypher language specification, you can add properties to filter patterns. For example:

MATCH (n)
WHERE (n)-[:KNOWS]-({name: 'Tobias'})
RETURN n.name, n.age

ORDER BY (Partially Supported)

An ORDER BY clause following RETURN or WITH specifies that the output should be sorted in either ascending (the default) or descending order.

Ordering Null (Not Supported)

Based on the Cypher language specification, when sorting the result set, null values will always be placed at the end of the result set with ascending sorting, and first in the result when doing descending sort.

Query
MATCH (n)
RETURN n.length, n.name, n.age ORDER BY n.length

SKIP (Partially Supported)

The SKIP clause specifies the record to start including in output records.

Using an Expression with SKIP to Return a Subset of the Rows (Not Supported)

Based on the Cypher language specification, SKIP accepts any expression that evaluates to a positive integer, as long as it is not referring to any external variables. For example:

MATCH (n)
RETURN n.name ORDER BY n.name
SKIP toInteger(3*rand())+ 1

LIMIT (Partially Supported)

The LIMIT clause specifies the maximum number of records to include in output results.

Using an Expression with LIMIT to Return a Subset of the Rows (Partially Supported)

Based on the Cypher language specification, LIMIT accepts any expression that evaluates to a positive integer, as long as it is not referring to any external variables:

MATCH (n)
RETURN n.name 
ORDER BY n.name
LIMIT toInteger(3 * rand())+ 1

CREATE (Partially Supported)

The CREATE clause is used to create nodes and relationships.

Return Created Node (Not Supported)

Based on the Cypher language specification, you can use RETURN to return the name and details about newly created nodes. For example:

CREATE (a {name: 'Andres'}) 
RETURN a

Create Node with a Parameter for the Properties (Not Supported)

Based on the Cypher language specification, you can also create a graph entity from a map.

All the key-value pairs in the map will be set as properties on the created relationship or node.

Create Multiple Nodes with a Parameter for Their Properties (Not Supported)

Based on the Cypher language specification, if you provide Cypher with an array of maps, it will create a node for each map.

DELETE (Supported)

The DELETE clause lets you specify nodes, relationships or paths to delete. Any node to be deleted must also have all associated relationships explicitly deleted.

The DETACH DELETE clause lets you delete a node or set of nodes. All associated relationships will automatically be deleted.

SET (Partially Supported)

The SET clause can be used to update labels on nodes and properties on nodes and relationships.

Copying Properties between Nodes and Relationships (Not Supported)

Based on the Cypher language specification, you can also use SET to copy all properties from one graph element to another. Doing this also removese all other properties on the receiving graph element.

Set a Property Using a Parameter (Not Supported)

Based on the Cypher language specification, you can use a parameter to specify the value of a property.

Set All Properties Using a Parameter (Not Supported)

Based on the Cypher language specification, you can replace all existing properties on a node with a new set of properties provided by the parameter.

REMOVE (Supported)

The REMOVE clause lets you remove properties and labels from nodes and relationships.

MERGE (Not supported)

The MERGE clause ensures that a pattern exists in the graph. Either the pattern already exists, or if it does not already exist, it will be created.

CALL[…YIELD] (Not Supported)

The CALL [...YIELD] clause let you invoke a procedure and return any results.

UNION and UNION ALL (Supported)

The UNION and UNION ALL clauses are used to combine the result of multiple queries into a single result set. UNION combines the results of two or more queries into a single result set that includes all the records that belong to all queries in the union. The number and the names of the fields must be identical in all queries combined by using UNION.

When using the UNION clause, it will combine and remove duplicates from the result set. To keep all the result records, you can use UNION ALL.

Combining Two Queries and Removing Duplicates (Supported)

By using the UNION clause without the ALL keyword, duplicates are removed from the combined result set. For example:

MATCH (n:Actor)
RETURN n.name AS name
UNION
MATCH (n:Movie)
RETURN n.title AS name

The combined result is returned, without duplicates.

Combining Two Queries and Retaining Duplicates (Supported)

You can combine the results from two queries, and keep duplicate records in the result, by using UNION ALL. For example:

MATCH (n:Actor)
RETURN n.name AS name
UNION ALL MATCH (n:Movie)
RETURN n.title AS name

The combined result is returned, including duplicates.

State Visibility and Behavior between Clauses (Partially Supported)

Based on the Cypher Language specification, Cypher allows clauses that read data from a graph to be interleaved with clauses that write to the graph. Some Cypher clauses can both read from a graph and write to it at the same time. Explicit state change visibility makes it possible to understand queries without having to worry about ordering of updates and reads.

Related Topics

• Working with Cypher and the Movies Graph
• Cypher Language Overview
• Cypher Patterns
• Cypher Types, Lists, and Maps
• Comparability, Equality, Orderability, and Equivalence
• Cypher Expressions, Variables, and Parameters
• Cypher Operators
• Cypher Functions