GQL (Graph Query Language) is the standardized query language for graph databases, similar to how SQL serves relational databases. The first version of the GQL standard was officially released by the ISO/IEC in April 2024, marking it as the first standardized database language since SQL's introduction in 1987.

This page covers the basics of GQL. For the complete guide, refer to GQL.

GQL Key Syntax

Node Patterns

A node pattern is to match nodes in the graph, represented using a pair of parentheses (), within which you can specify the node's label and properties.

To match any node:

()

To match User nodes:

(:User)

To match User nodes whose name is Areith and age is 32:

(:User {name: "Areith", age: 32})

To match nodes whose name is Areith:

({name: "Areith"})

Edge Patterns

An edge pattern is to match edges in the graph, represented using a pair of suqare brackets [], within which you can specify the edge's label and properties. Additionally, the pattern needs to indicates the direction of the edge.

To match any edge:

-[]-

To match rate edges pointing to the right:

-[:rate]->

To match rate edges pointing to the left with a score of 8:

<-[:rate {score: 8}]-

Path Patterns

A path pattern is to match paths in the graph, consisting of a concatenation of node patterns and edge patterns. Path patterns start and end with a node pattern and alternate between node patterns and edge patterns.

To match paths starting from Areith, through outgoing rate edges to Book nodes:

(:User {name: "Areith"})-[:rate]->(:Book)

To match paths describing the common connection between Areith and Kavi to any Book node:

(:User {name: "Areith"})-[]-(:Book)-[]-(:User {name: "Kavi"})

Label Expression

A label expression starts with a colon : and specifies the label of nodes or edges within a node or edge pattern.

Property Specification

Property key-value pairs can be enclosed in a pair of curly braces {} inside a node or edge pattern. This allows applying joint equalities to filter nodes or edges based on the values of their properties.

Variables

A variable is an identifier assigned to represent data retrieved from the database or manually defined, allowing you to reference the data throughout the query.

To define a variable p to represent the whole paths:

p = (:User {name: "Areith"})-[:rate]->(:Book)

To define a variable books to represent the books that Areith once rated:

(:User {name: "Areith"})-[:rate]->(books:Book)

To define a variable r to represent the rate edges connected to Areith, and use this variable in a WHERE clause to filter rate edges with a score greater than 8:

(:User {name: "Areith"})-[r:rate WHERE r.score > 8]-(:Book)

Example Graph

The following examples run against this graph:

Reading from the Database

The data you can read from a graph includes nodes, edges, and paths. To retrieve them, write the corresponding pattern in the MATCH statement, and you can use the RETURN statement to specify the output.

Nodes

This query retrieves Person nodes whose gender is male:

MATCH (p:Person {gender: "male"})
RETURN p

Result: p

Edges

This query retrieves WorkIn edges whose endOn is null:

MATCH -[e:WorkIn WHERE e.endOn IS NULL]->
RETURN e

Result: e

Paths

This query retrieves the paths, each indicating that a person is currently working in the company InnoVex, and returns the paths and names of the person:

MATCH p = (n:Person)-[e:WorkIn WHERE e.endOn IS NULL]->(:Company {name: "InnoVex"})
RETURN p, n.name

Result:

Writing to the Database

You can write to the database by inserting, updating and deleting nodes and edges in the database.

Insertion

The INSERT statement serves the purpose of creating new nodes and edges in the database.

This query inserts a Person node, its _id is set to P4, and name to Tiva Jorn:

INSERT (:Person {_id: "P4", name: "Tiva Jorn"})

This query inserts an WorkIn edge pointing from node P4 to the node CO1, its startOn is set to 2025-3-1:

MATCH (innovex {_id: "CO1"}), (tiva {_id: "P4"})
INSERT (tiva)-[:WorkIn {startOn: "2025-3-1"}]->(innovex)

Updating

The SET statement serves the purpose of updating the properties of existing nodes and edges in the database. The nodes or edges to be updated must firstly be retrieved from the database using the MATCH statement.

This query updates the node P4 by setting its gender to female:

MATCH (tiva {_id: "P4"})
SET tiva.gender = "female"

This query updates the WorkIn edge pointing from node P4 to the node CO1 by setting its startOn to 2025-4-1:

MATCH ({_id: "P4"})-[e:WorkIn]->({_id: "CO1"})
SET e.startOn = "2025-4-1"

Deletion

The DELETE statement serves the purpose of deleting nodes and edges in the database. The nodes or edges to be deleted must firstly be retrieved from the database using the MATCH statement. By default, you cannot delete a node who still has edges attached to it.

This query deletes the WorkIn edge pointing from node P4 to node CO1:

MATCH ({_id: "P4"})-[e:WorkIn]->({_id: "CO1"})
DELETE e

This query deletes the node P4:

MATCH (n {_id: "P4"})
DELETE n