graph-notebook: querying and drawing graph databases from a Jupyter cell

Three graph models behind one set of cell magics

graph-notebook is a Jupyter notebook extension for talking to graph databases. The repository describes it as a library that extends Jupyter notebooks to integrate with Apache TinkerPop, openCypher and RDF SPARQL, and the practical consequence is that one notebook can speak to three different kinds of graph store.

The distinctions matter because a graph database is not one thing. A property graph store exposes nodes and edges with properties, queried with Gremlin or openCypher. An RDF store exposes triples, queried with SPARQL. A single endpoint may expose a property graph, RDF, or both, which is exactly the case the documentation lists for Amazon Neptune. The extension does not try to hide this. It offers a cell magic per language, and the results come back rendered as a graph rather than as a list of rows.

The documentation also names the databases it has instructions for: Gremlin Server, Blazegraph, Amazon Neptune and Neo4J. For Gremlin Server and Neo4J the graph model is property graph, for Blazegraph it is RDF, and for Neptune it is property graph or RDF. Beyond those four, there is an additional-databases folder in the repository where configurations contributed by other users live, and the project invites contributions there.

Cell magics for %%gremlin, %%sparql and %%opencypher

The core of the package is a set of cell magics in the IPython 3 kernel, and each one runs a query against the configured endpoint. `%%gremlin` is documented as executing over web sockets, with results similar to what a Gremlin console would return, which matters because a Gremlin console is a websocket client and this is the same transport in a notebook cell. `%%sparql` runs a SPARQL query against the configured endpoint. `%%opencypher` runs an openCypher query and carries the short alias `%%oc`.

Two of the magics change the notebook's own state rather than running a query. `%%graph_notebook_config` sets the executing notebook's database configuration to the JSON payload in the cell body, which is how you point a notebook at a different endpoint mid-session. `%%graph_notebook_vis_options` does the same for vis.js options, the physics and layout settings that decide how the drawn graph looks.

The three query magics share a suite of common arguments for customising the appearance of the rendered graph, and the documentation points to the sample notebooks under 02-Visualization for examples. There is syntax highlighting for language query magic cells, which is a small quality-of-life detail that matters more in practice than it sounds when you are writing a long Gremlin traversal by hand.

One more cell magic sits alongside them, `%%neptune_ml`, a set of commands for NeptuneML functionality. The Neptune integration is not a bolt-on here, it runs through the same magic mechanism.

Line magics for status, bulk loading and endpoint configuration

The line magics cover the operational side. Status reporting comes in three flavours matching the three query languages: `%gremlin_status`, `%sparql_status`, and `%opencypher_status` with the alias `%oc_status`. Each returns the status of in-flight queries for its language.

The bulk loading group is Neptune specific and worth understanding in detail, because it is the part that has no equivalent in the other two ecosystems. `%load` generates a form to submit a bulk loader job. `%load_ids` gets ids of bulk load jobs, `%load_status` gets the status of a provided `load_id`, and `%cancel_load` cancels a job, either by a single `load_id` or with `--all-in-queue` to cancel every queued job that is not actively running.

The `--all-in-queue` flag is the interesting one, because it is a bulk operation with a scope wider than one job, and there is no confirmation step described in the documentation.

Endpoint configuration is handled by `%graph_notebook_host`, which sets the host endpoint queries are sent to, and `%graph_notebook_config`, which returns a JSON payload containing connection information for the host. `%status` checks the health status of the configured host endpoint, and `%graph_notebook_version` prints the version of the graph-notebook package, which is a quick way to confirm which build is actually loaded into a running kernel.

There is also `%seed`, a form for adding data to the graph using sets of insert queries rather than a bulk loader, with sample RDF and property graph data models provided. You can select a language type and give it a file path or a directory path containing query files. And `%stream_viewer` interactively explores the Neptune CDC stream when that feature is enabled on the database.

Running the container: ports, environment variables and a default password

The repository ships a Dockerfile, and it is the most concrete part of the material for setting up a local instance. The image is based on amazonlinux:2022, exposes the notebook port and the lab port, and runs as root:

FROM amazonlinux:2022

# Notebook Port
EXPOSE 8888
# Lab Port
EXPOSE 8889
USER root

The environment block shows the knobs the image expects. The notebook and lab ports are 8888 and 8889. A proxy port of 8192 and a separate graph notebook port of 8182 are defined alongside a proxy host that is empty by default. The Neptune host default points at a cluster endpoint pattern in us-east-1, the AWS region defaults to us-east-1, and SSL is on by default. Node is pinned at 20.19.0 and Python at 3.10, and there is a note that pipargs may need to be set to a mirror for China regions.

Two defaults deserve a second look before this image is deployed anywhere shared:

ENV NOTEBOOK_PASSWORD="admin"
ENV GRAPH_NOTEBOOK_AUTH_MODE="DEFAULT"

A notebook password of admin with the default authentication mode is a starting point for local work, not a production configuration. The image also sets a graceful stop signal of SIGUSR1, which the comments explain quits the process cleanly and closes established connections.

The dependency set is pinned hard, and Python 3.9 to 3.13

