Predicates

A predicate specifies a condition that can be evaluated to give a boolean value (true or false).

All Predicates

Comparison Predicates

Compares two values or expressions and returns true or false. GQL supports the following comparison operators:

• Equal to: =
• Not equal to: <> (or !=)
• Greater than: >
• Less than: <
• Greater than or equal to: >=
• Less than or equal to: <=
• Regular match: =~ (or REGEXP)

The >, <, >=, and <= can be used only with numeric, textual, temporal, boolean, and null values.

The =~ and REGEXP operators use full-string matching (the pattern must match the entire string). Use .*pattern.* for substring matching. Both operands must be strings (or null). The regex flavor is ECMAScript.

Comparable Values

In GQL, two values are considered comparable if they can be meaningfully evaluated using comparison operators. There are two kinds of comparable values:

• Essentially Comparable Values: These are values of the same type (e.g., two strings, two dates) or closely related types within the same category (e.g., an integer and a float). They can be directly compared.
• Universally Comparable Values: These include values from different categories that can still be compared by implicitly converting one value’s type to match the other. For example, comparing the integer 12 with the string "13ab" attempts a conversion before evaluation.

Comparing Numeric Values

GQL
RETURN 30.1 > 30 // true

Comparing Textual Values

The first differing character (from left to right) determines the result of the comparison. The characters are compared based on their Unicode values.

GQL
RETURN "campus" < "camera" // false

This query returns false because the first differing character, p, has a higher Unicode value than e (Unicode of p is 112, while e is 101).

GQL
LET email = "[email protected]"
RETURN email =~ "[a-zA-Z0-9_.-]+@[a-zA-Z0-9]+\.(com|cn)" // true

This query returns true because the email matches the specified email address pattern.

The REGEXP keyword is equivalent to =~:

GQL
MATCH (n:Person) WHERE n.name REGEXP "A.*" RETURN n.name

Common regex patterns:

GQL
RETURN "abc123" =~ "[a-z]+[0-9]+"       // true — character classes
RETURN "cat" =~ "cat|dog|bird"           // true — alternation
RETURN "ababab" =~ "(ab)+"              // true — grouping and quantifiers
RETURN "color" =~ "colou?r"             // true — optional character
RETURN "hello world" =~ "hello"          // false — full match required
RETURN "hello world" =~ ".*hello.*"      // true — substring via .*

Comparing Temporal Values

Temporal values are treated like numeric values, as time is measured in units such as seconds, hours, days, and years. In GQL, the comparison between two temporal values is based on their duration—the difference between the two points in time. If the duration is 0, the values are equal; if negative, the left value is smaller; otherwise, the left value is greater.

GQL
// p1.birthday is 1987-10-01, p2.birthday is 1987-10-02
MATCH (p1 {name: "Alex"}), (p2 {name: "Joy"})
RETURN p1.birthday < p2.birthday // true

Comparing List Values

Two lists are considered equal if they contain the same elements in the exact same order.

GQL
RETURN [1,2,3] = [1,2,3] // true

GQL
RETURN [] = [] // true

GQL
RETURN [1,2,3] = [1,3,2] // false

Comparing Records

Two records are considered equal if they have the same fields with identical values.

GQL
RETURN {a:1, b:2} = {a:1, b:2} // true

GQL
RETURN {a:1, b:2} = {a:2, b:2} // false

GQL
RETURN {a:1} = {b:1} // false

Comparing Paths

Paths are similar to lists, as they consist of sequences of nodes and edges.

GQL
MATCH p1 = (:User {name: "mochaeach"})-[:Joins]->(:Club {_id: "C02"})
MATCH p2 = (:User {name: "mochaeach"})-[:Joins]->(:Club {_id: "C02"})
RETURN p1 = p2 // true

GQL
MATCH p1 = (:User {name: "mochaeach"})-[:Joins]->(:Club {_id: "C02"}) 
MATCH p2 = (:Club {_id: "C02"})<-[:Joins]-(:User {name: "mochaeach"})
RETURN p1 = p2 // false

Comparing Nodes/Edges

Nodes and edges can be treated like records, where property names act as keys and their corresponding property values serve as values.

GQL
MATCH  (n1:User {name: "mochaeach"}), (n2:Club {_id: "C02"})
RETURN n1 = n2 // false

Comparing String and Numeric Values

GQL attempts to convert an entire string to a numeric value when it is compared with a numeric operand. The conversion succeeds only if the string is in a valid numeric format. For example:

• " 123 " → 123
• "-2" → -2
• "+2.3" → 2.3

If the string is not in a valid numeric format, it is interpreted as 0.

GQL
RETURN "-2.9" > -3 // true; converts "-2.9" to 2.9

GQL
RETURN "11a" > 10 // false; converts "11a" to 0

Comparing String and Temporal Values

In GQL, strings can be compared with temporal values by implicitly converting the string to a temporal type. This behavior is similar to string-numeric comparisons. For a string to be successfully compared to a temporal value, it must:

• Follow the ISO 8601 standard format for date, datetime, or duration values.
• Be interpreted as a temporal value matching the type of the other operand.

GQL
// p.birthday is 1987-10-01
MATCH (p1 {name: "Alex"}), (p2 {name: "Joy"})
RETURN p1.birthday < "1987-10-02" // true

Comparing Boolean Values and Others

Boolean values can be compared with other data types, such as numeric or textual values, through implicit type conversion.

GQL
RETURN true = 1 // true

GQL
RETURN false = 0 // true

GQL
RETURN true = "true" // false

Exists Predicate

The EXISTS predicate evaluates whether a specified graph pattern or query returns any results. If it finds matching data, the predicate evaluates to true; otherwise, it evaluates to false.

Syntax
<exists predicate> ::=
  "EXISTS" {
      "{" <graph pattern> "}"
    | "(" <graph pattern> ")"
    | "{" { <match statement>... } "}"
    | "(" { <match statement>... } ")"
    | "{" <query specification> "}"
  }

This query checks whether there is any path originating from node A exists in the graph:

GQL
RETURN EXISTS {
  MATCH ({_id: "A"})->()
}

The MATCH keyword can be omitted when EXISTS contains only a graph pattern. Additionally, a WHERE clause can be used with the pattern to apply conditions:

GQL
RETURN EXISTS {
  (n)->() WHERE n._id = "A"
}

EXISTS can also be used in the WHERE clause of a MATCH statement:

GQL
MATCH (n:movie)
WHERE n.rating > 7.5 AND EXISTS {
  MATCH (n)<-[:direct]-(m)
  WHERE m.name = "Ang Lee"
}
RETURN n.name

This query checks whether any element in a list is greater than 3:

GQL
RETURN EXISTS {
  FOR item in [1,2,3]
  FILTER item > 3
  RETURN item
}

This query checks whether the retrieved node has the property name; note that it returns true even if the name value is null:

GQL
MATCH (n:Paper {_id: "book92"}) LIMIT 1
RETURN EXISTS(n.name)

None Predicate

The NONE predicate evaluates whether a specified graph pattern or query returns no results. If it doesn't find any matching data, the predicate evaluates to true; otherwise, it evaluates to false.

Syntax
<none predicate> ::=
  "NONE" {
      "{" <graph pattern> "}"
    | "(" <graph pattern> ")"
    | "{" { <match statement>... } "}"
    | "(" { <match statement>... } ")"
    | "{" <query specification> "}"
  }

This query checks whether there is no path originating from node A in the graph:

GQL
RETURN NONE {
  MATCH ({_id: "A"})->()
}

The MATCH keyword can be omitted when NONE contains only a graph pattern. Additionally, a WHERE clause can be used with the pattern to apply conditions:

GQL
RETURN NONE {
  (n)->() WHERE n._id = "A"
}

NONE can also be used in the WHERE clause of a MATCH statement:

GQL
MATCH (n:movie)
WHERE n.rating > 7.5 AND NONE {
  MATCH (n)<-[:direct]-(m)
  WHERE m.name = "Ang Lee"
}
RETURN n.name

This query checks whether there is no element in a list is greater than 3:

GQL
RETURN NONE {
  FOR item in [1,2,3]
  FILTER item > 3
  RETURN item
}

Null Predicates

Specifies a test for a null value. GQL supports the following null predicates:

• IS NULL
• IS NOT NULL

This query retrieves the title of each Paper node if the value is not null; otherwise, it returns the message TITLE NOT FOUND:

GQL
MATCH (n:Paper)
RETURN CASE 
  WHEN n.title IS NOT NULL THEN n.title
  ELSE "TITLE NOT FOUND"
END

Normalized Predicates

Determines whether a character string value is normalized. GQL supports the following normalized predicates:

