Work with Spanner Graph visualizations

This page describes how to work with Spanner Graph visualizations. A Spanner Graph visualization can show the graph elements returned by a query or the elements of a graph schema. Visualizations help you understand how data points (nodes) are connected (edges). While a table of hundreds of data points can be difficult to interpret, its graph visualization can reveal patterns, dependencies, and anomalies.

Visualize Spanner Graph query results

To visualize Spanner Graph query results in Spanner Studio, the query must return graph elements in JSON format using the SAFE_TO_JSON or TO_JSON function. Also, we recommend returning graph paths instead of returning nodes and edges individually. Benefits of returning paths include the following:

  • Paths contain complete data of nodes and edges. Some intermediate nodes and edges in a visualization of a complex query might not be available if you return individual nodes and edges.

  • If you return paths, then your RETURN statement can be less complex than if you return nodes and edges individually.

The following sample query returns the paths of account transfers that can be visualized:

GRAPH FinGraph
MATCH result_paths = (account:Account {is_blocked: True})-[:Transfers]->(dest_account:Account)
RETURN SAFE_TO_JSON(result_paths) AS result_paths

After you run a query, the visualization is displayed in the query results area. The detail panel shows a summary of node and edge labels with counts for each. Click a node or edge to navigate the graph and view properties, neighbors, and connections, as shown in the following screenshot. Alternatively, you can also view the query results as a table or toggle to a visualization of the underlying graph schema.

Query result toggle button.

For more information, see Return graph elements as JSON.

Choose a Spanner Graph visualization layout

The following layout options are available from the menu on the visualization panel:

  • Force layout (default): presents nodes as points that repel each other while connected nodes are pulled together, simulating physical forces like magnetism, to create a visually intuitive layout
  • Hierarchical: positions nodes to generate a visual hierarchy based on connectivity
  • Sequential: positions nodes to generate a visual sequence based on connectivity
  • Show labels: displays all node and edge labels on the graph independent of zoom level

Troubleshoot visualizations

The following can help you troubleshoot and understand Spanner Graph visualization issues and behavior.

A visualization doesn't appear for a Spanner Graph query

Issue: You run a Spanner Graph query and it appears in table format only.

Possible cause: The query doesn't return graph elements in JSON format. For example:

  • The following query can't be visualized because it returns nodes and edge identifiers:
GRAPH FinGraph
MATCH (person:Person {name: "Dana"})-[owns:Owns]->(account:Account)
RETURN person.id as person_id, account.id as account_id
  • The following query can't be visualized because it returns property values:
GRAPH FinGraph
MATCH (person:Person {name: "Dana"})-[owns:Owns]->(account:Account)
RETURN owns.create_time, account.nick_name

Recommended solution:

Return graph elements in JSON format using SAFE_TO_JSON or TO_JSON. For more information, see Visualize Spanner Graph query results.

Query results are partially visualized

Issue: A query result visualization shows only a part of the query results.

Possible cause: The query returns more than 10 MB of data. A query visualization can display up to 10 MB of data.

Recommended solution: Simplify the query so it returns less than 10 MB of data.

A node or edge displays with an unexpected label

Issue: A node or an edge in a graph visualization shows an unexpected label.

Possible cause: The node or edge has multiple labels. A Spanner Graph visualization can show one label for each node and edge. If a node or edge has more than one label, then the first label shows in the visualization.

Recommended solution: None. You can't change which label displays.

Some graph elements aren't available in a visualization

Issue: A visualization includes all of the returned nodes and edges, but some of the graph elements are missing.

Possible cause: The query used to create the visualization returns individual nodes and edges instead of a graph path.

Recommended solution: Update the query to return a graph path.

What's next