GQL API - Node & Edge Patterns

Overview

Node patterns and edge patterns are collectively referred to as element patterns. They are the fundamental building blocks used to construct larger path patterns.

Node Patterns

A node pattern matches nodes in the graph and is represented using a pair of parentheses (). A node pattern consists of three optional components:

Node variable declaration
Label expression
Property specification or inline WHERE clause

-- Syntax
( [ node_variable ] [ label_expression ] [ property_specification | inline_where_clause ] )

Examples:

Match any node in the graph (simplest empty pattern):

()

Match Wizard nodes and bind them to the variable w:

(w:Wizard)

Match nodes with specific property values (using a property specification):

({name: "Albus", affinity: "Light"})

Match Wizard nodes whose level is greater than 50, binding them to w:

(w:Wizard WHERE w.level > 50)

Edge Patterns

Edge patterns match edges in the graph, typically placed between two node patterns. An edge pattern is either a full edge pattern or an abbreviated edge pattern.

Full Edge Pattern

Represented using a pair of square brackets []. It defines an edge's direction (left pointing, right pointing, or undirected) and can include variables, label expressions, and filters:

-- Left pointing (incoming)
<-[ edge_filter ]-

-- Right pointing (outgoing)
-[ edge_filter ]->

-- Undirected (any direction)
-[ edge_filter ]-

Examples:

Match all outgoing edges and bind them to the variable e:

()-[e]->()

Match outgoing AlliedWith edges where mana_cost is exactly 10, binding them to e:

()-[e:AlliedWith {mana_cost: 10}]->()

Match incoming edges where affinity_boost is less than 5, binding them to e:

()<-[e WHERE e.affinity_boost < 5]-()

Abbreviated Edge Pattern

Indicates only the direction of the edge. It does not support variables or pattern filtering:

-- Syntax: <- or -> or -

Examples:

Match nodes that a Wizard can reach through any outgoing edge:

(:Wizard)->(n)

Match all one-hop paths in the graph:

p = ()->()

Label Expressions

A label expression starts with a colon : (or the keyword IS). It specifies one or more labels and supports logical operators:

Operator	Description
`!`	Negation (NOT)
`&`	Conjunction (AND)
`\|`	Disjunction (OR)
`%`	Wildcard (Matches any label)

Examples:

Match nodes that are either a Wizard or a Spell:

(n:Wizard|Spell)

Match edges that are not Knows connections:

()-[e:!Knows]-()

Match nodes that have any label:

(n:%)

Match nodes that have no label (unlabeled nodes):

(n:!%)

Match Wizard nodes that have either the Light or Dark affinity (using grouping parentheses):

(w:Wizard&(Light|Dark))

Common Syntax Errors

1. Omitting the variable name in an inline WHERE clause:

You must use the dot operator on a declared variable to reference a property inside the WHERE clause.

-- SYNTAX ERROR
MATCH p = (:Wizard WHERE level > 50)-[]->()

-- CORRECT
MATCH p = (w:Wizard WHERE w.level > 50)-[]->()

2. Mixing property specification and inline WHERE clauses:

You cannot use both curly brace property specifications and a WHERE clause in the same element pattern.

-- SYNTAX ERROR
MATCH (w:Wizard {name: "Albus"} WHERE w.level > 50)

-- CORRECT
MATCH (w:Wizard WHERE w.name = "Albus" AND w.level > 50)