GQL functions

All GoogleSQL functions are supported, including the following GQL-specific functions:

Function list

Name Summary
DESTINATION_NODE_ID Gets a unique identifier of a graph edge's destination node.
EDGES Gets the edges in a graph path. The resulting array retains the original order in the graph path.
ELEMENT_ID Gets a graph element's unique identifier.
IS_ACYCLIC Checks if a graph path has a repeating node.
IS_FIRST Returns true if this row is in the first k rows (1-based) within the window.
IS_SIMPLE Checks if a graph path is simple.
IS_TRAIL Checks if a graph path has a repeating edge.
LABELS Gets the labels associated with a graph element.
NODES Gets the nodes in a graph path. The resulting array retains the original order in the graph path.
PATH Creates a graph path from a list of graph elements.
PATH_FIRST Gets the first node in a graph path.
PATH_LAST Gets the last node in a graph path.
PATH_LENGTH Gets the number of edges in a graph path.
PROPERTY_NAMES Gets the property names associated with a graph element.
SOURCE_NODE_ID Gets a unique identifier of a graph edge's source node.

DESTINATION_NODE_ID

DESTINATION_NODE_ID(edge_element)

Description

Gets a unique identifier of a graph edge's destination node. The unique identifier is only valid for the scope of the query where it's obtained.

Arguments

  • edge_element: A GRAPH_ELEMENT value that represents an edge.

Details

Returns NULL if edge_element is NULL.

Return type

STRING

Examples

GRAPHFinGraph
MATCH(:Person)-[o:Owns]->(a:Account)
RETURNa.idASaccount_id,DESTINATION_NODE_ID(o)ASdestination_node_id
/*------------------------------------------+
 |account_id | destination_node_id |
 +-----------|------------------------------+
 | 7 | mUZpbkdyYXBoLkFjY291bnQAeJEO |
 | 16 | mUZpbkdyYXBoLkFjY291bnQAeJEg |
 | 20 | mUZpbkdyYXBoLkFjY291bnQAeJEo |
 +------------------------------------------*/

Note that the actual identifiers obtained may be different from what's shown above.

EDGES

EDGES(graph_path)

Description

Gets the edges in a graph path. The resulting array retains the original order in the graph path.

Definitions

  • graph_path: A GRAPH_PATH value that represents a graph path.

Details

If graph_path is NULL, returns NULL.

Return type

ARRAY<GRAPH_ELEMENT>

Examples

GRAPHFinGraph
MATCHp=(src:Account)-[t1:Transfers]->(mid:Account)-[t2:Transfers]->(dst:Account)
LETes=EDGES(p)
RETURNARRAY_CONCAT(ARRAY_TRANSFORM(es,e->e.Id),[dst.Id])asids_in_path
/*-------------+
 | ids_in_path |
 +-------------+
 | [16,20,7] |
 +-------------+
 | [20,7,16] |
 +-------------+
 | [20,7,16] |
 +-------------+
 | [16,20,16] |
 +-------------+
 | [7,16,20] |
 +-------------+
 | [7,16,20] |
 +-------------+
 | [20,16,20] |
 +-------------*/

ELEMENT_ID

ELEMENT_ID(element)

Description

Gets a graph element's unique identifier. The unique identifier is only valid for the scope of the query where it's obtained.

Arguments

  • element: A GRAPH_ELEMENT value.

Details

Returns NULL if element is NULL.

Return type

STRING

Examples

GRAPHFinGraph
MATCH(p:Person)-[o:Owns]->(:Account)
RETURNp.nameASname,ELEMENT_ID(p)ASnode_element_id,ELEMENT_ID(o)ASedge_element_id
/*--------------------------------------------------------------------------------------------------------------------------------------------+
 | name | node_element_id | edge_element_id . |
 +------|------------------------------|------------------------------------------------------------------------------------------------------+
 | Alex | mUZpbkdyYXBoLlBlcnNvbgB4kQI= | mUZpbkdyYXBoLlBlcnNvbk93bkFjY291bnQAeJECkQ6ZRmluR3JhcGguUGVyc29uAHiRAplGaW5HcmFwaC5BY2NvdW50AHiRDg== |
 | Dana | mUZpbkdyYXBoLlBlcnNvbgB4kQQ= | mUZpbkdyYXBoLlBlcnNvbk93bkFjY291bnQAeJEGkSCZRmluR3JhcGguUGVyc29uAHiRBplGaW5HcmFwaC5BY2NvdW50AHiRIA== |
 | Lee | mUZpbkdyYXBoLlBlcnNvbgB4kQY= | mUZpbkdyYXBoLlBlcnNvbk93bkFjY291bnQAeJEEkSiZRmluR3JhcGguUGVyc29uAHiRBJlGaW5HcmFwaC5BY2NvdW50AHiRKA== |
 +--------------------------------------------------------------------------------------------------------------------------------------------*/

