GQL functions

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

Function list

NameSummary
DESTINATION_NODE_IDGets 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_IDGets a graph element's unique identifier.
IS_ACYCLICChecks if a graph path has a repeating node.
IS_FIRST Returnstrue if this row is in the firstk rows (1-based) within the window.
IS_SIMPLEChecks if a graph path is simple.
IS_TRAILChecks if a graph path has a repeating edge.
LABELSGets 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.
PATHCreates a graph path from a list of graph elements.
PATH_FIRSTGets the first node in a graph path.
PATH_LASTGets the last node in a graph path.
PATH_LENGTHGets the number of edges in a graph path.
PROPERTY_NAMESGets the property names associated with a graph element.
SOURCE_NODE_IDGets 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: AGRAPH_ELEMENT value that represents an edge.

Details

ReturnsNULL ifedge_element isNULL.

Return type

STRING

Examples

GRAPHFinGraphMATCH(: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 theoriginal order in the graph path.

Definitions

  • graph_path: AGRAPH_PATH value that represents a graph path.

Details

Ifgraph_path isNULL, returnsNULL.

Return type

ARRAY<GRAPH_ELEMENT>

Examples

GRAPHFinGraphMATCHp=(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: AGRAPH_ELEMENT value.

Details

ReturnsNULL ifelement isNULL.

Return type

STRING

Examples

GRAPHFinGraphMATCH(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. ReturnsTRUE if a repetitionisn't found, otherwise returnsFALSE.

Definitions

  • graph_path: AGRAPH_PATH value that represents a graph path.

Details

Two nodes are considered equal if they compare as equal.

ReturnsNULL ifgraph_path isNULL.

Return type

BOOL

Examples

GRAPHFinGraphMATCHp=(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_clauseover_clause:([window_specification])window_specification:[PARTITIONBYpartition_expression[,...]][ORDERBYexpression[{ASC|DESC}][,...]]

Description

Returnstrue if the current row is in the firstk rows (1-based) in thewindow; otherwise, returnsfalse. This function doesn't require theORDER BYclause.

Details

  • Thek value must be positive; otherwise, a runtime error is raised.
  • If any rows are tied or ifORDER BY is omitted, the result is non-deterministic.If theORDER BY clause is unspecified or if all rows are tied, theresult is equivalent toANY-k.

Return Type

BOOL

IS_SIMPLE

IS_SIMPLE(graph_path)

Description

Checks if a graph path is simple. ReturnsTRUE if the path has no repeatednodes, or if the only repeated nodes are its head and tail. Otherwise, returnsFALSE.

Definitions

  • graph_path: AGRAPH_PATH value that represents a graph path.

Details

ReturnsNULL ifgraph_path isNULL.

Return type

BOOL

Examples

GRAPHFinGraphMATCHp=(a1:Account)-[t1:Transferswheret1.amount >200]->(a2:Account)-[t2:Transferswheret2.amount >200]->(a3:Account)-[t3:Transferswheret3.amount >100]->(a4:Account)RETURNIS_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. ReturnsTRUE if a repetitionisn't found, otherwise returnsFALSE.

Definitions

  • graph_path: AGRAPH_PATH value that represents a graph path.

Details

ReturnsNULL ifgraph_path isNULL.

Return type

BOOL

Examples

GRAPHFinGraphMATCHp=(a1:Account)-[t1:Transfers]->(a2:Account)-[t2:Transfers]->(a3:Account)-[t3:Transfers]->(a4:Account)WHEREa1.id <a4.idRETURNIS_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 caseof each label.

Arguments

  • element: AGRAPH_ELEMENT value that represents the graph element toextract labels from.

Details

ReturnsNULL ifelement isNULL.

Note: Labels in a graph element are uniquely identified by their names. Labelsare case insensitive. A defined label in the schema always takes precedence overdynamic label when their names conflict.To learn how to model dynamic labels, see thedynamic label definition.

Return type

ARRAY<STRING>

Examples

GRAPHFinGraphMATCH(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 theoriginal order in the graph path.

Definitions

  • graph_path: AGRAPH_PATH value that represents a graph path.

Details

ReturnsNULL ifgraph_path isNULL.

Return type

ARRAY<GRAPH_ELEMENT>

Examples

GRAPHFinGraphMATCHp=(src:Account)-[t1:Transfers]->(mid:Account)-[t2:Transfers]->(dst:Account)LETns=NODES(p)RETURNJSON_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: AGRAPH_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 isNULL.
  • Nodes aren't interleaved with edges.
  • An edge doesn't connect to neighboring nodes.

Return type

GRAPH_PATH

Examples

GRAPHFinGraphMATCH(src:Account)-[t1:Transfers]->(mid:Account)-[t2:Transfers]->(dst:Account)LETp=PATH(src,t1,mid,t2,dst)RETURNJSON_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.GRAPHFinGraphMATCH(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.GRAPHFinGraphMATCH(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.GRAPHFinGraphMATCH(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: AGRAPH_PATH value that represents the graph path toextract the first node from.

Details

ReturnsNULL ifgraph_path isNULL.

Return type

GRAPH_ELEMENT

Examples

GRAPHFinGraphMATCHp=(src:Account)-[t1:Transfers]->(mid:Account)-[t2:Transfers]->(dst:Account)LETf=PATH_FIRST(p)RETURNLABELS(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: AGRAPH_PATH value that represents the graph path toextract the last node from.

Details

ReturnsNULL ifgraph_path isNULL.

Return type

GRAPH_ELEMENT

Examples

GRAPHFinGraphMATCHp=(src:Account)-[t1:Transfers]->(mid:Account)-[t2:Transfers]->(dst:Account)LETf=PATH_LAST(p)RETURNLABELS(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: AGRAPH_PATH value that represents the graph path with theedges to count.

Details

ReturnsNULL ifgraph_path isNULL.

Return type

INT64

Examples

GRAPHFinGraphMATCHp=(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 preservesthe original case of each name.

Note: Properties in a graph element are uniquely identified by their names.Properties are case insensitive. Defined properties in the schema alwaystake precedence overdynamic properties when their names conflict.For more information, seedynamic properties definition.

Arguments

  • element: AGRAPH_ELEMENT value.

Details

ReturnsNULL ifelement isNULL.

Return type

ARRAY<STRING>

Examples

GRAPHFinGraphMATCH(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: AGRAPH_ELEMENT value that represents an edge.

Details

ReturnsNULL ifedge_element isNULL.

Return type

STRING

Examples

GRAPHFinGraphMATCH(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 summarizesthe contents of exactly one array-typed value. Because a horizontal aggregatefunction doesn't need to aggregate vertically across rows like a traditionalaggregate function, you can use it like a normal function expression.Horizontal aggregates are only allowed in certain syntactic contexts:LET,FILTER statements orWHERE clauses.

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

Some aggregates use anORDER BY clause, such as theARRAY_AGG,STRING_AGG, andARRAY_CONCAT_AGG functions. For these aggregates thesystem orders inputs by their position in the array if you don't provide anORDER BY clause.

Syntactic restrictions

  • The argument to the aggregate function must reference exactly one array-typedvalue.
  • Can be used inLET,FILTER statements, orWHERE clauses only.
  • Nesting horizontal aggregates isn't allowed.

Examples

In the following query, theSUM function horizontally aggregates over anarray (arr), and then produces the sum of the values inarr:

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

In the following query, theSUM function horizontally aggregates over anarray of structs (arr), and then produces the sum of thex fields in thearray:

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

In the following query, theAVG function horizontally aggregates over anarray of structs (arr), and then produces the average of thex andyfields in the array:

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

TheARRAY_AGG function can be used as a projection when horizontallyaggregating. The resulting array is in the same order as the array that'shorizontally aggregated over.

GRAPHFinGraphLETarr=[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 intotheAVG aggregate function:

-- ERROR: Horizontal aggregation on more than one array-typed variable-- isn't allowedGRAPHFinGraphLETarr1=[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 arraythat we're horizontal aggregating over are treated as a single element from thatarray in the aggregate.

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

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

The fix:

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

In the following query, theCOUNT function counts the unique amounttransfers with one to three hops between a source account (src) and adestination account (dst):

GRAPHFinGraphMATCH(src:Account)-[e:Transfers]->{1,3}(dst:Account)WHEREsrc!=dstLETnum_transfers=COUNT(e)LETunique_amount_transfers=COUNT(DISTINCTe.amount)FILTERunique_amount_transfers!=num_transfersRETURNsrc.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, theSUM function takes a group variable calledethat represents an array of transfers, and then sums the amount for eachtransfer. Horizontal aggregation isn't allowed in theRETURNstatement.ARRAY_AGG is a vertical aggregate over the result set, which isgrouped implicitly by the non-aggregated columns(source_account_id,destination_account_id).ARRAY_AGG produces one rowfor each distinct destination account.

GRAPHFinGraphMATCH(src:Account{id:7})-[e:Transfers]->{1,2}(dst:Account)LETtotal_amount=SUM(e.amount)RETURNsrc.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 theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.