Source: https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/patterns/edge-patterns/
Documentation version: v5.3.2

# Edge patterns

An edge pattern is a pattern used to match edges in a property graph. There are two types of edge patterns: full edge patterns and abbreviated edge patterns. A full edge pattern contains detailed matching rules, while an abbreviated edge pattern contains only the edge direction.

[]()

## Full edge patterns

A full edge pattern consists of one edge pattern filler and an edge direction to be matched. The edge pattern filler specifies the details of the edges to be matched, including the labels and properties of edges, functioning in the same way as a node pattern filler.

The supported components of an edge pattern filler are listed below in the order of appearance when they are used in declarations:

1. Edge variable
2. Label expression
3. Edge type specification
4. Edge property specification
5. `SAMPLE` clause
6. `WHERE` clause

When declaring an edge pattern filler containing multiple components, make sure the following conditions are met:

- Up to four components of different types can be used, among which:

  - One can be an edge variable.
  - One can be either a label expression or an edge type specification.
  - One can be either an edge property specification or a `WHERE` clause.
  - One can be a `SAMPLE` clause.

- The order of the components must follow the order of appearance listed above.

The following sections summarize the syntax options for declaring edge pattern fillers:

diagramsource

 edge_pattern_filler_with_edge_variable edge_pattern_filler_with_label_expression edge_pattern_filler_with_edge_type_specification edge_pattern_filler_with_edge_property_specification edge_pattern_filler_with_SAMPLE_clause edge_pattern_filler_with_WHERE_clause  

````
edge_pattern_filler_with_edge_variable ::=
    edge_variable 

edge_pattern_filler_with_label_expression ::= 
    ( ':' | 'IS' ) label_expression

edge_pattern_filler_with_edge_type_specification ::=
    '@' ( edge_type_name | '[' edge_type_name ( ',' edge_type_name ) * ']' )

edge_pattern_filler_with_edge_property_specification ::=
    '{' ( property_name ':' value_expression ) ( ',' ( property_name ':' value_expression ) ) * '}'

edge_pattern_filler_with_SAMPLE_clause ::=
    'SAMPLE' 'RIGHT'? sampling_method? sample_size    

edge_pattern_filler_with_WHERE_clause ::=
    'WHERE' search_condition  

````

There are 7 variants of edge direction declarations in total:

 | Direction | Declaration
 | Left | `<-[ edge_pattern_filler ]-`
 | Undirected | `~[ edge_pattern_filler ]~`
 | Right | `-[ edge_pattern_filler ]->`
 | Left or undirected | `<~[ edge_pattern_filler ]~`
 | Right or undirected | `~[ edge_pattern_filler ]~>`
 | Left or right | `<-[ edge_pattern_filler ]->`
 | Any direction | `-[ edge_pattern_filler ]-`

Note

The brackets (`[ ]`) are part of edge direction declarations and used to enclose edge pattern fillers. They are retained in the following syntax examples for clarity.

### Edge pattern filler with an edge variable

````
'[' edge_variable ']'

````

An edge pattern filler can be declared with an edge variable, which is a variable in the form of a regular identifier. For example, `[e]` is a simple edge pattern filler that would match any edges from a graph. All matched edges would be identified by this identifier `e` in the rest of the GQL query.

### Edge pattern filler with a label expression

````
'[' ( ':' | 'IS' ) label_expression ']'

````

- `label_expression`: A label expression.

A label expression could be used to declare an edge pattern filler matching edges with or without specific labels. To do so, the label expression could be declared with a colon (`:`) prefix or the keyword `IS`. For example, `[:Follow]` is an edge pattern that matches edges with the label `Follow`. Label expressions could be used to declare edge patterns independently without extra edge variables, in cases when the underlying edge pattern is only needed for matching edges whose values would not be referenced after the matching.

For more information, see [Label expressions](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/expressions/label/).

Note

In `MATCH` statements, when an edge 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dql/match/).

Examples:

- Match edges with a single label:

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

````

- Match edges with the label `Act` or `Direct` using the disjunction operator (`|`):

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

````

- Exclude edges with the label `Act` using the negation operator (`!`):

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

````

### Edge pattern filler with an edge type specification

````
'[' '@' ( edge_type_name | '[' edge_type_name ( ',' edge_type_name ) * ']' ) ']'

````

- `edge_type_name`: The name of an edge type.

Edge pattern fillers could be declared with one or multiple edge type specifications. An edge type specification is an edge type name prefixed with the `@` symbol. For example, `[@Watch]` is an edge pattern that matches edges of the edge type `Watch`. You can also specify multiple edge type specifications. For example, `[@[Watch, Act]]` is an edge pattern that matches edges of the edge types `Watch` or `Act`.

Note

In `MATCH` statements, when an edge pattern specifies an edge type, the edge type can also be provided by a string variable. For example, see [MATCH statement](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dql/match/).

Examples:

- Match edges by a single edge type:

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

````

- Match edges by multiple edge types:

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

````

#### Edge type queries vs. label queries

