{"author":null,"author_email":null,"bugtrack_url":null,"classifiers":[],"description":"# Spanner Graph Notebook: Explore Your Data Visually\n\n\nThe Spanner Graph Notebook tool lets you visually query [Spanner Graph](https://cloud.google.com/spanner/docs/graph/overview) in a notebook environment (e.g. [Google Colab](https://colab.google/) and [Jupyter Notebook](https://jupyter.org/)). Using [GQL](https://cloud.google.com/spanner/docs/reference/standard-sql/graph-intro) 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.\n\n

\n\n## Table of Contents \n* [Prerequisites](#prerequisites)\n* [`%%spanner_graph` IPython Magics](#magic-usage)\n* [Google Colab Usage (Installation-Free)](#colab-usage)\n* [Installation and Usage in Jupyter Notebook](#jupyter-usage)\n* [Query Requirements](#query-requirements)\n\n

\n Prerequisites\n

\n\nTo 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](https://codelabs.developers.google.com/codelabs/spanner-graph-getting-started#0) codelab which walks through the setup.\n\n

\n %%spanner_graph IPython Magics\n

\n\nSpanner Graph Notebook is implemented as an [IPython Magics](https://ipython.readthedocs.io/en/stable/config/custommagics.html). Use the `%%spanner_graph` magic command in a code cell with GCP resource options and a query string:\n\n - a Google Cloud [Project ID](https://cloud.google.com/resource-manager/docs/creating-managing-projects) for `--project` option. \n - a Spanner [Instance ID](https://cloud.google.com/spanner/docs/create-manage-instances) for `--instance` option.\n - a Spanner [database name](https://cloud.google.com/spanner/docs/create-manage-databases) for `--database` option.\n - a [GQL](https://cloud.google.com/spanner/docs/graph/queries-overview) query string that returns graph elements as results.\n\nYou GQL query should return graph elements to have them visually displayed. See [Query Requirements](#query-requirements) section for examples. For instance, the code example below visually inspects 50 paths.\n\n```\n%%spanner_graph --project my-gcp-project --instance my-spanner-instance --database my-database\n\nGRAPH MyGraph\nMATCH p = (a)-[e]->(b)\nRETURN TO_JSON(p) AS path_json\nLIMIT 50\n\n(Note: `my-gcp-project`, `my-spanner-instance`, `my-database`, and `MyGraph` are placeholders. Replace them with your actual values.)\n```\n\nYou can also visualize a local dataset with `--mock` flag. Note that since this is a cell magic command, you must include two newlines after the command:\n\n```\n%%spanner_graph --mock\n\n\n```\n\n\n

\n Colab Usage (Installation-Free)\n

\n\nYou can directly invoke `%%spanner_graph` magic command in [Google Colab](https://colab.google/), a hosted Jupyter Notebook service that requires no setup to use. You'll be prompted to authenticate via [`pydata-google-auth`](https://github.com/pydata/pydata-google-auth) if Google Cloud Platform credentials aren't already available.\n\n

\n\n

\n Installation and Usage in Jupyter Notebook\n

\n\nYou can install and use this package in [Jupyter Notebook](https://jupyter.org/). We provided a [`sample.ipynb`](https://github.com/cloudspannerecosystem/spanner-graph-notebook/blob/main/sample.ipynb) in the root directory of this repo for you to follow.\n\n### Install dependencies\n\nFollow the commands below to create a managed Python environment (example based on [virtualenv](https://virtualenv.pypa.io/en/latest/)) and install [`spanner-graph-notebook`](https://pypi.org/project/spanner-graph-notebook/).\n\n```shell\n# Create the virtualenv `viz`.\npython3 -m venv viz\n\n# Activate the virtualenv.\nsource viz/bin/activate\n\n# Install dependencies.\npip install spanner-graph-notebook\n```\n\n### Using\n\n### Launch notebook and follow steps in `sample.ipynb`\n\nWhen in the root directory of the package, run `jupyter notebook` to launch Jupyter Notebook.\n\n```shell\njupyter notebook\n```\n\nAs Jupyter local server runs, it will open up a web portal. You can create or copy the [`sample.ipynb`](https://github.com/cloudspannerecosystem/spanner-graph-notebook/blob/main/sample.ipynb) to step through an example.\n\n

\n\nYou must run `%load_ext spanner_graphs` to load this package. `sample.ipynb` contains this cell already.\n\n

\n\nFollowing 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`](https://github.com/pydata/pydata-google-auth) if Google Cloud Platform credentials aren't already available.\n\n

\n\n

\n Query Requirements\n

\n\n### Use `TO_JSON` function to return graph elements\n\nTo 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.\n\n```sql\n👍 Good example returning a path as JSON.\n\n\nGRAPH FinGraph\nMATCH query_path = (person:Person {id: 5})-[owns:Owns]->(accnt:Account)\nRETURN SAFE_TO_JSON(query_path) AS path_json\n```\n\n```sql\n👍 Good example returning a path as JSON in a multiple-hop query.\n\nGRAPH FinGraph\nMATCH query_path = (src:Account {id: 9})-[edge]->{1,3}(dst:Account)\nRETURN SAFE_TO_JSON(query_path) as path_json\n```\n\n```sql\n👍 Good example returning multiple paths as JSON.\n\nGRAPH FinGraph\nMATCH path_1 = (person:Person {id: 5})-[:Owns]->(accnt:Account),\n path_2 = (src:Account {id: 9})-[:Transfers]->(dst:Account)\nRETURN SAFE_TO_JSON(path_1) as path_1,\n SAFE_TO_JSON(path_2) as path_2\n```\n\n```\n👎 Anti-example returning node properties rather than JSON format graph elements.\n Scalar results other than JSON format graph elements cannot be visualized.\n\nGRAPH FinGraph\nMATCH (person:Person {id: 5})-[owns:Owns]->(accnt:Account)\nRETURN person.id AS person,\n owns.amount AS owns,\n accnt.id AS accnt;\n```\n\n```sql\n👎 Anti-example returning each node and edges in JSON format verbosely. This will\n work but not as easy as returning a path directly.\n\nGRAPH FinGraph\nMATCH (person:Person {id: 5})-[owns:Owns]->(accnt:Account)\nRETURN SAFE_TO_JSON(person) AS person_json,\n SAFE_TO_JSON(owns) AS owns_json,\n SAFE_TO_JSON(accnt) AS accnt_json,\n```\n\n## Testing changes\n\nFirst, install the test dependencies:\n```shell\npip install -r requirements-test.txt\n```\n\nThen run unit and integration tests with the command below:\n```shell\ncd spanner_graphs && python -m unittest discover -s tests -p \"*_test.py\"\n```\n\nFor frontend testing:\n```shell\ncd frontend\nnpm install\nnpm run test:unit\nnpm run test:visual\n```\n","description_content_type":"text/markdown","docs_url":null,"download_url":null,"downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":["Description","Description-Content-Type","License-File","Requires-Dist","Summary"],"home_page":null,"keywords":null,"license":null,"license_expression":null,"license_files":["LICENSE"],"maintainer":null,"maintainer_email":null,"name":"spanner-graph-notebook","package_url":"https://pypi.org/project/spanner-graph-notebook/","platform":null,"project_url":"https://pypi.org/project/spanner-graph-notebook/","project_urls":null,"provides_extra":null,"release_url":"https://pypi.org/project/spanner-graph-notebook/1.1.6/","requires_dist":["networkx","numpy","google-cloud-spanner","ipython","ipywidgets","notebook","requests","portpicker","pydata-google-auth"],"requires_python":null,"summary":"Visually query Spanner Graph data in notebooks.","version":"1.1.6","yanked":false,"yanked_reason":null}

Dependency	Optional
google-cloud-spanner	false
ipython	false
ipywidgets	false
networkx	false
notebook	false
numpy	false
portpicker	false
pydata-google-auth	false
requests	false

Package search

spanner-graph-notebook

project_urls

Dependencies

All package metadata

Releases