Spanner Graph Notebook: Explore Your Data Visually

The Spanner Graph Notebook tool lets you visually query Spanner Graph in a notebook environment (e.g. Google Colab and Jupyter Notebook). Using GQL query syntax, you can extract graph insights and relationship patterns, including node and edge properties and neighbor analysis. The tool also provides graph schema metadata visualization, tabular results inspection and diverse layout topologies.

Table of Contents

• Prerequisites
• %%spanner_graph IPython Magics
• Google Colab Usage (Installation-Free)
• Installation and Usage in Jupyter Notebook
• Query Requirements

Prerequisites

To use this tool, you'll need to create a GCP project, a Spanner instance and a Spanner database with graph. You can follow our Getting started with Spanner Graph codelab which walks through the setup.

%%spanner_graph IPython Magics

Spanner Graph Notebook is implemented as an IPython Magics. Use the %%spanner_graph magic command in a code cell with GCP resource options and a query string:

• a Google Cloud Project ID for --project option.
• a Spanner Instance ID for --instance option.
• a Spanner database name for --database option.
• a GQL query string that returns graph elements as results.

You GQL query should return graph elements to have them visually displayed. See Query Requirements section for examples. For instance, the code example below visually inspects 50 paths.

%%spanner_graph --project my-gcp-project --instance my-spanner-instance --database my-database

GRAPH MyGraph
MATCH p = (a)-[e]->(b)
RETURN TO_JSON(p) AS path_json
LIMIT 50

(Note: `my-gcp-project`, `my-spanner-instance`, `my-database`, and `MyGraph` are placeholders.  Replace them with your actual values.)

You can also visualize a local dataset with --mock flag.

%%spanner_graph --mock

Colab Usage (Installation-Free)

You can directly invoke %%spanner_graph magic command in Google Colab, a hosted Jupyter Notebook service that requires no setup to use. You'll be prompted to authenticate via pydata-google-auth if Google Cloud Platform credentials aren't already available.

Installation and Usage in Jupyter Notebook

You can install and use this package in Jupyter Notebook. We provided a sample.ipynb in the root directory of this repo for you to follow.

Install dependencies

Follow the commands below to create a managed Python environment (example based on virtualenv) and install spanner-graph-notebook.

# Create the virtualenv `viz`.
python3 -m venv viz

# Activate the virtualenv.
source viz/bin/activate

# Install dependencies.
pip install spanner-graph-notebook

Using

Launch notebook and follow steps in sample.ipynb

When in the root directory of the package, run jupyter notebook to launch Jupyter Notebook.

jupyter notebook

As Jupyter local server runs, it will open up a web portal. You can create or copy the sample.ipynb to step through an example.

You must run %load_ext spanner_graphs to load this package. sample.ipynb contains this cell already.

Following the code steps in the sample notebook, you can visually inspect a mock dataset or your Spanner Graph. You'll be prompted to authenticate via pydata-google-auth if Google Cloud Platform credentials aren't already available.

Query Requirements

Use TO_JSON function to return graph elements

To visualize graph paths, nodes, and edges, graph queries must must use SAFE_TO_JSON or TO_JSON function in the RETURN statement. We recommend visualizing paths for data completeness and ease of use.

👍 Good example returning a path as JSON.


GRAPH FinGraph
MATCH query_path = (person:Person {id: 5})-[owns:Owns]->(accnt:Account)
RETURN SAFE_TO_JSON(query_path) AS path_json

👍 Good example returning a path as JSON in a multiple-hop query.

GRAPH FinGraph
MATCH query_path = (src:Account {id: 9})-[edge]->{1,3}(dst:Account)
RETURN SAFE_TO_JSON(query_path) as path_json

👍 Good example returning multiple paths as JSON.

GRAPH FinGraph
MATCH path_1 = (person:Person {id: 5})-[:Owns]->(accnt:Account),
      path_2 = (src:Account {id: 9})-[:Transfers]->(dst:Account)
RETURN SAFE_TO_JSON(path_1) as path_1,
       SAFE_TO_JSON(path_2) as path_2

👎 Anti-example returning node properties rather than JSON format graph elements.
   Scalar results other than JSON format graph elements cannot be visualized.

GRAPH FinGraph
MATCH (person:Person {id: 5})-[owns:Owns]->(accnt:Account)
RETURN person.id AS person,
       owns.amount AS owns,
       accnt.id AS accnt;

👎 Anti-example returning each node and edges in JSON format verbosely. This will
   work but not as easy as returning a path directly.

GRAPH FinGraph
MATCH (person:Person {id: 5})-[owns:Owns]->(accnt:Account)
RETURN SAFE_TO_JSON(person) AS person_json,
       SAFE_TO_JSON(owns) AS owns_json,
       SAFE_TO_JSON(accnt) AS accnt_json,

Testing changes

After adding new changes, please run unit and integration tests with the command below:

cd spanner_graphs && python -m unittest discover -s tests -p "*_test.py"

For frontend testing:

cd frontend
npm install
npm run test:unit
npm run test:visual