Prev |  | Next

## 16.4. Match

In the match part of a query, the pattern is described. The description of the pattern is made up of one or more paths, separated by commas.

All parts of the pattern must be directly or indirectly bound to a start point.

Graph

### 16.4.1. Related nodes

The symbol `--` means related to, without regard to type or direction.

Query

    START n=node(3)
    MATCH (n)--(x)
    RETURN x

All nodes related to A are returned

Result

x
3 rows, 1 ms
`Node[4]{name->"Bossman"}`
`Node[1]{name->"David"}`
`Node[5]{name->"Cesar"}`

### 16.4.2. Outgoing relationships

When the direction of a relationship is interesting, it is shown by using `-->` or `<--`, like this:

Query

    START n=node(3)
    MATCH (n)-->(x)
    RETURN x

All nodes that A has outgoing relationships to.

Result

x
2 rows, 1 ms
`Node[4]{name->"Bossman"}`
`Node[5]{name->"Cesar"}`

### 16.4.3. Directed relationships and identifier

If an identifier is needed, either for filtering on properties of the relationship, or to return the relationship, this is how you introduce the identifier.

Query

    START n=node(3)
    MATCH (n)-[r]->()
    RETURN r

All outgoing relationships from node A.

Result

r
2 rows, 0 ms
`:KNOWS[0] {}`
`:BLOCKS[1] {}`

### 16.4.4. Match by relationship type

When you know the relationship type you want to match on, you can specify it by using a colon.

Query

    START n=node(3)
    MATCH (n)-[:BLOCKS]->(x)
    RETURN x

All nodes that are BLOCKed by A.

Result

x
1 rows, 0 ms
`Node[5]{name->"Cesar"}`

### 16.4.5. Match by relationship type and use an identifier

If you both want to introduce an identifier to hold the relationship, and specify the relationship type you want, just add them both, like this.

Query

    START n=node(3)
    MATCH (n)-[r:BLOCKS]->()
    RETURN r

All `BLOCKS` relationship going out from A.

Result

r
1 rows, 0 ms
`:BLOCKS[1] {}`

### 16.4.6. Relationship types with uncommon characters

Sometime your database will have types with non-letter characters, or with spaces in them. Use ` to escape these.

Query

    START n=node(3)
    MATCH (n)-[r:`TYPE WITH SPACE IN IT`]->()
    RETURN r

This returns a relationship of a type with spaces in it.

Result

r
1 rows, 0 ms
`:TYPE WITH SPACE IN IT[6] {}`

### 16.4.7. Multiple relationships

Relationships can be expressed by using multiple statements in the form of `()--()`, or they can be strung together, like this:

Query

    START a=node(3)
    MATCH (a)-[:KNOWS]->(b)-[:KNOWS]->(c)
    RETURN a,b,c

The three nodes in the path.

Result

a | b | c
--- | --- | ---
1 rows, 1 ms
`Node[3]{name->"Anders"}` | `Node[4]{name->"Bossman"}` | `Node[2]{name->"Emil"}`

### 16.4.8. Variable length relationships

Nodes that are variable number of relationship→node hops can be found using `-[:TYPE*minHops..maxHops]->`.

Query

    START a=node(3), x=node(2, 4)
    MATCH a-[:KNOWS*1..3]->x
    RETURN a,x

Returns the start and end point, if there is a path between 1 and 3 relationships away

Result

a | x
--- | ---
2 rows, 1 ms
`Node[3]{name->"Anders"}` | `Node[2]{name->"Emil"}`
`Node[3]{name->"Anders"}` | `Node[4]{name->"Bossman"}`

### 16.4.9. Zero length paths

When using variable length paths that have the lower bound zero, it means that two identifiers can point to the same node. If the distance between two nodes is zero, they are, by definition, the same node.

Query

    START a=node(3)
    MATCH p1=a-[:KNOWS*0..1]->b, p2=b-[:BLOCKS*0..1]->c
    RETURN a,b,c, length(p1), length(p2)

This query will return four paths, some of them with length zero.

Result

a | b | c | LENGTH(p1) | LENGTH(p2)
--- | --- | --- | --- | ---
4 rows, 3 ms
`Node[3]{name->"Anders"}` | `Node[3]{name->"Anders"}` | `Node[3]{name->"Anders"}` | `0` | `0`
`Node[3]{name->"Anders"}` | `Node[3]{name->"Anders"}` | `Node[5]{name->"Cesar"}` | `0` | `1`
`Node[3]{name->"Anders"}` | `Node[4]{name->"Bossman"}` | `Node[4]{name->"Bossman"}` | `1` | `0`
`Node[3]{name->"Anders"}` | `Node[4]{name->"Bossman"}` | `Node[1]{name->"David"}` | `1` | `1`

### 16.4.10. Optional relationship

If a relationship is optional, it can be marked with a question mark. This similar to how a SQL outer join works, if the relationship is there, it is returned. If it’s not, `null` is returned in it’s place. Remember that anything hanging of an optional relation, is in turn optional, unless it is connected with a bound node some other path.

Query

    START a=node(2)
    MATCH a-[?]->x
    RETURN a,x

A node, and `null`, since the node has no relationships.

Result

a | x
--- | ---
1 rows, 0 ms
`Node[2]{name->"Emil"}` | `<null>`

### 16.4.11. Optional typed and named relationship

Just as with a normal relationship, you can decide which identifier it goes into, and what relationship type you need.

Query

    START a=node(3)
    MATCH a-[r?:LOVES]->()
    RETURN a,r

A node, and `null`, since the node has no relationships.

Result

a | r
--- | ---
1 rows, 0 ms
`Node[3]{name->"Anders"}` | `<null>`

### 16.4.12. Properties on optional elements

Returning a property from an optional element that is `null` will also return `null`.

Query

    START a=node(2)
    MATCH a-[?]->x
    RETURN x, x.name

The element x (null in this query), and null as it’s name.

Result

x | x.name
--- | ---
1 rows, 0 ms
`<null>` | `<null>`

### 16.4.13. Complex matching

Using Cypher, you can also express more complex patterns to match on, like a diamond shape pattern.

Query

    START a=node(3)
    MATCH (a)-[:KNOWS]->(b)-[:KNOWS]->(c), (a)-[:BLOCKS]-(d)-[:KNOWS]-(c)
    RETURN a,b,c,d

The four nodes in the path.

Result

a | b | c | d
--- | --- | --- | ---
1 rows, 2 ms
`Node[3]{name->"Anders"}` | `Node[4]{name->"Bossman"}` | `Node[2]{name->"Emil"}` | `Node[5]{name->"Cesar"}`

### 16.4.14. Shortest path

Finding the shortest path between two nodes is as easy as using the shortestPath-function, like this.

Query

    START d=node(1), e=node(2)
    MATCH p = shortestPath( d-[*..15]->e )
    RETURN p

This means: find the shortest path between two nodes, as long as the path is max 15 relationships long. Inside of the parenthesis you write a single link of a path - the starting node, the connecting relationship and the end node. Characteristics describing the relationship like relationship type, max hops and direction are all used when finding the shortest path.

Result

p
1 rows, 0 ms
`(1)--[KNOWS,2]-->(3)--[KNOWS,0]-->(4)--[KNOWS,3]-->(2)`

### 16.4.15. Named path

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

Query

    START a=node(3)
    MATCH p = a-->b
    RETURN p

The two paths starting from the first node.

Result

p
2 rows, 0 ms
`(3)--[KNOWS,0]-->(4)`
`(3)--[BLOCKS,1]-->(5)`

### 16.4.16. Matching on a bound relationship

When your pattern contains a bound relationship, and that relationship pattern doesn specify direction, Cypher will try to match the relationship where the connected nodes switch sides.

Query

    START r=rel(0)
    MATCH a-[r]-b
    RETURN a,b

This returns the two connected nodes, once as the start node, and once as the end node

Result

a | b
--- | ---
2 rows, 1 ms
`Node[3]{name->"Anders"}` | `Node[4]{name->"Bossman"}`
`Node[4]{name->"Bossman"}` | `Node[3]{name->"Anders"}`

Copyright © 2011 Neo Technology

Prev | Up | Next
| Home |