GQL API

Graph Patterns & Modes

Overview

A graph pattern matches structures in the graph. It consists of three parts:

  1. Match mode (optional)
  2. Path pattern list (comma-separated list of path patterns)
  3. Global WHERE clause (optional)
-- Syntax
[ match_mode ] path_pattern_1, path_pattern_2, ... [ WHERE global_expression ]

Connected vs. Disconnected Path Lists

When multiple path patterns are supplied in a comma-separated list, GQL evaluates them and combines the results:

1. Connected Paths (Equi-Joins)

If the path patterns share one or more variables, the query engine performs an equi-join on those variables, returning only records where the bound elements are identical.

Find wizards who are common knows-connections of "Albus" and "Draco" and also teach a spell:

MATCH ({name: "Albus"})-[:Knows]->(u:Wizard)<-[:Knows]-({name: "Draco"}),
      (u)-[:Teaches]->(s:Spell)
RETURN u.name AS common_friend, s.name AS spell

Here, the variable u is declared in both path patterns. GQL joins the records on u.

2. Disconnected Paths (Cartesian Product)

If the path patterns share no common variables, the query engine performs a Cartesian product, pairing every record from the first match with every record from the second. 

MATCH (w1:Wizard {affinity: "Light"}), (w2:Wizard {affinity: "Dark"})
RETURN w1.name, w2.name

Warning: Cartesian products can generate large result sets and increase query execution times. Avoid disconnected path patterns unless explicitly necessary.

Match Modes

Match modes determine whether edges or nodes can be repeated across matched paths in a single record.

Match Mode Description
DIFFERENT EDGES Default. Repeated edges are strictly prohibited in the same match record. Nodes may be repeated.
REPEATABLE ELEMENTS No restrictions. Both nodes and edges can be repeated.
Example Scenario:

Consider two wizards connected by multiple relationships, or a cycle. Using different modes yields different behaviors:

-- Finds paths utilizing distinct edges:
MATCH DIFFERENT EDGES (w1:Wizard)-[e1]-(n), (n)-[e2]-(w2)
RETURN w1.name, w2.name
-- Permits e1 and e2 to match the exact same edge:
MATCH REPEATABLE ELEMENTS (w1:Wizard)-[e1]-(n), (n)-[e2]-(w2)
RETURN w1.name, w2.name

Variable Reuse Restrictions in DIFFERENT EDGES

In DIFFERENT EDGES mode, because edges must be unique, reusing an edge variable at different positions in the match pattern will always fail to return records: 

-- RETURNS ZERO RESULTS (e cannot be bound to two different edges simultaneously)
MATCH DIFFERENT EDGES ()-[e]->(), ()<-[e]-()
RETURN e