# Using notebooks with Neptune Analytics
Using notebooks

The Neptune managed open-source [graph-notebook project](https://github.com/aws/graph-notebook) provides a plethora of [Jupyter](https://jupyter.org/) extensions and sample notebooks that make it easy to interact with and learn to use a Neptune Analytics graph.

These graph notebooks support a suite of intuitive Jupyter line- and cell-magic commands. The magic commands abstract away much of the initial setup typically required for using Neptune Analytics, and take care of SigV4 signing of requests. They can create graph connections, load data, run openCypher queries, and interact with various Neptune Analytics APIs.

You can find a list of the full set of Neptune graph-notebook magics and their options [in the Neptune Userguide](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html). However, only the following magics are compatible with Neptune Analytics graphs:
+ [%seed](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-line-magics-seed)   (adds sample data to a graph).
+ [%load](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-line-magics-load)   (uses the [`neptune-load()`](batch-load.md) openCypher integration to let you batch-load data).
+ [%status](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-line-magics-status) or [ %get\$1graph](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-line-magics-get-graph)   (gets status information about the graph).
+ [%%opencypher or %%oc](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-cell-magics-opencypher)   (issues an openCypher query).
+ [%opencypher\$1status, or %oc\$1status](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-line-magics-opencypher-status)   (retrieves query status for, or cancels, an openCypher query).
+ [%%graph\$1notebook\$1config](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-cell-magics-graph-notebook-config)   (displays a JSON object containing the configuration that the notebook is using).
+ [%graph\$1notebook\$1host](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-line-magics-graph-notebook-host)   (sets the line input as the notebook's host).
+ [%graph\$1notebook\$1version](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-line-magics-graph-notebook-version)   (returns the Neptune workbench notebook release number).
+ [%graph\$1notebook\$1service](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-line-magics-graph-notebook-service)   (sets the line input as the Neptune service name to use).
+ [%%graph\$1notebook\$1vis\$1options](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-cell-magics-graph-notebook-vis-options)   (lets you set visualization options for the notebook).
+ [%summary](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-line-magics-summary)   (retrieves graph summary information).
+ [%graph\$1reset](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-line-magics-reset-graph)   (empties the data from a graph).

You can use a Neptune graph notebook to generate an interactive visualization of the results returned from an openCypher query, and use options to customize the appearance of the visualized graph (see [Graph visualization in the Neptune workbench](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-visualization.html)).

## Take advantage of all the sample notebooks
Sample notebooks

A wide variety of sample Jupyter notebooks are available in the Neptune [graph-notebook project](https://github.com/aws/graph-notebook). Some of these are purpose-built for learning how to get the most of a Neptune Analytics graph and its powerful built-in algorithms in the context of common real-world applications.

After installing the graph-notebook project either locally or on SageMaker AI, you should be able to find sample notebooks under the notebook directory, `../Neptune/02-Neptune-Analytics`.

# Creating a new Neptune Analytics notebook using a CloudFormation template
Create a notebook with CloudFormation

[Amazon SageMaker AI Notebook instances](https://docs.aws.amazon.com/sagemaker/latest/dg/nbi.html) provide a fully managed Jupyter environment for running graph notebooks that are connected to a Neptune Analytics graph. SageMaker AI Notebooks run natively on Amazon Linux 2, and support use of the Jupyter Classic Notebook or JupyterLab 3 interface on the same instance.

You can use one of the following CloudFormation templates to set up a new Neptune Analytics notebook to use with your Neptune Analytics graph:

**To use an CloudFormation stack to create a new Neptune Analytics notebook**

1. Choose one of the **Launch Stack** buttons in the following table to launch the CloudFormation stack on the CloudFormation console.    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/neptune-analytics/latest/userguide/create-notebook-cfn.html)

1.  On the **Select Template** page, choose **Next**.

1. In the **Stack Details** page, under **GraphEndpoint**, enter the public or private endpoint of your Neptune Analytics graph.

1. Under **Notebook Name** enter a name for the new notebook that is unique for your account and region in SageMaker AI.

1. On the **Options** page, choose **Next**.

1. If you're using a private endpoint for your Neptune Analytics graph, enter the following under **Network Options**:

   1. Under **GraphVPC** enter the ID of a VPC associated with the private graph endpoint.

   1. Under **GraphSubnetId** enter the ID of any subnet associated with your private graph endpoint.

   1. Under **GraphSecurityGroup** enter the ID of a security group associated with the VPC. This is optional; if not provided, a new security group is automatically created for this purpose.

1. Click through the rest of the stack creation steps, leaving everything as default, and submit for creation.

In around 5 minutes, you should see the new Neptune Analytics notebook appear in the SageMaker AI and Neptune consoles.

# Creating a new Neptune Analytics notebook using the AWS Management Console
Create a notebook on the console

You can create a new notebook for Neptune Analytics by following the instructions mentioned in [ Using the Neptune workbench to host Neptune notebooks](https://docs.aws.amazon.com//neptune/latest/userguide/graph-notebooks.html#graph-notebooks-workbench) with a few changes: 
+  While selecting the Neptune service, please choose **Analytics**. 
+  The console can create an AWS AWS Identity and Access Management role for your notebooks, or you can create one yourself by following [ Create an IAM role for a Neptune Analytics notebook](https://docs.aws.amazon.com//neptune-analytics/latest/userguide/create-notebook-console.html#create-notebook-iam-role). 

## Create an IAM role for a Neptune Analytics notebook
Create an IAM role

**To create an IAM role for a Neptune Analytics notebook**

1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

1. In the navigation pane, expand **Access management**, then choose **Roles**.

1. Select **Create role**.

1. Under **Trusted entity type**, select **Custom trust policy** and copy in the following trust policy:

------
#### [ JSON ]

****  

   ```
   {
     "Version":"2012-10-17",		 	 	 
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "Service": "sagemaker.amazonaws.com"
         },
         "Action": "sts:AssumeRole"
       }
     ]
   }
   ```

------

1. Choose **Next**, and then **Next** again.

1. Enter a name and description for the role, and select **Create role**.

1. Go back to the **Roles** page, search for the name of the role you just created, and open it. 

1. On the **Permissions** tab Under **Permissions policies**, select **Add permissions** and choose **Create inline policy**.

1. In the **Policy editor**, switch to the **JSON** option, and copy in the following policy:

------
#### [ JSON ]

****  

   ```
   {
     "Version":"2012-10-17",		 	 	 
     "Statement": [
       {
         "Sid": "AllowS3",
         "Effect": "Allow",
         "Action": [
           "s3:GetObject",
           "s3:ListBucket"
         ],
         "Resource": [
           "arn:aws:s3:::aws-neptune-notebook-us-east-1",
           "arn:aws:s3:::aws-neptune-notebook-us-east-1/*",
           "arn:aws:s3:::aws-neptune-customer-samples-us-east-1",
           "arn:aws:s3:::aws-neptune-customer-samples-us-east-1/*"
         ]
       },
       {
         "Sid": "AllowNeptuneGraph",
         "Effect": "Allow",
         "Action": "neptune-graph:*",
         "Resource": [
           "arn:aws:neptune-graph:us-east-1:111122223333:graph/resource-id"
         ]
       },
       {
         "Sid": "AllowLogs",
         "Effect": "Allow",
         "Action": [
           "logs:CreateLogGroup",
           "logs:CreateLogStream",
           "logs:PutLogEvents"
         ],
         "Resource": [
           "arn:aws:logs:*:*:log-group:/aws/sagemaker/*"
         ]
       },
       {
         "Sid": "AllowSagemaker",
         "Effect": "Allow",
         "Action": "sagemaker:DescribeNotebookInstance",
         "Resource": [
           "arn:aws:sagemaker:us-east-1:111122223333:notebook-instance/*"
         ]
       }
     ]
   }
   ```

------

1. Choose **Next**.

1. Give a name to the inline policy.

1. Select **Create policy**. Make note of the name of the policy you just created.

# Hosting a Neptune Analytics graph-notebook on your local machine
Local hosting

It is also possible to install and run a Neptune Analytics graph notebook on your local machine. You can find instructions in the [GitHub graph-notebook repository](https://github.com/aws/graph-notebook):
+ [Prerequisites](https://github.com/aws/graph-notebook/#prerequisites)
+ [Jupyter Classic Notebook](https://github.com/aws/graph-notebook/#installation) or [https://github.com/aws/graph-notebook/#jupyterlab-3x](https://github.com/aws/graph-notebook/#jupyterlab-3x) installation
+ [Connecting to Neptune ](https://github.com/aws/graph-notebook/#amazon-neptune)

When setting up for Neptune Analytics:
+ When setting the connection using [%%graph\$1notebook\$1config](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-cell-magics-graph-notebook-config), make sure to set the `neptune_service` field to the value `neptune-graph`. 
+ If you're connecting to a private graph endpoint, you need to enable access to the VPC where the Neptune Analytics instance resides. The easiest way to set this is up is using an SSH tunnel to a proxy EC2 instance in the VPC. For more information, see [Connecting graph notebook locally to Amazon Neptune](https://github.com/aws/graph-notebook/blob/main/additional-databases/neptune/README.md#connecting-graph-notebook-locally-to-amazon-neptune-first-time-setup) in GitHub.
+ If you're using a public graph endpoint, no additional connectivity setup is required.