Package: graph-notebook
Graph Notebook: easily query and visualize graphsThe graph notebook provides an easy way to interact with graph databases using Jupyter notebooks. Using this open-source Python package, you can connect to any graph database that supports theApache TinkerPop,openCypheror theRDF SPARQLgraph models. These databases could be running locally on your desktop or in the cloud. Graph databases can be used to explore a variety of use cases includingknowledge graphsandidentity graphs.Visualizing Gremlin queriesVisualizing openCypher queriesVisualizing SPARQL queriesInstructions for connecting to the following graph databases:EndpointGraph modelQuery languageGremlin Serverproperty graphGremlinBlazegraphRDFSPARQLAmazon Neptuneproperty graph or RDFGremlin, openCypher, or SPARQLNeo4Jproperty graphCypherWe encourage others to contribute configurations they find useful. There is anadditional-databasesfolder where more information can be found.FeaturesNotebook cell 'magic' extensions in the IPython 3 kernel%%sparql- Executes a SPARQL query against your configured database endpoint.Documentation%%gremlin- Executes a Gremlin query against your database using web sockets. The results are similar to those a Gremlin console would return.Documentation%%opencypheror%%ocExecutes an openCypher query against your database.Documentation%%graph_notebook_config- Sets the executing notebook's database configuration to the JSON payload provided in the cell body.%%graph_notebook_vis_options- Sets the executing notebook'svis.js optionsto the JSON payload provided in the cell body.%%neptune_ml- Set of commands to integrate with NeptuneML functionality, as describedhere.DocumentationTIP:point_right:%%sparql,%%gremlin, and%%ocshare asuite of common argumentsthat be used to customize the appearance of rendered graphs. Example usage of these arguments can also be found in the sample notebooks under02-Visualization.TIP:point_right: There is syntax highlighting for language query magic cells to help you structure your queries more easily.Notebook line 'magic' extensions in the IPython 3 kernel%gremlin_status- Obtain the status of Gremlin queries.Documentation%sparql_status- Obtain the status of SPARQL queries.Documentation%opencypher_statusor%oc_status- Obtain the status of openCypher queries.Documentation%load- Generate a form to submit a bulk loader job.Documentation%load_ids- Get ids of bulk load jobs.Documentation%load_status- Get the status of a providedload_id.Documentation%cancel_load- Cancels a bulk load job. You can either provide a singleload_id, or specify--all-in-queueto cancel all queued (and not actively running) jobs.Documentation%neptune_ml- Set of commands to integrate with NeptuneML functionality, as describedhere. You can find a set of tutorial notebookshere.Documentation%status- Check the Health Status of the configured host endpoint.Documentation%seed- Provides a form to add data to your graph, using sets of insert queries instead of a bulk loader. Sample RDF and Property Graph data models are provided with this command. Alternatively, you can select a language type and provide a file path(or a directory path containing one or more of these files) to load the queries from.%stream_viewer- Interactively explore the Neptune CDC stream (if enabled)%graph_notebook_config- Returns a JSON payload that contains connection information for your host.%graph_notebook_host- Set the host endpoint to send queries to.%graph_notebook_version- Print the version of thegraph-notebookpackage%graph_notebook_vis_options- Print the Vis.js options being used for rendered graphsTIP:point_right: You can list all the magics installed in the Python 3 kernel using the%lsmagiccommand.TIP:point_right: Many of the magic commands support a--helpoption in order to provide additional information.Example notebooksThis project includes many example Jupyter notebooks. It is recommended to explore them. All of the commands and features supported bygraph-notebookare explained in detail with examples within the sample notebooks. You can find themhere. As this project has evolved, many new features have been added. If you are already familiar with graph-notebook but want a quick summary of new features added, a good place to start is the Air-Routes notebooks in the02-Visualizationfolder.Keeping track of new featuresIt is recommended to check theChangeLog.mdfile periodically to keep up to date as new features are added.PrerequisitesYou will need:Python3.8.x-3.10.13A graph database that provides one or more of:A SPARQL 1.1 endpointAn Apache TinkerPop Gremlin Server compatible endpointAn endpoint compatible with openCypherInstallationBegin by installinggraph-notebookand its prerequisites, then follow the remaining instructions for either Jupyter Classic Notebook or JupyterLab.# install the packagepipinstallgraph-notebookJupyter Classic Notebook# Enable the visualization widgetjupyternbextensionenable--py--sys-prefixgraph_notebook.widgets# copy static html resourcespython-mgraph_notebook.static_resources.install
python-mgraph_notebook.nbextensions.install# copy premade starter notebookspython-mgraph_notebook.notebooks.install--destination~/notebook/destination/dir# create nbconfig file and directory tree, if they do not already existmkdir~/.jupyter/nbconfig
touch~/.jupyter/nbconfig/notebook.json# start jupyter notebookpython-mgraph_notebook.start_notebook--notebooks-dir~/notebook/destination/dirJupyterLab 3.x# install jupyterlabpipinstall"jupyterlab>=3,<4"# copy premade starter notebookspython-mgraph_notebook.notebooks.install--destination~/notebook/destination/dir# start jupyterlabpython-mgraph_notebook.start_jupyterlab--jupyter-dir~/notebook/destination/dirLoading magic extensions in JupyterLabWhen attempting to run a line/cell magic on a new notebook in JupyterLab, you may encounter the error:UsageError:Cellmagic`%%graph_notebook_config`notfound.To fix this, run the following command, then restart JupyterLab.python-mgraph_notebook.ipython_profile.configure_ipython_profileAlternatively, the magic extensions can be manually reloaded for a single notebook by running the following command in any empty cell.%load_extgraph_notebook.magicsUpgrading an existing installation# upgrade graph-notebookpipinstallgraph-notebook--upgradeAfter the above command completes, rerun the commands given atJupyter Classic NotebookorJupyterLab 3.xbased on which flavour is installed.Connecting to a graph databaseConfiguration options can be set using the%graph_notebook_configmagic command. The command accepts a JSON object as an argument. The JSON object can contain any of the configuration options listed below. The command can be run multiple times to change the configuration. The configuration is stored in the notebook's metadata and will be used for all subsequent queries.Configuration OptionDescriptionDefault ValueTypeauth_modeThe authentication mode to use for Amazon Neptune connectionsDEFAULTstringaws_regionThe AWS region to use for Amazon Neptune connectionsyour-region-1stringhostThe host url to form a connection withlocalhoststringload_from_s3_arnThe ARN of the S3 bucket to load data from [Amazon Neptune only]stringneptune_serviceThe name of the Neptune service for the host url [Amazon Neptune only]neptune-dbstringportThe port to use when creating a connection8182numberproxy_hostThe proxy host url to route a connection through [Amazon Neptune only]stringproxy_portThe proxy port to use when creating proxy connection [Amazon Neptune only]8182numbersslWhether to make connections to the created endpoint with ssl or not [True/False]Falsebooleanssl_verifyWhether to verify the server's TLS certificate or not [True/False]TruebooleansparqlSPARQL connection object{ "path": "sparql" }stringgremlinGremlin connection object{ "username": "", "password": "", "traversal_source": "g",  "message_serializer": "graphsonv3" }stringneo4jNeo4J connection object{ "username": "neo4j", "password": "password", "auth": true, "database": null }stringGremlin ServerIn a new cell in the Jupyter notebook, change the configuration using%%graph_notebook_configand modify the fields forhost,port, andssl. Optionally, modifytraversal_sourceif your graph traversal source name differs from the default value,usernameandpasswordif required by the graph store, ormessage_serializerfor a specific data transfer format. For a local Gremlin server (HTTP or WebSockets), you can use the following command:%%graph_notebook_config{"host":"localhost","port":8182,"ssl":false,"gremlin":{"traversal_source":"g","username":"","password":"","message_serializer":"graphsonv3"}}To setup a new local Gremlin Server for use with the graph notebook, check outadditional-databases/gremlin serverBlazegraphChange the configuration using%%graph_notebook_configand modify the fields forhost,port, andssl. For a local Blazegraph database, you can use the following command:%%graph_notebook_config{"host":"localhost","port":9999,"ssl":false,"sparql":{"path":"sparql"}}You can also make use of namespaces for Blazegraph by specifying the pathgraph-notebookshould use when querying your SPARQL like below:%%graph_notebook_config{"host":"localhost","port":9999,"ssl":false,"sparql":{"path":"blazegraph/namespace/foo/sparql"}}This will result in the urllocalhost:9999/blazegraph/namespace/foo/sparqlbeing used when executing any%%sparqlmagic commands.To setup a new local Blazegraph database for use with the graph notebook, check out theQuick Startfrom Blazegraph.Amazon NeptuneChange the configuration using%%graph_notebook_configand modify the defaults as they apply to your Neptune instance.Neptune DB%%graph_notebook_config{"host":"your-neptune-endpoint","neptune_service":"neptune-db","port":8182,"auth_mode":"DEFAULT","load_from_s3_arn":"","ssl":true,"ssl_verify":true,"aws_region":"your-neptune-region"}Neptune Analytics%%graph_notebook_config{"host":"your-neptune-endpoint","neptune_service":"neptune-graph","port":443,"auth_mode":"IAM","ssl":true,"ssl_verify":true,"aws_region":"your-neptune-region"}To setup a new Amazon Neptune cluster, check out theAmazon Web Services documentation.When connecting the graph notebook to Neptune via a private endpoint, make sure you have a network setup to communicate to the VPC that Neptune runs on. If not, you can followthis guide.In addition to the above configuration options, you can also specify the following options:Amazon Neptune Proxy Connection%%graph_notebook_config{"host":"clustername.cluster-ididididid.us-east-1.neptune.amazonaws.com","neptune_service":"neptune-db","port":8182,"ssl":true,"proxy_port":8182,"proxy_host":"host.proxy.com","auth_mode":"IAM","aws_region":"us-east-1","load_from_s3_arn":""}See also: Connecting to Amazon Neptune from clients outside the Neptune VPC using AWS NetworkLoad BalancerAuthentication (Amazon Neptune)If you are running a SigV4 authenticated endpoint, ensure that your configuration hasauth_modeset toIAM:%%graph_notebook_config{"host":"your-neptune-endpoint","neptune_service":"neptune-db","port":8182,"auth_mode":"IAM","load_from_s3_arn":"","ssl":true,"ssl_verify":true,"aws_region":"your-neptune-region"}Additionally, you should have the following Amazon Web Services credentials available in a location accessible to Boto3:Access Key IDSecret Access KeyDefault RegionSession Token (OPTIONAL. Use if you are using temporary credentials)These variables must follow a specific naming convention, as listed in theBoto3 documentationA list of all locations checked for Amazon Web Services credentials can also be foundhere.Neo4JChange the configuration using%%graph_notebook_configand modify the fields forhost,port,ssl, andneo4jauthentication.If your Neo4J instance supportsmultiple databases, you can specify a database name via thedatabasefield. Otherwise, leave thedatabasefield blank to query the default database.For a local Neo4j Desktop database, you can use the following command:%%graph_notebook_config{"host":"localhost","port":7687,"ssl":false,"neo4j":{"username":"neo4j","password":"password","auth":true,"database":""}}Ensure that you also specify the%%oc boltoption when submitting queries to the Bolt endpoint.To setup a new local Neo4J Desktop database for use with the graph notebook, check out theNeo4J Desktop User Interface Guide.Building From SourceA pre-release distribution can be built from the graph-notebook repository via the following steps:# 1) Clone the repository and navigate into the clone directorygitclonehttps://github.com/aws/graph-notebook.gitcdgraph-notebook# 2) Create a new virtual environment# 2a) Option 1 - pyenvpyenvinstall3.10.13# Only if not already installed; this can be any supported Python 3 version in Prerequisitespyenvvirtualenv3.10.13build-graph-notebook
pyenvlocalbuild-graph-notebook# 2b) Option 2 - venvrm-rf/tmp/venv
python3-mvenv/tmp/venvsource/tmp/venv/bin/activate# 3) Install build dependenciespipinstall--upgradepipsetuptoolswheeltwine
pipinstall"jupyterlab>=3,<4"# 4) Build the distributionpython3setup.pybdist_wheelYou should now be able to find the built distribution at./dist/graph_notebook-4.1.0-py3-none-any.whlAnd use it by following theinstallationsteps, replacingpipinstallgraph-notebookwithpipinstall./dist/graph_notebook-4.1.0-py3-none-any.whlContributing GuidelinesSeeCONTRIBUTINGfor more information.LicenseThis project is licensed under the Apache-2.0 License.