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 languages. The standard is currently in the draft stage.

TuGraph has implemented GQL based on the ISO GQL (ISO/IEC 39075) Antlr4 grammar file. 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

[{"n.birthyear":1908}]

Vertex matching with filter

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

return

[{"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

[{"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

[{"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

[{"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

[{"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

[{"n.birthyear":1908}]

Match Not Found

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

return

[{"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

[{"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

[{"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

[{"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

[{"`/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

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

Optional property

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

return

[{"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

[{"\"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

[{"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

[{"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

[{"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

[{"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

[{"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

[{"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

[{"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

[{"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

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