Skip to content

Patterns

Patterns and graph pattern matching are the very heart of a graph query language. This topic will describe the patterns in NebulaGraph, some of which have not yet been implemented.

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.

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

(a)-[]->(b)

This pattern describes a very simple data structure: two vertices and a single edge from one to the other. In this example, the two vertices are 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 when one needs to refer to the same vertex again, either later in the pattern or elsewhere in the query. If not, the name may be omitted as follows:

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

Patterns for tags

Note

The concept of tag in nGQL has a few differences from that of label in openCypher. For example, users must create a tag before using it. And a tag also defines the type of properties.

In addition to simply describing the vertices in the graphs, patterns can also describe the tags of the vertices. For example:

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

Patterns can also describe a vertex that has multiple tags. For example:

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

OpenCypher compatibility

The MATCH statement in nGQL does not support matching multiple tags with (a:User:Admin). If users need to match multiple tags, use filtering conditions, such as WHERE "User" IN tags(n) AND "Admin" IN tags(n).

Patterns for properties

Vertices and edges are the fundamental elements in a graph. In nGQL, properties are added to them for richer models.

In the patterns, the properties can be expressed as follows: some key-value pairs are enclosed in curly brackets and separated by commas. For example, a vertex with two properties will be like:

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

One of the edges that connect to this vertex can be like:

(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.

Users can describe an edge and its direction using the following statement. If users do not care about its direction, the arrowhead can be omitted. For example:

(a)-[]-(b)

Like vertices, edges can also be named. A pair of square brackets will be used to separate the arrow and the variable will be placed between them. For example:

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

Like the tags on vertices, edges can also 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 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)

Like vertices, the name of an edge can be omitted. For example:

(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)

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

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

The 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)

Note

The upper bound must be specified. The following are NOT accepted.

(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 variables. For example:

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

Users can do this in the MATCH statement.


Last update: March 13, 2023