GQL functions, operators and predicates

Switch services using the Version drop-down list. Learn more about navigation.
Applies to: ✅ Azure Data Explorer

This article lists the scalar functions, operators, and predicates supported in GQL (Graph Query Language).

The examples use the movies graph G() from Create a graph and set a graph reference: Person nodes (Name, Born), Movie nodes (Title, Description, Year), and ACTED_IN / DIRECTED edges (Role).

Access operators

Use these operators to read a property or element from a node, edge, map, list, or path.

match () limit 1 return [10, 20, 30][1] as byIndex, {a: 1, b: 2}.a as byDot, {a: 1, b: 2}['b'] as byKey

String functions

String predicates:

match () limit 1 return upper("abc") as result

match () limit 1 return trim(leading 'a' from 'aabc') as result

match () limit 1 return string_join(["a", "bc"], "") as result

MATCH (p :Person)
WHERE p.Name starts with 'T'
RETURN p.Name as actorName

Numeric functions

Numbers combine with the arithmetic operators +, -, *, and /:

match () limit 1 return 2 + 3 * 4 as a, 10 - 6 as b, mod(10, 4) as c, abs(-7) as d

match () limit 1 return sqrt(9) as `sqrt`, 9 / 3 as divideResult

Conditional expressions

CASE

CASE returns a value based on conditions, in searched form (evaluate independent predicates) or simple form (compare one expression to a series of values).

Searched form evaluates each WHEN predicate in turn:

match (m:Movie)
return m.Title as Title, case when m.Year < 2000 then 'C' else 'M' end as Era

Simple form compares one expression against each WHEN value:

match (m:Movie)
return m.Title as Title,
    case m.Title
        when 'T1' then 'A'
        when 'T3' then 'G'
        else 'O'
    end as Name

Type conversion

CAST

CAST(value AS type) converts a value to another type, such as string, int64. It's required in two common situations.

Nested property access. When a property is reached through a nested or indexed expression, such as an element of a path or a member of a map, the result is a dynamic value whose type isn't known in advance. Cast it to the expected type before you compare or compute with it.

See here the supported types.

match p = (a:Person)-[:ACTED_IN]->(m:Movie)
return m.Title as Title, cast(nodes(p)[0].Born as int) as ActorBorn

MATCH (p:Person)
RETURN p.Name || ', ' || CAST(p.Born as string) as nameAndYear

Aggregating on object keys. An aggregation key can't be an object (dynamic) value such as a node, edge, or property map. Convert the object value to a string first, using to_json_string(...) or CAST(... AS string).

match (p:Person)->(m:Movie)
return to_json_string(p), count(m) as participatedInMoviesCount

JSON functions

MATCH (n:Person {Name: 'Julia'})
RETURN TO_JSON_STRING(n) AS `json`

MATCH (p:Person)
limit 1
RETURN parse_json_string('{"a":"Michael", "b":"John"}'.a as string) AS name

MATCH (p:Person)
limit 1
RETURN cast(parse_json_string('{"a":1, "b":2}').a as integer) AS a

MATCH () limit 1 RETURN PARSE_JSON_STRING('[1,2,3]')[1] as second

List and Map functions and predicates

match () limit 1 return ["a", "b", "c"][1] as second

match () limit 1 return size([1, 2, 3]) as `size`

match () limit 1 return keys({"a":1, "b":2}) as my_keys

MATCH (p:Person)
WHERE p.Name IN ['Tom', 'Kevin']
RETURN p.Name as actor

match () limit 1 return ["a"] || ["b"] as lst

Date and Time functions

match () limit 1 return duration ({minutes: 5}) as "5min"

match () limit 1 return duration ({minutes: 5, seconds:25}) as "5min25sec"

If nodes in the graph have a property such as event_timestamp of KQL type datetime, you can find all graph nodes with an event that occurred in the last 10 minutes, measured from now or from a specific timestamp:

MATCH (n) where n.event_timestamp < CURRENT_TIMESTAMP - duration({minutes:10}) return n

MATCH (n) where n.event_timestamp < zoned_datetime('2025-09-15 09:00:00.0') - duration({minutes:10}) return n

MATCH () limit 1
RETURN DURATION_BETWEEN(zoned_datetime('2025-09-15 09:00:00.0'), zoned_datetime()) AS Elapsed

Graph and path functions

match (m: Movie) limit 1 return labels(m) as lbls

match p = (n:Person)-[e: ACTED_IN]->(m: Movie) return p, path_length(p), nodes(p), edges(p)

Aggregations

Aggregate functions summarize the matched rows. When an aggregate appears next to non-aggregated expressions, those expressions become the grouping keys.

MATCH (p:Person)
RETURN COUNT(*) AS people, MIN(p.Born) AS earliest, MAX(p.Born) AS latest, SUM(p.Born) AS bornSum, AVG(p.Born) AS bornAvg

Count the actors in each movie:

MATCH (p:Person)-[:ACTED_IN]->(m:Movie)
RETURN m.Title as Movie, COUNT(*) AS ActorsCount

MATCH (n:Person)-[:ACTED_IN]->(m:Movie)
RETURN collect_list(distinct n.Name) as actors

Find how many movies each actor acted in:

MATCH (n:Person)-[:ACTED_IN]->(m:Movie)
RETURN TO_JSON_STRING(n) as actor, count(m) as moviesCount

For more, see Aggregations in the GQL guide.

Predicates

Comparison operators compare two scalar values and return a Boolean. They apply to scalar values, not to nodes or edges.

Other operators:

match (p:Person)
where p.Name in ['Tom', 'Julia']
return p.Name as name

Negate the test with NOT to keep only values that are absent from the list:

match (p:Person)
where not p.Name in ['Tom', 'Kevin', 'Ron']
return p.Name as name

Other predicates:

MATCH (p:Person)
WHERE p.Name IN ['Tom', 'Kevin'] AND p.Born IS NOT NULL
RETURN p.Name as name

It's possible to use IS TRUE or IS FALSE to test the result of a Boolean expression:

MATCH (p:Person)
WHERE (p.Born > 1960) IS TRUE
RETURN p.Name

Related content

• GQL (Graph Query Language)
• GQL guide
• GQL clauses
• Create a graph and set a graph reference