This section navigates users to get started with GQL in Ultipa Graph Database.

Example Graph

The following examples run against this graph:

Notes

• This graph includes the following labels:
  • Node labels: Person, Club and Company
  • Edge labels: Join and WorkIn
• Apart from the label, each node and edge is associated with some properties, such as _id, name and gender properties for nodes labeled Person.
• If a property does not have a value assigned, its value is null, such as the endOn property of the edge between nodes P1 and CO1.
• In addition to the properties mentioned, every node and edge also has a _uuid property, which serves as a unique identifier generated by system during data insertion.

Returning Hello World

The RETURN statement is used to output the result to the GQL client.

RETURN "Hello World"

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.

Nodes

GQL uses a pair of parentheses () to represent nodes:

// Any anonymous node
()

// Any anonymous node labeled "Person"
(:Person)

// Any node labeled "Person", bound to the variable n
(n:Person)

// Any anonymous node where its name is "Kavi Moore"
({name: "Kavi Moore"})

// Any node labeled "Club" where its score exceeds 7, bound to the variable n
(n:Club WHERE n.score > 7)

This query retrieves nodes labeled Person whose gender is "male":

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

Result: p

Edges

GQL uses a pair of square brackets [] with the indication of edge direction to represent edges:

// Any anonymous edge in any direction 
-[]-
  
// Any edge labeled "Join" pointing right, bound to the variable e
-[e:Join]->
  
// Any edge labeled "Join" pointing left, where its memberNo is 1, bound to the variable e
<-[e:Join {memberNo: 1}]-

// Any edge in any direction, where its startOn is earlier than 2022-1-1, bound to the variable e
-[e WHERE startOn < "2022-1-1"]-

This query retrieves edges labeled WorkIn whose endOn is null:

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

Result: e

Paths

A path typically starts and ends with a node, and alternates between nodes and edges. Therefore, you can concatenate node patterns and edge patterns recursively to build a path pattern.

// Any anonymous 1-step path where two anonymous nodes are connected by an anonymous edge
()-[]-()
  
// Any 1-step path where a node labeled "Club" is connected to an anonymous node by an edge labeled "Join" pointing left; the path is bound to the variable p, the first node is bound to the variable c
p = (c:Club)<-[:Join]-()

// Any 2-step path where two nodes labeled "Person" are connected to a node with _id "C1", both through an edge labeled "Join" pointing to "C1"; the path is bound to the variable p
p = (:Person)-[:Join]->({_id: "C1"})<-[:Join]-(:Person) 

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 node labeled Person, its _id is set to "P4", and name is set to "Tiva Jorn":

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

This query inserts an edge labeled WorkIn pointing from node with _id "P4" to the node with _id "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 with _id "P4" by setting its gender to "female":

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

This query updates the edge labeled WorkIn pointing from node with _id "P4" to the node with _id "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 edge labeled WorkIn pointing from node with _id "P4" to node with _id "CO1":

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

This query deletes the node with _id "P4":

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