Note that the actual identifiers obtained may be different from what's shown above.

IS_ACYCLIC

IS_ACYCLIC(graph_path)

Description

Checks if a graph path has a repeating node. Returns TRUE if a repetition isn't found, otherwise returns FALSE.

Definitions

  • graph_path: A GRAPH_PATH value that represents a graph path.

Details

Two nodes are considered equal if they compare as equal.

Returns NULL if graph_path is NULL.

Return type

BOOL

Examples

GRAPHFinGraph
MATCHp=(src:Account)-[t1:Transfers]->(mid:Account)-[t2:Transfers]->(dst:Account)
RETURNsrc.idASsource_account_id,IS_ACYCLIC(p)ASis_acyclic_path
/*-------------------------------------+
 | source_account_id | is_acyclic_path |
 +-------------------------------------+
 | 16 | TRUE |
 | 20 | TRUE |
 | 20 | TRUE |
 | 16 | FALSE |
 | 7 | TRUE |
 | 7 | TRUE |
 | 20 | FALSE |
 +-------------------------------------*/

IS_FIRST

IS_FIRST(k)
OVERover_clause
over_clause:
([window_specification])
window_specification:
[PARTITIONBYpartition_expression[,...]]
[ORDERBYexpression[{ASC|DESC}][,...]]

Description

Returns true if the current row is in the first k rows (1-based) in the window; otherwise, returns false. This function doesn't require the ORDER BY clause.

Details

  • The k value must be positive; otherwise, a runtime error is raised.
  • If any rows are tied or if ORDER BY is omitted, the result is non-deterministic. If the ORDER BY clause is unspecified or if all rows are tied, the result is equivalent to ANY-k.

Return Type

BOOL

IS_SIMPLE

IS_SIMPLE(graph_path)

Description

Checks if a graph path is simple. Returns TRUE if the path has no repeated nodes, or if the only repeated nodes are its head and tail. Otherwise, returns FALSE.

Definitions

  • graph_path: A GRAPH_PATH value that represents a graph path.

Details

Returns NULL if graph_path is NULL.

Return type

BOOL

Examples

GRAPHFinGraph
MATCHp=(a1:Account)-[t1:Transferswheret1.amount > 200]->
(a2:Account)-[t2:Transferswheret2.amount > 200]->
(a3:Account)-[t3:Transferswheret3.amount > 100]->(a4:Account)
RETURN
IS_SIMPLE(p)ASis_simple_path,
a1.idasa1_id,a2.idasa2_id,a3.idasa3_id,a4.idasa4_id
/*----------------+-------+-------+-------+-------+
 | is_simple_path | a1_id | a2_id | a3_id | a4_id |
 +----------------+-------+-------+-------+-------+
 | TRUE | 7 | 16 | 20 | 7 |
 | TRUE | 16 | 20 | 7 | 16 |
 | FALSE | 7 | 16 | 20 | 16 |
 | TRUE | 20 | 7 | 16 | 20 |
 +----------------+-------+-------+-------+-------*/

IS_TRAIL

IS_TRAIL(graph_path)

Description

Checks if a graph path has a repeating edge. Returns TRUE if a repetition isn't found, otherwise returns FALSE.

Definitions

  • graph_path: A GRAPH_PATH value that represents a graph path.

Details

Returns NULL if graph_path is NULL.

Return type

BOOL

Examples

GRAPHFinGraph
MATCH
p=(a1:Account)-[t1:Transfers]->(a2:Account)-[t2:Transfers]->
(a3:Account)-[t3:Transfers]->(a4:Account)
WHEREa1.id < a4.id
RETURN
IS_TRAIL(p)ASis_trail_path,t1.idast1_id,t2.idast2_id,t3.idast3_id
/*---------------+-------+-------+-------+
 | is_trail_path | t1_id | t2_id | t3_id |
 +---------------+-------+-------+-------+
 | FALSE | 16 | 20 | 16 |
 | TRUE | 7 | 16 | 20 |
 | TRUE | 7 | 16 | 20 |
 +---------------+-------+-------+-------*/

LABELS

LABELS(element)

Description

Gets the labels associated with a graph element and preserves the original case of each label.

Arguments

  • element: A GRAPH_ELEMENT value that represents the graph element to extract labels from.

Details