The manifest declares the package as graph-notebook, version 5.3.0, built with hatchling and hatch-jupyter-builder, and requires Python >=3.9,<3.14. The classifier list covers Python 3.9 through 3.13 and marks the project as a production stable development status.

The dependency list is where a graph project earns its keep, and here it is split into labelled groups. The Jupyter ecosystem block pins ipyfilechooser at 0.6.0, ipython between 7.16.1 and 8.10.0, ipywidgets between 8.0.0 and 9.0.0, jupyterlab between 4.3.5 and 5.0.0, notebook between 7.0.0 and 8.0.0 and nbconvert between 6.3.0 and 7.2.8.

Data processing and visualization pull in itables, networkx, numpy, pandas and plotly. The graph database group is the one that defines which endpoints work:

gremlinpython>=3.5.1,<=3.7.2
neo4j>=5.0.0,<=5.23.1
rdflib==7.0.0
SPARQLWrapper==2.0.0

That is one driver per query model. gremlinpython covers TinkerPop endpoints such as Gremlin Server and Neptune, neo4j covers Neo4J, and rdflib with SPARQLWrapper covers the RDF path used by Blazegraph and Neptune's RDF side. boto3 and botocore, both at 1.34.74 or newer, sit in the AWS SDK group for the Neptune calls.

The upper bounds are the practical constraint. Both gremlinpython and neo4j are capped, and neo4j is capped below 5.24, so a project already on a newer driver will not install cleanly. The bounds are duplicated in requirements.txt, with slightly different comparison operators in places, so the two files are not perfectly identical descriptions of the same constraint set.The documentation gives no pip install command for the package itself. What it points to instead is the sample notebook set under src/graph_notebook/notebooks and the Dockerfile at the repository root, so a first use is either a local Jupyter install driven from the sample notebooks or a container built from that Dockerfile.

What it is not: a query service, and the Neptune bias

Two limitations are visible without reading much.

The first is that this is a notebook tool. The magics run in an IPython kernel, they need a Jupyter server to serve the notebook, and the form-generating magics like `%load` and `%seed` exist to be filled in by a human in a browser. None of that is a substitute for a scheduled job or an API. If you need a graph query to run unattended on a schedule, this is the wrong shape of tool, and the obvious alternative is to call the same endpoint with the same client libraries the manifest already lists, gremlinpython or neo4j, from your own code.

The second is the Neptune bias. A large share of the magic list is Neptune specific: the bulk load group, the NeptuneML commands, the CDC stream viewer, the Neptune host default baked into the container image. The graph query magics are portable across the three models, and the status magics largely are too, but bulk loading through the notebook is a Neptune feature rather than a general graph database capability.

The other boundary is the range of the drivers. Because neo4j is pinned below 5.24 and gremlinpython below 3.7.3, a team on a current driver version will hit the upper bound during installation, and the resolution is a version conflict decision rather than a configuration change. The project's own sample notebooks under src/graph_notebook/notebooks, including the 02-Visualization and 04-Machine-Learning directories it links to, are the fastest way to see which combinations the maintainers actually exercise.

Licence, release cadence and what the project ships

The project is under the Apache License 2.0, recorded in the manifest as a licence file, and the repository carries a LICENSE file, a NOTICE file, a THIRD_PARTY_LICENSES.txt file and a CODE_OF_CONDUCT.md. The presence of a third party licence file matters for a package that vendors a Jupyter extension and pulls in the Neo4j, rdflib and gremlinpython ecosystems, since the obligations of those upstream licences flow through to a distributor. Which obligations apply to your own deployment is a question for your own legal review, not something this repository settles.

The release line is recent and the version numbers are real. Release 5.3.0 shipped on 2026-08-05, v5.2.0 on 2026-03-17 and v5.1.0 on 2025-10-30, and the last push on the repository was on 2026-09-01, so the source tree is ahead of the 5.3.0 tag in the same way any actively worked project is. The manifest version and the released version agree at 5.3.0.

The repository layout also tells you what kind of project this is. There is a src directory, a test directory, a docker directory, an additional-databases directory, install.json, a ChangeLog.md and a CONTRIBUTING.md, plus a pytest.ini. The Dockerfile is a separate build path from the Python package, and the additional-databases folder is a community extension point rather than a core feature, which is a good sign for a project that expects to outlive any single vendor's endpoint.

Editorial conclusion

graph-notebook fits data engineers and graph engineers who want to explore a Gremlin, openCypher or SPARQL endpoint interactively and hand a colleague a rendered result rather than a wall of JSON. It is a poor fit if you need a production query service, if your Python is outside the 3.9 to 3.13 range the manifest declares, or if you want to avoid the Neptune-specific commands that make up a large part of the magic list. Before you adopt it, confirm which of the three query languages your endpoint speaks, check that your driver is covered by the pinned dependency set such as gremlinpython between 3.5.1 and 3.7.2 or neo4j up to 5.23.1, and decide how you will handle the default notebook password in the container image. The last push on the repository was on 2026-09-01, and the released version was 5.3.0 on 2026-08-05.

Frequently asked questions

Official sources

1. aws/graph-notebook on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases