Graph Query Language (GQL) lets you execute multiple linear graph queries in one query. Each linear graph query generates results (the working table) and then passes those results to the next.
GQL supports the following building blocks, which can be composited into a GQL query based on the syntax rules .
Language list
| Name | Summary |
|---|---|
| GQL syntax | Creates a graph query with the GQL syntax. |
GRAPH
clause
|
Specifies a property graph to query. |
FILTER
statement
|
Filters out rows in the query results that don't satisfy a specified condition. |
FOR
statement
|
Unnests an ARRAY
-typed expression. |
LET
statement
|
Defines variables and assigns values for later use in the current linear query statement. |
LIMIT
statement
|
Limits the number of query results. |
MATCH
statement
|
Matches data described by a graph pattern. |
NEXT
statement
|
Chains multiple linear query statements together. |
OFFSET
statement
|
Skips a specified number of rows in the query results. |
ORDER BY
statement
|
Orders the query results. |
RETURN
statement
|
Marks the end of a linear query statement and returns the results. |
SKIP
statement
|
Synonym for the OFFSET
statement. |
WITH
statement
|
Passes on the specified columns, optionally filtering, renaming, and transforming those results. |
| Set operation | Combines a sequence of linear query statements with a set operation. |
| Graph hints | Query hints, which make the query optimizer use a specific operator in the execution plan. |
GQL syntax
graph_query : GRAPH clause multi_linear_query_statement multi_linear_query_statement : linear_query_statement [ NEXT linear_query_statement ] [...] linear_query_statement : { simple_linear_query_statement | composite_linear_query_statement } composite_linear_query_statement : simple_linear_query_statement set_operator simple_linear_query_statement [...] simple_linear_query_statement : primitive_query_statement [...]
Description
Creates a graph query with the GQL syntax. The syntax rules define how to composite the building blocks of GQL into a query.
Definitions
-
primitive_query_statement: A statement in Query statements except for theNEXTstatement. -
simple_linear_query_statement: A list ofprimitive_query_statements that ends with aRETURNstatement . -
composite_linear_query_statement: A list ofsimple_linear_query_statements composited with the set operators . -
linear_query_statement: A statement that's either asimple_linear_query_statementor acomposite_linear_query_statement. -
multi_linear_query_statement: A list oflinear_query_statements chained together with theNEXTstatement . -
graph_query: A GQL query that starts with aGRAPHclause , then follows with amulti_linear_query_statement.
GRAPH
clause
GRAPH property_graph_name multi_linear_query_statement
Description
Specifies a property graph to query. This clause must be added before the first linear query statement in a graph query.
Definitions
-
property_graph_name: The name of the property graph to query. -
multi_linear_query_statement: A multi linear query statement. For more information, seemulti_linear_query_statementin GQL syntax .
Examples
The following example queries the FinGraph
property graph to find
accounts with incoming transfers and looks up their owners:
GRAPH
FinGraph
MATCH
(
:
Account
)
-[:
Transfers
]-
> (
account
:
Account
)
RETURN
account
,
COUNT
(
*
)
AS
num_incoming_transfers
GROUP
BY
account
NEXT
MATCH
(
account
:
Account
)
< -[:
Owns
]-
(
owner
:
Person
)
RETURN
account
.
id
AS
account_id
,
owner
.
name
AS
owner_name
,
num_incoming_transfers
/*--------------------------------------------------+
| account_id | owner_name | num_incoming_transfers |
+--------------------------------------------------+
| 7 | Alex | 1 |
| 20 | Dana | 1 |
| 6 | Lee | 3 |
+--------------------------------------------------*/
FILTER
statement
FILTER [ WHERE ] bool_expression
Description
Filters out rows in the query results that don't satisfy a specified condition.
Definitions
-
bool_expression: A boolean expression. Only rows whosebool_expressionevaluates toTRUEare included. Rows whosebool_expressionevaluates toNULLorFALSEare discarded.
Details
The FILTER
statement can reference columns in the working table.
The syntax for the FILTER
statement is similar to the syntax for the graph pattern WHERE
clause
, but they are evaluated
differently. The FILTER
statement is evaluated after the previous statement.
The WHERE
clause is evaluated as part of the containing statement.
Examples
In the following query, only people who were born before 1990-01-10
are included in the results table:
GRAPH
FinGraph
MATCH
(
p
:
Person
)
-[
o
:
Owns
]-
> (
a
:
Account
)
FILTER
p
.
Id
<>
1
RETURN
p
.
name
,
a
.
Id
AS
account_id
/*--------+------------+
| name | account_id |
+--------+------------+
| "Dana" | 20 |
| "Lee" | 16 |
+--------+------------*/
WHERE
is an optional keyword that you can include in a FILTER
statement.
The following query is semantically identical to the previous query:
GRAPH
FinGraph
MATCH
(
p
:
Person
)
-[
o
:
Owns
]-
> (
a
:
Account
)
FILTER
WHERE
p
.
Id
<>
1
RETURN
p
.
name
,
a
.
Id
AS
account_id
/*--------+------------+
| name | account_id |
+--------+------------+
| "Dana" | 20 |
| "Lee" | 16 |
+--------+------------*/
In the following example, FILTER
follows an aggregation step with
grouping. Semantically, it's similar to the HAVING
clause in SQL:
GRAPH
FinGraph
MATCH
(
source
:
Account
)
-[
e
:
Transfers
]-
> (
dest
:
Account
)
RETURN
source
,
COUNT
(
e
)
AS
num_transfers
GROUP
BY
source
NEXT
FILTER
WHERE
num_transfers
>
1
RETURN
source
.
id
AS
source_id
,
num_transfers
/*---------------------------+
| source_id | num_transfers |
+---------------------------+
| 7 | 2 |
| 20 | 2 |
+---------------------------*/
In the following example, an error is produced because FILTER
references m
, which isn't in the working table:
-- Error: m doesn't exist
GRAPH
FinGraph
MATCH
(
p
:
Person
)
-[
o
:
Owns
]-
> (
a
:
Account
)
FILTER
WHERE
m
.
Id
<>
1
RETURN
p
.
name
In the following example, an error is produced because even though p
is in the
working table, p
doesn't have a property called date_of_birth
:
-- ERROR: date_of_birth isn't a property of p
GRAPH
FinGraph
MATCH
(
p
:
Person
)
-[
o
:
Owns
]-
> (
a
:
Account
)
FILTER
WHERE
p
.
date_of_birth
<
'1990-01-10'
RETURN
p
.
name
FOR
statement
FOR element_name IN array_expression [ with_offset_clause ] with_offset_clause : WITH OFFSET [ AS offset_name ]
Description
Unnests an ARRAY
-typed expression and joins the result with the current working table.
Definitions
-
array_expression: AnARRAY-typed expression. -
element_name: The name of the element column. The name can't be the name of a column that already exists in the current linear query statement. -
offset_name: The name of the offset column. The name can't be the name of a column that already exists in the current linear query statement. If not specified, the default isoffset.
Details
The FOR
statement expands the working table by defining a new column for the
elements of array_expression
, with an optional offset column. The cardinality
of the working table might change as a result.
The FOR
statement can reference columns in the working table.
The FOR
statement evaluation is similar to the UNNEST
operator.
The FOR
statement doesn't preserve order.
And empty or NULL
array_expression
produces zero rows.
The keyword WITH
following the FOR
statement is always interpreted as the
beginning of with_offset_clause
. If you want to use the WITH
statement
following the FOR
statement, you should fully qualify the FOR
statement with with_offset_clause
, or use the RETURN
statement instead of the WITH
statement.
Examples
In the following query, there are three rows in the working table prior to the FOR
statement. After the FOR
statement, each row is expanded into two rows,
one per element
value from the array.
GRAPH
FinGraph
MATCH
(
p
:
Person
)
-[
o
:
Owns
]-
> (
a
:
Account
)
FOR
element
in
[
"all"
,
"some"
]
WITH
OFFSET
RETURN
p
.
Id
,
element
as
alert_type
,
offset
ORDER
BY
p
.
Id
,
element
,
offset
/*----------------------------+
| Id | alert_type | offset |
+----------------------------+
| 1 | all | 0 |
| 1 | some | 1 |
| 2 | all | 0 |
| 2 | some | 1 |
| 3 | all | 0 |
| 3 | some | 1 |
+----------------------------*/
In the following query, there are two rows in the working table prior to the FOR
statement. After the FOR
statement, each row is expanded into a
different number of rows, based on the value of array_expression
for that row.
GRAPH
FinGraph
MATCH
(
p
:
Person
)
-[
o
:
Owns
]-
> (
a
:
Account
)
FILTER
WHERE
p
.
Id
<>
1
FOR
element
in
GENERATE_ARRAY
(
1
,
p
.
Id
)
RETURN
p
.
Id
,
element
ORDER
BY
p
.
Id
,
element
/*----------------+
| Id | element |
+----------------+
| 2 | 1 |
| 2 | 2 |
| 3 | 1 |
| 3 | 2 |
| 3 | 3 |
+----------------*/
In the following query, there are three rows in the working table prior to the FOR
statement. After the FOR
statement, no row is produced because array_expression
is an empty array.
-- No rows produced
GRAPH
FinGraph
MATCH
(
p
:
Person
)
FOR
element
in
[]
WITH
OFFSET
AS
off
RETURN
p
.
name
,
element
,
off
In the following query, there are three rows in the working table prior to the FOR
statement. After the FOR
statement, no row is produced because array_expression
is a NULL
array.
-- No rows produced
GRAPH
FinGraph
MATCH
(
p
:
Person
)
FOR
element
in
CAST
(
NULL
AS
ARRAY<STRING>
)
WITH
OFFSET
RETURN
p
.
name
,
element
,
offset
In the following example, an error is produced because WITH
is used directly
After the FOR
statement. The query can be fixed by adding WITH OFFSET
after
the FOR
statement, or by using RETURN
directly instead of WITH
.
-- Error: Expected keyword OFFSET but got identifier "element"
GRAPH
FinGraph
FOR
element
in
[
1
,
2
,
3
]
WITH
element
as
col
RETURN
col
ORDER
BY
col
GRAPH
FinGraph
FOR
element
in
[
1
,
2
,
3
]
WITH
OFFSET
WITH
element
as
col
RETURN
col
ORDER
BY
col
/*-----+
| col |
+-----+
| 1 |
| 2 |
| 3 |
+-----*/
LET
statement
LET linear_graph_variable [, ...] linear_graph_variable : variable_name = value
Description
Defines variables and assigns values to them for later use in the current linear query statement.
Definitions
-
linear_graph_variable: The variable to define. -
variable_name: The name of the variable. -
value: A scalar expression that represents the value of the variable. The names referenced by this expression must be in the incoming working table.
Details
LET
doesn't change the cardinality of the working table nor modify its
existing columns.
The variable can only be used in the current linear query statement. To use it
in a following linear query statement, you must include it in the RETURN
statement as a column.
You can't define and reference a variable within the same LET
statement.
You can't redefine a variable with the same name.
You can use horizontal aggregate functions in this statement. To learn more, see Horizontal aggregate function calls in GQL .
Examples
In the following graph query, the variable a
is defined and then referenced
later:
GRAPH
FinGraph
MATCH
(
source
:
Account
)
-[
e
:
Transfers
]-
> (
destination
:
Account
)
LET
a
=
source
RETURN
a
.
id
AS
a_id
/*------+
| a_id |
+------+
| 20 |
| 7 |
| 7 |
| 20 |
| 16 |
+------*/
The following LET
statement in the second linear query statement is valid
because a
is defined and returned from the first linear query statement:
GRAPH
FinGraph
MATCH
(
source
:
Account
)
-[
e
:
Transfers
]-
> (
destination
:
Account
)
LET
a
=
source
RETURN
a
NEXT
LET
b
=
a
-- Valid: 'a' is defined and returned from the linear query statement above.
RETURN
b
.
id
AS
b_id
/*------+
| b_id |
+------+
| 20 |
| 7 |
| 7 |
| 20 |
| 16 |
+------*/
The following LET
statement in the second linear query statement is invalid
because a
isn't returned from the first linear query statement.
GRAPH
FinGraph
MATCH
(
source
:
Account
)
-[
e
:
Transfers
]-
> (
destination
:
Account
)
LET
a
=
source
RETURN
source
.
id
NEXT
LET
b
=
a
-- ERROR: 'a' doesn't exist.
RETURN
b
.
id
AS
b_id
The following LET
statement is invalid because a
is defined and then
referenced in the same LET
statement:
GRAPH
FinGraph
MATCH
(
source
:
Account
)
-[
e
:
Transfers
]-
> (
destination
:
Account
)
LET
a
=
source
,
b
=
a
-- ERROR: Can't define and reference 'a' in the same operation.
RETURN
a
The following LET
statement is valid because a
is defined first and then
referenced afterwards:
GRAPH
FinGraph
MATCH
(
source
:
Account
)
-[
e
:
Transfers
]-
> (
destination
:
Account
)
LET
a
=
source
LET
b
=
a
RETURN
b
.
id
AS
b_id
/*------+
| b_id |
+------+
| 20 |
| 7 |
| 7 |
| 20 |
| 16 |
+------*/
In the following examples, the LET
statements are invalid because a
is
redefined:
GRAPH
FinGraph
MATCH
(
source
:
Account
)
-[
e
:
Transfers
]-
> (
destination
:
Account
)
LET
a
=
source
,
a
=
destination
-- ERROR: 'a' has already been defined.
RETURN
a
.
id
AS
a_id
GRAPH
FinGraph
MATCH
(
source
:
Account
)
-[
e
:
Transfers
]-
> (
destination
:
Account
)
LET
a
=
source
LET
a
=
destination
-- ERROR: 'a' has already been defined.
RETURN
a
.
id
AS
a_id
In the following examples, the LET
statements are invalid because b
is
redefined:
GRAPH
FinGraph
MATCH
(
source
:
Account
)
-[
e
:
Transfers
]-
> (
destination
:
Account
)
LET
a
=
source
LET
b
=
destination
RETURN
a
,
b
NEXT
MATCH
(
a
)
LET
b
=
a
-- ERROR: 'b' has already been defined.
RETURN
b
.
id
The following LET
statement is valid because although b
is defined in the
first linear query statement, it's not passed to the second linear query
statement:
GRAPH
FinGraph
MATCH
(
source
:
Account
)
-[
e
:
Transfers
]-
> (
destination
:
Account
)
LET
a
=
source
LET
b
=
destination
RETURN
a
NEXT
MATCH
(
a
)
LET
b
=
a
RETURN
b
.
id
/*------+
| b_id |
+------+
| 20 |
| 7 |
| 7 |
| 20 |
| 16 |
+------*/
LIMIT
statement
LIMIT count
Description
Limits the number of query results.
Definitions
-
count: A non-negativeINT64value that represents the number of results to produce. For more information, see theLIMITandOFFSETclauses .
Details
The LIMIT
statement can appear before the RETURN
statement. You can also use
it as a qualifying clause in the RETURN
statement
.
Examples
The following example uses the LIMIT
statement to limit the query results to
three rows:
GRAPH
FinGraph
MATCH
(
source
:
Account
)
-[
e
:
Transfers
]-
> (
destination
:
Account
)
ORDER
BY
source
.
Id
LIMIT
3
RETURN
source
.
Id
,
source
.
nick_name
/*---------+---------------+
| Id | nick_name |
+---------+---------------+
| 7 | Vacation fund |
| 7 | Vacation fund |
| 16 | Vacation fund |
+-------------------------*/
The following query finds the account and its owner with the most outgoing transfers to a blocked account:
GRAPH
FinGraph
MATCH
(
src_account
:
Account
)
-[
transfer
:
Transfers
]-
> (
dst_account
:
Account
{
is_blocked
:
true
}
)
RETURN
src_account
,
COUNT
(
transfer
)
as
total_transfers
ORDER
BY
total_transfers
LIMIT
1
NEXT
MATCH
(
src_account
:
Account
)
< -[
owns
:
Owns
]-
(
owner
:
Person
)
RETURN
src_account
.
id
AS
account_id
,
owner
.
name
AS
owner_name
/*-------------------------+
| account_id | owner_name |
+-------------------------+
| 20 | Dana |
+-------------------------*/
MATCH
statement
[ OPTIONAL ] MATCH [ match_hint ] graph_pattern
Description
Matches data described by a graph pattern. You can have zero or more MATCH
statements in a linear query statement.
Definitions
-
MATCH graph_pattern: The graph pattern to match. For more information, seeMATCHgraph pattern definition . -
OPTIONAL MATCH graph_pattern: The graph pattern to optionally match. If there are missing parts in the pattern, the missing parts are represented byNULLvalues. For more information, seeOPTIONAL MATCHgraph pattern definition . -
match_hint: A hint that makes the query optimizer use a specific statement in the execution plan. This statement supports graph hints. For more information, see Graph hints .
Details
The MATCH
statement joins the incoming working table with the matched
result with either INNER JOIN
or CROSS JOIN
semantics.
The INNER JOIN
semantics is used when the working table and matched result
have variables in common. In the following example, the INNER JOIN
semantics is used because friend
is produced by both MATCH
statements:
MATCH
(
person
:
Person
)
-[:
knows
]-
> (
friend
:
Person
)
MATCH
(
friend
)
-[:
knows
]-
> (
otherFriend
:
Person
)
The CROSS JOIN
semantics is used when the incoming working table and matched
result have no variables in common. In the following example, the CROSS JOIN
semantics is used because person1
and friend
exist in the result of the
first MATCH
statement, but not the second one:
MATCH
(
person1
:
Person
)
-[:
knows
]-
> (
friend
:
Person
)
MATCH
(
person2
:
Person
)
-[:
knows
]-
> (
otherFriend
:
Person
)
Examples
The following query matches all Person
nodes and returns the name and ID of
each person:
GRAPH
FinGraph
MATCH
(
p
:
Person
)
RETURN
p
.
name
,
p
.
id
/*-----------+
| name | id |
+-----------+
| Alex | 1 |
| Dana | 2 |
| Lee | 3 |
+-----------*/
The following query matches all Person
and Account
nodes and returns their
labels and ID:
GRAPH
FinGraph
MATCH
(
n
:
Person
|
Account
)
RETURN
LABELS
(
n
)
AS
label
,
n
.
id
/*----------------+
| label | id |
+----------------+
| [Account] | 7 |
| [Account] | 16 |
| [Account] | 20 |
| [Person] | 1 |
| [Person] | 2 |
| [Person] | 3 |
+----------------*/
The following query matches all Account
nodes that aren't blocked:
GRAPH
FinGraph
MATCH
(
a
:
Account
{
is_blocked
:
false
}
)
RETURN
a
.
id
/*----+
| id |
+----+
| 7 |
| 20 |
+----*/
The following query matches all Person
nodes that have a birthday
less than 1990-01-10
:
GRAPH
FinGraph
MATCH
(
p
:
Person
WHERE
p
.
birthday
<
'1990-01-10'
)
RETURN
p
.
name
/*------+
| name |
+------+
| Dana |
| Lee |
+------*/
The following query matches all Owns
edges:
GRAPH
FinGraph
MATCH
-[
e
:
Owns
]-
> RETURN
e
.
id
/*----+
| id |
+----+
| 1 |
| 3 |
| 2 |
+----*/
The following query matches all Owns
edges created within a specific period of
time:
GRAPH
FinGraph
MATCH
-[
e
:
Owns
WHERE
e
.
create_time
>
'2020-01-14'
AND
e
.
create_time
<
'2020-05-14'
]-
> RETURN
e
.
id
/*----+
| id |
+----+
| 2 |
| 3 |
+----*/
The following query matches all Transfers
edges where a blocked account is
involved in any direction:
GRAPH
FinGraph
MATCH
(
account
:
Account
)
-[
transfer
:
Transfers
]-
(
:
Account
{
is_blocked
:
true
}
)
RETURN
transfer
.
order_number
,
transfer
.
amount
/*--------------------------+
| order_number | amount |
+--------------------------+
| 304330008004315 | 300 |
| 304120005529714 | 100 |
| 103650009791820 | 300 |
| 302290001255747 | 200 |
+--------------------------*/
The following query matches all Transfers
initiated from an Account
owned by Person
with id
equal to 2
:
GRAPH
FinGraph
MATCH
(
p
:
Person
{
id
:
2
}
)
-[:
Owns
]-
> (
account
:
Account
)
-[
t
:
Transfers
]-
>
(
to_account
:
Account
)
RETURN
p
.
id
AS
sender_id
,
to_account
.
id
AS
to_id
/*-------------------+
| sender_id | to_id |
+-------------------+
| 2 | 7 |
| 2 | 16 |
+-------------------*/
The following query matches all the destination Accounts
one to three
transfers away from a source Account
with id
equal to 7
, other than the
source itself:
GRAPH
FinGraph
MATCH
(
src
:
Account
{
id
:
7
}
)
-[
e
:
Transfers
]->{
1
,
3
}
(
dst
:
Account
)
WHERE
src
!=
dst
RETURN
ARRAY_LENGTH
(
e
)
AS
hops
,
dst
.
id
AS
destination_account_id
/*-------------------------------+
| hops | destination_account_id |
+-------------------------------+
| 1 | 16 |
| 3 | 16 |
| 3 | 16 |
| 1 | 16 |
| 2 | 20 |
| 2 | 20 |
+-------------------------------*/
The following query matches paths between Account
nodes with one to two Transfers
edges through intermediate accounts that are blocked:
GRAPH
FinGraph
MATCH
(
src
:
Account
)
((
a
:
Account
)
-[:
Transfers
]-
> (
b
:
Account
{
is_blocked
:
true
}
)
WHERE
a
!=
b
)
{
1
,
2
}
-[:
Transfers
]-
> (
dst
:
Account
)
RETURN
src
.
id
AS
source_account_id
,
dst
.
id
AS
destination_account_id
/*--------------------------------------------+
| source_account_id | destination_account_id |
+--------------------------------------------+
| 7 | 20 |
| 7 | 20 |
| 20 | 20 |
+--------------------------------------------*/
The following query finds unique reachable accounts which are one or two
transfers away from a given Account
node:
GRAPH
FinGraph
MATCH
ANY
(
src
:
Account
{
id
:
7
}
)
-[
e
:
Transfers
]->{
1
,
2
}
(
dst
:
Account
)
LET
ids_in_path
=
ARRAY_CONCAT
(
ARRAY_AGG
(
e
.
Id
),
[
dst
.
Id
]
)
RETURN
src
.
id
AS
source_account_id
,
dst
.
id
AS
destination_account_id
,
ids_in_path
/*----------------------------------------------------------+
| source_account_id | destination_account_id | ids_in_path |
+----------------------------------------------------------+
| 7 | 16 | [7, 16] |
| 7 | 20 | [7, 16, 20] |
+----------------------------------------------------------*/
The following query matches all Person
nodes and optionally matches the
blocked Account
owned by the Person
. The missing blocked Account
is
represented as NULL
:
GRAPH
FinGraph
MATCH
(
n
:
Person
)
OPTIONAL
MATCH
(
n
:
Person
)
-[:
Owns
]-
> (
a
:
Account
{
is_blocked
:
TRUE
}
)
RETURN
n
.
name
,
a
.
id
AS
blocked_account_id
/*--------------+
| name | id |
+--------------+
| Lee | 16 |
| Alex | NULL |
| Dana | NULL |
+--------------*/
NEXT
statement
NEXT
Description
Chains multiple linear query statements together.
Examples
The following linear query statements are chained by the NEXT
statement:
GRAPH
FinGraph
MATCH
(
:
Account
)
-[:
Transfers
]-
> (
account
:
Account
)
RETURN
account
,
COUNT
(
*
)
AS
num_incoming_transfers
GROUP
BY
account
NEXT
MATCH
(
account
:
Account
)
< -[:
Owns
]-
(
owner
:
Person
)
RETURN
account
.
id
AS
account_id
,
owner
.
name
AS
owner_name
,
num_incoming_transfers
NEXT
FILTER
num_incoming_transfers
<
2
RETURN
account_id
,
owner_name
/*-------------------------+
| account_id | owner_name |
+-------------------------+
| 7 | Alex |
| 20 | Dana |
+-------------------------*/
OFFSET
statement
OFFSET count
Description
Skips a specified number of rows in the query results.
Definitions
-
count: A non-negativeINT64value that represents the number of rows to skip. For more information, see theLIMITandOFFSETclauses .
Details
The OFFSET
statement can appear anywhere in a linear query statement before
the RETURN
statement.
Examples
In the following example, the first two rows aren't included in the results:
GRAPH
FinGraph
MATCH
(
p
:
Person
)
OFFSET
2
RETURN
p
.
name
,
p
.
id
/*-----------+
| name | id |
+-----------+
| Lee | 3 |
+-----------*/
ORDER BY
statement
ORDER BY order_by_specification [, ...] order_by_specification : expression [ COLLATE collation_specification ] [ { ASC | ASCENDING | DESC | DESCENDING } ]
Description
Orders the query results.
Definitions
-
expression: The sort criterion for the result set. For more information, see theORDER BYclause . -
COLLATE collation_specification: The collation specification forexpression. For more information, see theORDER BYclause . -
ASC | ASCENDING | DESC | DESCENDING: The sort order, which can be either ascending or descending. The following options are synonymous:-
ASCandASCENDING -
DESCandDESCENDING
For more information about sort order, see the
ORDER BYclause . -
Details
Ordinals aren't supported in the ORDER BY
statement.
The ORDER BY
statement is ignored unless it's immediately followed by the LIMIT
or OFFSET
statement.
If you would like to apply ORDER BY
to what is in RETURN
statement, use the ORDER BY
clause in RETURN
statement. For more information, see RETURN
statement
.
Examples
The following query sorts the results by the transfer.amount
values in descending order:
GRAPH
FinGraph
MATCH
(
src_account
:
Account
)
-[
transfer
:
Transfers
]-
> (
dst_account
:
Account
)
ORDER
BY
transfer
.
amount
DESC
LIMIT
3
RETURN
src_account
.
id
AS
account_id
,
transfer
.
amount
AS
transfer_amount
/*------------------------------+
| account_id | transfer_amount |
+------------------------------+
| 20 | 500 |
| 7 | 300 |
| 16 | 300 |
+------------------------------*/
GRAPH
FinGraph
MATCH
(
src_account
:
Account
)
-[
transfer
:
Transfers
]-
> (
dst_account
:
Account
)
ORDER
BY
transfer
.
amount
DESC
OFFSET
1
RETURN
src_account
.
id
AS
account_id
,
transfer
.
amount
AS
transfer_amount
/*------------------------------+
| account_id | transfer_amount |
+------------------------------+
| 7 | 300 |
| 16 | 300 |
| 20 | 200 |
| 7 | 100 |
+------------------------------*/
If you don't include the LIMIT
or OFFSET
statement right after the ORDER BY
statement, the effect of ORDER BY
is discarded and the result is
unordered.
-- Warning: The transfer.amount values aren't sorted because the
-- LIMIT statement is missing.
GRAPH
FinGraph
MATCH
(
src_account
:
Account
)
-[
transfer
:
Transfers
]-
> (
dst_account
:
Account
)
ORDER
BY
transfer
.
amount
DESC
RETURN
src_account
.
id
AS
account_id
,
transfer
.
amount
AS
transfer_amount
/*------------------------------+
| account_id | transfer_amount |
+------------------------------+
| 7 | 300 |
| 7 | 100 |
| 16 | 300 |
| 20 | 500 |
| 20 | 200 |
+------------------------------*/
-- Warning: Using the LIMIT clause in the RETURN statement, but not immediately
-- after the ORDER BY statement, also returns the unordered transfer.amount
-- values.
GRAPH
FinGraph
MATCH
(
src_account
:
Account
)
-[
transfer
:
Transfers
]-
> (
dst_account
:
Account
)
ORDER
BY
transfer
.
amount
DESC
RETURN
src_account
.
id
AS
account_id
,
transfer
.
amount
AS
transfer_amount
LIMIT
10
/*------------------------------+
| account_id | transfer_amount |
+------------------------------+
| 7 | 300 |
| 7 | 100 |
| 16 | 300 |
| 20 | 500 |
| 20 | 200 |
+------------------------------*/
RETURN
statement
RETURN *
RETURN [ { ALL | DISTINCT } ] return_item [, ... ] [ group_by_clause ] [ order_by_clause ] [ limit_and_offset_clauses ] return_item : { expression [ AS alias ] | * } limit_and_offset_clauses : { limit_clause | offset_clause | offset_clause limit_clause }
Description
Marks the end of a linear query statement and returns the results. Only one RETURN
statement is allowed in a linear query statement.
Definitions
-
*: Returns all columns in the current working table. -
return_item: A column to include in the results. -
ALL: Returns all rows. This is equivalent to not using any prefix. -
DISTINCT: Duplicate rows are discarded and only the remaining distinct rows are returned. This deduplication takes place after any aggregation is performed. -
expression: An expression that represents a column to produce. Aggregation is supported. -
alias: An alias forexpression. -
group_by_clause: Groups the current rows of the working table, using theGROUP BYclause . -
order_by_clause: Orders the current rows in a linear query statement, using theORDER BYclause . -
limit_clause: Limits the number of current rows in a linear query statement, using theLIMITclause . -
offset_clause: Skips a specified number of rows in a linear query statement, using theOFFSETclause .
Details
If any expression performs aggregation, and no GROUP BY
clause is
specified, all groupable items from the return list are used implicitly as
grouping keys.
Ordinals aren't supported in the ORDER BY
and GROUP BY
clauses.
Examples
The following query returns p.name
and p.id
:
GRAPH
FinGraph
MATCH
(
p
:
Person
)
RETURN
p
.
name
,
p
.
id
/*-----------+
| name | id |
+-----------+
| Alex | 1 |
| Dana | 2 |
| Lee | 3 |
+-----------*/
In the following example, the first linear query statement returns all columns
including p
, a
, b
, and c
. The second linear query statement returns the
specified p.name
and d
columns:
GRAPH
FinGraph
MATCH
(
p
:
Person
)
LET
a
=
1
,
b
=
2
,
c
=
3
RETURN
*
NEXT
RETURN
p
.
name
,
(
a
+
b
+
c
)
AS
d
/*----------+
| name | d |
+----------+
| Alex | 6 |
| Dana | 6 |
| Lee | 6 |
+----------*/
The following query returns distinct rows:
GRAPH
FinGraph
MATCH
(
src
:
Account
{
id
:
7
}
)
-[
e
:
Transfers
]->{
1
,
3
}
(
dst
:
Account
)
RETURN
DISTINCT
ARRAY_LENGTH
(
e
)
AS
hops
,
dst
.
id
AS
destination_account_id
/*-------------------------------+
| hops | destination_account_id |
+-------------------------------+
| 3 | 7 |
| 1 | 16 |
| 3 | 16 |
| 2 | 20 |
+-------------------------------*/
In the following example, the first linear query statement returns account
and
aggregated num_incoming_transfers
per account. The second statement returns
sorted result.
GRAPH
FinGraph
MATCH
(
:
Account
)
-[:
Transfers
]-
> (
account
:
Account
)
RETURN
account
,
COUNT
(
*
)
AS
num_incoming_transfers
GROUP
BY
account
NEXT
MATCH
(
account
:
Account
)
< -[:
Owns
]-
(
owner
:
Person
)
RETURN
owner
.
name
AS
owner_name
,
num_incoming_transfers
ORDER
BY
num_incoming_transfers
DESC
/*-------------------------------------+
| owner_name | num_incoming_transfers |
+-------------------------------------+
| Lee | 3 |
| Alex | 1 |
| Dana | 1 |
+-------------------------------------*/
In the following example, the LIMIT
clause in the RETURN
statement
reduces the results to one row:
GRAPH
FinGraph
MATCH
(
p
:
Person
)
RETURN
p
.
name
,
p
.
id
LIMIT
1
/*-----------+
| name | id |
+-----------+
| Alex | 1 |
+-----------*/
In the following example, the OFFSET
clause in the RETURN
statement
skips the first row:
GRAPH
FinGraph
MATCH
(
p
:
Person
)
RETURN
p
.
name
,
p
.
id
OFFSET
1
/*-----------+
| name | id |
+-----------+
| Dana | 2 |
| Lee | 3 |
+-----------*/
In the following example, the OFFSET
clause in the RETURN
statement
skips the first row, then the LIMIT
clause reduces the
results to one row:
GRAPH
FinGraph
MATCH
(
p
:
Person
)
RETURN
p
.
name
,
p
.
id
OFFSET
1
LIMIT
1
/*-----------+
| name | id |
+-----------+
| Dana | 2 |
+-----------*/
In the following example, an error is produced because the OFFSET
clause must
come before the LIMIT
clause when they are both used in the RETURN
statement:
-- Error: The LIMIT clause must come after the OFFSET clause in a
-- RETURN operation.
GRAPH
FinGraph
MATCH
(
p
:
Person
)
RETURN
p
.
name
,
p
.
id
LIMIT
1
OFFSET
1
In the following example, the ORDER BY
clause in the RETURN
statement sorts
the results by hops
and then destination_account_id
:
GRAPH
FinGraph
MATCH
(
src
:
Account
{
id
:
7
}
)
-[
e
:
Transfers
]->{
1
,
3
}
(
dst
:
Account
)
RETURN
DISTINCT
ARRAY_LENGTH
(
e
)
AS
hops
,
dst
.
id
AS
destination_account_id
ORDER
BY
hops
,
destination_account_id
/*-------------------------------+
| hops | destination_account_id |
+-------------------------------+
| 1 | 16 |
| 2 | 20 |
| 3 | 7 |
| 3 | 16 |
+-------------------------------*/
SKIP
statement
SKIP count
Description
Synonym for the OFFSET
statement
.
Examples
SKIP
is a synonym for OFFSET
. Therefore, these queries are equivalent:
GRAPH
FinGraph
MATCH
(
p
:
Person
)
SKIP
2
RETURN
p
.
name
,
p
.
id
/*-----------+
| name | id |
+-----------+
| Lee | 3 |
+-----------*/
GRAPH
FinGraph
MATCH
(
p
:
Person
)
OFFSET
2
RETURN
p
.
name
,
p
.
id
/*-----------+
| name | id |
+-----------+
| Lee | 3 |
+-----------*/
WITH
statement
WITH [ { ALL | DISTINCT } ] return_item [, ... ] [ group_by_clause ] return_item : { expression [ AS alias ] | * }
Description
Passes on the specified columns, optionally filtering, renaming, and transforming those results.
Definitions
-
*: Returns all columns in the current working table. -
ALL: Returns all rows. This is equivalent to not using any prefix. -
DISTINCT: Returns distinct rows. Deduplication takes place after aggregations are performed. -
return_item: A column to include in the results. -
expression: An expression that represents a column to produce. Aggregation is supported. -
alias: An alias forexpression. -
group_by_clause: Groups the current rows of the working table, using theGROUP BYclause .
Details
If any expression performs aggregation, and no GROUP BY
clause is
specified, all groupable items from the return list are implicitly used as
grouping keys.
Window functions aren't supported in expression
.
Ordinals aren't supported in the GROUP BY
clause.
Examples
The following query returns all distinct destination account IDs:
GRAPH
FinGraph
MATCH
(
src
:
Account
)
-[
transfer
:
Transfers
]-
> (
dst
:
Account
)
WITH
DISTINCT
dst
RETURN
dst
.
id
AS
destination_id
/*----------------+
| destination_id |
+----------------+
| 7 |
| 16 |
| 20 |
+----------------*/
The following query uses *
to carry over the existing columns of
the working table in addition to defining a new one for the destination
account id.
GRAPH
FinGraph
MATCH
(
src
:
Account
)
-[
transfer
:
Transfers
]-
> (
dst
:
Account
)
WITH
*
,
dst
.
id
RETURN
dst
.
id
AS
destination_id
/*----------------+
| destination_id |
+----------------+
| 7 |
| 16 |
| 16 |
| 16 |
| 20 |
+----------------*/
In the following example, aggregation is performed implicitly because the WITH
statement has an aggregate expression but doesn't specify a GROUP BY
clause. All groupable items from the return item list are used as grouping keys
.
In this case, the grouping keys inferred are src.id
and dst.id
.
Therefore, this query returns the number of transfers for each
distinct combination of src.id
and dst.id
.
GRAPH
FinGraph
MATCH
(
src
:
Account
)
-[
transfer
:
Transfers
]-
> (
dst
:
Account
)
WITH
COUNT
(
*
)
AS
transfer_total
,
src
.
id
AS
source_id
,
dst
.
id
AS
destination_id
RETURN
transfer_total
,
destination_id
,
source_id
/*---------------------------------------------+
| transfer_total | destination_id | source_id |
+---------------------------------------------+
| 2 | 16 | 7 |
| 1 | 20 | 16 |
| 1 | 7 | 20 |
| 1 | 16 | 20 |
+---------------------------------------------*/
In the following example, an error is produced because the WITH
statement only
contains dst
. src
isn't visible after the WITH
statement in the RETURN
statement.
-- Error: src doesn't exist
GRAPH
FinGraph
MATCH
(
src
:
Account
)
-[
transfer
:
Transfers
]-
> (
dst
:
Account
)
WITH
dst
RETURN
src
.
id
AS
source_id
Set operation
linear_query_statement set_operator linear_query_statement [ set_operator linear_graph_query ][...] set_operator : { UNION ALL | UNION DISTINCT | INTERSECT ALL | INTERSECT DISTINCT | EXCEPT ALL | EXCEPT DISTINCT }
Description
Combines a sequence of linear query statements with a set operation. Only one type of set operation is allowed per set operation.
Definitions
-
linear_query_statement: A linear query statement to include in the set operation.
Details
Each linear query statement in the same set operation shares the same working table.
Most of the rules for GQL set operators are the same as those for SQL set operators , but there are some differences:
- A GQL set operator doesn't support hints, or the
CORRESPONDINGkeyword. Since each set operation input (a linear query statement) only produces columns with names, the default behavior of GQL set operations requires all inputs to have the same set of column names and all paired columns to share the same supertype . - GQL doesn't allow chaining different kinds of set operations in the same set operation.
- GQL doesn't allow using parentheses to separate different set operations.
- The results produced by the linear query statements are combined in a left associative order.
Examples
A set operation between two linear query statements with the same set of output column names and types but with different column orders is supported. For example:
GRAPH
FinGraph
MATCH
(
p
:
Person
)
RETURN
p
.
name
,
1
AS
group_id
UNION
ALL
MATCH
(
p
:
Person
)
RETURN
2
AS
group_id
,
p
.
name
/*------+----------+
| name | group_id |
+------+----------+
| Alex | 1 |
| Dana | 1 |
| Lee | 1 |
| Alex | 2 |
| Dana | 2 |
| Lee | 2 |
+------+----------*/
In a set operation, chaining the same kind of set operation is supported, but chaining different kinds of set operations isn't. For example:
GRAPH
FinGraph
MATCH
(
p
:
Person
)
RETURN
p
.
name
,
1
AS
group_id
UNION
ALL
MATCH
(
p
:
Person
)
RETURN
2
AS
group_id
,
p
.
name
UNION
ALL
MATCH
(
p
:
Person
)
RETURN
3
AS
group_id
,
p
.
name
/*------+----------+
| name | group_id |
+------+----------+
| Alex | 1 |
| Dana | 1 |
| Lee | 1 |
| Alex | 2 |
| Dana | 2 |
| Lee | 2 |
| Alex | 3 |
| Dana | 3 |
| Lee | 3 |
+------+----------*/
-- ERROR: GQL doesn't allow chaining EXCEPT DISTINCT with UNION ALL
GRAPH
FinGraph
MATCH
(
p
:
Person
)
RETURN
p
.
name
,
1
AS
group_id
UNION
ALL
MATCH
(
p
:
Person
)
RETURN
2
AS
group_id
,
p
.
name
EXCEPT
DISTINCT
MATCH
(
p
:
Person
)
RETURN
3
AS
group_id
,
p
.
name
Graph hints
@"{" hint_key = hint_value "}"
Graph Query Language (GQL) supports hints, which make the query optimizer use a specific operator in the execution plan. If performance is an issue for you, a GQL hint might be able to help by suggesting a different query execution plan shape for your engine. Only one hint key and value are allowed per hint.
Details
You can add the following types of hints to a GQL query:
A join hint that applies to graph traversal. A graph traversal is semantically equivalent to a join operation between any two tables.
You can use traversal hints in the following ways:
- A traversal hint between two path patterns .
- A traversal hint from an edge to a node in a path pattern .
- A traversal hint from a node to an edge in a path pattern .
- A traversal hint between a graph subpath pattern and an edge pattern .
Traversal hints aren't allowed between two subpath patterns or between a subpath pattern and a node pattern.
A table hint that applies to a graph element. You can use an element hint at the beginning of a pattern filler .
Examples
Example of a traversal hint from one MATCH
statement to
the next MATCH
statement:
GRAPH
FinGraph
MATCH
(
p
:
Person
{
id
:
1
}
)
-[:
Owns
]-
> (
a
:
Account
)
MATCH
@{
JOIN_METHOD
=
APPLY_JOIN
}
(
a
:
Account
)
-[
e
:
Transfers
]-
> (
oa
:
Account
)
RETURN
oa
.
id
Example of a traversal hint between two path patterns :
GRAPH
FinGraph
MATCH
(
p
:
Person
{
id
:
1
}
)
-[:
Owns
]-
> (
a
:
Account
),
-- path pattern 1
@{
JOIN_METHOD
=
HASH_JOIN
,
HASH_JOIN_BUILD_SIDE
=
BUILD_RIGHT
}
-- traversal hint
(
a
:
Account
)
-[
e
:
Transfers
]-
> (
c
:
Account
)
-- path pattern 2
RETURN
c
.
id
Example of a traversal hint from an edge to a node in a path pattern :
GRAPH
FinGraph
MATCH
(
p
:
Person
{
id
:
1
}
)
-[
e
:
Owns
]->@{
JOIN_METHOD
=
APPLY_JOIN
}
(
a
:
Account
)
RETURN
a
.
id
Example of a traversal hint from a node to an edge in a path pattern :
GRAPH
FinGraph
MATCH
(
p
:
Person
{
id
:
1
}
)
@{
JOIN_METHOD
=
APPLY_JOIN
}-[
e
:
Owns
]-
> (
a
:
Account
)
RETURN
a
.
id
Example of a traversal hint between a graph subpath pattern and an edge pattern:
GRAPH
FinGraph
MATCH
(
p
:
Person
{
id
:
1
}
)
-[
e
:
Owns
]-
>
@{
JOIN_METHOD
=
APPLY_JOIN
}
((
a
:
Account
)
-[
s
:
Transfers
]-
> (
oa
:
Account
))
RETURN
oa
.
id
Example of an element hint at the beginning of a pattern filler :
GRAPH
FinGraph
MATCH
(
a
:
Account
{
id
:
7
}
)
-[@{
INDEX_STRATEGY
=
FORCE_INDEX_UNION
}
:
Transfers
]-
(
oa
:
Account
)
RETURN
oa
.
id
