# Graph Notebook: easily query and visualize graphs
The 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 the [Apache TinkerPop](https://tinkerpop.apache.org/), [openCypher](https://github.com/opencypher/openCypher) or the [RDF SPARQL](https://www.w3.org/TR/rdf-sparql-query/) graph 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 including [knowledge graphs](https://aws.amazon.com/neptune/knowledge-graphs-on-aws/) and [identity graphs](https://aws.amazon.com/neptune/identity-graphs-on-aws/).
## Visualizing Gremlin queries
## Visualizing openCypher queries
## Visualizing SPARQL queries
Instructions for connecting to the following graph databases:
| Endpoint | Graph model | Query language |
| :-----------------------------: | :---------------------: | :-----------------: |
|[Gremlin Server](#gremlin-server)| property graph | Gremlin |
| [Blazegraph](#blazegraph) | RDF | SPARQL |
|[Amazon Neptune](#amazon-neptune)| property graph or RDF | Gremlin, openCypher, or SPARQL |
| [Neo4J](#neo4j) | property graph | Cypher |
We encourage others to contribute configurations they find useful. There is an [`additional-databases`](https://github.com/aws/graph-notebook/blob/main/additional-databases) folder where more information can be found.
## Features
### Notebook cell 'magic' extensions in the IPython 3 kernel
`%%sparql` - Executes a SPARQL query against your configured database endpoint. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-cell-magics-sparql)
`%%gremlin` - Executes a Gremlin query against your database using web sockets. The results are similar to those a Gremlin console would return. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-cell-magics-gremlin)
`%%opencypher` or `%%oc` Executes an openCypher query against your database. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-cell-magics-opencypher)
`%%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's [vis.js options](https://visjs.github.io/vis-network/docs/network/physics.html) to the JSON payload provided in the cell body.
`%%neptune_ml` - Set of commands to integrate with NeptuneML functionality, as described [here](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-line-magics-neptune_ml). [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/machine-learning.html)
**TIP** :point_right: `%%sparql`, `%%gremlin`, and `%%oc` share a [suite of common arguments](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebook-magics-query-args) that be used to customize the appearance of rendered graphs. Example usage of these arguments can also be found in the sample notebooks under [02-Visualization](https://github.com/aws/graph-notebook/tree/main/src/graph_notebook/notebooks/02-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](https://docs.aws.amazon.com/neptune/latest/userguide/gremlin-api-status.html)
`%sparql_status` - Obtain the status of SPARQL queries. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/sparql-api-status.html)
`%opencypher_status` or `%oc_status` - Obtain the status of openCypher queries. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/access-graph-opencypher-status.html)
`%load` - Generate a form to submit a bulk loader job. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/bulk-load.html)
`%load_ids` - Get ids of bulk load jobs. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/load-api-reference-status-examples.html)
`%load_status` - Get the status of a provided `load_id`. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/load-api-reference-status-examples.html)
`%cancel_load` - Cancels a bulk load job. You can either provide a single `load_id`, or specify `--all-in-queue` to cancel all queued (and not actively running) jobs. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/load-api-reference-cancel.html)
`%neptune_ml` - Set of commands to integrate with NeptuneML functionality, as described [here](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-cell-magics-neptune_ml). You can find a set of tutorial notebooks [here](https://github.com/aws/graph-notebook/tree/main/src/graph_notebook/notebooks/04-Machine-Learning).
[Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/machine-learning.html)
`%status` - Check the Health Status of the configured host endpoint. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/access-graph-status.html)
`%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 the `graph-notebook` package
`%graph_notebook_vis_options` - Print the Vis.js options being used for rendered graphs
**TIP** :point_right: You can list all the magics installed in the Python 3 kernel using the `%lsmagic` command.
**TIP** :point_right: Many of the magic commands support a `--help` option in order to provide additional information.
## Example notebooks
This project includes many example Jupyter notebooks. It is recommended to explore them. All of the commands and features supported by `graph-notebook` are explained in detail with examples within the sample notebooks. You can find them [here](./src/graph_notebook/notebooks/). 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 the [02-Visualization](./src/graph_notebook/notebooks/02-Visualization) folder.
## Keeping track of new features
It is recommended to check the [ChangeLog.md](ChangeLog.md) file periodically to keep up to date as new features are added.
## Prerequisites
You will need:
* [Python](https://www.python.org/downloads/) 3.8.x-3.10.13
* A graph database that provides one or more of:
* A SPARQL 1.1 endpoint
* An Apache TinkerPop Gremlin Server compatible endpoint
* An endpoint compatible with openCypher
## Installation
Begin by installing `graph-notebook` and its prerequisites, then follow the remaining instructions for either Jupyter Classic Notebook or JupyterLab.
``` bash
# install the package
pip install graph-notebook
```
### Jupyter Classic Notebook
``` bash
# Enable the visualization widget
jupyter nbextension enable --py --sys-prefix graph_notebook.widgets
# copy static html resources
python -m graph_notebook.static_resources.install
python -m graph_notebook.nbextensions.install
# copy premade starter notebooks
python -m graph_notebook.notebooks.install --destination ~/notebook/destination/dir
# create nbconfig file and directory tree, if they do not already exist
mkdir ~/.jupyter/nbconfig
touch ~/.jupyter/nbconfig/notebook.json
# start jupyter notebook
python -m graph_notebook.start_notebook --notebooks-dir ~/notebook/destination/dir
```
### JupyterLab 3.x
``` bash
# install jupyterlab
pip install "jupyterlab>=3,<4"
# copy premade starter notebooks
python -m graph_notebook.notebooks.install --destination ~/notebook/destination/dir
# start jupyterlab
python -m graph_notebook.start_jupyterlab --jupyter-dir ~/notebook/destination/dir
```
#### Loading magic extensions in JupyterLab
When attempting to run a line/cell magic on a new notebook in JupyterLab, you may encounter the error:
``` bash
UsageError: Cell magic `%%graph_notebook_config` not found.
```
To fix this, run the following command, then restart JupyterLab.
``` bash
python -m graph_notebook.ipython_profile.configure_ipython_profile
```
Alternatively, the magic extensions can be manually reloaded for a single notebook by running the following command in any empty cell.
``` bash
%load_ext graph_notebook.magics
```
## Upgrading an existing installation
``` bash
# upgrade graph-notebook
pip install graph-notebook --upgrade
```
After the above command completes, rerun the commands given at [Jupyter Classic Notebook](#jupyter-classic-notebook) or [JupyterLab 3.x](#jupyterlab-3x) based on which flavour is installed.
## Connecting to a graph database
Configuration options can be set using the `%graph_notebook_config` magic 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 Option | Description | Default Value | Type |
| --- | --- | --- | --- |
| auth_mode | The authentication mode to use for Amazon Neptune connections | DEFAULT | string |
| aws_region | The AWS region to use for Amazon Neptune connections | your-region-1 | string |
| host | The host url to form a connection with | localhost | string |
| load_from_s3_arn | The ARN of the S3 bucket to load data from [Amazon Neptune only] | | string |
| neptune_service | The name of the Neptune service for the host url [Amazon Neptune only] | neptune-db | string |
| port | The port to use when creating a connection | 8182 | number |
| proxy_host | The proxy host url to route a connection through [Amazon Neptune only]| | string |
| proxy_port | The proxy port to use when creating proxy connection [Amazon Neptune only] | 8182 | number |
| ssl | Whether to make connections to the created endpoint with ssl or not [True/False] | False | boolean |
| ssl_verify | Whether to verify the server's TLS certificate or not [True/False] | True | boolean |
| sparql | SPARQL connection object | ``` { "path": "sparql" } ``` | string |
| gremlin | Gremlin connection object | ``` { "username": "", "password": "", "traversal_source": "g", "message_serializer": "graphsonv3" } ```| string |
| neo4j | Neo4J connection object |``` { "username": "neo4j", "password": "password", "auth": true, "database": null } ``` | string |
### Gremlin Server
In a new cell in the Jupyter notebook, change the configuration using `%%graph_notebook_config` and modify the fields for `host`, `port`, and `ssl`. Optionally, modify `traversal_source` if your graph traversal source name differs from the default value, `username` and `password` if required by the graph store, or `message_serializer` for a specific data transfer format. For a local Gremlin server (HTTP or WebSockets), you can use the following command:
``` python
%%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 out [`additional-databases/gremlin server`](additional-databases/gremlin-server)
### Blazegraph
Change the configuration using `%%graph_notebook_config` and modify the fields for `host`, `port`, and `ssl`. For a local Blazegraph database, you can use the following command:
``` python
%%graph_notebook_config
{
"host": "localhost",
"port": 9999,
"ssl": false,
"sparql": {
"path": "sparql"
}
}
```
You can also make use of namespaces for Blazegraph by specifying the path `graph-notebook` should use when querying your SPARQL like below:
``` python
%%graph_notebook_config
{
"host": "localhost",
"port": 9999,
"ssl": false,
"sparql": {
"path": "blazegraph/namespace/foo/sparql"
}
}
```
This will result in the url `localhost:9999/blazegraph/namespace/foo/sparql` being used when executing any `%%sparql` magic commands.
To setup a new local Blazegraph database for use with the graph notebook, check out the [Quick Start](https://github.com/blazegraph/database/wiki/Quick_Start) from Blazegraph.
### Amazon Neptune
Change the configuration using `%%graph_notebook_config` and modify the defaults as they apply to your Neptune instance.
#### Neptune DB
``` python
%%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
``` python
%%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 the [Amazon Web Services documentation](https://docs.aws.amazon.com/neptune/latest/userguide/manage-console-launch.html).
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 follow [this guide](https://github.com/aws/graph-notebook/tree/main/additional-databases/neptune).
In addition to the above configuration options, you can also specify the following options:
### Amazon Neptune Proxy Connection
``` python
%%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 Network [Load Balancer](https://aws-samples.github.io/aws-dbs-refarch-graph/src/connecting-using-a-load-balancer/#connecting-to-amazon-neptune-from-clients-outside-the-neptune-vpc-using-aws-network-load-balancer)
## Authentication (Amazon Neptune)
If you are running a SigV4 authenticated endpoint, ensure that your configuration has `auth_mode` set to `IAM`:
``` python
%%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 ID
* Secret Access Key
* Default Region
* Session Token (OPTIONAL. Use if you are using temporary credentials)
These variables must follow a specific naming convention, as listed in the [Boto3 documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html#using-environment-variables)
A list of all locations checked for Amazon Web Services credentials can also be found [here](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html#configuring-credentials).
### Neo4J
Change the configuration using `%%graph_notebook_config` and modify the fields for `host`, `port`, `ssl`, and `neo4j` authentication.
If your Neo4J instance supports [multiple databases](https://neo4j.com/developer/manage-multiple-databases/), you can specify a database name via the `database` field. Otherwise, leave the `database` field blank to query the default database.
For a local Neo4j Desktop database, you can use the following command:
``` python
%%graph_notebook_config
{
"host": "localhost",
"port": 7687,
"ssl": false,
"neo4j": {
"username": "neo4j",
"password": "password",
"auth": true,
"database": ""
}
}
```
Ensure that you also specify the `%%oc bolt` option when submitting queries to the Bolt endpoint.
To setup a new local Neo4J Desktop database for use with the graph notebook, check out the [Neo4J Desktop User Interface Guide](https://neo4j.com/developer/neo4j-desktop/).
## Building From Source
A pre-release distribution can be built from the graph-notebook repository via the following steps:
``` bash
# 1) Clone the repository and navigate into the clone directory
git clone https://github.com/aws/graph-notebook.git
cd graph-notebook
# 2) Create a new virtual environment
# 2a) Option 1 - pyenv
pyenv install 3.10.13 # Only if not already installed; this can be any supported Python 3 version in Prerequisites
pyenv virtualenv 3.10.13 build-graph-notebook
pyenv local build-graph-notebook
# 2b) Option 2 - venv
rm -rf /tmp/venv
python3 -m venv /tmp/venv
source /tmp/venv/bin/activate
# 3) Install build dependencies
pip install --upgrade pip setuptools wheel twine
pip install "jupyterlab>=3,<4"
# 4) Build the distribution
python3 setup.py bdist_wheel
```
You should now be able to find the built distribution at
`./dist/graph_notebook-4.1.0-py3-none-any.whl`
And use it by following the [installation](https://github.com/aws/graph-notebook#installation) steps, replacing
``` python
pip install graph-notebook
```
with
``` python
pip install ./dist/graph_notebook-4.1.0-py3-none-any.whl
```
## Contributing Guidelines
See [CONTRIBUTING](https://github.com/aws/graph-notebook/blob/main/CONTRIBUTING.md) for more information.
## License
This project is licensed under the Apache-2.0 License.
Raw data
{
"_id": null,
"home_page": "https://github.com/aws/graph-notebook",
"name": "graph-notebook",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "jupyter neptune gremlin sparql",
"author": "amazon-neptune",
"author_email": "amazon-neptune-pypi@amazon.com",
"download_url": "https://files.pythonhosted.org/packages/1c/41/145e7ad4e34a95b39fc0dc45bdc79a1e225792f51fd09687784657bc8742/graph-notebook-4.1.0.tar.gz",
"platform": null,
"description": "# Graph Notebook: easily query and visualize graphs\n\nThe 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 the [Apache TinkerPop](https://tinkerpop.apache.org/), [openCypher](https://github.com/opencypher/openCypher) or the [RDF SPARQL](https://www.w3.org/TR/rdf-sparql-query/) graph 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 including [knowledge graphs](https://aws.amazon.com/neptune/knowledge-graphs-on-aws/) and [identity graphs](https://aws.amazon.com/neptune/identity-graphs-on-aws/).\n\n\n\n## Visualizing Gremlin queries\n\n\n\n## Visualizing openCypher queries\n\n\n\n## Visualizing SPARQL queries\n\n\n\nInstructions for connecting to the following graph databases:\n\n| Endpoint | Graph model | Query language |\n| :-----------------------------: | :---------------------: | :-----------------: |\n|[Gremlin Server](#gremlin-server)| property graph | Gremlin |\n| [Blazegraph](#blazegraph) | RDF | SPARQL |\n|[Amazon Neptune](#amazon-neptune)| property graph or RDF | Gremlin, openCypher, or SPARQL |\n| [Neo4J](#neo4j) | property graph | Cypher |\n\nWe encourage others to contribute configurations they find useful. There is an [`additional-databases`](https://github.com/aws/graph-notebook/blob/main/additional-databases) folder where more information can be found.\n\n## Features\n\n### Notebook cell 'magic' extensions in the IPython 3 kernel\n\n`%%sparql` - Executes a SPARQL query against your configured database endpoint. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-cell-magics-sparql)\n\n`%%gremlin` - Executes a Gremlin query against your database using web sockets. The results are similar to those a Gremlin console would return. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-cell-magics-gremlin)\n\n`%%opencypher` or `%%oc` Executes an openCypher query against your database. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-cell-magics-opencypher)\n\n`%%graph_notebook_config` - Sets the executing notebook's database configuration to the JSON payload provided in the cell body.\n\n`%%graph_notebook_vis_options` - Sets the executing notebook's [vis.js options](https://visjs.github.io/vis-network/docs/network/physics.html) to the JSON payload provided in the cell body.\n\n`%%neptune_ml` - Set of commands to integrate with NeptuneML functionality, as described [here](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-line-magics-neptune_ml). [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/machine-learning.html)\n\n**TIP** :point_right: `%%sparql`, `%%gremlin`, and `%%oc` share a [suite of common arguments](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebook-magics-query-args) that be used to customize the appearance of rendered graphs. Example usage of these arguments can also be found in the sample notebooks under [02-Visualization](https://github.com/aws/graph-notebook/tree/main/src/graph_notebook/notebooks/02-Visualization).\n\n**TIP** :point_right: There is syntax highlighting for language query magic cells to help you structure your queries more easily.\n\n#### Notebook line 'magic' extensions in the IPython 3 kernel\n\n`%gremlin_status` - Obtain the status of Gremlin queries. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/gremlin-api-status.html)\n\n`%sparql_status` - Obtain the status of SPARQL queries. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/sparql-api-status.html)\n\n`%opencypher_status` or `%oc_status` - Obtain the status of openCypher queries. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/access-graph-opencypher-status.html)\n\n`%load` - Generate a form to submit a bulk loader job. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/bulk-load.html)\n\n`%load_ids` - Get ids of bulk load jobs. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/load-api-reference-status-examples.html)\n\n`%load_status` - Get the status of a provided `load_id`. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/load-api-reference-status-examples.html)\n\n`%cancel_load` - Cancels a bulk load job. You can either provide a single `load_id`, or specify `--all-in-queue` to cancel all queued (and not actively running) jobs. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/load-api-reference-cancel.html)\n\n`%neptune_ml` - Set of commands to integrate with NeptuneML functionality, as described [here](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-cell-magics-neptune_ml). You can find a set of tutorial notebooks [here](https://github.com/aws/graph-notebook/tree/main/src/graph_notebook/notebooks/04-Machine-Learning).\n[Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/machine-learning.html)\n\n`%status` - Check the Health Status of the configured host endpoint. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/access-graph-status.html)\n\n`%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.\n\n`%stream_viewer` - Interactively explore the Neptune CDC stream (if enabled)\n\n`%graph_notebook_config` - Returns a JSON payload that contains connection information for your host.\n\n`%graph_notebook_host` - Set the host endpoint to send queries to.\n\n`%graph_notebook_version` - Print the version of the `graph-notebook` package\n\n`%graph_notebook_vis_options` - Print the Vis.js options being used for rendered graphs\n\n**TIP** :point_right: You can list all the magics installed in the Python 3 kernel using the `%lsmagic` command.\n\n**TIP** :point_right: Many of the magic commands support a `--help` option in order to provide additional information.\n\n## Example notebooks\n\nThis project includes many example Jupyter notebooks. It is recommended to explore them. All of the commands and features supported by `graph-notebook` are explained in detail with examples within the sample notebooks. You can find them [here](./src/graph_notebook/notebooks/). 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 the [02-Visualization](./src/graph_notebook/notebooks/02-Visualization) folder.\n\n## Keeping track of new features\n\nIt is recommended to check the [ChangeLog.md](ChangeLog.md) file periodically to keep up to date as new features are added.\n\n## Prerequisites\n\nYou will need:\n\n* [Python](https://www.python.org/downloads/) 3.8.x-3.10.13\n* A graph database that provides one or more of:\n * A SPARQL 1.1 endpoint\n * An Apache TinkerPop Gremlin Server compatible endpoint\n * An endpoint compatible with openCypher\n \n## Installation\n\nBegin by installing `graph-notebook` and its prerequisites, then follow the remaining instructions for either Jupyter Classic Notebook or JupyterLab.\n\n``` bash\n# install the package\npip install graph-notebook\n```\n\n### Jupyter Classic Notebook\n\n``` bash\n# Enable the visualization widget\njupyter nbextension enable --py --sys-prefix graph_notebook.widgets\n\n# copy static html resources\npython -m graph_notebook.static_resources.install\npython -m graph_notebook.nbextensions.install\n\n# copy premade starter notebooks\npython -m graph_notebook.notebooks.install --destination ~/notebook/destination/dir\n\n# create nbconfig file and directory tree, if they do not already exist\nmkdir ~/.jupyter/nbconfig\ntouch ~/.jupyter/nbconfig/notebook.json\n\n# start jupyter notebook\npython -m graph_notebook.start_notebook --notebooks-dir ~/notebook/destination/dir\n```\n\n### JupyterLab 3.x\n\n``` bash\n# install jupyterlab\npip install \"jupyterlab>=3,<4\"\n\n# copy premade starter notebooks\npython -m graph_notebook.notebooks.install --destination ~/notebook/destination/dir\n\n# start jupyterlab\npython -m graph_notebook.start_jupyterlab --jupyter-dir ~/notebook/destination/dir\n```\n\n#### Loading magic extensions in JupyterLab\n\nWhen attempting to run a line/cell magic on a new notebook in JupyterLab, you may encounter the error:\n\n``` bash\nUsageError: Cell magic `%%graph_notebook_config` not found.\n```\n\nTo fix this, run the following command, then restart JupyterLab.\n\n``` bash\npython -m graph_notebook.ipython_profile.configure_ipython_profile\n```\n\nAlternatively, the magic extensions can be manually reloaded for a single notebook by running the following command in any empty cell.\n\n``` bash\n%load_ext graph_notebook.magics\n```\n\n## Upgrading an existing installation\n\n``` bash\n# upgrade graph-notebook\npip install graph-notebook --upgrade\n```\n\nAfter the above command completes, rerun the commands given at [Jupyter Classic Notebook](#jupyter-classic-notebook) or [JupyterLab 3.x](#jupyterlab-3x) based on which flavour is installed.\n\n## Connecting to a graph database\n\nConfiguration options can be set using the `%graph_notebook_config` magic 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.\n\n| Configuration Option | Description | Default Value | Type |\n| --- | --- | --- | --- |\n| auth_mode | The authentication mode to use for Amazon Neptune connections | DEFAULT | string |\n| aws_region | The AWS region to use for Amazon Neptune connections | your-region-1 | string |\n| host | The host url to form a connection with | localhost | string |\n| load_from_s3_arn | The ARN of the S3 bucket to load data from [Amazon Neptune only] | | string |\n| neptune_service | The name of the Neptune service for the host url [Amazon Neptune only] | neptune-db | string |\n| port | The port to use when creating a connection | 8182 | number |\n| proxy_host | The proxy host url to route a connection through [Amazon Neptune only]| | string |\n| proxy_port | The proxy port to use when creating proxy connection [Amazon Neptune only] | 8182 | number |\n| ssl | Whether to make connections to the created endpoint with ssl or not [True/False] | False | boolean |\n| ssl_verify | Whether to verify the server's TLS certificate or not [True/False] | True | boolean |\n| sparql | SPARQL connection object | ``` { \"path\": \"sparql\" } ``` | string |\n| gremlin | Gremlin connection object | ``` { \"username\": \"\", \"password\": \"\", \"traversal_source\": \"g\", \"message_serializer\": \"graphsonv3\" } ```| string |\n| neo4j | Neo4J connection object |``` { \"username\": \"neo4j\", \"password\": \"password\", \"auth\": true, \"database\": null } ``` | string |\n\n### Gremlin Server\n\nIn a new cell in the Jupyter notebook, change the configuration using `%%graph_notebook_config` and modify the fields for `host`, `port`, and `ssl`. Optionally, modify `traversal_source` if your graph traversal source name differs from the default value, `username` and `password` if required by the graph store, or `message_serializer` for a specific data transfer format. For a local Gremlin server (HTTP or WebSockets), you can use the following command:\n\n``` python\n%%graph_notebook_config\n{\n \"host\": \"localhost\",\n \"port\": 8182,\n \"ssl\": false,\n \"gremlin\": {\n \"traversal_source\": \"g\",\n \"username\": \"\",\n \"password\": \"\",\n \"message_serializer\": \"graphsonv3\"\n }\n}\n```\n\nTo setup a new local Gremlin Server for use with the graph notebook, check out [`additional-databases/gremlin server`](additional-databases/gremlin-server)\n\n### Blazegraph\n\nChange the configuration using `%%graph_notebook_config` and modify the fields for `host`, `port`, and `ssl`. For a local Blazegraph database, you can use the following command:\n\n``` python\n%%graph_notebook_config\n{\n \"host\": \"localhost\",\n \"port\": 9999,\n \"ssl\": false,\n \"sparql\": {\n \"path\": \"sparql\"\n }\n}\n```\n\nYou can also make use of namespaces for Blazegraph by specifying the path `graph-notebook` should use when querying your SPARQL like below:\n\n``` python\n%%graph_notebook_config\n\n{\n \"host\": \"localhost\",\n \"port\": 9999,\n \"ssl\": false,\n \"sparql\": {\n \"path\": \"blazegraph/namespace/foo/sparql\"\n }\n}\n```\n\nThis will result in the url `localhost:9999/blazegraph/namespace/foo/sparql` being used when executing any `%%sparql` magic commands.\n\nTo setup a new local Blazegraph database for use with the graph notebook, check out the [Quick Start](https://github.com/blazegraph/database/wiki/Quick_Start) from Blazegraph.\n\n### Amazon Neptune\n\nChange the configuration using `%%graph_notebook_config` and modify the defaults as they apply to your Neptune instance.\n\n#### Neptune DB\n\n``` python\n%%graph_notebook_config\n{\n \"host\": \"your-neptune-endpoint\",\n \"neptune_service\": \"neptune-db\",\n \"port\": 8182,\n \"auth_mode\": \"DEFAULT\",\n \"load_from_s3_arn\": \"\",\n \"ssl\": true,\n \"ssl_verify\": true,\n \"aws_region\": \"your-neptune-region\"\n}\n```\n\n#### Neptune Analytics\n\n``` python\n%%graph_notebook_config\n{\n \"host\": \"your-neptune-endpoint\",\n \"neptune_service\": \"neptune-graph\",\n \"port\": 443,\n \"auth_mode\": \"IAM\",\n \"ssl\": true,\n \"ssl_verify\": true,\n \"aws_region\": \"your-neptune-region\"\n}\n```\n\nTo setup a new Amazon Neptune cluster, check out the [Amazon Web Services documentation](https://docs.aws.amazon.com/neptune/latest/userguide/manage-console-launch.html).\n\nWhen 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 follow [this guide](https://github.com/aws/graph-notebook/tree/main/additional-databases/neptune).\n\nIn addition to the above configuration options, you can also specify the following options:\n\n### Amazon Neptune Proxy Connection\n\n``` python\n%%graph_notebook_config\n{\n \"host\": \"clustername.cluster-ididididid.us-east-1.neptune.amazonaws.com\",\n \"neptune_service\": \"neptune-db\",\n \"port\": 8182,\n \"ssl\": true,\n \"proxy_port\": 8182,\n \"proxy_host\": \"host.proxy.com\",\n \"auth_mode\": \"IAM\",\n \"aws_region\": \"us-east-1\",\n \"load_from_s3_arn\": \"\"\n}\n```\n\nSee also: Connecting to Amazon Neptune from clients outside the Neptune VPC using AWS Network [Load Balancer](https://aws-samples.github.io/aws-dbs-refarch-graph/src/connecting-using-a-load-balancer/#connecting-to-amazon-neptune-from-clients-outside-the-neptune-vpc-using-aws-network-load-balancer)\n\n## Authentication (Amazon Neptune)\n\nIf you are running a SigV4 authenticated endpoint, ensure that your configuration has `auth_mode` set to `IAM`:\n\n``` python\n%%graph_notebook_config\n{\n \"host\": \"your-neptune-endpoint\",\n \"neptune_service\": \"neptune-db\",\n \"port\": 8182,\n \"auth_mode\": \"IAM\",\n \"load_from_s3_arn\": \"\",\n \"ssl\": true,\n \"ssl_verify\": true,\n \"aws_region\": \"your-neptune-region\"\n}\n```\n\nAdditionally, you should have the following Amazon Web Services credentials available in a location accessible to Boto3:\n\n* Access Key ID\n* Secret Access Key\n* Default Region\n* Session Token (OPTIONAL. Use if you are using temporary credentials)\n\nThese variables must follow a specific naming convention, as listed in the [Boto3 documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html#using-environment-variables)\n\nA list of all locations checked for Amazon Web Services credentials can also be found [here](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html#configuring-credentials).\n\n### Neo4J\n\nChange the configuration using `%%graph_notebook_config` and modify the fields for `host`, `port`, `ssl`, and `neo4j` authentication.\n\nIf your Neo4J instance supports [multiple databases](https://neo4j.com/developer/manage-multiple-databases/), you can specify a database name via the `database` field. Otherwise, leave the `database` field blank to query the default database.\n\nFor a local Neo4j Desktop database, you can use the following command:\n\n``` python\n%%graph_notebook_config\n{\n \"host\": \"localhost\",\n \"port\": 7687,\n \"ssl\": false,\n \"neo4j\": {\n \"username\": \"neo4j\",\n \"password\": \"password\",\n \"auth\": true,\n \"database\": \"\"\n }\n}\n```\n\nEnsure that you also specify the `%%oc bolt` option when submitting queries to the Bolt endpoint.\n\nTo setup a new local Neo4J Desktop database for use with the graph notebook, check out the [Neo4J Desktop User Interface Guide](https://neo4j.com/developer/neo4j-desktop/).\n\n## Building From Source\n\nA pre-release distribution can be built from the graph-notebook repository via the following steps:\n\n``` bash\n# 1) Clone the repository and navigate into the clone directory\ngit clone https://github.com/aws/graph-notebook.git\ncd graph-notebook\n\n# 2) Create a new virtual environment\n\n# 2a) Option 1 - pyenv\npyenv install 3.10.13 # Only if not already installed; this can be any supported Python 3 version in Prerequisites\npyenv virtualenv 3.10.13 build-graph-notebook\npyenv local build-graph-notebook\n\n# 2b) Option 2 - venv\nrm -rf /tmp/venv\npython3 -m venv /tmp/venv\nsource /tmp/venv/bin/activate\n\n# 3) Install build dependencies\npip install --upgrade pip setuptools wheel twine\npip install \"jupyterlab>=3,<4\"\n\n# 4) Build the distribution\npython3 setup.py bdist_wheel\n```\n\nYou should now be able to find the built distribution at\n\n`./dist/graph_notebook-4.1.0-py3-none-any.whl`\n\nAnd use it by following the [installation](https://github.com/aws/graph-notebook#installation) steps, replacing\n\n``` python\npip install graph-notebook\n```\n\nwith\n\n``` python\npip install ./dist/graph_notebook-4.1.0-py3-none-any.whl\n```\n\n## Contributing Guidelines\n\nSee [CONTRIBUTING](https://github.com/aws/graph-notebook/blob/main/CONTRIBUTING.md) for more information.\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n",
"bugtrack_url": null,
"license": "",
"summary": "jupyter notebook extension to connect to graph databases",
"version": "4.1.0",
"project_urls": {
"Homepage": "https://github.com/aws/graph-notebook"
},
"split_keywords": [
"jupyter",
"neptune",
"gremlin",
"sparql"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a2418319190fd929fa2a48f41b71161db3f3abe5e47d11be496b5c407bf09924",
"md5": "2205b2dafb319e8651e8cb913a99f9ab",
"sha256": "292f2f114c832582808de98638d62b74615df152d7b03e425a57cc9684ff0816"
},
"downloads": -1,
"filename": "graph_notebook-4.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2205b2dafb319e8651e8cb913a99f9ab",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 18714227,
"upload_time": "2024-02-02T00:41:53",
"upload_time_iso_8601": "2024-02-02T00:41:53.682077Z",
"url": "https://files.pythonhosted.org/packages/a2/41/8319190fd929fa2a48f41b71161db3f3abe5e47d11be496b5c407bf09924/graph_notebook-4.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1c41145e7ad4e34a95b39fc0dc45bdc79a1e225792f51fd09687784657bc8742",
"md5": "cecc51f4c7c06a0fc18aafef6a984932",
"sha256": "79100be7b3bad2ee1f09bac861a4f336335ea4fbeea72f94d02457428a27fb11"
},
"downloads": -1,
"filename": "graph-notebook-4.1.0.tar.gz",
"has_sig": false,
"md5_digest": "cecc51f4c7c06a0fc18aafef6a984932",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 20759157,
"upload_time": "2024-02-02T00:42:00",
"upload_time_iso_8601": "2024-02-02T00:42:00.618975Z",
"url": "https://files.pythonhosted.org/packages/1c/41/145e7ad4e34a95b39fc0dc45bdc79a1e225792f51fd09687784657bc8742/graph-notebook-4.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-02 00:42:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aws",
"github_project": "graph-notebook",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "SPARQLWrapper",
"specs": [
[
"==",
"1.8.4"
]
]
},
{
"name": "networkx",
"specs": [
[
"==",
"2.4"
]
]
},
{
"name": "Jinja2",
"specs": [
[
"<=",
"3.1.3"
],
[
">=",
"3.0.3"
]
]
},
{
"name": "jupyter",
"specs": [
[
"==",
"1.0.0"
]
]
},
{
"name": "notebook",
"specs": [
[
"<",
"7.0.0"
],
[
">=",
"6.1.5"
]
]
},
{
"name": "ipywidgets",
"specs": [
[
"==",
"7.7.2"
]
]
},
{
"name": "jupyterlab_widgets",
"specs": [
[
"<",
"3.0.0"
],
[
">=",
"1.0.0"
]
]
},
{
"name": "nbclient",
"specs": [
[
"<=",
"0.7.0"
]
]
},
{
"name": "jupyter-contrib-nbextensions",
"specs": [
[
"<=",
"0.7.0"
]
]
},
{
"name": "widgetsnbextension",
"specs": [
[
"<=",
"3.6.1"
]
]
},
{
"name": "gremlinpython",
"specs": [
[
"<=",
"3.6.2"
],
[
">=",
"3.5.1"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.27.0"
],
[
"<=",
"2.31.0"
]
]
},
{
"name": "ipython",
"specs": [
[
">=",
"7.16.1"
],
[
"<=",
"8.10.0"
]
]
},
{
"name": "ipykernel",
"specs": [
[
"==",
"5.3.4"
]
]
},
{
"name": "ipyfilechooser",
"specs": [
[
"==",
"0.6.0"
]
]
},
{
"name": "neo4j",
"specs": [
[
">=",
"4.4.9"
],
[
"<",
"5.0.0"
]
]
},
{
"name": "rdflib",
"specs": [
[
"==",
"5.0.0"
]
]
},
{
"name": "setuptools",
"specs": [
[
">=",
"65.5.1"
],
[
"<=",
"66.0.0"
]
]
},
{
"name": "nbconvert",
"specs": [
[
">=",
"6.3.0"
],
[
"<=",
"7.2.8"
]
]
},
{
"name": "jedi",
"specs": [
[
">=",
"0.18.1"
],
[
"<=",
"0.18.2"
]
]
},
{
"name": "markupsafe",
"specs": [
[
"<",
"2.1.0"
]
]
},
{
"name": "itables",
"specs": [
[
"!=",
"1.4.3"
],
[
"!=",
"1.4.4"
],
[
"<=",
"1.5.2"
],
[
">=",
"1.0.0"
]
]
},
{
"name": "pandas",
"specs": [
[
"<=",
"1.5.3"
],
[
">=",
"1.3.5"
]
]
},
{
"name": "numpy",
"specs": [
[
"<",
"1.24.0"
]
]
},
{
"name": "nest_asyncio",
"specs": [
[
"<=",
"1.5.6"
],
[
">=",
"1.5.5"
]
]
},
{
"name": "botocore",
"specs": [
[
"~=",
"1.21.49"
]
]
},
{
"name": "boto3",
"specs": [
[
"~=",
"1.18.49"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"6.2.5"
]
]
},
{
"name": "parameterized",
"specs": [
[
"==",
"0.8.1"
]
]
}
],
"lcname": "graph-notebook"
}
JSON
