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:ASCandASCENDINGDESCandDESCENDING
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:
| 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 aren't 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 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