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 do not 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 theNEXT
statement.simple_linear_query_statement
: A list ofprimitive_query_statement
s that ends with aRETURN
statement.composite_linear_query_statement
: A list ofsimple_linear_query_statement
s composited with the set operators.linear_query_statement
: A statement that is either asimple_linear_query_statement
or acomposite_linear_query_statement
.multi_linear_query_statement
: A list oflinear_query_statement
s chained together with theNEXT
statement.graph_query
: A GQL query that starts with aGRAPH
clause, 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_statement
in 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 do not satisfy a specified condition.
Definitions
bool_expression
: A boolean expression. Only rows whosebool_expression
evaluates toTRUE
are included. Rows whosebool_expression
evaluates toNULL
orFALSE
are 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.birthday < '1990-01-10'
RETURN p.name
/*------+
| name |
+------+
| Dana |
| Lee |
+------*/
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.birthday < '1990-01-10'
RETURN p.name
/*------+
| name |
+------+
| Dana |
| Lee |
+------*/
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, dest, SUM(e.amount) AS total_amount
GROUP BY source, dest
NEXT
FILTER WHERE total_amount < 400
RETURN source.id AS source_id, dest.id AS destination_id, total_amount
/*-------------------------------------------+
| source_id | destination_id | total_amount |
+-------------------------------------------+
| 16 | 20 | 300 |
| 20 | 16 | 200 |
+-------------------------------------------*/
In the following example, an error is produced because FILTER
references
m
, which is not in the working table:
-- Error: m does not exist
GRAPH FinGraph
MATCH (p:Person)-[o:Owns]->(a:Account)
FILTER WHERE m.birthday < '1990-01-10'
RETURN p.name
In the following example, an error is produced because even though p
is in the
working table, p
does not have a property called date_of_birth
:
-- ERROR: date_of_birth is not 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 does not 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.name, element as alert_type, offset
ORDER BY p.name, element, offset
/*----------------------------+
| name | alert_type | offset |
+----------------------------+
| Alex | all | 0 |
| Alex | some | 1 |
| Dana | all | 0 |
| Dana | some | 1 |
| Lee | all | 0 |
| Lee | 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 p.name != "Alex"
FOR element in GENERATE_ARRAY(1,LENGTH(p.name))
RETURN p.name, element
ORDER BY p.name, element
/*----------------+
| name | element |
+----------------+
| Dana | 1 |
| Dana | 2 |
| Dana | 3 |
| Dana | 4 |
| Lee | 1 |
| Lee | 2 |
| Lee | 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
does not 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
is not 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' does not 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-negativeINT64
value that represents the number of results to produce. For more information, see theLIMIT
andOFFSET
clauses.
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.nick_name
LIMIT 3
RETURN source.nick_name
/*----------------+
| nick_name |
+----------------+
| Rainy day fund |
| Rainy day fund |
| Vacation fund |
+----------------*/
The following query finds the account and its owner with the largest outgoing transfer to a blocked account:
GRAPH FinGraph
MATCH (src_account:Account)-[transfer:Transfers]->(dst_account:Account)
WHERE dst_account.is_blocked
ORDER BY transfer.amount DESC
LIMIT 1
MATCH (src_account:Account)<-[owns:Owns]-(owner:Person)
RETURN src_account.id AS account_id, owner.name AS owner_name
/*-------------------------+
| account_id | owner_name |
+-------------------------+
| 7 | Alex |
+-------------------------*/
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, seeMATCH
graph 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 byNULL
values. For more information, seeOPTIONAL MATCH
graph 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 are not 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)
WHERE account.is_blocked
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)
((:Account)-[:Transfers]->(interm:Account) WHERE interm.is_blocked){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(SELECT e.to_id FROM UNNEST(e) AS e)
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 | 16 |
| 7 | 20 | 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
UNION ALL
RETURN "Bob" AS owner_name, 100 AS account_id
/*-------------------------+
| account_id | owner_name |
+-------------------------+
| 7 | Alex |
| 20 | Dana |
| 100 | Bob |
| 100 | Bob |
| 100 | Bob |
+-------------------------*/
OFFSET
statement
OFFSET count
Description
Skips a specified number of rows in the query results.
Definitions
count
: A non-negativeINT64
value that represents the number of rows to skip. For more information, see theLIMIT
andOFFSET
clauses.
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 are not 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 BY
clause.COLLATE collation_specification
: The collation specification forexpression
. For more information, see theORDER BY
clause.ASC | ASCENDING | DESC | DESCENDING
: The sort order, which can be either ascending or descending. The following options are synonymous:ASC
andASCENDING
DESC
andDESCENDING
For more information about sort order, see the
ORDER BY
clause.NULLS FIRST | NULLS LAST
: Determines howNULL
values are sorted forexpression
. For more information, see theORDER BY
clause.
Details
Ordinals are not supported in the ORDER BY
statement.
The ORDER BY
statement is ignored unless it is 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 are not 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 BY
clause.order_by_clause
: Orders the current rows in a linear query statement, using theORDER BY
clause.limit_clause
: Limits the number of current rows in a linear query statement, using theLIMIT
clause.offset_clause
: Skips a specified number of rows in a linear query statement, using theOFFSET
clause.
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 are not 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 BY
clause.
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 are not supported in expression
.
Ordinals are not 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 does not 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
is not visible after the WITH
statement in the RETURN
statement.
-- Error: src does not 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 does not support hints, or the
CORRESPONDING
keyword. 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 does not allow chaining different kinds of set operations in the same set operation.
- GQL does not 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 is not. 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 does not 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:
Hint type | Description |
---|---|
Join (graph traversal) |
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:
Traversal hints are not allowed between two subpath patterns or between a subpath pattern and a node pattern. |
Join (match statement) | |
Table (graph element) |
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 join hint with the 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