Console
    Start free

    Best practices for tuning Spanner Graph queries

    This document describes best practices for tuning Spanner Graph query performance, which include the following optimizations:

    • Avoid a full scan of the input table for nodes and edges.
    • Reduce the amount of data the query needs to read from storage.
    • Reduce the size of intermediate data.

    Start from lower cardinality nodes

    Write the path traversal so that it starts with the lower cardinality nodes. This approach keeps the intermediate result set small, and speeds up query execution.

    For example, the following queries have the same semantics:

    • Forward edge traversal:

        GRAPH 
  
 FinGraph 
 MATCH 
  
 ( 
 p 
 : 
 Person 
  
 { 
 name 
 : 
 "Alex" 
 } 
 ) 
 - 
 [: 
 Owns 
 ] 
 - 
> ( 
 a 
 : 
 Account 
  
 { 
 is_blocked 
 : 
  
 true 
 } 
 ) 
 RETURN 
  
 p 
 . 
 id 
  
 AS 
  
 person_id 
 , 
  
 a 
 . 
 id 
  
 AS 
  
 account_id 
 ;

    • Reverse edge traversal:

        GRAPH 
  
 FinGraph 
 MATCH 
  
 ( 
 a 
 : 
 Account 
  
 { 
 is_blocked 
 : 
 true 
 } 
 ) 
< - 
 [: 
 Owns 
 ] 
 - 
 ( 
 p 
 : 
 Person 
  
 { 
 name 
 : 
  
 "Alex" 
 } 
 ) 
 RETURN 
  
 p 
 . 
 id 
  
 AS 
  
 person_id 
 , 
  
 a 
 . 
 id 
  
 AS 
  
 account_id 
 ;

    Assuming that there are fewer people with the name Alex than there are blocked accounts, we recommend that you write this query in the forward edge traversal.

    Starting from lower cardinality nodes is especially important for variable-length path traversal. The following example shows the recommended way to find accounts that are within three transfers of a given account.

      GRAPH 
  
 FinGraph 
 MATCH 
  
 (: 
 Account 
  
 { 
 id 
 : 
  
 7 
 } 
 ) 
 - 
 [: 
 Transfers 
 ] 
 - 
> { 
 1 
 , 
 3 
 } 
 ( 
 a 
 : 
 Account 
 ) 
 RETURN 
  
 a 
 . 
 id 
 ;

    Specify all labels by default

    Spanner Graph infers the qualifying nodes and edge labels if labels are omitted. We recommend that you specify labels for all nodes and edges where possible, because this inference might not always be possible and it might cause more labels than necessary to be scanned.

    Single MATCH statement

    The following example finds accounts linked by at most 3 transfers from the given account:

      GRAPH 
  
 FinGraph 
 MATCH 
  
 ( 
 src 
 : 
 Account 
  
 { 
 id 
 : 
  
 7 
 } 
 ) 
 - 
 [: 
 Transfers 
 ] 
 - 
> { 
 1 
 , 
 3 
 } 
 ( 
 dst 
 : 
 Account 
 ) 
 RETURN 
  
 dst 
 . 
 id 
 ;

    Across MATCH statements

    Specify labels on nodes and edges when they refer to the same element but are across MATCH statements.

    The following example shows this recommended approach:

      GRAPH 
  
 FinGraph 
 MATCH 
  
 ( 
 acct 
 : 
 Account 
  
 { 
 id 
 : 
  
 7 
 } 
 ) 
 - 
 [: 
 Transfers 
 ] 
 - 
> { 
 1 
 , 
 3 
 } 
 ( 
 other_acct 
 : 
 Account 
 ) 
 RETURN 
  
 acct 
 , 
  
 COUNT 
 ( 
 DISTINCT 
  
 other_acct 
 ) 
  
 AS 
  
 related_accts 
 GROUP 
  
 BY 
  
 acct 
 NEXT 
 MATCH 
  
 ( 
 acct 
 : 
 Account 
 ) 
< - 
 [: 
 Owns 
 ] 
 - 
 ( 
 p 
 : 
 Person 
 ) 
 RETURN 
  
 p 
 . 
 id 
  
 AS 
  
 person 
 , 
  
 acct 
 . 
 id 
  
 AS 
  
 acct 
 , 
  
 related_accts 
 ;

    Use IS_FIRST to optimize queries

    You can use the IS_FIRST function to improve query performance by sampling edges and limiting traversals in graphs. This function helps handle high-cardinality nodes and optimize multi-hop queries.

    If your specified sample size is too small, the query might return no data. Because of this, you might need to try different sample sizes to find the optimal balance of returned data and improved query performance.

    These IS_FIRST examples use FinGraph , a financial graph with Account nodes and Transfers edges for money transfers. To create the FinGraph and use it to run the sample queries, see Set up and query Spanner Graph .

    Limit traversed edges to improve query performance

    When you query graphs, some nodes can have a significantly larger number of incoming or outgoing edges compared to other nodes. These high-cardinality nodes are sometimes called super nodes or hub nodes. Super nodes can cause performance issues because traversals through them might involve processing huge amounts of data, which leads to data skew and long execution times.

    To optimize a query of a graph with super nodes, use the IS_FIRST function within a FILTER clause to limit the number of edges the query traverses from a node. Because accounts in FinGraph might have significantly higher numbers of transactions than others, you might use IS_FIRST to prevent an inefficient query. This technique is particularly useful when you don't need a complete enumeration of all connections from a super node.

    The following query finds accounts ( a2 ) that either directly or indirectly receive transfers from blocked accounts ( a1 ). The query uses IS_FIRST to prevent slow performance when an account has many transfers by limiting the number of Transfers edges to consider for each Account .

      GRAPH 
  
 FinGraph 
 MATCH 
 ( 
 a1 
 : 
 Account 
  
 { 
 is_blocked 
 : 
  
 true 
 } 
 ) 
 - 
 [ 
 e 
 : 
 Transfers 
  
 WHERE 
  
 e 
  
 IN 
  
 { 
  
 MATCH 
  
 - 
 [ 
 selected_e 
 : 
 Transfers 
 ] 
 - 
>  
 FILTER 
  
 IS_FIRST 
 ( 
 @ 
 max_transfers_per_account 
 ) 
  
 OVER 
  
 ( 
  
 PARTITION 
  
 BY 
  
 SOURCE_NODE_ID 
 ( 
 selected_e 
 ) 
  
 ORDER 
  
 BY 
  
 selected_e 
 . 
 create_time 
  
 DESC 
 ) 
  
 RETURN 
  
 selected_e 
  
 } 
 ] 
 - 
> { 
 1 
 , 
 5 
 } 
 ( 
 a2 
 : 
 Account 
 ) 
 RETURN 
  
 a1 
 . 
 id 
  
 AS 
  
 src_id 
 , 
  
 a2 
 . 
 id 
  
 AS 
  
 dst_id 
 ;

    This example uses the following:

    • @max_transfers_per_account : A query parameter that specifies the maximum number of Transfers edges to consider for each account ( a1 ).

    • PARTITION BY SOURCE_NODE_ID(selected_e) : Ensures that the IS_FIRST limit applies independently for each account ( a1 ).

    • ORDER BY selected_e.create_time DESC : Specifies that the most recent transfers are returned.

    Sample intermediate nodes to optimize multi-hop queries

    You can also improve query efficiency by using IS_FIRST to sample intermediate nodes in multi-hop queries. This technique improves efficiency by limiting the number of paths the query considers for each intermediate node. To do this, break a multi-hop query into multiple MATCH statements separated by NEXT , and apply IS_FIRST at the midpoint where you need to sample:

      GRAPH 
  
 FinGraph 
 MATCH 
  
 ( 
 a1 
 : 
 Account 
  
 { 
 is_blocked 
 : 
  
 true 
 } 
 ) 
 - 
 [ 
 e1 
 : 
 Transfers 
 ] 
 - 
> ( 
 a2 
 : 
 Account 
 ) 
 FILTER 
  
 IS_FIRST 
 ( 
 1 
 ) 
  
 OVER 
  
 ( 
 PARTITION 
  
 BY 
  
 a2 
 ) 
 RETURN 
  
 a1 
 , 
  
 a2 
 NEXT 
 MATCH 
  
 ( 
 a2 
 ) 
 - 
 [ 
 e2 
 : 
 Transfers 
 ] 
 - 
> ( 
 a3 
 : 
 Account 
 ) 
 RETURN 
  
 a1 
 . 
 id 
  
 AS 
  
 src_id 
 , 
  
 a2 
 . 
 id 
  
 AS 
  
 mid_id 
 , 
  
 a3 
 . 
 id 
  
 AS 
  
 dst_id 
 ;

    To understand how IS_FIRST optimizes this query:

    • The clause FILTER IS_FIRST(1) OVER (PARTITION BY a2) is applied in the first MATCH statement.

    • For each intermediate account node ( a2 ), IS_FIRST considers only the first incoming Transfers edge ( e1 ), reducing the number of paths to explore in the second MATCH statement.

    • The overall two-hop query's efficiency is improved because the second MATCH doesn't process unnecessary data, especially when a2 has many incoming transfers.

    What's next
    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: