Source: https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/patterns/path-patterns/ Documentation version: v5.3.2 # Path patterns Path patterns match paths from graphs. A path pattern consists of the following parts: ```` path_variable_declaration? ( path_mode_prefix | path_search_prefix )? path_pattern_expression ```` - An optional path variable declaration (`path_variable_declaration`). A path variable is a regular variable binding to matched paths. - An optional path pattern prefix. A path pattern prefix could be a path mode prefix (`path_mode_prefix`) or a path search prefix (`path_search_prefix`) indicating whether the path matching is trying to find all, any or the shortest paths. - A path pattern expression (`path_pattern_expression`). ## Path mode prefixes A path mode prefix consists of a path mode and an optional postfix of either `PATH` or `PATHS`. The path mode specifies the type of paths to be matched. The following table introduces the different path modes: | Path mode | Meaning | `WALK` | The default mode with no filters for nodes and edges of any kind | `TRAIL` | Paths with repeated edges are filtered out | `ACYCLIC` | Paths with repeated nodes are filtered out | `SIMPLE` | Paths with repeated nodes are filtered out unless they are either the first or the last nodes in the path ## Path search prefixes A path search prefix, which is used to specify the number of paths to be returned, may consist of one of the keywords: `ALL`, `ANY`, `ALL SHORTEST`, `ANY SHORTEST`, and `SHORTEST`, an optional number of paths to be returned (`number_of_paths`), and an optional path mode (`path_mode`). The following table introduces the path search prefixes: | Path search prefix | Meaning | `ALL` `path_mode?` | Return all paths that meet the optional path mode requirement. | `ANY` `number_of_paths?` `path_mode?` | Non-deterministically return some paths that meet the optional path mode requirement. An optional number of paths to be returned could be specified. When the number of paths is not specified, the default number is 1. | `ALL SHORTEST` `path_mode?` | Return all shortest paths that meet the optional path mode requirement. | `ANY SHORTEST` `path_mode?` | Match all start and end nodes that meet the optional path mode requirement, and return one shortest path for each pair of start and end nodes. | `SHORTEST` `number_of_paths?` `path_mode?` | Match all start and end nodes that meet the optional path mode requirement, and return the specified number of shortest paths for each pair of start and end nodes. When the number of paths is not specified, the default number is 1. ## Path pattern expressions A path pattern expression specifies a pattern to match paths from a graph. ### Fixed-length path pattern expressions A fixed-length path pattern expression in the current implementation can be one of the following: - With at least one [node pattern](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/patterns/node-patterns/). For example, `(v)`. - Starting and ending with a node pattern. For example, `(v1)->(v2)`. - Alternating between node patterns and [edge patterns](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/patterns/edge-patterns/). For example, `()-[e1]->()-[e2]->(v1)<-[]-(v2)`. ### Variable-length path pattern expressions By suffixing an edge pattern or a parenthesized path pattern with a graph pattern quantifier, you can specify the number of times the pattern is allowed to occur in a path, which forms a variable-length path pattern expression. Variable-length path pattern expressions can take one of the following forms: - Starting and ending with a node pattern, and including a quantified edge pattern, which is an edge pattern followed by a graph pattern quantifier. For example: `(v1)-[e]->{1,3}(v2)`, where `-[e]->{1,3}` is the quantified edge pattern. - Starting and ending with a node pattern, and including a quantified path pattern, which is a path pattern followed by a graph pattern quantifier and enclosed within a pair of parentheses. For example, in `(a) ((n)-[e1]->()-[e2]->(m)){1,3} (b)`: - `((n)-[e1]->()-[e2]->(m)){1,3}` is the quantified path pattern. - `n` represents a list of nodes that always contains the source node `a`. - `m` represents a list of nodes that always contains the destination node `b`. Note A quantified path pattern must include at least one edge pattern. When a quantified path pattern has only one edge pattern, it can be simplified to a quantified edge pattern. For example, `(()-[e]->()){1,3}` can be simplified to `-[e]->{1,3}`. Parenthesized path patterns are used to group path patterns so that graph pattern quantifiers can be used within the path pattern. `(()-[e]->()){1,3}` indicates that the path pattern `()-[e]->()` within the parentheses must occur at least `1` time and at most `3` times. The following table introduces the meaning of different graph pattern quantifiers: | Graph pattern quantifier | Meaning | * | 0 or more times | + | 1 or more times | { fixed_number } | A fixed number of times, which must be greater than 0. | { lower_bound , upper_bound } | Any number of times in the bounded range. Both the lower and upper bounds are optional. When not specified, the default lower and upper bounds are 0 or the positive infinity, respectively. ### Expressions The following table shows some examples of path pattern expressions. | Examples | Meaning | `(v)` | A path containing a single node pattern | `(v1)-[e]->(v2)` | A path pattern containing two node patterns connected by an edge pattern | `()-[e]->()` | A path pattern similar to the above but with only one edge variable | `()-[e1]->()-[e2]->(v1)<-[]-(v2)` | A path pattern with 4 node patterns and 3 edge patterns connecting the node patterns | `(v1)<-[e]->*(v2)` | A path between `v1` and `v2` with 0 or more edges | `(v1)<-[e]->+(v2)` | A path between `v1` and `v2` with 1 or more edges | `(v1)<-[e]->{1,10}(v2)` | A path between `v1` and `v2` with some number of edges, the number of which is within the range of [1, 10] | `(v1) (()-[e1]->()-[e2]->()){1,3} (v2)` | A path between `v1` and `v2` that consists of 2, 4, or 6 edges, where the path `()-[e1]->()-[e2]->()` appears at least 1 time and at most 3 times. ## Examples The following example finds 1 shortest path satisfying a path pattern with two node patterns and one edge pattern. The required path mode is `WALK`, meaning the same nodes and edges could appear multiple times. ```` ''' MATCH p=SHORTEST 1 WALK PATH (person1:Person{id:1})<-[e:FOLLOWS]->*(person2:Person{id:3}) RETURN collect(e) AS l GROUP BY () ''' ```` - `p=` is the path variable declaration, used to reference the matched path. - `MATCH SHORTEST 1 WALK PATH` specifies the path pattern prefix of the query, which indicates that it searches for a shortest path, and the path type is `WALK`. - `(person1:Person{id:1})<-[e:FOLLOWS]->*(person2:Person{id:3})` specifies the path pattern, which indicates the path from `person1` to `person2` via the `FOLLOWS` relationship, where `*` indicates that the `FOLLOWS` relationship can occur zero or more times. For more information, see [MATCH statement](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dql/match/).