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 by using the SAFE_TO_JSON or TO_JSON function. We recommend that you return graph paths instead of returning nodes and edges individually. Returning paths offers the following benefits:

  • 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, 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, which you can visualize:

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 query results area displays the visualization. The detail panel shows a summary of node and edge labels with counts for each. Click a node or an edge to navigate the graph and view properties, neighbors, and connections, as the following screenshot shows. Alternatively, you can 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 menu on the visualization panel provides the following layout options:

  • Force layout (default): Presents nodes as points that repel each other, while connected nodes pull together, simulating physical forces to create a visually intuitive layout.

  • Hierarchical: Positions nodes to create a visual hierarchy based on connectivity.

  • Sequential: Positions nodes to create a visual sequence based on connectivity.

  • Show labels: Displays all node and edge labels on the graph at all zoom levels.

Troubleshoot Spanner Graph 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.

Spanner Graph 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 Spanner Graph visualization includes a node or edge with an unexpected label

Issue: A node or an edge in a Spanner 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 displayed in a Spanner Graph visualization

Issue: A visualization includes all of the returned nodes and edges, but some of the graph elements aren't displayed.

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

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

What's next