Patterns¶

Patterns and graph pattern matching are the very heart of a graph query language.

Patterns for vertices¶

A vertex is described using a pair of parentheses, and is typically given a name. For example:

(a)

This simple pattern describes a single vertex, and names that vertex using the variable a.

Patterns for related vertices¶

A more powerful construct is a pattern that describes multiple vertices and edges between them. Patterns describe edges by employing an arrow between two vertices. For example:

(a)-[]->(b)

This pattern describes a very simple data shape: two vertices, and a single edge from one to the other. In this example, the two vertices are both named as a and b respectively, and the edge is directed: it goes from a to b.

This manner of describing vertices and edges can be extended to cover an arbitrary number of vertices and the edges between them, for example:

(a)-[]->(b)<-[]-(c)

Such a series of connected vertices and edges is called a "path".

Note that the naming of the vertices in these patterns is only necessary should one need to refer to the same vertex again, either later in the pattern or elsewhere in the query. If this is not necessary, then the name may be omitted, as follows:

(a)-[]->()<-[]-(c)

Patterns for tags¶

In addition to simply describing the shape of a vertex in the pattern, one can also describe attributes. The most simple attribute that can be described in the pattern is a tag that the vertex must have. For example:

(a:User)-[]->(b)

One can also describe a vertex that has multiple tags: (a:User:Admin)-[]->(b).

Patterns for properties¶

Nodes and edges are the fundamental structures in a graph. nGQL uses properties on both of these to allow for far richer models.

Properties can be expressed in patterns using a map-construct: curly brackets surrounding a number of key-expression pairs, separated by commas. E.g. a vertex with two properties on it would look like:

(a {name: 'Andres', sport: 'Brazilian Ju-Jitsu'})

An edge with expectations on it is given by:

(a)-[{blocked: false}]->(b)

Patterns for edges¶

The simplest way to describe an edge is by using the arrow between two vertices, as in the previous examples.

Using this syntax, you can describe that the edge should exist and the directionality of it. If you don’t care about the direction of the edge, the arrowhead is omitted, as exemplified by:

(a)-[]-(b)

As with vertices, edges may also be given names. In this case, a pair of square brackets is used to break up the arrow and the variable is placed between. For example:

(a)-[r]->(b)

Much like tags on vertices, edges can have types. To describe an edge with a specific type, use the pattern as follows:

(a)-[r:REL_TYPE]->(b)

An edge can only have one edge type. But if we’d like to describe some data such that the edge could have any one of a set of types, then they can all be listed in the pattern, separating them with the pipe symbol | like this:

(a)-[r:TYPE1|TYPE2]->(b)

As with vertices, the name of the edge can always be omitted, as exemplified by:

(a)-[:REL_TYPE]->(b)

Variable-length pattern¶

Rather than describing a long path using a sequence of many vertex and edge descriptions in a pattern, many edges (and the intermediate vertices) can be described by specifying a length in the edge description of a pattern. For example:

(a)-[*2]->(b)

This describes a graph of three vertices and two edges, all in one path (a path of length 2). This is equivalent to:

(a)-[]->()-[]->(b)

A range of lengths can also be specified: such edge patterns are called 'variable-length edges'. For example:

(a)-[*3..5]->(b)

The preceding example defines a path with a minimum length of 3, and a maximum length of 5. It describes a graph of either 4 vertices and 3 edges, 5 vertices and 4 edges, or 6 vertices and 5 edges, all connected in a single path.

the lower bound can be omitted. For example, to describe paths of length 5 or less, use:

(a)-[*..5]->(b)

(a)-[*3..]->(b)
(a)-[*]->(b)

Assigning to path variables¶

As described above, a series of connected vertices and edges is called a "path". nGQL allows paths to be named using a variable, as exemplified by:

p = (a)-[*3..5]->(b)

You can do this in MATCH.