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:

Node variable
Label expression
Node type specification
Node property specification
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.

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.

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.

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.

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.