MATCH statement¶

The MATCH statement retrieves data from a graph or temporary graph by pattern matching.

Note

An ordinary MATCH usually returns query results with RETURN. In NebulaGraph Database Developer Edition, it supports both persistent graphs and temporary graphs. It differs from a match compute statement, which uses MATCH ... PER PATH or MATCH ... PER NODE for iterative computation and can run only on a temporary graph.

Note

An operation involving a non-default schema or an object in it requires access to the schema, either implicitly or through an explicit USAGE grant, as well as the privilege required for the operation. The schema access check and the privilege check for the requested operation are independent; satisfying one does not satisfy the other. Schema access control does not apply to temporary graphs or built-in procedures and functions. For more information, see Schema access control.

Prerequisites¶

A graph or temporary graph is created. For more information, see CREATE GRAPH and CREATE TEMPORARY GRAPH.

To retrieve data from a graph, you must be granted to perform the action MATCH ANY GRAPH on the used schema or the action MATCH on the resource object that you want to query. For more information, see Roles and privileges.

To retrieve data from a temporary graph, you must be the user with the role ADMIN or the owner of the temporary graph.

Syntax¶

diagramsource

match_statement
graph_pattern
match_mode
path_pattern
path_mode_prefix
path_search_prefix
path_term
path_factor
parenthesized_path_pattern
element_pattern
graph_pattern_yield_clause

match_statement ::=
    ( 'OPTIONAL' )? 'MATCH' graph_pattern graph_pattern_yield_clause?

graph_pattern ::= match_mode? path_pattern ( ',' path_pattern )* ( 'WHERE' search_condition )?

match_mode ::=
      'REPEATABLE' ('ELEMENTS' | 'ELEMENT' 'BINDINGS'?)
    | 'DIFFERENT' ( ('EDGE' | 'RELATIONSHIP') 'BINDINGS'? | ('EDGES' | 'RELATIONSHIPS') )

path_pattern ::=
    ( path_variable '=' )? ( path_mode_prefix | path_search_prefix )? path_term

path_mode_prefix ::=
    ( 'WALK' | 'TRAIL' | 'ACYCLIC' | 'SIMPLE' ) ( 'PATH' | 'PATHS' )?

path_search_prefix ::=
      'ALL' ( 'WALK' | 'TRAIL' | 'ACYCLIC' | 'SIMPLE' )? ( 'PATH' | 'PATHS' )?
    | 'ANY' ( number_of_paths )? ( 'WALK' | 'TRAIL' | 'ACYCLIC' | 'SIMPLE')? ( 'PATH' | 'PATHS' )?
    | 'ALL SHORTEST' ( 'WALK' | 'TRAIL' | 'ACYCLIC' | 'SIMPLE' )? ( 'PATH' | 'PATHS' )?
    | 'ANY SHORTEST' ( 'WALK' | 'TRAIL' | 'ACYCLIC' | 'SIMPLE')? ( 'PATH' | 'PATHS' )?
    | 'SHORTEST' number_of_paths  ( 'WALK' | 'TRAIL' | 'ACYCLIC' | 'SIMPLE' )? ( 'PATH' | 'PATHS' )?

path_term ::=
      path_factor path_factor*

path_factor ::=
      element_pattern index_hint?
    | edge_pattern index_hint? graph_pattern_quantifier
    | parenthesized_path_pattern graph_pattern_quantifier

parenthesized_path_pattern ::=
    '(' ( path_variable '=' )? path_mode_prefix? path_term ( 'WHERE' search_condition )? ')'  

element_pattern ::=
      node_pattern
    | edge_pattern

graph_pattern_yield_clause ::=
    'YIELD' ( element_variable_reference | path_variable_reference) ( ',' (element_variable_reference | path_variable_reference) )*

Parameters¶

`OPTIONAL`¶

When the keyword OPTIONAL is used, the query returns null as its result even if no match is found for the graph pattern, and the entire query may return other data from other clauses. Otherwise, the match statement returns no data.

`match_mode`¶

The match mode that restricts whether edges can be repeated in the paths matched by the path patterns defined in the query. The following match modes are supported:

REPEATABLE: If the match mode starts with the keyword REPEATABLE, edges and nodes can be repeated in the paths matched by the path patterns defined in the query. This is the default match mode.
DIFFERENT: If the match mode starts with the keyword DIFFERENT, edges cannot be repeated in the paths matched by the path patterns defined in the query.

`path_variable`¶

A variable that represents a path. For more information about variables, see Variable value expression.

`WALK | TRAIL | SIMPLE | ACYCLIC`¶

The path mode that filters paths during path matching. The following path modes are supported:

WALK: Applies no filtering to the paths. This is the default path mode.
TRAIL: Filters out paths with repeated edges.
ACYCLIC: Filters out paths with repeated nodes.
SIMPLE: Filters out paths with repeated nodes unless these nodes are either the first or last nodes in the path.

Note

If the match mode starts with the keyword DIFFERENT and the path mode is set to WALK or unset, the path mode TRAIL takes effect.

`PATH | PATHS`¶

Each path mode can be followed by the optional keyword PATH or PATHS to indicate that paths are to be searched.

`ALL | ANY | ALL SHORTEST | ANY SHORTEST`¶

Paths can be selectively filtered during path matching. The following selectors are supported:

ALL: Default selector, which selects all paths that match the pattern.
ANY: Selects any path that matches the pattern. You can add a non-negative integer (number_of_paths) to specify the maximum number of paths to return.
ALL SHORTEST: Selects all shortest paths that match the pattern.
ANY SHORTEST: Selects any shortest path that matches the pattern.

`number_of_paths`¶

The maximum number of paths to return. The default value is 1. It must be a non-negative integer.

`element_pattern`¶

The element pattern to match, which is either a node pattern or an edge pattern.

`node_pattern`¶

The node pattern to match. For more information, see Node patterns.

`edge_pattern`¶

The edge pattern to match. For more information, see Edge patterns.

`index_hint`¶

The index hint that is used to advise the query optimizer on which index to use or not use when executing the query. For more information, see Configure index hints.

`graph_pattern_quantifier`¶

The upper and lower bounds of the number of times that the preceding edge pattern is matched.

The following formats are supported:

{lower_bound, upper_bound}: A general quantifier. Both the upper bound and lower bound are optional. If lower_bound is not specified, the default value is 0. If upper_bound is not specified, the default value is infinity.
{fixed_number}: A fixed quantifier, whose value must be an integer greater than 0. It indicates the same upper and lower bounds. For example, {2} equals {2,2}.
*: Equivalent to {0,}, which means 0 or more times.
+: Equivalent to {1,}, which means 1 or more times.

`search_condition`¶

The boolean value expression that can be used to extract a subset of data from the previous statement. For more information, see WHERE clause.

The search_condition cannot contain subquery value expressions when used in the following scenarios:

An edge_pattern followed by a graph_pattern_quantifier. For example, -[e WHERE EXISTS ((b)-[:KNOWS]->())]->{1,3} is not supported.
A parenthesized_path_pattern followed by a graph_pattern_quantifier. For example, ((a)-[e]->(b) WHERE EXISTS ((b)-[:KNOWS]->())){1,2} is not supported.

`element_variable_reference`¶

The reference to a variable that represents a graph element.

`path_variable_reference`¶

The reference to a variable that represents a path.

Element type queries vs. label queries¶

In GQL MATCH patterns, you can use @type_name to match by node type or edge type, or match by label.

@type_name is for precise matching by structural type in the graph type, while label-based queries are for cross-type filtering by semantic label.

Be aware that label syntax depends on the context:

In a pattern, label expressions are typically written as (v:Person), (v IS Person), or [e:Act].
In a WHERE clause, the full labeled-predicate form is typically WHERE v IS LABELED Person; a colon shorthand is also valid, for example WHERE e:Act.

For the detailed differences, result-scope examples, and usage guidance, see Graph patterns.

Variables in labels and element types¶

In MATCH patterns, labels and element types can be specified either as literal names or as string variables.

If the variable value is known when the query is planned, the optimizer can treat it similarly to a literal name. If the value is known only at execution time, the label or element-type check is applied at runtime.

A variable used in a pattern must evaluate to a string that names a valid label or element type.

Examples¶

The following examples are based on the example dataset.

Warning

When there is a large amount of data in the graph, provide search conditions in as much detail as possible or use LIMIT to limit the number of results returned. Otherwise, the execution may result in OOM.

Match by node patterns¶

The following examples demonstrate how to match nodes by node patterns. For more information, see Node patterns.

Match nodes by a node variable¶

'''
USE movie 
MATCH (v) RETURN v LIMIT 5
'''

The preceding statement retrieves all nodes in the graph and uses the clause LIMIT to return up to 5 of these nodes to avoid OOM.

Return:

+---------------------------------------------------------------------------------------------+
| v                                                                                           |
+---------------------------------------------------------------------------------------------+
| (288540739078455297@Director:Person{birthDate:1965-05-23,id:1071,name:"Tom Tykwer"})        |
| (288543470677655553@Director:Person{birthDate:1968-09-10,id:956,name:"Guy Ritchie"})        |
| (288544205117063169@Director:Person{birthDate:1925-05-25,id:1961,name:"Claude Pinoteau"})   |
| (288544797822550018@Director:Person{birthDate:1941-03-14,id:5231,name:"Wolfgang Petersen"}) |
| (288544845067190274@Director:Person{birthDate:1944-05-14,id:1,name:"George Lucas"})         |
+---------------------------------------------------------------------------------------------+

Match nodes by a label¶

'''
USE movie
MATCH (v:Person) RETURN v LIMIT 5
'''

The preceding statement retrieves the nodes with the label Person in the graph.

Return:

+------------------------------------------+
| v                                        |
+------------------------------------------+
| (288907520695599107@User:Person{id:267}) |
| (288908057566511106@User:Person{id:262}) |
| (288911003914076161@User:Person{id:392}) |
| (288911467770544130@User:Person{id:557}) |
| (288912447023087619@User:Person{id:100}) |
+------------------------------------------+

Match nodes by multiple labels¶

You can use label expressions with the disjunction operator (|) or the conjunction operator (&) to match nodes that have one of multiple labels or all of multiple labels. For more information, see Label expressions.

The following example matches nodes labeled Person or Movie:

'''
USE movie
MATCH (v:Person|Movie) RETURN v.name AS name ORDER BY name LIMIT 5
'''

Return:

+-----------------------+
| name                  |
+-----------------------+
|  Bridget Jones' Diary |
| 001                   |
| 12 Monkeys            |
| 7 (seven) Virgins     |
| 8 1⁄2                 |
+-----------------------+

The following example matches nodes that are labeled both Person and Movie:

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

Return:

Error: [NS239]: No element type matching pattern `(v:(Person) & (Movie))` was found

Since no nodes have both labels in this dataset, no results are returned.

You can also use the negation operator (!) to exclude a label:

'''
USE movie
MATCH (v:Person&!Movie) RETURN v.name AS name ORDER BY name LIMIT 5
'''

Return:

+------------------+
| name             |
+------------------+
| Aaron Eckhart    |
| Ada Lonati       |
| Adam Alexi-Malle |
| Adam Baldwin     |
| Adam Bousdoukos  |
+------------------+

Match nodes by a variable label¶

'''
USE movie {
  VALUE s = "Person"
  MATCH (v:s) 
  WHERE v.id = 1
  RETURN v.id, type(v)
}
'''

Return:

+------+----------+
| v.id | type(v)  |
+------+----------+
| 1    | Director |
| 1    | User     |
+------+----------+

Match nodes by a label and a search condition¶

'''
USE movie
MATCH (v:Person) WHERE v.birthDate > date("1990-01-20") RETURN v LIMIT 5
'''

The preceding statement retrieves the nodes with the label Person and the date of birth later than 1990-01-20 in the graph.

Return:

+--------------------------------------------------------------------------------------------+
| v                                                                                          |
+--------------------------------------------------------------------------------------------+
| (288306491562131457@Actor:Person{birthDate:1993-05-19,id:19593,name:"Ryunosuke Kamiki"})   |
| (288271934255267841@Actor:Person{birthDate:1992-11-30,id:247365,name:"Dylan Smith"})       |
| (288374798722007041@Actor:Person{birthDate:1990-04-15,id:10990,name:"Emma Watson"})        |
| (288375481621807106@Actor:Person{birthDate:1991-11-13,id:91842,name:"Devon Bostick"})      |
| (288381722209288193@Actor:Person{birthDate:1990-11-07,id:1608,name:"Nacho Pérez"})         |
+--------------------------------------------------------------------------------------------+

Match nodes by a node property¶

'''
USE movie
MATCH (v {id:199}) RETURN v
'''

Return:

+------------------------------------------------------------------------------------+
| v                                                                                  |
+------------------------------------------------------------------------------------+
| (288269194066132994@Actor:Person{birthDate:1951-09-07,id:199,name:"Julie Kavner"}) |
| (288832144019554307@User:Person{id:199})                                           |
| (289113618996264961@Movie:Movie{id:199,name:"Star Trek: First Contact"})           |
+------------------------------------------------------------------------------------+

Match nodes by a node type¶

'''
USE movie
MATCH (v@Actor) RETURN v LIMIT 5
'''

The preceding statement retrieves the nodes that have the node type Actor in the graph.

Return:

+--------------------------------------------------------------------------------------+
| v                                                                                    |
+--------------------------------------------------------------------------------------+
| (288455711610896385@Actor:Person{birthDate:1952-07-11,id:74614,name:"Tim De Zarn"})  |
| (288455758855536641@Actor:Person{birthDate:1994-02-10,id:2139,name:"Makenzie Vega"}) |
| (288455810395144193@Actor:Person{birthDate:null,id:16219,name:"Cedric Scott"})       |
| (288455973603901441@Actor:Person{birthDate:null,id:47547,name:"John Bennett"})       |
| (288455982193836033@Actor:Person{birthDate:1956-01-16,id:1566,name:"Anders Hove"})   |
+--------------------------------------------------------------------------------------+

Match nodes by multiple node types¶

'''
USE movie
MATCH (v@[Actor,Director]) RETURN v LIMIT 5
'''

The preceding statement retrieves the nodes that have the node types Actor or Director in the graph and randomly returns 5 nodes.

Return:

+------------------------------------------------------------------------------------------------------+
| v                                                                                                    |
+------------------------------------------------------------------------------------------------------+
| (288710325862137857@Director:Person{birthDate:1969-02-12,id:6431,name:"Darren Aronofsky"})           |
| (288710433236320257@Director:Person{birthDate:1963-08-15,id:223,name:"Alejandro González Iñárritu"}) |
| (288713401058721793@Director:Person{birthDate:1957-12-29,id:7832,name:"Oliver Hirschbiegel"})        |
| (288715978039099394@Director:Person{birthDate:1952-05-14,id:24,name:"Robert Zemeckis"})              |
| (288717240759484417@Director:Person{birthDate:1864-10-05,id:1868,name:"Louis  Lumière"})             |
+------------------------------------------------------------------------------------------------------+

Match nodes by a variable node type¶

'''
USE movie {
  VALUE s = "Director"
  MATCH (v@[s,"User"]) 
  WHERE v.id = 1
  RETURN v.id, type(v)
}
'''

Return:

+------+----------+
| v.id | type(v)  |
+------+----------+
| 1    | Director |
| 1    | User     |
+------+----------+

Use a previous query result as a node type¶

"""
USE movie {
  MATCH (v:Person {id:1}) RETURN type(v) AS t
  NEXT
  MATCH (v@t {id:1}) RETURN type(v)
}
"""

Return:

+----------+
| type(v)  |
+----------+
| Director |
| User     |
+----------+

Match by edge patterns¶

The following examples demonstrate how to match edges by edge patterns. For more information, see Edge patterns.

Match edges by an edge variable¶

'''
USE movie
MATCH ()-[e]->() RETURN e LIMIT 5
'''

The preceding statement retrieves 5 random edges in the graph.

Return:

+----------------------------------------------------------+
| e                                                        |
+----------------------------------------------------------+
| (288483723387600897)-[0@Act:Act{}]->(289086826990272513) |
| (288483766337273857)-[0@Act:Act{}]->(289272773304385537) |
| (288483792107077633)-[0@Act:Act{}]->(289317990720077825) |
| (288483860826554369)-[0@Act:Act{}]->(289285894429474817) |
| (288483865121521665)-[0@Act:Act{}]->(289150834887884801) |
+----------------------------------------------------------+

Match edges by a label¶

'''
USE movie
MATCH ()-[e:Act]->() RETURN e LIMIT 5
'''

The preceding statement retrieves the edges with the label Act in the graph.

Return:

+----------------------------------------------------------+
| e                                                        |
+----------------------------------------------------------+
| (288483723387600897)-[0@Act:Act{}]->(289086826990272513) |
| (288483766337273857)-[0@Act:Act{}]->(289272773304385537) |
| (288483792107077633)-[0@Act:Act{}]->(289317990720077825) |
| (288483860826554369)-[0@Act:Act{}]->(289285894429474817) |
| (288483865121521665)-[0@Act:Act{}]->(289150834887884801) |
+----------------------------------------------------------+

Match edges by multiple labels¶

You can use label expressions with the disjunction operator (|) to match edges with one of multiple labels. For more information, see Label expressions.

The following example matches edges labeled Act or Direct:

'''
USE movie
MATCH ()-[e:Act|Direct]->() RETURN e LIMIT 5
'''

Return:

+----------------------------------------------------------+
| e                                                        |
+----------------------------------------------------------+
| (288483723387600897)-[0@Act:Act{}]->(289086826990272513) |
| (288483766337273857)-[0@Act:Act{}]->(289272773304385537) |
| (288483792107077633)-[0@Act:Act{}]->(289317990720077825) |
| (288483860826554369)-[0@Act:Act{}]->(289285894429474817) |
| (288483865121521665)-[0@Act:Act{}]->(289150834887884801) |
+----------------------------------------------------------+

You can also use the negation operator (!) to exclude a label:

'''
USE movie
MATCH ()-[e:!Act]->() RETURN e LIMIT 5
'''

Return:

+----------------------------------------------------------------------+
| e                                                                    |
+----------------------------------------------------------------------+
| (289047300406247427)-[0@Watch:Watch{rate:4.0}]->(289108623949299713) |
| (289047300406247427)-[0@Watch:Watch{rate:1.0}]->(289138379482726401) |
| (288710325862137857)-[0@Direct:Direct{}]->(289222513597087745)       |
| (288710433236320257)-[0@Direct:Direct{}]->(289182609055940609)       |
| (288713401058721793)-[0@Direct:Direct{}]->(289136996503257089)       |
+----------------------------------------------------------------------+

Note

The label expression syntax (:Act|Direct) and the type specification syntax (@[Act,Direct]) both filter by multiple types, but they work differently. Label expressions filter by labels and support operators like |, &, and !. Type specifications filter by element types. For more details, see Label expressions and Edge patterns.

Match edges by a variable label¶

'''
USE movie {
  VALUE et = "Direct"
  MATCH (src:Person)-[e:et]->(dst) WHERE src.id = 1 RETURN type(src), type(e), type(dst)
}
'''

Return:

+-----------+---------+-----------+
| type(src) | type(e) | type(dst) |
+-----------+---------+-----------+
| Director  | Direct  | Movie     |
+-----------+---------+-----------+

Match edges by a label and a search condition¶

'''
USE movie
MATCH ()-[e:Watch]->() 
WHERE e.rate > 4 
RETURN e, e.rate AS rate 
ORDER BY rate 
LIMIT 3
'''

The preceding statement retrieves the edges with the label Watch and the rate greater than 4 in the graph.

Return:

+----------------------------------------------------------------------+------+
| e                                                                    | rate |
+----------------------------------------------------------------------+------+
| (288905240067964929)-[0@Watch:Watch{rate:4.5}]->(289222513597087745) | 4.5  |
| (288904325239930881)-[0@Watch:Watch{rate:4.5}]->(289217037513785345) | 4.5  |
| (288902753281900548)-[0@Watch:Watch{rate:4.5}]->(289219219357171713) | 4.5  |
+----------------------------------------------------------------------+------+

Match edges by an edge property¶

'''
USE movie
MATCH ()-[e {rate: 4}]->() RETURN e LIMIT 5
'''

The preceding statement retrieves the edges that have the property rate with the value 4 in the graph.

Return:

+----------------------------------------------------------------------+
| e                                                                    |
+----------------------------------------------------------------------+
| (288990422154346498)-[0@Watch:Watch{rate:4.0}]->(289113618996264961) |
| (288990585363103745)-[0@Watch:Watch{rate:4.0}]->(289159802779598849) |
| (288990585363103745)-[0@Watch:Watch{rate:4.0}]->(289222513597087745) |
| (288991908213030914)-[0@Watch:Watch{rate:4.0}]->(289217037513785345) |
| (288992135846297601)-[0@Watch:Watch{rate:4.0}]->(289315302070550529) |
+----------------------------------------------------------------------+

Match edges by an edge type¶

'''
USE movie
MATCH ()-[e@Watch]->() RETURN e LIMIT 5
'''

The preceding statement retrieves the edges that have the edge type Watch in the graph.

Return:

+----------------------------------------------------------------------+
| e                                                                    |
+----------------------------------------------------------------------+
| (288990422154346498)-[0@Watch:Watch{rate:4.0}]->(289113618996264961) |
| (288990422154346498)-[0@Watch:Watch{rate:5.0}]->(289158106267516929) |
| (288990422154346498)-[0@Watch:Watch{rate:5.0}]->(289169659729543169) |
| (288990585363103745)-[0@Watch:Watch{rate:4.0}]->(289159802779598849) |
| (288990585363103745)-[0@Watch:Watch{rate:4.0}]->(289222513597087745) |
+----------------------------------------------------------------------+

Match edges by a variable edge type¶

'''
USE movie {
  VALUE et = "Direct"
  MATCH (src:Person)-[e@et]->(dst) WHERE src.id = 1 RETURN type(src), type(e), type(dst)
}
'''

Return:

+-----------+---------+-----------+
| type(src) | type(e) | type(dst) |
+-----------+---------+-----------+
| Director  | Direct  | Movie     |
+-----------+---------+-----------+

Match edges by edge types¶

'''
USE movie
MATCH ()-[e@[Direct,Watch]]->() RETURN e LIMIT 5
'''

The preceding statement retrieves the edges that have the edge types Direct or Watch in the graph and randomly returns 5 edges.

Return:

+----------------------------------------------------------------+
| e                                                              |
+----------------------------------------------------------------+
| (288710325862137857)-[0@Direct:Direct{}]->(289222513597087745) |
| (288710433236320257)-[0@Direct:Direct{}]->(289182609055940609) |
| (288713401058721793)-[0@Direct:Direct{}]->(289136996503257089) |
| (288713401058721793)-[0@Direct:Direct{}]->(289194725158682625) |
| (288715978039099394)-[0@Direct:Direct{}]->(289278923697553409) |
+----------------------------------------------------------------+

Match incoming edges¶

An edge in a pattern can have a direction, e.g. (a:Movie)<-[e:Direct]-(b:Director), where e is the incoming edge to node a, and e is the outgoing edge to node b.

'''
USE movie
MATCH (a:Genre)<-[e:WithGenre]-(b:Movie) RETURN a LIMIT 3
'''

Return:

+-----------------------------------------------------------------+
| a                                                               |
+-----------------------------------------------------------------+
| (289405968830169091@Genre:Genre{id:127,name:"Marital Tragedy"}) |
| (289405968830169091@Genre:Genre{id:127,name:"Marital Tragedy"}) |
| (289405968830169091@Genre:Genre{id:127,name:"Marital Tragedy"}) |
+-----------------------------------------------------------------+

Match undirected edges¶

An edge can also have no direction, indicating a symmetric relationship.

'''
USE movie
MATCH (a:Person)~[e:Act]~(b:Movie) RETURN e LIMIT 3
'''

Return:

Error: [NS239]: No element type matching pattern `~[e:Act]~` was found

Since there are no undirected edges in the graph, an error is returned.

Match undirected and incoming edges¶

'''
USE movie
MATCH (a:Genre)<~[e:WithGenre]~(b:Movie) RETURN a,b LIMIT 3
'''

Return:

+------------------------------------------------------------------------+---------------------------------------------------------------------+
| a                                                                      | b                                                                   |
+------------------------------------------------------------------------+---------------------------------------------------------------------+
| (289559539680804865@Genre:Genre{id:10214,name:Exciting})               | (289085370996359169@Movie:Movie{id:130,name:"Tales from Earthsea"}) |
| (289566566247301122@Genre:Genre{id:34,name:"Japanese Animation Film"}) | (289085370996359169@Movie:Movie{id:130,name:"Tales from Earthsea"}) |
| (289587822040449025@Genre:Genre{id:10223,name:Serious})                | (289085370996359169@Movie:Movie{id:130,name:"Tales from Earthsea"}) |
+------------------------------------------------------------------------+---------------------------------------------------------------------+

Match outgoing and incoming edges¶

'''
USE movie
MATCH (a:Movie)<-[e]->(b) RETURN a,b,e LIMIT 3
'''

Return:

+-----------------------------------------------------------------+--------------------------------------------------------------------------------------------+----------------------------------------------------------------+
| a                                                               | b                                                                                          | e                                                              |
+-----------------------------------------------------------------+--------------------------------------------------------------------------------------------+----------------------------------------------------------------+
| (289254734441742337@Movie:Movie{id:618,name:"The Clansman,"})   | (288657437634854913@Director:Person{birthDate:1875-01-22,id:8812,name:"D. W. Griffith"})   | (288657437634854913)-[0@Direct:Direct{}]->(289254734441742337) |
| (289111664786145281@Movie:Movie{id:662,name:"The Pier"})        | (288675751375405057@Director:Person{birthDate:1921-07-29,id:9956,name:"Chris Marker"})     | (288675751375405057)-[0@Direct:Direct{}]->(289111664786145281) |
| (289309246166663169@Movie:Movie{id:155,name:"Batman Begins 2"}) | (288655693878132737@Director:Person{birthDate:1970-07-30,id:525,name:"Christopher Nolan"}) | (288655693878132737)-[0@Direct:Direct{}]->(289309246166663169) |
+-----------------------------------------------------------------+--------------------------------------------------------------------------------------------+----------------------------------------------------------------+

Match edges with any direction¶

The any-direction edge pattern matches the edges in any direction including incoming and outgoing directions, and undirected edges.

'''
USE movie
MATCH (a:Movie)-[e]-(b) RETURN e,a,b LIMIT 3
'''

Return:

+----------------------------------------------------------------+--------------------------------------------------------------------+------------------------------------------------------------------------------------------------+
| e                                                              | a                                                                  | b                                                                                              |
+----------------------------------------------------------------+--------------------------------------------------------------------+------------------------------------------------------------------------------------------------+
| (288573432369512449)-[0@Direct:Direct{}]->(289195390878613505) | (289195390878613505@Movie:Movie{id:364,name:"Batman 2"})           | (288573432369512449@Director:Person{birthDate:1958-08-25,id:510,name:"Tim Burton"})            |
| (288574192578723841)-[0@Direct:Direct{}]->(289271897131057153) | (289271897131057153@Movie:Movie{id:572,name:"Next Door"})          | (288574192578723841@Director:Person{birthDate:null,id:7736,name:"Pål Sletaune"})               |
| (288573896225980417)-[0@Direct:Direct{}]->(289210736796762113) | (289210736796762113@Movie:Movie{id:139,name:"Mifune's Last Song"}) | (288573896225980417@Director:Person{birthDate:1947-03-02,id:1558,name:"Søren Kragh-Jacobsen"}) |
+----------------------------------------------------------------+--------------------------------------------------------------------+------------------------------------------------------------------------------------------------+

Match by quantified edge patterns¶

Edge patterns can be quantified with graph_pattern_quantifier to match variable-length paths.

'''
USE movie
MATCH (a{id:1})-[e]->{1,2}(b:Genre) RETURN labels(a)
'''

The preceding query starts from a node with ID 1, hops over one or two edges, and reaches nodes with the label Genre. The statement returns the labels of the starting nodes.

Return:

+-----------+
| labels(a) |
+-----------+
| [Person]  |
| [Person]  |
| [Movie]   |
...
+-----------+
Got 126 rows (time spent 6.815ms/7.647592ms)

Besides, you can also use quantified path patterns to match variable-length paths. For more information, see Variable-length path pattern expressions.

Match by path patterns¶

Node patterns and edge patterns can be concatenated to form path patterns. The following examples demonstrate how to match by path patterns. For more information, see Path patterns.

Match nodes by a simple path pattern¶

'''
USE movie
MATCH (v1)-[e:Watch]->(v2) RETURN v1,v2 LIMIT 3
'''

The preceding statement retrieves the paths in the graph where the path pattern is an edge containing the label Watch between two nodes, and returns the starting node and the ending node of each path.

Return:

+------------------------------------------+----------------------------------------------------+
| v1                                       | v2                                                 |
+------------------------------------------+----------------------------------------------------+
| (288891079560790018@User:Person{id:154}) | (289212480553484289@Movie:Movie{id:601,name:E.T.}) |
| (288889636451778562@User:Person{id:390}) | (289212480553484289@Movie:Movie{id:601,name:E.T.}) |
| (288880982092677121@User:Person{id:41})  | (289212480553484289@Movie:Movie{id:601,name:E.T.}) |
+------------------------------------------+----------------------------------------------------+

Match nodes by a complex path pattern¶

'''
USE movie
MATCH (v1)-[e1]->(v2)-[e2]->(v3:Genre) RETURN v3 LIMIT 5
'''

The preceding statement retrieves a complex path pattern. The pattern consists of three nodes and two edges, and the last node contains the label Genre. The statement returns the last node of each path.

Return:

+--------------------------------------------------------+
| v3                                                     |
+--------------------------------------------------------+
| (289457800495497219@Genre:Genre{id:16,name:Animation}) |
| (289457800495497219@Genre:Genre{id:16,name:Animation}) |
| (289457800495497219@Genre:Genre{id:16,name:Animation}) |
| (289457800495497219@Genre:Genre{id:16,name:Animation}) |
| (289457800495497219@Genre:Genre{id:16,name:Animation}) |
+--------------------------------------------------------+

Match by quantified path patterns¶

Path patterns can be quantified with graph_pattern_quantifier to match variable-length paths. The following examples returns the same results as Match by quantified edge patterns.

'''
USE movie
MATCH (a{id:1})(()-[e]->()){1,2}(b:Genre) RETURN labels(a)
'''

Return:

+-----------+
| labels(a) |
+-----------+
| [Movie]   |
| [Person]  |
| [Person]  |
...
+-----------+
Got 126 rows (time spent 7.973ms/8.821899ms)

Match and return variable-length paths¶

If you need to return paths, you can declare a variable for the path pattern and return it with the RETURN statement.

Note

In the following example, n represents a list of nodes that always contains the source node a and m represents a list of nodes that always contains the destination node b.

'''
USE movie
MATCH p = (a{id:1})((n)-[e]->(m WHERE m.id > 1000)){1,2}(b:Genre) RETURN p
'''

The preceding statement declares a path pattern named p and returns it.

Return:

+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| p                                                                                                                                                                                                          |
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| (289107795020611585@Movie:Movie{id:1,name:Cowboy Bebop})-[0@WithGenre:WithGenre{}]->(289517113993854978@Genre:Genre{id:1037,name:Realism})                                                                 |
| (289107795020611585@Movie:Movie{id:1,name:Cowboy Bebop})-[0@WithGenre:WithGenre{}]->(289517672339603457@Genre:Genre{id:10215,name:Thrilling})                                                              |
| (289107795020611585@Movie:Movie{id:1,name:Cowboy Bebop})-[0@WithGenre:WithGenre{}]->(289361829451268098@Genre:Genre{id:1505,name:Famous Score})                                                            |
| (289107795020611585@Movie:Movie{id:1,name:Cowboy Bebop})-[0@WithGenre:WithGenre{}]->(289374843202174977@Genre:Genre{id:1110,name:Classic})                                                                 |
| (289107795020611585@Movie:Movie{id:1,name:Cowboy Bebop})-[0@WithGenre:WithGenre{}]->(289383519036112897@Genre:Genre{id:1119,name:Episode Film})                                                            |
| (288826320043900931@User:Person{id:1})-[0@Watch:Watch{rate:5.0}]->(289211982337277953@Movie:Movie{id:10004,name:movie2})-[0@WithGenre:WithGenre{}]->(289449824741228545@Genre:Genre{id:11003,name:genre3}) |
| (289107795020611585@Movie:Movie{id:1,name:Cowboy Bebop})-[0@WithGenre:WithGenre{}]->(289465634515845121@Genre:Genre{id:1033,name:Traumsequenz})                                                            |
| (289107795020611585@Movie:Movie{id:1,name:Cowboy Bebop})-[0@WithGenre:WithGenre{}]->(289468834266480642@Genre:Genre{id:10224,name:Sad})                                                                    |
| (289107795020611585@Movie:Movie{id:1,name:Cowboy Bebop})-[0@WithGenre:WithGenre{}]->(289528487067254785@Genre:Genre{id:10216,name:Funny})                                                                  |
| (289107795020611585@Movie:Movie{id:1,name:Cowboy Bebop})-[0@WithGenre:WithGenre{}]->(289529470614765570@Genre:Genre{id:3167,name:TV Film})                                                                 |
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Specify path mode TRAIL to match paths without repeated edges¶

When the path mode is not specified or explicitly specified as WALK, the returned paths are not filtered. When the path mode is specified as TRAIL, paths with repeated edges are filtered out.

'''
USE movie
MATCH p = TRAIL (a@Actor)-[e:Act]->{1,3}(b:Movie) RETURN p LIMIT 3
'''

The preceding statement matches a variable-length path pattern that filters out the repeated edges.

Return:

+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| p                                                                                                                                                                |
+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| (288242801492099073@Actor:Person{birthDate:1971-09-02,id:5860,name:Stephan Grossmann})-[0@Act:Act{}]->(289254790276317185@Movie:Movie{id:434,name:Tough Enough}) |
| (288234568039792641@Actor:Person{birthDate:null,id:48481,name:Fabian Krüger})-[0@Act:Act{}]->(289254790276317185@Movie:Movie{id:434,name:Tough Enough})          |
| (288257142387900417@Actor:Person{birthDate:null,id:5857,name:Peter Bucksch})-[0@Act:Act{}]->(289254790276317185@Movie:Movie{id:434,name:Tough Enough})           |
+------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Specify path mode ACYCLIC to match paths without repeated nodes¶

When the path mode is specified as ACYCLIC, paths with repeated nodes are filtered out.

'''
USE movie
MATCH p = ACYCLIC (a@Actor)-[e:Act]->{1,3}(b:Movie) RETURN p LIMIT 3
'''

Return:

+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| p                                                                                                                                                                         |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| (288500052853260289@Actor:Person{birthDate:null,id:271947,name:Dino Zamboni})-[0@Act:Act{}]->(289154137717735425@Movie:Movie{id:335,name:Once Upon A Time In The West})   |
| (288496835922755585@Actor:Person{birthDate:null,id:271934,name:Marilù Carteny})-[0@Act:Act{}]->(289154137717735425@Movie:Movie{id:335,name:Once Upon A Time In The West}) |
| (288492558135328770@Actor:Person{birthDate:null,id:108398,name:Al Mulock})-[0@Act:Act{}]->(289154137717735425@Movie:Movie{id:335,name:Once Upon A Time In The West})      |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Specify match mode DIFFERENT to match paths without repeated edges¶