Returns NULL if element is NULL.

Return type

ARRAY<STRING>

Examples

GRAPHFinGraph
MATCH(n:Person|Account)
RETURNLABELS(n)ASlabel,n.id
/*----------------+
 | label | id |
 +----------------+
 | [Account] | 7 |
 | [Account] | 16 |
 | [Account] | 20 |
 | [Person] | 1 |
 | [Person] | 2 |
 | [Person] | 3 |
 +----------------*/

NODES

NODES(graph_path)

Description

Gets the nodes in a graph path. The resulting array retains the original order in the graph path.

Definitions

  • graph_path: A GRAPH_PATH value that represents a graph path.

Details

Returns NULL if graph_path is NULL.

Return type

ARRAY<GRAPH_ELEMENT>

Examples

GRAPHFinGraph
MATCHp=(src:Account)-[t1:Transfers]->(mid:Account)-[t2:Transfers]->(dst:Account)
LETns=NODES(p)
RETURN
JSON_QUERY(TO_JSON(ns)[0],'$.labels')ASlabels,
JSON_QUERY(TO_JSON(ns)[0],'$.properties.nick_name')ASnick_name;
/*--------------------------------+
 | labels | nick_name |
 +--------------------------------+
 | ["Account"] | "Vacation Fund" |
 | ["Account"] | "Rainy Day Fund" |
 | ["Account"] | "Rainy Day Fund" |
 | ["Account"] | "Rainy Day Fund" |
 | ["Account"] | "Vacation Fund" |
 | ["Account"] | "Vacation Fund" |
 | ["Account"] | "Vacation Fund" |
 | ["Account"] | "Rainy Day Fund" |
 +--------------------------------*/

PATH

PATH(graph_element[,...])

Description

Creates a graph path from a list of graph elements.

Definitions

  • graph_element: A GRAPH_ELEMENT value that represents a graph element, such as a node or edge, to add to a graph path.

Details

This function produces an error if:

  • A graph element is NULL.
  • Nodes aren't interleaved with edges.
  • An edge doesn't connect to neighboring nodes.

Return type

GRAPH_PATH

Examples

GRAPHFinGraph
MATCH(src:Account)-[t1:Transfers]->(mid:Account)-[t2:Transfers]->(dst:Account)
LETp=PATH(src,t1,mid,t2,dst)
RETURN
JSON_QUERY(TO_JSON(p)[0],'$.labels')ASelement_a,
JSON_QUERY(TO_JSON(p)[1],'$.labels')ASelement_b,
JSON_QUERY(TO_JSON(p)[2],'$.labels')ASelement_c
/*-------------------------------------------+
 | element_a | element_b | element_c |
 +-------------------------------------------+
 | ["Account"] | ["Transfers"] | ["Account"] |
 | ... | ... | ... |
 +-------------------------------------------*/

-- Error: in 'p', a graph element is NULL.
GRAPHFinGraph
MATCH(src:Account)-[t1:Transfers]->(mid:Account)-[t2:Transfers]->(dst:Account)
LETp=PATH(src,NULL,mid,t2,dst)
RETURNTO_JSON(p)ASresults

-- Error: in 'p', 'src' and 'mid' are nodes that should be interleaved with an
-- edge.
GRAPHFinGraph
MATCH(src:Account)-[t1:Transfers]->(mid:Account)-[t2:Transfers]->(dst:Account)
LETp=PATH(src,mid,t2,dst)
RETURNTO_JSON(p)ASresults

-- Error: in 'p', 't2' is an edge that doesn't connect to a neighboring node on
-- the right.
GRAPHFinGraph
MATCH(src:Account)-[t1:Transfers]->(mid:Account)-[t2:Transfers]->(dst:Account)
LETp=PATH(src,t2,mid)
RETURNTO_JSON(p)ASresults

PATH_FIRST

PATH_FIRST(graph_path)

Description

Gets the first node in a graph path.

Definitions

  • graph_path: A GRAPH_PATH value that represents the graph path to extract the first node from.

Details

Returns NULL if graph_path is NULL.

Return type

GRAPH_ELEMENT

Examples

GRAPHFinGraph
MATCHp=(src:Account)-[t1:Transfers]->(mid:Account)-[t2:Transfers]->(dst:Account)
LETf=PATH_FIRST(p)
RETURN
LABELS(f)ASlabels,
f.nick_nameASnick_name;
/*--------------------------+
 | labels | nick_name |
 +--------------------------+
 | Account | Vacation Fund |
 | Account | Rainy Day Fund |
 | Account | Rainy Day Fund |
 | Account | Vacation Fund |
 | Account | Vacation Fund |
 | Account | Vacation Fund |
 | Account | Rainy Day Fund |
 +--------------------------*/

PATH_LAST

PATH_LAST(graph_path)

Description

Gets the last node in a graph path.

Definitions

  • graph_path: A GRAPH_PATH value that represents the graph path to extract the last node from.

Details

Returns NULL if graph_path is NULL.

Return type

GRAPH_ELEMENT

Examples

GRAPHFinGraph
MATCHp=(src:Account)-[t1:Transfers]->(mid:Account)-[t2:Transfers]->(dst:Account)
LETf=PATH_LAST(p)
RETURN
LABELS(f)ASlabels,
f.nick_nameASnick_name;
/*--------------------------+
 | labels | nick_name |
 +--------------------------+
 | Account | Vacation Fund |
 | Account | Vacation Fund |
 | Account | Vacation Fund |
 | Account | Vacation Fund |
 | Account | Rainy Day Fund |
 | Account | Rainy Day Fund |
 | Account | Rainy Day Fund |
 +--------------------------*/

PATH_LENGTH

PATH_LENGTH(graph_path)

Description

Gets the number of edges in a graph path.

Definitions

  • graph_path: A GRAPH_PATH value that represents the graph path with the edges to count.

Details

Returns NULL if graph_path is NULL.

Return type

INT64

Examples

GRAPHFinGraph
MATCHp=(src:Account)-[t1:Transfers]->(mid:Account)-[t2:Transfers]->(dst:Account)
RETURNPATH_LENGTH(p)ASresults
/*---------+
 | results |
 +---------+
 | 2 |
 | 2 |
 | 2 |
 | 2 |
 | 2 |
 | 2 |
 | 2 |
 +---------*/

PROPERTY_NAMES

PROPERTY_NAMES(element)

Description

Gets the name of each property associated with a graph element and preserves the original case of each name.

Arguments

  • element: A GRAPH_ELEMENT value.

Details

Returns NULL if element is NULL.

Return type

ARRAY<STRING>

Examples

GRAPHFinGraph
MATCH(n:Person|Account)
RETURNPROPERTY_NAMES(n)ASproperty_names,n.id
/*-----------------------------------------------+
 | label | id |
 +-----------------------------------------------+
 | [create_time, id, is_blocked, nick_name] | 7 |
 | [create_time, id, is_blocked, nick_name] | 16 |
 | [create_time, id, is_blocked, nick_name] | 20 |
 | [birthday, city, country, id, name] | 1 |
 | [birthday, city, country, id, name] | 2 |
 | [birthday, city, country, id, name] | 3 |
 +-----------------------------------------------*/

SOURCE_NODE_ID

SOURCE_NODE_ID(edge_element)

Description

Gets a unique identifier of a graph edge's source node. The unique identifier is only valid for the scope of the query where it's obtained.

Arguments

  • edge_element: A GRAPH_ELEMENT value that represents an edge.

Details

Returns NULL if edge_element is NULL.

Return type

STRING

Examples

GRAPHFinGraph
MATCH(p:Person)-[o:Owns]->(:Account)
RETURNp.nameASname,SOURCE_NODE_ID(o)ASsource_node_id
/*-------------------------------------+
 | name | source_node_id |
 +------|------------------------------+
 | Alex | mUZpbkdyYXBoLlBlcnNvbgB4kQI= |
 | Dana | mUZpbkdyYXBoLlBlcnNvbgB4kQQ= |
 | Lee | mUZpbkdyYXBoLlBlcnNvbgB4kQY= |
 +-------------------------------------*/

Note that the actual identifiers obtained may be different from what's shown above.

Supplemental materials

Horizontal aggregate function calls in GQL

In GQL, a horizontal aggregate function is an aggregate function that summarizes the contents of exactly one array-typed value. Because a horizontal aggregate function doesn't need to aggregate vertically across rows like a traditional aggregate function, you can use it like a normal function expression. Horizontal aggregates are only allowed in certain syntactic contexts: LET, FILTER statements or WHERE clauses.

Horizontal aggregation is especially useful when paired with a group variable. You can create a group variable inside a quantified path pattern in a linear graph query.

Some aggregates use an ORDER BY clause, such as the ARRAY_AGG, STRING_AGG, and ARRAY_CONCAT_AGG functions. For these aggregates the system orders inputs by their position in the array if you don't provide an ORDER BY clause.

Syntactic restrictions

  • The argument to the aggregate function must reference exactly one array-typed value.
  • Can be used in LET, FILTER statements, or WHERE clauses only.
  • Nesting horizontal aggregates isn't allowed.

