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

# GPML

> Graph Pattern Matching Language (GPML)

# Background

The International Standards Committee Working Group develops the [GQL](https://gql.net) standard for Database Languages (WG3), which is also responsible for maintaining and enhancing SQL. This team consists of experts from both academia and industry. The SQL/PGQ (Property Graph Queries) part is a new addition to the SQL standard, which was developed alongside [GQL](https://gql.net). [GQL](https://gql.net) is a property graph query language. In [GQL](https://gql.net), a property graph can be an undirected graph, a directed graph, or a combination of both: partially directed.

# Graph Pattern Matching Language (GPML)

[Graph query languages](https://gql.net) extract data from a graph by matching a given graph pattern. This is accomplished using the Graph Pattern Matching Language (GPML), which enables you to define a set of path patterns. Such a path pattern maps graph vertices and edges to variables through variable binding, which can be used to reference graph elements, their labels and their properties. GPML, defined in [GQL](https://gql.net), draws much inspiration from the Open-Cypher query language. The overall way of writing a pattern-matching query in both languages is the same. To better understand how GPML works, let's take a brief tour of its core syntax. We will use the following Graph with `FRIEND` and `WATCHED` relationships to illustrate the syntax:

```mermaid theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

%%{init: {'theme':'base', 'themeVariables': {'lineColor':'#F1FA8C','secondaryColor':'#F1FA8C','background':'#282A36'}}}%%
graph TB

    subgraph row1[" "]
    Maryam(<b>:account 🧕</b><br/>name: Maryam)
    Sara(<b>:account 🧕</b><br/>name: Sara)
    Uroosa(<b>:account 🧕</b><br/>name: Uroosa)
    Fatima(<b>:account 🧕</b><br/>name: Fatima)
    Zainab(<b>:account 🧕</b><br/>name: Zainab)
    Hannah(<b>:account 🧕</b><br/>name: Hannah)
    end

    subgraph row2[" "]
    despicable_me(<b>:movie 🎬</b><br/>name: Despicable Me)
    penguins_of_madagascar(<b>:movie 🎬</b><br/>name: Penguins of Madagascar)
    time_hoppers(<b>:movie 🎬</b><br/>name: Time Hoppers)
    zootopia(<b>:movie 🎬</b><br/>name: Zootopia)
    end


    Sara <-->|<b>:friend</b>| Uroosa
    Uroosa <-->|<b>:friend</b>| Maryam
    Maryam <-->|<b>:friend</b>| Fatima
    Zainab <-->|<b>:friend</b>| Hannah
    Sara -->|<b>:watched 👀</b>| zootopia
    Uroosa -->|<b>:watched 👀</b>| penguins_of_madagascar
    Maryam -->|<b>:watched 👀</b>| time_hoppers
    Fatima -->|<b>:watched 👀</b>| time_hoppers
    Zainab -->|<b>:watched 👀</b>| time_hoppers
    Fatima -->|<b>:watched 👀</b>| despicable_me
    Hannah -->|<b>:watched 👀</b>| despicable_me



    classDef nodes fill:#BD93F9,stroke-width:0px
    class Maryam,Sara,Uroosa,Fatima,Hannah,Zainab,highway7,highway8,highway9,highway10,highway11,highway12,highway13 nodes
    
    classDef subgraphStyle fill:#282A36, stroke-width:0px
    class row1,row2,row3 subgraphStyle

```

GPML is designed to be intuitive and visual, often described as "ASCII-art" for graphs. At its most basic, a node is represented by parentheses and an edge is represented by square brackets. A variable can be assigned to a node to reference it later, like so: `(x)`. This pattern matches any single node in the graph, binding it to the variable `x`.

Labels and properties can be added to query more specific nodes. A node label specifies the type of the node and it is expressed with a colon as prefix. For example, `(x:ACCOUNT)` will only match nodes with the label `ACCOUNT`. We can further filter nodes by specifying key-value pairs, or properties, inside curly braces: `(x:ACCOUNT {name: 'Uroosa'})`. This pattern will only match `ACCOUNT` nodes where the `name` property is exactly `'Uroosa'`.

Edges are represented using arrows between nodes. A directed edge is drawn with `->` or `<-`, while undirected edges use a simple dash `-`. Similar to nodes, edges can be assigned variables, have labels (often called types), and contain properties. For example, `-[e:WATCHED]->` represents a directed edge bound to the variable `e` with the label `WATCHED`. An edge pattern also supports specifying a property filter similarly to how this is done for nodes. By combining these elements, we can form expressive path patterns. A complete pattern describes a sequence of nodes and the edges that connect them. For instance, the pattern:

```gql theme={null}
(a:ACCOUNT {name: 'Uroosa'})-[e:WATCHED]->(m:MOVIE)
```

searches for a specific `ACCOUNT` node named `'Uroosa'` (bound to `a`), connected by  `WATCHED` relationship (bound to `e`) to any other `MOVIE` node (bound to `m)`. This simple, declarative syntax allows users to easily express complex structural queries to retrieve data from the graph.

### Multi-hop traversal

Furthermore, these path patterns can be chained together to describe longer, more complex traversals. For example, the pattern:

```gql theme={null}
(a:ACCOUNT)-[:WATCHED]->(m:MOVIE)<-[:WATCHED]-(b:ACCOUNT)
```

would find all pairs of `ACCOUNT` that watched the same `MOVIE` `m`.

### Multiple patterns matching

A query can also contain multiple patterns, separated by a comma. This allows for reusing variables to create more complex conditions. For instance, the pattern:

```gql theme={null}
(a:ACCOUNT)-[:WATCHED]->(m:MOVIE)<-[:WATCHED]-(b:ACCOUNT)
, (a)-[:FRIEND]->(b)
```

extends the previous query to include a predicate such that `a` and `b` ALSO have a `FRIEND` relationship between them. This comma separated patterns effectively join the results of two distinct patterns on the common variables `a` and `b`.

### Variable-length path (quantified path pattern)

GPML also supports more advanced constructs to handle complex queries. One of the most powerful features is specifying variable-length paths using a quantifier in the edge pattern. For example, `(a)-[:FRIEND]->{1,}(b)` will find a path of any length greater than one between nodes `a` and `b` using only `FRIEND` relationships. Quantifiers can also specify bounds, such as `{2,5}` to match paths with a length between two and five edges.

### Path variable binding

Finally, an entire path can be bound to a variable, such as: `z = (a)-[:FRIEND]->{1,6}(b)` which allows the pattern to bind the whole sequence of nodes and edges that make up the path `z`.