When the match mode starts with the keyword DIFFERENT, paths with repeated edges are filtered out.

'''
USE movie
MATCH DIFFERENT EDGES p= (a:Movie)-[e]-{0,2}(b) RETURN p, length(p) AS l LIMIT 5
'''

Return:

+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---+
| p                                                                                                                                                                        | l |
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---+
| (289259673654132737@Movie:Movie{id:614,name:Wild Strawberries})<-[0@Act:Act{}]-(288256055761174529@Actor:Person{birthDate:1916-05-06,id:180694,name:Sif Ruud})           | 1 |
| (289319098821640193@Movie:Movie{id:302,name:Swimming Pool})<-[0@Act:Act{}]-(288236526544879617@Actor:Person{birthDate:null,id:4398,name:Erarde Forestali})               | 1 |
| (289298959719989249@Movie:Movie{id:18,name:The 5th Element})<-[0@Act:Act{}]-(288231381174059009@Actor:Person{birthDate:null,id:169371,name:George Khan})                 | 1 |
| (289123411521699841@Movie:Movie{id:258,name:Bed and Board})<-[0@Act:Act{}]-(288251692074401793@Actor:Person{birthDate:null,id:3579,name:Danièle Girard})                 | 1 |
| (289286641753784321@Movie:Movie{id:221,name:Rebel without a Cause})<-[0@Act:Act{}]-(288250841670877185@Actor:Person{birthDate:1883-06-11,id:2780,name:Virginia Brissac}) | 1 |
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---+

Match all paths between each pair of nodes that match the pattern¶

'''
USE movie
MATCH p = ALL (a@Actor{id:134060})-[e:Act]-{1,3}(b:Movie) RETURN p
'''

The preceding statement matches all paths between each pair of nodes that match the pattern.

Return:

+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| p                                                                                                                                                                                                                                                                                                                                                 |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289240870287310849@Movie:Movie{id:298,name:Ocean's Thirteen})<-[0@Act:Act{}]-(288291721169600513@Actor:Person{birthDate:1970-10-08,id:1892,name:Matt Damon})-[0@Act:Act{}]->(289200227011788801@Movie:Movie{id:489,name:mente indomable})    |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289240870287310849@Movie:Movie{id:298,name:Ocean's Thirteen})<-[0@Act:Act{}]-(288299211592564737@Actor:Person{birthDate:1975-08-12,id:1893,name:Casey Affleck})-[0@Act:Act{}]->(289200227011788801@Movie:Movie{id:489,name:mente indomable}) |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289240870287310849@Movie:Movie{id:298,name:Ocean's Thirteen})<-[0@Act:Act{}]-(288343033143885825@Actor:Person{birthDate:1940-04-25,id:1158,name:Al Pacino})-[0@Act:Act{}]->(289197740225724417@Movie:Movie{id:240,name:The Godfather II})    |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289240870287310849@Movie:Movie{id:298,name:Ocean's Thirteen})<-[0@Act:Act{}]-(288248818741280769@Actor:Person{birthDate:1959-03-16,id:1906,name:Scott L. Schwartz})-[0@Act:Act{}]->(289192942747254785@Movie:Movie{id:557,name:Spiderman})   |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289240870287310849@Movie:Movie{id:298,name:Ocean's Thirteen})<-[0@Act:Act{}]-(288507972772954113@Actor:Person{birthDate:1963-12-18,id:287,name:Brad Pitt})-[0@Act:Act{}]->(289148695994171393@Movie:Movie{id:63,name:12 Monkeys})            |
...
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Got 171 rows (time spent 25.504ms/27.461934ms)

Match any two paths between each pair of nodes that match the pattern¶

'''
USE movie
MATCH p= ANY 2 (a@Actor{id:134060})-[e:Act]-{1,3}(b:Movie) RETURN p
'''

The preceding statement matches any two paths between each pair of nodes that match the pattern.

Return:

+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| p                                                                                                                                                                                                                                                                                                                                                                                 |
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289100304597647361@Movie:Movie{id:193,name:Star Trek: Generations})<-[0@Act:Act{}]-(288242427829944321@Actor:Person{birthDate:1949-02-02,id:2389,name:Brent Spiner})-[0@Act:Act{}]->(289283845730074625@Movie:Movie{id:200,name:Star Trek: Insurrection})                    |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289100304597647361@Movie:Movie{id:193,name:Star Trek: Generations})<-[0@Act:Act{}]-(288279575002087425@Actor:Person{birthDate:1940-07-13,id:2387,name:Patrick Stewart})-[0@Act:Act{}]->(289283845730074625@Movie:Movie{id:200,name:Star Trek: Insurrection})                 |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289240870287310849@Movie:Movie{id:298,name:Ocean's Thirteen})<-[0@Act:Act{}]-(288507972772954113@Actor:Person{birthDate:1963-12-18,id:287,name:Brad Pitt})-[0@Act:Act{}]->(289148695994171393@Movie:Movie{id:63,name:12 Monkeys})                                            |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289240870287310849@Movie:Movie{id:298,name:Ocean's Thirteen})<-[0@Act:Act{}]-(288343033143885825@Actor:Person{birthDate:1940-04-25,id:1158,name:Al Pacino})-[0@Act:Act{}]->(289182480206921729@Movie:Movie{id:242,name:The Godfather Coda: The Death of Michael Corleone})   |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289240870287310849@Movie:Movie{id:298,name:Ocean's Thirteen})<-[0@Act:Act{}]-(288467131928936449@Actor:Person{birthDate:1956-04-12,id:1271,name:Andy Garcia})-[0@Act:Act{}]->(289182480206921729@Movie:Movie{id:242,name:The Godfather Coda: The Death of Michael Corleone}) |
...
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Got 39 rows (time spent 22.282ms/22.971691ms)

Match all shortest paths between each pair of nodes that match the pattern¶

'''
USE movie
MATCH p = ALL SHORTEST (a@Actor{id:134060})-[e:Act]-{1,3}(b:Movie) RETURN p
'''

The preceding statement matches all shortest paths between each pair of nodes that match the pattern.

Return:

+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| p                                                                                                                                                                                                                                                                                                                                                            |
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289100304597647361@Movie:Movie{id:193,name:Star Trek: Generations})<-[0@Act:Act{}]-(288475601604444161@Actor:Person{birthDate:1955-11-13,id:2395,name:Whoopi Goldberg})-[0@Act:Act{}]->(289114817292140545@Movie:Movie{id:201,name:Star Trek: Nemesis}) |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289100304597647361@Movie:Movie{id:193,name:Star Trek: Generations})<-[0@Act:Act{}]-(288415549371711489@Actor:Person{birthDate:1949-03-02,id:2392,name:Gates McFadden})-[0@Act:Act{}]->(289114817292140545@Movie:Movie{id:201,name:Star Trek: Nemesis})  |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289100304597647361@Movie:Movie{id:193,name:Star Trek: Generations})<-[0@Act:Act{}]-(288404275082559489@Actor:Person{birthDate:1957-02-16,id:2390,name:LeVar Burton})-[0@Act:Act{}]->(289114817292140545@Movie:Movie{id:201,name:Star Trek: Nemesis})    |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289100304597647361@Movie:Movie{id:193,name:Star Trek: Generations})<-[0@Act:Act{}]-(288317830275792897@Actor:Person{birthDate:1952-12-09,id:2391,name:Michael Dorn})-[0@Act:Act{}]->(289114817292140545@Movie:Movie{id:201,name:Star Trek: Nemesis})    |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289100304597647361@Movie:Movie{id:193,name:Star Trek: Generations})<-[0@Act:Act{}]-(288448809598451713@Actor:Person{birthDate:1955-03-29,id:2393,name:Marina Sirtis})-[0@Act:Act{}]->(289114817292140545@Movie:Movie{id:201,name:Star Trek: Nemesis})   |
...
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Got 77 rows (time spent 200.31ms/201.743343ms)