For the general rules behind `@edge_type_name` and `:label` / `IS LABELED`, see [Graph patterns](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/patterns/).

In edge patterns, the most common practical difference is:

- `MATCH ()-[e@Watch]->()` matches one specific edge type.
- `MATCH ()-[e:Watch]->()` can match edges across multiple edge types that share the same label.

When the label appears inside an edge pattern, it uses edge-pattern syntax, such as `[e:Watch]` or `[e IS Watch]`. When the label appears in a `WHERE` clause, it uses labeled-predicate syntax, such as `WHERE e IS LABELED Watch`; `WHERE e:Watch` is also valid as a shorthand.

If a graph model happens to use the same name for both the edge type and the label, the two forms may return the same results. If multiple edge types reuse the same label, however, the result scopes differ.

### Edge pattern filler with an edge property specification

````
'[' '{' ( property_name ':' value_expression ) ( ',' ( property_name ':' value_expression ) ) * '}' ']'

````

- `property_name`: The property name.
- `value_expression`: A value expression.

Edge 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 an edge pattern filler to match edges with an `id` property that equals 1 and a `name` property that equals `Bob`. And, `[e{id:1}]` equals `[e WHERE e.id = 1]`.

### Edge pattern filler with a SAMPLE clause

````
'[' 'SAMPLE' 'RIGHT'? sampling_method? sample_size ']'

````

- `sampling_method`: The sampling method.
- `sample_size`: The sample size.

Edge pattern fillers could be declared with a `SAMPLE` clause to sample edges. For example, `[SAMPLE RIGHT 2]` samples the first 2 edges for each sampling context.

For more information, see [SAMPLE clause](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dql/clauses/sample/).

### Edge pattern filler with a WHERE clause

````
'[' 'WHERE' search_condition ']'

````

- `search_condition`: The search condition.

Edge pattern fillers could be declared with a `WHERE` clause containing a search condition. For example, `[WHERE true]` and `[WHERE false]` match all and none edges, respectively. `[e WHERE e.id = 1]` matches edges `e` whose `id` property equals 1.

For more information, see [WHERE clause](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dql/clauses/where/).

### Examples

The following example shows how to declare edge patterns with different edge directions in a path pattern from a GQL query:

````
MATCH 
    (v1)<-[e]-(v2), # v1 and v2 connected by the edge e pointing at v1
    (v1)~[e]~(v2),  # v1 and v2 connected by the undirected edge e
    (v1)-[e]->(v2), # v1 and v2 connected by the edge e pointing at v2
    (v1)<~[e]~(v2), # v1 and v2 connected by the edge e pointing at v1 or undirected
    (v1)~[e]~>(v2), # v1 and v2 connected by the edge e pointing at v2 or undirected
    (v1)<-[e]->(v2), # v1 and v2 connected by the edge e pointing at either v1 or v2
    (v1)-[e]-(v2)   # v1 and v2 connected by the edge e with any direction
RETURN *

````

The following example shows how to declare edge patterns with different edge pattern fillers:

````
MATCH
    (v1)<-[e:Watch]-(v2),                    # v1 and v2 connected by the edge e with the label Watch
    (v1)<-[e IS Watch]-(v2),                 # v1 and v2 connected by the edge e with the label Watch
    (v1)<-[e:Watch{rate:3}]-(v2),            # v1 and v2 connected by the edge e with the label Watch and a property rate whose value is specified
    (v1)<-[e:Watch WHERE e.rate = 3]-(v2),   # v1 and v2 connected by the edge e with the label Watch and a property rate whose value is specified in a WHERE clause
    (v1)<-[e@Watch]-(v2),                    # v1 and v2 connected by the edge e of the edge type Watch
    (v1)<-[e:Watch SAMPLE RIGHT 2]-(v2)     # v1 and v2 connected by the edge e with the label Watch and samples the first 2 edges
RETURN e

````

## Abbreviated edge patterns

Abbreviated edge patterns declare edge directions without any edge pattern filler.

The following table lists the meaning of the symbols:

 | Symbol | Meaning
 | `<-` | Edge pointing left
 | `~` | Edge undirected
 | `->` | Edge pointing right
 | `<~` | Edge pointing left or undirected
 | `~>` | Edge pointing right or undirected
 | `<->` | Edge pointing left or right
 | `-` | Edge with any direction

The following example shows how abbreviated edge patterns could be used in a path pattern from a GQL query.

### Examples

````
MATCH 
    (v1)<-(v2),     # v1 and v2 connected by edges pointing at v1
    (v1)~(v2),      # v1 and v2 connected by undirected edges
    (v1)->(v2),     # v1 and v2 connected by edges pointing at v2
    (v1)<~(v2),     # v1 and v2 connected by edges pointing at v1 or undirected edges
    (v1)~>(v2),     # v1 and v2 connected by edges pointing at v2 or undirected edges
    (v1)<->(v2),    # v1 and v2 connected by edges pointing at either v1 or v2
    (v1)-(v2)       # v1 and v2 connected by edges with any direction
RETURN *

````