Operators

Operators are symbols or keywords used to perform operations on data.

All Operators

Property Accessor

The . (dot) operator allows you to access a property of a graph element.

GQL
MATCH (n)
RETURN n._id LIMIT 10

You can also use the . (dot) operator to access the coordinate of a POINT (latitude and longitude) or POINT3D (x, y, and z) property.

GQL
MATCH (n:City)
RETURN n.location.latitude,n.location.longitude

Logical Operators

AND

Combines two or more conditions in a way that all of them must be true for the entire expression to evaluate to true.

Truth table for the AND operator:

This query returns users whose age exceeds 30 and incomeGroup equals to 4:

GQL
MATCH (n:User)
WHERE n.age > 30 AND n.incomeGroup = 4
RETURN n

OR

Combines two or more conditions where only one of them needs to be true for the entire expression to evaluate to true.

Truth table for the OR operator:

This query returns users whose age exceeds 30, or incomeGroup equals to 4:

GQL
MATCH (n:User)
WHERE n.age > 30 OR n.incomeGroup = 4
RETURN n

XOR

Combines two or more conditions by evaluating two conditions at a time. For two conditions, the result is true only if exactly one of the conditions is true. If both are true or both are false, the result is false. When applied to multiple conditions, XOR first evaluates the result of the first two conditions, then compares that result with the next condition, continuing this process until all conditions are checked.

Truth table for the XOR operator:

This query returns users whose age exceeds 30, or incomeGroup equals to 4, but excludes users who meet both criteria:

GQL
MATCH (n:Person)
WHERE n.age > 30 XOR n.incomeGroup = 4
RETURN n

NOT

Negates a condition, returning true if the specified condition is false and vice versa.

Truth table for the NOT operator:

This query returns users whose age is not 30:

GQL
MATCH (n:Person)
WHERE NOT n.age = 30
RETURN n

Arithmetic Operators

Performs mathematical operations on numerical values. GQL supports the following arithmetic operators:

• Addition: +
• Subtraction: -
• Multiplication: *
• Division: /
• Modulus: %

GQL
RETURN 2 + 8

Result:

Assignment Operators

The = operator is used to assign values in statements like LET and SET, and to declare path variables within MATCH statements.

GQL
LET a = 1 RETURN a

GQL
MATCH (n:Person WHERE n.name = "John Doe")
SET n.gender = "male"

GQL
MATCH p = ()->() RETURN p

String Operators

String Concatenation

The || or + operators combines multiple strings into a single string by merging the characters of each string in order.

GQL
RETURN "data" || "base"

Result:

GQL
RETURN "data" + "base"

Result:

String Matching

The CONTAINS operator checks if one string contains another (case-sensitive).

This query returns user nodes whose aboutMe contains "graph database":

GQL
MATCH (n:user WHERE n.aboutMe CONTAINS "graph database")
RETURN n

You can transform all letters to upper or lower cases for case-insensitive matching:

GQL
MATCH (n:user WHERE lower(n.aboutMe) CONTAINS "graph database")
RETURN n

The CONTAINS operator is also used to match the specified keywords with tokens of a full-text index (precise or fuzzy match). See Using Full-text Indexes.

This query finds nodes using the full-text index prodDesc where their tokens include "graph" and "database":

GQL
MATCH (n WHERE ~prodDesc CONTAINS "graph database")
RETURN n

List Operators

List Construction

The [] or LIST[] or ARRAY[] can create a list by placing comma-separated elements inside.

GQL
LET items = [1,2,3]
RETURN items

Result:

The [] can also construct a nested list:

GQL
LET items = [[1,2],[2,3]]
RETURN items

Result:

Elements Accessing

The [] can access elements within a list by their indexes. Lists use 0-based indexing, meaning the first element is at index 0.

Note: m and n are both positive integers and n > m.

GQL
LET items = ["a", 1, "b", 34]
RETURN items[0], items[1], items[-1], items[-2], items[1:], items[:2], items[1:3]

Result:

Membership Checking

The IN checks whether a specified element exists within a list. It evaluates to 1 for true and 0 for false.

This query returns nodes whose _id can be found in the list of ["U01", "U02"]:

GQL
MATCH (n) WHERE n._id IN ["U01", "U02"]
RETURN n

List Concatenation

The concatenation operator || combines multiple lists into a single list by merging the elements of each list in order.

GQL
RETURN [1,2,3] || [3,4,5] AS newList

Result:

Path Operators

Path Construction

The PATH[] creates a path by enumerating node and edge references in order.

Syntax
<path value constructor> ::= "PATH[" <path element list> "]"

<path element list> ::= <node reference> [ <path element list step>... ]

<path element list step> ::= "," <edge reference> "," <node reference>

Details

• If <path element list> contains the null value or does not identify a path, then an exception condition is raised: Malformed path.

GQL
MATCH (n1 {_id: "U01"}), (n2 {_id: "U02"}), -[e {_uuid:39}]->
RETURN PATH[n2, e, n1]

Path Concatenation

The concatenation operator || joins multiple paths into a continuous single path, merging the last node of the first path with the first node of the second path when they are identical. If this condition is not met, then an exception condition is raised: Malformed path.

GQL
MATCH p1 = ({_id: "U01"})->(n), p2 = (n)->()
RETURN p1 || p2

Note: The expression p1 || p2 returns no result if there is no continuous path in the graph that matches ({_id: "U01"})->(n)->(). In other words, the concatenation only succeeds when such a full path exists.

Record Operators

Record Construction

The {} or RECORD{} creates a record. You can define its fields and corresponding values, including nested records:

GQL
RETURN {name: 'Alice', age: 30}
RETURN {user: {name: 'Alice', role: 'admin'}, count: 5}

GQL
LET rec = {length: 20, width: 59, height: 10}
RETURN rec.length

Result:

Field Reference

The . (period) operator allows you to reference a field of a record:

GQL
LET rec = RECORD{length: 20, width: 59, height: 10}
RETURN rec.length * rec.width * rec.height AS capacity

Result:

Fields can also be accessed using the recordGet() function:

GQL
RETURN recordGet({name: 'Alice', age: 30}, 'name')

MAP Projection

MAP projection creates a record from entity properties by selecting specific fields:

GQL
MATCH (n:Person {_id: 'alice'})
RETURN n{.name, .age}

Deduplication

The DISTINCT ensures that only unique values are included.

This query returns distinct age values of users:

GQL
MATCH (n:User)
RETURN DISTINCT n.age