Specify ANY SHORTEST to match any shortest path between each pair of nodes that match the pattern¶

'''
USE movie
MATCH p= ANY SHORTEST (a@Actor{id:134060})-[e:Act]-{1,3}(b:Movie) RETURN p
'''

The preceding statement matches any shortest path between each pair of nodes that match the pattern.

Return:

+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| p                                                                                                                                                                                                                                                                                                                                                                             |
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289100304597647361@Movie:Movie{id:193,name:Star Trek: Generations})<-[0@Act:Act{}]-(288242427829944321@Actor:Person{birthDate:1949-02-02,id:2389,name:Brent Spiner})-[0@Act:Act{}]->(289114817292140545@Movie:Movie{id:201,name:Star Trek: Nemesis})                     |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289100304597647361@Movie:Movie{id:193,name:Star Trek: Generations})<-[0@Act:Act{}]-(288245734954762241@Actor:Person{birthDate:1920-03-03,id:1751,name:James Doohan})-[0@Act:Act{}]->(289110225972101121@Movie:Movie{id:174,name:Star Trek VI: The Undiscovered Country}) |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289100304597647361@Movie:Movie{id:193,name:Star Trek: Generations})                                                                                                                                                                                                      |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289100304597647361@Movie:Movie{id:193,name:Star Trek: Generations})<-[0@Act:Act{}]-(288245734954762241@Actor:Person{birthDate:1920-03-03,id:1751,name:James Doohan})-[0@Act:Act{}]->(289172554537500673@Movie:Movie{id:154,name:Star Trek: The Wrath of Khan})           |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289240870287310849@Movie:Movie{id:298,name:Ocean's Thirteen})<-[0@Act:Act{}]-(288507972772954113@Actor:Person{birthDate:1963-12-18,id:287,name:Brad Pitt})-[0@Act:Act{}]->(289078181221105665@Movie:Movie{id:628,name:Interview with the Vampire})                       |
...
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Got 25 rows (time spent 204.379ms/205.327694ms)

Specify SHORTEST 1 to match any shortest path between each pair of nodes that match the pattern¶

'''
USE movie
MATCH p= SHORTEST 1 (a@Actor{id:134060})-[e:Act]-{1,3}(b:Movie) RETURN p
'''

The preceding statement matches any shortest path between each pair of nodes that match the pattern.

Return:

+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| p                                                                                                                                                                                                                                                                                                                                                                        |
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289100304597647361@Movie:Movie{id:193,name:Star Trek: Generations})<-[0@Act:Act{}]-(288475601604444161@Actor:Person{birthDate:1955-11-13,id:2395,name:Whoopi Goldberg})-[0@Act:Act{}]->(289114817292140545@Movie:Movie{id:201,name:Star Trek: Nemesis})             |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289100304597647361@Movie:Movie{id:193,name:Star Trek: Generations})<-[0@Act:Act{}]-(288439811641966593@Actor:Person{birthDate:null,id:133761,name:Judy Levitt})-[0@Act:Act{}]->(289110225972101121@Movie:Movie{id:174,name:Star Trek VI: The Undiscovered Country}) |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289100304597647361@Movie:Movie{id:193,name:Star Trek: Generations})                                                                                                                                                                                                 |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289240870287310849@Movie:Movie{id:298,name:Ocean's Thirteen})<-[0@Act:Act{}]-(288427532330467329@Actor:Person{birthDate:1964-11-29,id:1896,name:Don Cheadle})-[0@Act:Act{}]->(289086826990272513@Movie:Movie{id:205,name:Ashley Palacios})                          |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289240870287310849@Movie:Movie{id:298,name:Ocean's Thirteen})<-[0@Act:Act{}]-(288299211592564737@Actor:Person{birthDate:1975-08-12,id:1893,name:Casey Affleck})-[0@Act:Act{}]->(289200227011788801@Movie:Movie{id:489,name:mente indomable})                        |
...
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Got 25 rows (time spent 178.729ms/179.511682ms)

Match the shortest two paths between each pair of nodes that match the pattern¶

'''
USE movie
MATCH p= SHORTEST 2 (a@Actor{id:134060})-[e:Act]-{1,3}(b:Movie) RETURN p
'''

The preceding statement matches any two shortest paths between each pair of nodes that match the pattern.

Return:

+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| p                                                                                                                                                                                                                                                                                                                                                                             |
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289100304597647361@Movie:Movie{id:193,name:Star Trek: Generations})                                                                                                                                                                                                      |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289240870287310849@Movie:Movie{id:298,name:Ocean's Thirteen})                                                                                                                                                                                                            |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289100304597647361@Movie:Movie{id:193,name:Star Trek: Generations})<-[0@Act:Act{}]-(288388491077746689@Actor:Person{birthDate:1936-09-14,id:1754,name:Walter Koenig})-[0@Act:Act{}]->(289078829761167361@Movie:Movie{id:157,name:Star Trek III: The Search for Spock})   |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289100304597647361@Movie:Movie{id:193,name:Star Trek: Generations})<-[0@Act:Act{}]-(288372067122806785@Actor:Person{birthDate:1931-03-22,id:1748,name:William Shatner})-[0@Act:Act{}]->(289078829761167361@Movie:Movie{id:157,name:Star Trek III: The Search for Spock}) |
| (288348049665687553@Actor:Person{birthDate:1960-05-31,id:134060,name:Tommy Hinkley})-[0@Act:Act{}]->(289100304597647361@Movie:Movie{id:193,name:Star Trek: Generations})<-[0@Act:Act{}]-(288475601604444161@Actor:Person{birthDate:1955-11-13,id:2395,name:Whoopi Goldberg})-[0@Act:Act{}]->(289114817292140545@Movie:Movie{id:201,name:Star Trek: Nemesis})                  |
...
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Got 37 rows (time spent 155.32ms/156.292194ms)

Match multiple patterns¶

Match multiple node patterns¶

'''
USE movie
MATCH (a@Actor),(b@Movie)
WHERE EXISTS {(a)-[:Act]->(b)}
RETURN a.name, b.name LIMIT 3
'''

The preceding statement matches two types of nodes that match the specified patterns.

Return:

+--------------------+------------------------+
| a.name             | b.name                 |
+--------------------+------------------------+
| Sieghardt Rupp     | A Fistful of Dollars   |
| Sammi Davis        | Four Rooms and a Hotel |
| Martin Spang Olsen | In China They Eat Dogs |
+--------------------+------------------------+

Match multiple edge patterns¶

'''
USE movie
MATCH ()-[e1:Watch]->(b), (c)-[e2:WithGenre]->()
WHERE b.id = c.id AND e1.rate >= 4
RETURN DISTINCT b.name, e1.rate  LIMIT 5
'''

The preceding statement matches two types of edges that match the specified patterns.

Return:

+------------------------+---------+
| b.name                 | e1.rate |
+------------------------+---------+
| Wild Strawberries      | 4.5     |
| Saw III                | 4.5     |
| Saw III                | 5.0     |
| In China They Eat Dogs | 4.0     |
| Rashomon               | 4.0     |
+------------------------+---------+

Match multiple path patterns¶

'''
USE movie
MATCH p1 = (a:Person{id:5498})-[e1:Act]->(b), p2= (b)-[e2:WithGenre]->(d) RETURN p1, p2 
'''

The preceding statement matches two types of paths that match the specified patterns.

Return:

+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| p1                                                                                                                                                                  | p2                                                                                                                                                      |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| (288372217446662145@Actor:Person{birthDate:1974-01-25,id:5498,name:Adam Bousdoukos})-[0@Act:Act{}]->(289212884280410113@Movie:Movie{id:407,name:Short Sharp Shock}) | (289212884280410113@Movie:Movie{id:407,name:Short Sharp Shock})-[0@WithGenre:WithGenre{}]->(289476741301272578@Genre:Genre{id:87,name:Low Budget Film}) |
| (288372217446662145@Actor:Person{birthDate:1974-01-25,id:5498,name:Adam Bousdoukos})-[0@Act:Act{}]->(289212884280410113@Movie:Movie{id:407,name:Short Sharp Shock}) | (289212884280410113@Movie:Movie{id:407,name:Short Sharp Shock})-[0@WithGenre:WithGenre{}]->(289576822629203970@Genre:Genre{id:53,name:Thriller})        |
| (288372217446662145@Actor:Person{birthDate:1974-01-25,id:5498,name:Adam Bousdoukos})-[0@Act:Act{}]->(289212884280410113@Movie:Movie{id:407,name:Short Sharp Shock}) | (289212884280410113@Movie:Movie{id:407,name:Short Sharp Shock})-[0@WithGenre:WithGenre{}]->(289596025427984386@Genre:Genre{id:707,name:Tragedy})        |
| (288372217446662145@Actor:Person{birthDate:1974-01-25,id:5498,name:Adam Bousdoukos})-[0@Act:Act{}]->(289212884280410113@Movie:Movie{id:407,name:Short Sharp Shock}) | (289212884280410113@Movie:Movie{id:407,name:Short Sharp Shock})-[0@WithGenre:WithGenre{}]->(289611968346587137@Genre:Genre{id:866,name:Teen Film})      |
| (288372217446662145@Actor:Person{birthDate:1974-01-25,id:5498,name:Adam Bousdoukos})-[0@Act:Act{}]->(289212884280410113@Movie:Movie{id:407,name:Short Sharp Shock}) | (289212884280410113@Movie:Movie{id:407,name:Short Sharp Shock})-[0@WithGenre:WithGenre{}]->(289631476088045571@Genre:Genre{id:33,name:Romance Film})    |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+

Optional match¶

The following examples demonstrate how to perform optional matches by specifying the keyword OPTIONAL.

Specify OPTIONAL to match a non-existent node¶

'''
USE movie
OPTIONAL MATCH (v:NotExistLabel) RETURN v
'''

The preceding statement fails to match any node with the label NotExistLabel and returns an error as the result.

Return:

Error: [NS228]: node label `NotExistLabel` not found in graph type `movie_type`

Match a non-existent node without specifying OPTIONAL¶

'''
USE movie
MATCH (v:NotExistLabel) RETURN v
'''

The preceding statement fails to match any node with the label NotExistLabel and returns an error.

Return:

Error: [NS228]: node label `NotExistLabel` not found in graph type `movie_type`

Use match and optional match together¶

'''
USE movie
MATCH (b:Genre{id:87}) 
OPTIONAL MATCH p = (a:Movie{id:2000})-[e]->(b) 
RETURN b, p
'''

The preceding statement first matches a node and then matches a path using OPTIONAL MATCH. Since no path that matches the pattern exists, the result is null.

Return:

+----------------------------------------------------------------+------+
| b                                                              | p    |
+----------------------------------------------------------------+------+
| (289476741301272578@Genre:Genre{id:87,name:"Low Budget Film"}) | null |
+----------------------------------------------------------------+------+

MATCH statement¶

Prerequisites¶

Syntax¶

Parameters¶

OPTIONAL¶

match_mode¶

path_variable¶

WALK | TRAIL | SIMPLE | ACYCLIC¶

PATH | PATHS¶

ALL | ANY | ALL SHORTEST | ANY SHORTEST¶

number_of_paths¶

element_pattern¶

node_pattern¶

edge_pattern¶

index_hint¶

graph_pattern_quantifier¶

search_condition¶

element_variable_reference¶

path_variable_reference¶

Element type queries vs. label queries¶

Variables in labels and element types¶

Examples¶

Match by node patterns¶

Match nodes by a node variable¶

Match nodes by a label¶

Match nodes by multiple labels¶

Match nodes by a variable label¶

Match nodes by a label and a search condition¶

Match nodes by a node property¶

Match nodes by a node type¶

Match nodes by multiple node types¶

Match nodes by a variable node type¶

Use a previous query result as a node type¶

Match by edge patterns¶

Match edges by an edge variable¶

Match edges by a label¶

Match edges by multiple labels¶

Match edges by a variable label¶

Match edges by a label and a search condition¶

Match edges by an edge property¶

Match edges by an edge type¶

Match edges by a variable edge type¶

Match edges by edge types¶

Match incoming edges¶

Match undirected edges¶

Match undirected and incoming edges¶

Match outgoing and incoming edges¶

Match edges with any direction¶

Match by quantified edge patterns¶

Match by path patterns¶

Match nodes by a simple path pattern¶

Match nodes by a complex path pattern¶

Match by quantified path patterns¶

Match and return variable-length paths¶

Specify path mode TRAIL to match paths without repeated edges¶

Specify path mode ACYCLIC to match paths without repeated nodes¶

Specify match mode DIFFERENT to match paths without repeated edges¶

Match all paths between each pair of nodes that match the pattern¶

Match any two paths between each pair of nodes that match the pattern¶

Match all shortest paths between each pair of nodes that match the pattern¶

Specify ANY SHORTEST to match any shortest path between each pair of nodes that match the pattern¶

Specify SHORTEST 1 to match any shortest path between each pair of nodes that match the pattern¶

Match the shortest two paths between each pair of nodes that match the pattern¶

Match multiple patterns¶

Match multiple node patterns¶

Match multiple edge patterns¶

Match multiple path patterns¶

Optional match¶

Specify OPTIONAL to match a non-existent node¶

Match a non-existent node without specifying OPTIONAL¶

Use match and optional match together¶

`OPTIONAL`¶

`match_mode`¶

`path_variable`¶

`WALK | TRAIL | SIMPLE | ACYCLIC`¶

`PATH | PATHS`¶

`ALL | ANY | ALL SHORTEST | ANY SHORTEST`¶

`number_of_paths`¶

`element_pattern`¶

`node_pattern`¶

`edge_pattern`¶

`index_hint`¶

`graph_pattern_quantifier`¶

`search_condition`¶

`element_variable_reference`¶

`path_variable_reference`¶