# ISO GQL


## 1.Introduction to ISO GQL

Graph Query Language (GQL) is an upcoming International Standard language for property graph querying. It builds on the foundations of SQL and integrates proven ideas from the existing [openCypher, PGQL, GSQL, and G-CORE](https://gql.today/comparing-cypher-pgql-and-g-core/) languages. The standard is currently in the draft stage.

TuGraph has implemented GQL based on the [ISO GQL (ISO/IEC 39075) Antlr4 grammar file](https://github.com/TuGraph-family/gql-grammar). It includes some extensions and modifications. Not all GQL syntax is fully supported at the moment, but we will continue to improve and enhance it in the future.

## 2.List of Clauses

| Category            | Clauses        |
| ------------------- | -------------- |
| Reading clauses     | MATCH          |
|                     | OPTIONAL MATCH |
| Projecting clauses  | RETURN         |
|                     | NEXT           |
| Reading sub-clauses | WHERE          |
|                     | ORDER BY       |
|                     | SKIP           |
|                     | LIMIT          |


### 2.1.MATCH

The `MATCH` clause is the most basic clause in GQL, and almost all queries are expanded through `MATCH`.

The `MATCH` clause is used to specify the matching pattern to search in the graph, to match vertices or paths that meet certain conditions.


#### Vertex basics

##### Get all vertices

```
MATCH (n)
RETURN n
```

##### Get all vertices with a label

```
MATCH (n:Person)
RETURN n
```

##### Vertex matching with property

```
MATCH (n:Person{name:'Michael Redgrave'})
RETURN n.birthyear
```

return
```JSON
[{"n.birthyear":1908}]
```

##### Vertex matching with filter


```
MATCH (n:Person WHERE n.birthyear > 1910)
RETURN n.name LIMIT 2
```

return
```JSON
[{"n.name":"Christopher Nolan"},{"n.name":"Corin Redgrave"}]
```

#### Edge basics

##### Edge pointing right

```
MATCH (n:Person WHERE n.birthyear = 1970)-[e]->(m)
RETURN n.name, label(e), m.name
```

return
```JSON
[{"label(e)":"BORN_IN","m.name":"London","n.name":"Christopher Nolan"},{"label(e)":"DIRECTED","m.name":null,"n.name":"Christopher Nolan"}]
```

##### Edge pointing left

```
MATCH (n:Person WHERE n.birthyear = 1939)<-[e]-(m)
RETURN n.name, label(e), m.name
```

return
```JSON
[{"label(e)":"HAS_CHILD","m.name":"Rachel Kempson","n.name":"Corin Redgrave"},{"label(e)":"HAS_CHILD","m.name":"Michael Redgrave","n.name":"Corin Redgrave"}]
```

##### Edge matching with filter

```
MATCH (n:Person)-[e:BORN_IN WHERE e.weight > 20]->(m)
RETURN n.name, e.weight, m.name
```

return
```JSON
[{"e.weight":20.549999237060547,"m.name":"New York","n.name":"John Williams"},{"e.weight":20.6200008392334,"m.name":"New York","n.name":"Lindsay Lohan"}]
```

#### Path matching

##### Variable length

```
MATCH (n:Person)-[e]->{2,3}(m:Person)
RETURN m.name LIMIT 2
```

return
```JSON
[{"m.name":"Liam Neeson"},{"m.name":"Natasha Richardson"}]
```

### 2.2.OPTIONAL MATCH

The `OPTIONAL MATCH` clause matches a graph pattern and returns `null` if there is no match.


#### Match found

```
OPTIONAL MATCH (n:Person{name:'Michael Redgrave'})
RETURN n.birthyear
```

return
```JSON
[{"n.birthyear":1908}]
```

#### Match Not Found

```
OPTIONAL MATCH (n:Person{name:'Redgrave Michael'})
RETURN n.birthyear
```

return

```JSON
[{"n.birthyear":null}]
```

### 2.3.RETURN

The `RETURN` clause specifies the results to be returned, including vertices, edges, paths, properties, etc.

#### Return vertices

```
MATCH (n)
RETURN n LIMIT 2
```

return
```JSON
[{"n":{"identity":0,"label":"Person","properties":{"birthyear":1910,"name":"Rachel Kempson"}}},{"n":{"identity":1,"label":"Person","properties":{"birthyear":1908,"name":"Michael Redgrave"}}}]
```

#### Return edges

```
MATCH (n)-[e]->(m)
RETURN e LIMIT 2
```

return

```JSON
[{"e":{"dst":2,"forward":false,"identity":0,"label":"HAS_CHILD","label_id":0,"src":0,"temporal_id":0}},{"e":{"dst":3,"forward":false,"identity":0,"label":"HAS_CHILD","label_id":0,"src":0,"temporal_id":0}}]
```

#### Return property

```
MATCH (n:Person)
RETURN n.name LIMIT 2
```

return

```JSON
[{"n.name":"Christopher Nolan"},{"n.name":"Corin Redgrave"}]
```

#### Uncommon string used as variable name

```
MATCH (`/uncommon variable`:Person)
RETURN `/uncommon variable`.name LIMIT 3
```

return

```JSON
[{"`/uncommon variable`.name":"Christopher Nolan"},{"`/uncommon variable`.name":"Corin Redgrave"},{"`/uncommon variable`.name":"Dennis Quaid"}]
```

#### Alias

```
MATCH (n:Person)
RETURN n.name AS nname LIMIT 2
```

return

```JSON
[{"nname":"Christopher Nolan"},{"nname":"Corin Redgrave"}]
```

#### Optional property

```
MATCH (n:Person)
RETURN n.age LIMIT 2
```

return

```JSON
[{"n.age":null},{"n.age":null}]
```

#### Other expressions

```
MATCH (n:Person)
RETURN n.birthyear > 1970, "I'm a literal", 1 + 2, abs(-2)
LIMIT 2
```

return

```JSON
[{"\"I'm a literal\"":"I'm a literal","1 + 2":3,"abs(-2)":2,"n.birthyear > 1970":false},{"\"I'm a literal\"":"I'm a literal","1 + 2":3,"abs(-2)":2,"n.birthyear > 1970":false}]
```

#### Distinct


```
MATCH (n)
RETURN DISTINCT label(n) AS label
```

return

```JSON
[{"label":"Person"},{"label":"City"},{"label":"Film"}]
```

### 2.4.NEXT

The `NEXT` clause is used to connect multiple clauses.

#### Connecting MATCH clauses

```
MATCH (n:Person) WHERE n.birthyear = 1970
RETURN n
NEXT
MATCH (m:Person) WHERE m.birthyear < 1968
RETURN n.name, n.birthyear, m.name LIMIT 2
```

return

```JSON
[{"m.name":"Rachel Kempson","n.birthyear":1970,"n.name":"Christopher Nolan"},{"m.name":"Michael Redgrave","n.birthyear":1970,"n.name":"Christopher Nolan"}]
```

### 2.5.WHERE

`WHERE` clause is used to filter records.

#### Filter vertex

```
MATCH (n:Person WHERE n.birthyear > 1965)
RETURN n.name
```

returns
```JSON
[{"n.name":"Christopher Nolan"},{"n.name":"Lindsay Lohan"}]
```

#### Filter edge

```
MATCH (n:Person WHERE n.birthyear > 1965)-[e:ACTED_IN]->(m:Film)
WHERE e.charactername = 'Halle/Annie'
RETURN m.title
```

returns

```JSON
[{"m.title":"The Parent Trap"}]
```

#### Boolean expressions

`AND`, `OR`, `XOR`, and `NOT` Boolean expressions can be used in the `WHERE` clause to filter data.

```
MATCH (n:Person)
WHERE
	n.birthyear > 1930 AND (n.birthyear < 1950 OR n.name = 'Corin Redgrave')
RETURN n LIMIT 2
```

returns

```JSON
[{"n":{"identity":3,"label":"Person","properties":{"birthyear":1939,"name":"Corin Redgrave"}}},{"n":{"identity":11,"label":"Person","properties":{"birthyear":1932,"name":"John Williams"}}}]
```

### 2.6.ORDER BY

`ORDER BY` is a clause of `RETURN` that sorts the output result.

#### Sorting the Result

```
MATCH (n:Person WHERE n.birthyear < 1970)
RETURN n.birthyear AS q
ORDER BY q ASC
LIMIT 5
```

return
```JSON
[{"q":1873},{"q":1908},{"q":1910},{"q":1930},{"q":1932}]
```

### 2.7.SKIP

`SKIP` specifies the offset of the result rows.

#### Without SKIP

```
MATCH (n:Person)
RETURN n.name LIMIT 3
```

return

```JSON
[{"n.name":"Christopher Nolan"},{"n.name":"Corin Redgrave"},{"n.name":"Dennis Quaid"}]
```

#### Using SKIP

```
MATCH (n:Person)
RETURN n.name SKIP 1 LIMIT 2
```

return
```JSON
[{"n.name":"Corin Redgrave"},{"n.name":"Dennis Quaid"}]
```

### 2.8.LIMIT

The `LIMIT` clause is used to limit the number of rows in the result.

#### Using LIMIT

```
MATCH (n:Person)
RETURN n.name LIMIT 2;
```

return
```JSON
[{"n.name":"Christopher Nolan"},{"n.name":"Corin Redgrave"}]
```