Operators

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

All Operators

Property Reference

The . (period) operator allows you to reference a property of a graph element.

MATCH (n)
RETURN n._id LIMIT 10

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:

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:

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:

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:

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: %
• Exponentiation: ^

RETURN (2+8)%3

Result:

Assignment Operators

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

LET a = 1 RETURN a

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

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.

RETURN "data" || "base"

Result:

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":

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:

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":

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.

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

Result:

The [] can also construct a nested list:

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.

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"]:

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.

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.

<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.

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.

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.

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.

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

Result:

Deduplication

The DISTINCT ensures that only unique values are included.

This query returns distinct age values of users:

MATCH (n:User)
RETURN DISTINCT n.age