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

# Node patterns

A node pattern is a common pattern used to match nodes in a property graph. Each node pattern consists of one node pattern filler enclosed in parentheses (`()`). The node pattern filler specifies details of the nodes to match, including labels and properties.

The supported components of a node pattern filler are listed below in the order of appearance when they are used in declarations:

1. Node variable
2. Label expression
3. Node type specification
4. Node property specification
5. `WHERE` clause

When declaring a node pattern filler containing multiple components, make sure the following conditions are met:

- Up to three components of different types can be used, among which:

  - One can be a node variable.
  - One can be either a label expression or a node type specification.
  - One can be either a node property specification or a `WHERE` clause.

- The order of the components must follow the order of appearance listed above.

The following sections summarize the syntax options for declaring node pattern fillers:

diagramsource

 node_pattern_filler_with_node_variable node_pattern_filler_with_label_expression node_pattern_filler_with_node_type_specification node_pattern_filler_with_node_property_specification node_pattern_filler_with_WHERE_clause  

````
node_pattern_filler_with_node_variable ::=
    node_variable 

node_pattern_filler_with_label_expression ::= 
    ( ':' | 'IS' ) label_expression

node_pattern_filler_with_node_type_specification ::=
    '@' ( node_type_name | '[' node_type_name ( ',' node_type_name ) * ']' )

node_pattern_filler_with_node_property_specification ::=
    '{' ( property_name ':' value_expression ) ( ',' ( property_name ':' value_expression ) ) * '}' 

node_pattern_filler_with_WHERE_clause ::=
    'WHERE' search_condition    

````

Note

The parentheses (`()`) are part of node pattern declarations and used to enclose node pattern fillers. They are retained in the following syntax examples for clarity.

## Node pattern filler with a node variable

````
'(' node_variable ')'

````

- `node_variable`: A node variable.

A node pattern filler can be simply declared with a node variable, which is a variable in the form of a regular identifier. For example, `(v)` is a simple node pattern that would match any nodes from a graph. All matched nodes would be identified by this identifier `v` in the rest of the GQL query.

Example:

````
'''
USE movie
MATCH (v) RETURN v LIMIT 3
'''

````

## Node pattern filler with a label expression

````
'(' ( ':' | 'IS' ) label_expression ')'

````

- `label_expression`: A label expression.

A label expression could be used to declare a node pattern filler matching nodes with or without specific labels. To do so, the label expression could be declared with a colon (`:`) prefix or the keyword `IS`. For example, `(:Person)` is a node pattern that matches nodes with the label `Person`. Label expressions could be used to declare node patterns independently without extra node variables, in cases when the underlying node pattern is only needed for matching nodes whose values would not be referenced after the matching.

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

Note

In `MATCH` statements, when a node pattern uses a label name, the label can be specified either as a literal label name or as a string variable. For example, see [MATCH statement](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dql/match/). 

Examples:

- Match nodes with a single label:

````
'''
USE movie
MATCH (v:Person) RETURN v.name AS name LIMIT 3
'''

````

- Match nodes with the label `Person` or `Movie` using the disjunction operator (`|`):

````
'''
USE movie
MATCH (v:Person|Movie) RETURN v.name AS name LIMIT 3
'''

````

- Match nodes that are labeled both `Person` and `Movie` using the conjunction operator (`&`):

````
'''
USE movie
MATCH (v:Person&Movie) RETURN v.name AS name LIMIT 3
'''

````

- Exclude a label using the negation operator (`!`):

````
'''
USE movie
MATCH (v:Person&!Movie) RETURN v.name AS name LIMIT 3
'''

````

## Node pattern filler with a node type specification

````
'(' '@' ( node_type_name | '[' node_type_name ( ',' node_type_name ) * ']' ) ')'

````

- `node_type_name`: The name of a node type.

Node pattern fillers could be declared with one or multiple node type specifications. The node type specification is a node type name prefixed with the `@` symbol. For example, `(@User)` is a node pattern that matches nodes of the node type `User`. You can also specify multiple node type specifications. For example, `(@[User, Actor])` is a node pattern that matches nodes of the node types `User` or `Actor`.

Note

In `MATCH` statements, when a node pattern specifies a node type, the node type can also be provided by a string variable. For example, see [MATCH statement](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dql/match/).

Examples:

- Match nodes by a single node type:

````
'''
USE movie
MATCH (v@Actor) RETURN v.name AS name LIMIT 3
'''

````

- Match nodes by multiple node types:

````
'''
USE movie
MATCH (v@[Actor,Director]) RETURN v.name AS name LIMIT 3
'''

````

### Node type queries vs. label queries

For the general rules behind `@node_type_name` and `:label` / `IS LABELED`, see [Graph patterns](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/patterns/#label-expressions-vs-type-specifications).

In node patterns, the most common practical difference is:

- `MATCH (v@Actor)` matches one specific node type.
- `MATCH (v:Person)` can match nodes across multiple node types that share the same label.

When the label appears inside a node pattern, it uses node-pattern syntax, such as `(v:Person)` or `(v IS Person)`. When the label appears in a `WHERE` clause, it uses labeled-predicate syntax, such as `WHERE v IS LABELED Person`.

If you want to narrow the result by node type first and then further check the label, you can also combine them, for example:

````
'''
USE movie
MATCH (v@Actor)
WHERE v IS LABELED Person
RETURN v.name AS name
LIMIT 3
'''

````

In this dataset, the `WHERE` condition is redundant, but it can still be useful when you want to make the intent explicit: first restrict by type, then verify the label.

## Node pattern filler with a node property specification

````
'(' '{' ( property_name ':' value_expression ) ( ',' ( property_name ':' value_expression ) ) * '}' ')'

````

- `property_name`: The property name.
- `value_expression`: A value expression.

Node pattern fillers could be declared by specifying properties. Each property is essentially a pair of a property name and a value expression, separated by a colon (`:`). Properties, separated by commas, could be accepted in braces as a list. For example, `({id:1,name:"Bob"})` declares a node pattern to match nodes with an `id` property that equals 1 and a `name` property that equals `Bob`. And, `(v{id:1})` equals `(v WHERE v.id = 1)`.

Example:

````
'''
USE movie
MATCH (v {id:1}) RETURN v.name AS name, type(v)
'''

````

## Node pattern filler with a WHERE clause

````
'(' 'WHERE' search_condition ')'

````

- `search_condition`: The search condition.

Node patterns could be declared with a `WHERE` clause containing a search condition. For example, `(WHERE true)` and `(WHERE false)` match all and none nodes, respectively. `(v WHERE v.id = 1)` matches nodes `v` whose `id` property equals 1.

Example:

````
'''
USE movie
MATCH (v WHERE v.id = 1 AND v IS LABELED Person) RETURN v.name AS name, type(v)
'''

````

For more information, see [WHERE clause](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dql/clauses/where/).