• IS [ <normal form> ] NORMALIZED
• IS NOT [ <normal form> ] NORMALIZED

Details

• The <normal form> defaults to NFC. Other available normalization forms are NFD, NFKC and NFKD.

GQL
RETURN "Å" IS NORMALIZED AS normRes

Result:

GQL
RETURN "Å" IS NFD NORMALIZED AS normRes

Result:

Labeled Predicates

Determines whether a graph element satisfies a label expression. GQL supports the following labeled predicates:

• IS LABELED
• IS NOT LABELED
• :

GQL
MATCH (n) WHERE n IS NOT LABELED Paper
RETURN n

GQL
MATCH (n) WHERE n:Paper
RETURN n

Property Exists Predicate

The PROPERTY_EXISTS predicate evaluates whether a referenced graph element contains a property, regardless of its value. This means it returns true even if the property's value is null.

GQL
MATCH (n:Paper) LIMIT 1
RETURN PROPERTY_EXISTS(n, "name")

Value Type Predicates

Determines whether a value conforms to a specific type. GQL supports the following value type predicates:

• IS TYPED <value type>
• IS NOT TYPED <value type>

Details

• Currently, the <value type> supports the following data type keywords: STRING, BOOL.

GQL
RETURN "a" IS TYPED BOOL AS typeCheck

Result:

Boolean Value Predicates

Evaluates the truthiness of a boolean expression or variable, determining whether it is true or false. GQL supports the following boolean value predicates:

• IS TRUE
• IS FALSE

GQL
RETURN 1 > 2 IS TRUE

Result:

All Different Predicate

The ALL_DIFFERENT predicate evaluates whether all graph elements bound to a list of element variables are pairwise different from one another.

GQL
MATCH (n1 {_id:"P1"})
MATCH ({_id:"P1"})-(n2)
MATCH ({_id:"P3"})-(n3)
RETURN table(n1._id, n2._id, n3._id, ALL_DIFFERENT(n1, n2, n3))

Result:

Same Predicate

The SAME predicate evaluates whether all element variables bind to the same graph element.

GQL
MATCH ({_id:"P1"})-(n1)
MATCH ({_id:"P3"})-(n2)
RETURN table(n1._id, n2._id, SAME(n1, n2))

Result:

Source/Destination Predicates

Determines whether a node is the source or destination of an edge. GQL supports the following source/destination predicates:

• <node reference> IS SOURCE OF <edge reference>
• <node reference> IS NOT SOURCE OF <edge reference>
• <node reference> IS DESTINATION OF <edge reference>
• <node reference> IS NOT DESTINATION OF <edge reference>

GQL
MATCH (n {_id: "P1"}), ()-[e:Cites]->() WHERE n IS SOURCE OF e
RETURN e

Directed Predicates

Directed predicates determine whether an edge variable is bound to a directed edge. GQL supports the following directed predicates:

• IS DIRECTED
• IS NOT DIRECTED

Details

• All edges created in Ultipa Graph Database are directed.

GQL
MATCH ()-[e]-()
RETURN e IS DIRECTED

Result:

List Predicates

List predicates evaluate a condition over each element of a list. They use the syntax:

GQL
<function>(variable IN list WHERE predicate)

• variable: Iterator variable bound to each element during evaluation.
• list: Any expression evaluating to a list (literal list, property, or variable).
• predicate: Boolean expression that can reference the iterator variable and outer scope variables.

Behavior with empty and NULL lists:

NULL elements in a list do not satisfy any predicate (treated as false).

Examples

Basic usage:

GQL
RETURN ALL(x IN [1, 2, 3] WHERE x > 0)

Result:

GQL
RETURN ANY(x IN ["a", "b", "c"] WHERE x = "b")

Result:

GQL
RETURN SINGLE(x IN [1, 2, 3] WHERE x > 2)

Result:

GQL
RETURN NONE(x IN [1, 2, 3] WHERE x < 0)

Result:

Using list predicates with graph data:

GQL
MATCH (n:Person)
WHERE ALL(x IN [n.age] WHERE x > 20)
RETURN n._id

Using list predicates with complex expressions:

GQL
RETURN ALL(x IN [2, 4, 6, 8] WHERE x % 2 = 0)

Result:

Nested list predicates:

GQL
RETURN ALL(x IN [1, 2, 3] WHERE ANY(y IN [0, 1] WHERE y < x))

Result: