Skip to content


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:


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:


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:


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:


Patterns for tags


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:


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


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, and the tag or edge type to which a property belongs must be specified.

For example, a vertex with two properties will be like:

(a:player{name: "Tim Duncan", age: 42})

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

(a)-[e:follow{degree: 95}]->(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:


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:


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


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:


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


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:


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:


The range of lengths can also be specified. Such edge patterns are called variable-length edges. For example:


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.

You may specify either the upper limit or lower limit of the length range, or neither of them, for example:

(a)-[*..5]->(b)   // The minimum length is 1 and the maximum length is 5.
(a)-[*3..]->(b)   // The minimum length is 3 and the maximum length is infinity.
(a)-[*]->(b)      // The minimum length is 1 and the maximum length is infinity.

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: December 5, 2023