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 expansion analysis. The tool also provides graph schema metadata visualization, tabular results inspection and diverse layout topologies.

The notebook visualization provides a user experience similar to Spanner Studio visualization, enabling you to visually inspect Spanner Graph data outside of Google Cloud console.

Table of Contents

• Prerequisites
• Google Colab Usage (Installation-Free)
• Installation and Usage in Jupyter Notebook or JupyterLab
• Query Requirements

Prerequisites

You need a Spanner database with graph schema and data. The Getting started with Spanner Graph codelab or the Set up and query Spanner Graph page walks through the setup process.

Google Colab Usage (Installation-Free)

You can directly use %%spanner_graph magic command to visualize graph query results in Google Colab. The magic command must provide 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.

The query must return graph elements in JSON format using the SAFE_TO_JSON or TO_JSON function. The following example code cell in Colab visualizes account transfers:

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

GRAPH FinGraph
MATCH result_paths = (src:Account {is_blocked: true})-[:Transfers]->(dest:Account)
RETURN SAFE_TO_JSON(result_paths) AS result_paths

You'll be prompted to authenticate via pydata-google-auth if Google Cloud Platform credentials aren't readily available.

Installation and Usage in Jupyter Notebook or JupyterLab

Install the package

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

Launch Jupyter Notebook

When in the root directory of the package, run jupyter notebook or jupyter lab to launch your Jupyter notebook environment.

jupyter notebook

As Jupyter local server runs, it will open up a web portal. You can step through an example notebook sample.ipynb.

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 readily available.

Query Requirements

Use TO_JSON function to return graph elements

Graph queries must use SAFE_TO_JSON or TO_JSON function to return graph elements in JSON format . We recommend visualizing graph 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 graph elements in JSON.
   Scalar intergers or strings 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 individually.
   This will work but is more verbose than returning paths.

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

First, install the test dependencies:

pip install -r requirements-test.txt

Then 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