> ## Documentation Index
> Fetch the complete documentation index at: https://gql.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# MATCH

> Ascii-art `()-[]->()` syntax for expressing patterns.

A [GQL](https://gql.net) query typically begins with the `MATCH` clause, which identifies a graph pattern to search for in the data. It is the foundation for querying nodes, relationships, and their properties. The `MATCH` clause specifies the structural shape of the subgraph being queried.

```gql theme={null}
MATCH (u: User)−[:PERFORMED]−>(e: Event {activity: 'Submit'})
```

In this example, the pattern searches for users who performed an event labeled "Submit". The nodes (`u`, `e`) are labeled with semantic roles, and the relationship `[:PERFORMED]` describes the interaction between them.

Patterns can include multiple relationships and variable-length traversals using the `{m,n}` quantifier. For example, `[:FOLLOWS]->{,3}` matches up to 3 levels of consecutive FOLLOWS relationships. The `MATCH` clause is frequently used in combination with [WHERE](/docs/querying/where), [RETURN](/docs/querying/return), and [WITH](/docs/querying/with) clauses to build complex queries.

## Variable Binding in GQL

Retrieve all the teachers who liked a comment made by students who they know since 2021 or earlier:

```mermaid theme={null}
%%{init: {'theme':'base', 'themeVariables': {'lineColor':'#F1FA8C','secondaryColor':'#F1FA8C','background':'#282A36'}}}%%
graph LR
    fatima[:Teacher <br/>name: Fatima 👩<br/>status: Active]
    uroosa[:Student <br/>name: Uroosa 👩<br/>status: Active]

    comment_1[:comment<br/>content: I love GQL<br/>comment_date:2025-01-01<br/>]

    fatima -->|:knowns<br/>since:2025| uroosa
    fatima -->|:likes| comment_1
    comment_1 -->|:author| uroosa

    classDef nodes fill:#BD93F9,stroke-width:0px
    class eva,fatima,angela,uroosa,eleni,scott nodes
	

    classDef subgraphStyle fill:#282A36, stroke-width:0px
    class row1,row2,row3 subgraphStyle
```

```gql theme={null}
MATCH path = (x:teacher)-[:likes ]->
(:comment)-[:author]->
(:student)-[y:knows WHERE y.since < 2021]->(x)
```

Here we are binding a `:teacher`-labelled node to the variable `x` and requiring there be a `:likes`-labelled edge to a node representing a `comment`. In GQL ASCII-art syntax, round brackets represent nodes, while square brackets represent edges. We then require this comment to have been made by a student (represented by an `:author` edge to a node with the label `student`). Finally, we require this student to have any edge to the original node bound to `x`, that this edge is labelled with `:knows` and that the value of its since attribute is greater than 2021

## Shortest Path

Find shortest path `path`, from a user `u1` to user `u2` traversing `:knows` edges 1+ (`{1,}`) times.

```mermaid theme={null}
%%{init: {'theme':'base', 'themeVariables': {'lineColor':'#F1FA8C','secondaryColor':'#F1FA8C','background':'#282A36'}}}%%
graph TB
    saqib[Saqib 👨]
    fatima[Fatima 👩]
    scott[Scott 👨]
    eleni[Eleni 👩]
    uroosa[Uroosa 👩]
    angela[Angela 👩]
    saqib -->|co-worker| fatima
    fatima -->|friend| eleni
    eleni -->|friend| uroosa
    saqib -->|friend| angela
    angela -->|co-worker| scott
    scott -->|friend| uroosa


    classDef nodes fill:#BD93F9,stroke-width:0px
    class saqib,fatima,angela,uroosa,eleni,scott nodes
	
```

```gql theme={null}
MATCH path = ANY SHORTEST (u1:users {username: "saqib"})-
[:knows]->{1,}(t2:users {username: "uroosa"})
RETURN u1.username, u2.username, path_length(p) AS num_hops
```

## Expressing complex queries using Multiple Paths

Find a pair of friends in the same city (`(y.city = x.city)`) who transfer money (`(account_x)−[t1:transfer]−>(account_z)−[t2:transfer]−>(account_y)`) to each other using a common friend who lives elsewhere (`(x.city<>z.city)`).

```mermaid theme={null}
%%{init: {'theme':'base', 'themeVariables': {'lineColor':'#F1FA8C','secondaryColor':'#F1FA8C','background':'#282A36'}}}%%
graph LR
    subgraph row1[" "]
    eva[Eva 👩<br/>Carmel, CA]
    eleni[Eleni 👩<br/>Santa Cruz, CA]
    angela[Angela 👩<br/>Carmel, CA]
    end

    subgraph row2[" "]
    account_1[Account 1<br/>type: savings<br/>balance: 1000]
    account_2[Account 2<br/>type: savings<br/>balance: 3000]
    account_3[Account 3<br/>type: checking<br/>balance: 500]
    end

    eva -->|owns| account_1
    eleni -->|owns| account_2
    angela -->|owns| account_3

    eva <-->|friends| angela
    eva <-->|friends| eleni
    eleni <-->|friends| angela



    account_1 -->|Transfer<br/>amount:20000<br/>timestamp:00001|account_2
    account_2 -->|Transfer<br/>amount:15000<br/>timestamp:00002|account_3

    classDef nodes fill:#BD93F9,stroke-width:0px
    class eva,fatima,angela,uroosa,eleni,scott nodes
	

    classDef subgraphStyle fill:#282A36, stroke-width:0px
    class row1,row2,row3 subgraphStyle

```

```gql theme={null}
MATCH (x:account_holder)−[:friends]−>(y:account_holder)−
[:friends]−>(z:account_holder)−
[:friends]−>(x:account_holder)
, (x)−[:owns]−>(account_x)
, (y)−[:owns]−>(account_y)
, (z)−[:owns]−>(account_z)
, (account_x)−[t1:transfer]−>(account_z)−[t2:transfer]−>(account_y)
FILTER (y.city = x.city) AND (x.city<>z.city)
RETURN x.name AS name1, y.name AS name2
```

This pattern consists of five path patterns, separated by a commas. In GQL, the comma performs a logical join on the results of the two path patterns.