Examples

In the following query, the SUM function horizontally aggregates over an array (arr), and then produces the sum of the values in arr:

GRAPHFinGraph
LETarr=[1,2,3]
LETtotal=SUM(arr)
RETURNtotal
/*-------+
 | total |
 +-------+
 | 6 |
 +-------*/

In the following query, the SUM function horizontally aggregates over an array of structs (arr), and then produces the sum of the x fields in the array:

GRAPHFinGraph
LETarr=[STRUCT(1asx,10asy),STRUCT(2,9),STRUCT(3,8)]
LETtotal=SUM(arr.x)
RETURNtotal
/*-------+
 | total |
 +-------+
 | 6 |
 +-------*/

In the following query, the AVG function horizontally aggregates over an array of structs (arr), and then produces the average of the x and y fields in the array:

GRAPHFinGraph
LETarr=[STRUCT(1asx,10asy),STRUCT(2,9),STRUCT(3,8)]
LETavg_sum=AVG(arr.x+arr.y)
RETURNavg_sum
/*---------+
 | avg_sum |
 +---------+
 | 11 |
 +---------*/

The ARRAY_AGG function can be used as a projection when horizontally aggregating. The resulting array is in the same order as the array that's horizontally aggregated over.

GRAPHFinGraph
LETarr=[STRUCT(1asx,9asy),STRUCT(2,9),STRUCT(4,8)]
LETresult=ARRAY_AGG(arr.x+arr.y)
RETURNresult
/*--------------+
 | result |
 +--------------+
 | [10, 11, 12] |
 +--------------*/

The following query produces an error because two arrays were passed into the AVG aggregate function:

-- ERROR: Horizontal aggregation on more than one array-typed variable
-- isn't allowed
GRAPHFinGraph
LETarr1=[1,2,3]
LETarr2=[5,4,3]
LETavg_val=AVG(arr1+arr2)
RETURNavg_val

The following query demonstrates a common pitfall. All instances of the array that we're horizontal aggregating over are treated as a single element from that array in the aggregate.

The fix is to lift any expressions that want to use the array as is outside the horizontal aggregation.

-- ERROR: No matching signature for function ARRAY_LENGTH for argument types: INT64
GRAPHFinGraph
LETarr1=[1,2,3]
LETbad_avg_val=SUM(arr1/ARRAY_LENGTH(arr1))
RETURNbad_avg_val

The fix:

GRAPHFinGraph
LETarr1=[1,2,3]
LETlen=ARRAY_LENGTH(arr1)
LETavg_val=SUM(arr1/len)
RETURNavg_val

In the following query, the COUNT function counts the unique amount transfers with one to three hops between a source account (src) and a destination account (dst):

GRAPHFinGraph
MATCH(src:Account)-[e:Transfers]->{1,3}(dst:Account)
WHEREsrc!=dst
LETnum_transfers=COUNT(e)
LETunique_amount_transfers=COUNT(DISTINCTe.amount)
FILTERunique_amount_transfers!=num_transfers
RETURNsrc.idassrc_id,num_transfers,unique_amount_transfers,dst.idASdestination_account_id
/*---------------------------------------------------------------------------+
 | src_id | num_transfers | unique_transfers_amount | destination_account_id |
 +---------------------------------------------------------------------------+
 | 7 | 3 | 2 | 16 |
 | 20 | 3 | 2 | 16 |
 | 7 | 2 | 1 | 20 |
 | 16 | 3 | 2 | 20 |
 +---------------------------------------------------------------------------*/

In the following query, the SUM function takes a group variable called e that represents an array of transfers, and then sums the amount for each transfer. Horizontal aggregation isn't allowed in the RETURN statement. ARRAY_AGG is a vertical aggregate over the result set, which is grouped implicitly by the non-aggregated columns (source_account_id, destination_account_id). ARRAY_AGG produces one row for each distinct destination account.

GRAPHFinGraph
MATCH(src:Account{id:7})-[e:Transfers]->{1,2}(dst:Account)
LETtotal_amount=SUM(e.amount)
RETURN
src.idASsource_account_id,dst.idASdestination_account_id,
ARRAY_AGG(total_amount)astotal_amounts_per_path
/*---------------------------------------------------------------------+
 | source_account_id | destination_account_id | total_amounts_per_path |
 +---------------------------------------------------------------------+
 | 7 | 16 | 300,100 |
 | 7 | 20 | 600,400 |
 +---------------------------------------------------------------------*/

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025年11月24日 UTC.