Source: https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/patterns/
Documentation version: v5.3.2

# Graph patterns

Graph pattern matching is the process of matching a list of regular expressions, which are specifically defined by the GQL standard, against a property graph to get a set of reduced matches.

A graph pattern is a list of path patterns, which are in turn lists of interleaving node patterns and edge patterns. A path pattern always starts and ends with nodes. The following is an example of a path pattern containing two node patterns (i.e., aliased as `a` and `b`, respectively) connected by an edge pattern (i.e., aliased as `e` and labeled as `KNOWS`). In the node pattern for `a`, a filter condition `WHERE` is declared on the property `id`.

`(a:Person WHERE a.id IN LIST[2, 3, 4, 888])-[e:KNOWS]->(b)`

In GQL, we define the term `path` as `walk` from the graph theory, where a node or edge may appear multiple times in a path. If you need to find a path with distinct nodes and edges, you can declare patterns with filter conditions to rule out duplicate nodes and edges.

For more information, see the following topics:

- [Node patterns](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/patterns/node-patterns/)
- [Edge patterns](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/patterns/edge-patterns/)
- [Path patterns](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/patterns/path-patterns/)

[]()

## Label expressions vs. type specifications

In GQL patterns, there are two common ways to narrow graph elements:

- Label expressions use the `:` or `IS` prefix to filter by label.
- Type specifications use the `@` prefix to filter by node type or edge type.

The key difference is:

- A type is a structural definition in the graph type. It determines the property set, primary keys, and for edges, source and destination constraints.
- A label is a semantic classification of graph elements. The same label can be reused by multiple types.

As a result, type-based queries are usually more precise and are better when you want to target one specific structure. Label-based queries are usually more flexible and are better when you want to filter across multiple types by shared semantics.

### Label expressions

Label expressions support the `|` (or), `&` (and), and `!` (not) operators. For example:

- `(v:Person|Movie)` matches nodes labeled `Person` or `Movie`.
- `(v:Person&Movie)` matches nodes labeled both `Person` and `Movie`.
- `[e:!Act]` matches edges not labeled `Act`.

Note that labels use different syntax in different contexts:

- In a pattern filler, the label expression appears directly after the variable and uses `:` or `IS`, for example `(v:Person)` or `(v IS Person)`.
- In a WHERE clause, label matching uses a labeled predicate. The full form is `v IS LABELED Person`. For example: `MATCH (v)-[e]->() WHERE v IS LABELED Person RETURN v`.

In a `WHERE` clause, you can also use a colon (`:`) as a shorthand for `IS LABELED`, for example `WHERE e:Act`. For more information, see [Labeled predicate](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/predicates/labeled/).

### Type specifications

Type specifications support listing multiple types with `@[Type1, Type2]`. For example:

- `(v@[Actor,Director])` matches nodes of type `Actor` or `Director`.
- `[e@[Watch,Direct]]` matches edges of type `Watch` or `Direct`.

### Difference in result scope

Using the [example dataset](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/overview/example-dataset/) as an example, the node types `Actor`, `Director`, and `User` all use the `Person` label. Therefore:

- `MATCH (v@Actor)` matches only `Actor` nodes.
- `MATCH (v:Person)` matches all nodes labeled `Person`, including `Actor`, `Director`, and `User`.

The same idea applies to edge patterns. If multiple edge types reuse the same label, then:

- `MATCH ()-[e@Click]->()` matches only the `Click` edge type.
- `MATCH ()-[e:Behavior]->()` matches all edges labeled `Behavior`.

### When to use each

- Use `@type_name` when you need precise matching by structural type in the schema.
- Use `:label` or `IS LABELED` when you need cross-type filtering by semantic label.

Both approaches filter in the pattern and enable the optimizer to use indexes. Avoid filtering types in `WHERE` clauses, such as `WHERE type(e) IN [...]`, because this is usually less efficient.

For more information, see [Label expressions](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/expressions/label/), [Node patterns](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/patterns/node-patterns/), and [Edge patterns](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/patterns/edge-patterns/).