{"id":42482628,"url":"https://github.com/cloudspannerecosystem/spanner-graph-notebook","last_synced_at":"2026-01-28T11:15:48.376Z","repository":{"id":263864407,"uuid":"881018053","full_name":"cloudspannerecosystem/spanner-graph-notebook","owner":"cloudspannerecosystem","description":"Visually query Spanner Graph data in notebooks","archived":false,"fork":false,"pushed_at":"2025-09-18T23:37:14.000Z","size":10132,"stargazers_count":37,"open_issues_count":14,"forks_count":10,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-28T12:51:23.717Z","etag":null,"topics":["graph","spanner","spanner-graph"],"latest_commit_sha":null,"homepage":"https://cloud.google.com/spanner/docs/graph/overview","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudspannerecosystem.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-10-30T19:19:18.000Z","updated_at":"2025-10-22T11:40:33.000Z","dependencies_parsed_at":"2025-01-09T21:25:46.677Z","dependency_job_id":"91bd4bf5-fce0-4371-9900-29b24470b5e6","html_url":"https://github.com/cloudspannerecosystem/spanner-graph-notebook","commit_stats":null,"previous_names":["cloudspannerecosystem/spanner-graph-notebook"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/cloudspannerecosystem/spanner-graph-notebook","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudspannerecosystem%2Fspanner-graph-notebook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudspannerecosystem%2Fspanner-graph-notebook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudspannerecosystem%2Fspanner-graph-notebook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudspannerecosystem%2Fspanner-graph-notebook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudspannerecosystem","download_url":"https://codeload.github.com/cloudspannerecosystem/spanner-graph-notebook/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudspannerecosystem%2Fspanner-graph-notebook/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28844862,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T10:53:21.605Z","status":"ssl_error","status_checked_at":"2026-01-28T10:53:20.789Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["graph","spanner","spanner-graph"],"created_at":"2026-01-28T11:15:47.601Z","updated_at":"2026-01-28T11:15:48.335Z","avatar_url":"https://github.com/cloudspannerecosystem.png","language":"JavaScript","readme":"# 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/)). \n\nUsing [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 expansion analysis. The tool also provides graph schema metadata visualization, tabular results inspection and diverse layout topologies.\n\nThe notebook visualization provides a user experience similar to Spanner Studio visualization, enabling you to visually inspect Spanner Graph data outside of Google Cloud console.\n\n\u003cimg src=\"./assets/full_viz.png\" width=\"800\"/\u003e\n\n## Table of Contents  \n* [Prerequisites](#prerequisites)\n* [Google Colab Usage (Installation-Free)](#colab-usage)\n* [Installation and Usage in Jupyter Notebook or JupyterLab](#jupyter-usage)\n* [Query Requirements](#query-requirements)\n\n\u003ch2 id=\"prerequisites\"\u003e\n  Prerequisites\n\u003c/h2\u003e\n\nYou need a Spanner database with graph schema and data. The [Getting started with Spanner Graph](https://codelabs.developers.google.com/codelabs/spanner-graph-getting-started#0) codelab or the [Set up and query Spanner Graph](https://cloud.google.com/spanner/docs/graph/set-up) page walks through the setup process.\n\n\n\u003ch2 id=\"colab-usage\"\u003e\n  Google Colab Usage (Installation-Free)\n\u003c/h2\u003e\n\nYou can directly use `%%spanner_graph` magic command to visualize graph query results in [Google Colab](https://colab.google/). The magic command must provide 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\n\nThe query must return [**graph elements in JSON format**](https://cloud.google.com/spanner/docs/graph/queries-overview#return-graph-elements-json) using the `SAFE_TO_JSON` or `TO_JSON` function. The following example code cell in Colab visualizes account transfers:\n\n```sql\n%%spanner_graph --project my-gcp-project --instance my-spanner-instance --database my-database\n\nGRAPH FinGraph\nMATCH result_paths = (src:Account {is_blocked: true})-[:Transfers]-\u003e(dest:Account)\nRETURN SAFE_TO_JSON(result_paths) AS result_paths\n```\n\nYou'll be prompted to authenticate via [`pydata-google-auth`](https://github.com/pydata/pydata-google-auth) if Google Cloud Platform credentials aren't readily available.\n\n\u003cimg src=\"./assets/colab_usage.gif\" width=\"600\"/\u003e\n\n\u003ch2 id=\"jupyter-usage\"\u003e\n  Installation and Usage in Jupyter Notebook or JupyterLab\n\u003c/h2\u003e\n\n### Install the package\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### Launch Jupyter Notebook\n\nWhen in the root directory of the package, run `jupyter notebook` or `jupyter lab` to launch your Jupyter notebook environment.\n\n```shell\njupyter notebook\n```\n\nAs Jupyter local server runs, it will open up a web portal. You can step through an example notebook [`sample.ipynb`](https://github.com/cloudspannerecosystem/spanner-graph-notebook/blob/main/sample.ipynb).\n\n\u003cimg src=\"./assets/sample_jupyter.png\" width=\"600\"/\u003e\n\nYou must run `%load_ext spanner_graphs` to load this package. `sample.ipynb` contains this cell already.\n\n\u003cimg src=\"./assets/load_ext.png\" width=\"600\"/\u003e\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 readily available.\n\n\u003cimg src=\"./assets/jupyter.gif\" width=\"600\"/\u003e\n\n\u003ch2 id=\"query-requirements\"\u003e\n  Query Requirements\n\u003c/h2\u003e\n\n### Use `TO_JSON` function to return graph elements\n\nGraph queries **must use** `SAFE_TO_JSON` or `TO_JSON` function to return [graph elements in JSON format](https://cloud.google.com/spanner/docs/graph/queries-overview#return-graph-elements-json) . We recommend visualizing **graph 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]-\u003e(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]-\u003e{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]-\u003e(accnt:Account),\n      path_2 = (src:Account {id: 9})-[:Transfers]-\u003e(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 graph elements in JSON.\n   Scalar intergers or strings cannot be visualized.\n\nGRAPH FinGraph\nMATCH (person:Person {id: 5})-[owns:Owns]-\u003e(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 individually.\n   This will work but is more verbose than returning paths.\n\nGRAPH FinGraph\nMATCH (person:Person {id: 5})-[owns:Owns]-\u003e(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 \u0026\u0026 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","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudspannerecosystem%2Fspanner-graph-notebook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudspannerecosystem%2Fspanner-graph-notebook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudspannerecosystem%2Fspanner-graph-notebook/lists"}