Visually query Spanner Graph data in notebooks.
Project description
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
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file spanner_graph_notebook-1.1.1.tar.gz
.
File metadata
- Download URL: spanner_graph_notebook-1.1.1.tar.gz
- Upload date:
- Size: 5.5 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.12.8
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1646d4f8c1e9bd7b3d240d151fc6dd7f4a2a4329ad646bbd2d4ed24d6a4d1170 |
|
MD5 | 962497908a8d8ef03137b1190b89844b |
|
BLAKE2b-256 | 68b813ec76240c06cc66320ff1b5cdaf5f57cc35b86ba62a320fb9f58ce168ee |
Provenance
The following attestation bundles were made for spanner_graph_notebook-1.1.1.tar.gz
:
Publisher:
publish-to-pypi.yml
on cloudspannerecosystem/spanner-graph-notebook
-
Statement:
- Statement type:
https://in-toto.io/Statement/v1
- Predicate type:
https://docs.pypi.org/attestations/publish/v1
- Subject name:
spanner_graph_notebook-1.1.1.tar.gz
- Subject digest:
1646d4f8c1e9bd7b3d240d151fc6dd7f4a2a4329ad646bbd2d4ed24d6a4d1170
- Sigstore transparency entry: 170771535
- Sigstore integration time:
- Permalink:
cloudspannerecosystem/spanner-graph-notebook@942abb3a95451021696223c1daf8054d37267ac9
- Branch / Tag:
refs/tags/v1.1.1
- Owner: https://github.com/cloudspannerecosystem
- Access:
public
- Token Issuer:
https://token.actions.githubusercontent.com
- Runner Environment:
github-hosted
- Publication workflow:
publish-to-pypi.yml@942abb3a95451021696223c1daf8054d37267ac9
- Trigger Event:
release
- Statement type:
File details
Details for the file spanner_graph_notebook-1.1.1-py3-none-any.whl
.
File metadata
- Download URL: spanner_graph_notebook-1.1.1-py3-none-any.whl
- Upload date:
- Size: 5.5 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.12.8
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | b329ea277b681f89f4b1fcab239b3e5f917a4b4215abda213fcb7ac8f695624e |
|
MD5 | 40a242e4c4a628021a80518826e95d50 |
|
BLAKE2b-256 | 18a8b4e58c4bcdb89547062a71281fabb6d9bf41052c30ce9333ba80f89741e4 |
Provenance
The following attestation bundles were made for spanner_graph_notebook-1.1.1-py3-none-any.whl
:
Publisher:
publish-to-pypi.yml
on cloudspannerecosystem/spanner-graph-notebook
-
Statement:
- Statement type:
https://in-toto.io/Statement/v1
- Predicate type:
https://docs.pypi.org/attestations/publish/v1
- Subject name:
spanner_graph_notebook-1.1.1-py3-none-any.whl
- Subject digest:
b329ea277b681f89f4b1fcab239b3e5f917a4b4215abda213fcb7ac8f695624e
- Sigstore transparency entry: 170771536
- Sigstore integration time:
- Permalink:
cloudspannerecosystem/spanner-graph-notebook@942abb3a95451021696223c1daf8054d37267ac9
- Branch / Tag:
refs/tags/v1.1.1
- Owner: https://github.com/cloudspannerecosystem
- Access:
public
- Token Issuer:
https://token.actions.githubusercontent.com
- Runner Environment:
github-hosted
- Publication workflow:
publish-to-pypi.yml@942abb3a95451021696223c1daf8054d37267ac9
- Trigger Event:
release
- Statement type: