From 76cf41a99c38b00f764e661deae7b2d603a212d7 Mon Sep 17 00:00:00 2001 From: steffyP Date: Wed, 13 Sep 2023 12:01:26 +0200 Subject: [PATCH] update neptune docs (#819) Co-authored-by: HarshCasper --- content/en/user-guide/aws/neptune/index.md | 132 ++++++++++++++++++--- 1 file changed, 113 insertions(+), 19 deletions(-) diff --git a/content/en/user-guide/aws/neptune/index.md b/content/en/user-guide/aws/neptune/index.md index 09a313b1e5..b1cc759da7 100644 --- a/content/en/user-guide/aws/neptune/index.md +++ b/content/en/user-guide/aws/neptune/index.md @@ -1,30 +1,124 @@ --- title: "Neptune" linkTitle: "Neptune" -categories: ["LocalStack Pro"] description: > - Get started with Amazon Neptune on LocalStack -aliases: - - /aws/neptune/ + Get started with Neptune on LocalStack --- -The Neptune API provides a graph database to store nodes and edges that can be accessed via Apache TinkerPop and Gremlin queries. +## Introduction -For example, you can create a Neptune cluster like this: -```python -import boto3 -from gremlin_python.driver import client as gremlin_client -client = boto3.client('neptune', endpoint_url='http://localhost:4566') -cluster = client.create_db_cluster(DBClusterIdentifier='c1', Engine='neptune')['DBCluster'] -cluster_url = 'ws://localhost:%s/gremlin' % cluster['Port'] -graph_client = gremlin_client.Client(cluster_url, 'g') +Neptune is a fully managed, highly available, and scalable graph database service offered by AWS. +It is designed for storing and querying highly connected data for applications that require complex relationship modeling, such as social networks, recommendation engines, and fraud detection. +Neptune supports popular graph query languages like Gremlin and SPARQL, making it compatible with a wide range of graph applications and tools. + +LocalStack supports Neptune via the Pro/Team offering, allowing you to use the Neptune APIs in your local environment to support both property graph and RDF graph models. +The supported APIs are available on our [API coverage page](https://docs.localstack.cloud/references/coverage/coverage_neptune/), which provides information on the extent of Neptune's integration with LocalStack. + +## Getting started + +This guide is designed for users new to Neptune and assumes basic knowledge of the AWS CLI and our `awslocal` wrapper script. + +Start your LocalStack container using your preferred method. We will demonstrate the following with AWS CLI & Python: + +- Creating a Neptune cluster. +- Starting a connection to the Neptune cluster. +- Running a Python script to create nodes and edges and query the graph database. + +### Create a Neptune cluster + +To create a Neptune cluster you can use the [`CreateDBCluster`](https://docs.aws.amazon.com/neptune/latest/APIReference/API_CreateDBCluster.html) API. +Run the following command to create a Neptune cluster: + +{{< command >}} +$ awslocal neptune create-db-cluster \ + --engine neptune \ + --db-cluster-identifier my-neptune-db +{{< / command >}} + +You should see the following output: + +```json +{ + "DBCluster": { + ... + "Endpoint": "localhost:4510", + "Port": 4510, # may vary + "DBClusterArn": "arn:aws:rds:us-east-1:000000000000:cluster:my-neptune-db", + ... + } +} ``` -... and then submit and query values to the DB like this: + +### Add an instance to the cluster + +To add an instance you can use the [`CreateDBInstance`](https://docs.aws.amazon.com/neptune/latest/APIReference/API_CreateDBInstance.html) API. +Run the following command to create a Neptune instance: + +{{< command >}} +$ awslocal neptune create-db-instance \ + --db-cluster-identifier my-neptune-db \ + --db-instance-identifier my-neptune-instance \ + --engine neptune \ + --db-instance-class db.t3.medium +{{< / command >}} + +In LocalStack the `Endpoint` for the `DBCluster` and the `Endpoint.Address` of the `DBInstance` will be the same and can be used to connect to the graph database. + +### Start a connection + +To start a connection you have to use the `ws` protocol. + +Here is an example that uses Python and [`gremlinpython`](https://pypi.org/project/gremlinpython/) to connect to the database: + ```python -values = '[1,2,3,4]' -result_set = graph_client.submit(values) -results = result_set.all().result() -assert results == [1, 2, 3, 4] +from gremlin_python.driver.driver_remote_connection import DriverRemoteConnection +from gremlin_python.process.anonymous_traversal import traversal +from gremlin_python.process.traversal import Bindings, T, gt + +ENDPOINT = "localhost:4510" # TODO change to your endpoint +DATABASE_URL = f"ws://{ENDPOINT}/gremlin" + + +if __name__ == '__main__': + conn = DriverRemoteConnection( + DATABASE_URL, + "g", + pool_size=1, + ) + + g = traversal().withRemote(conn) + + # add some nodes + v1 = g.addV("person").property(T.id, "1").property("name", "marko").property("age", 29).next() + v2 = g.addV("person").property(T.id, "2").property("name", "stephen").property("age", 33).next() + v3 = g.addV("person").property(T.id, "3").property("name", "mia").property("age", 30).next() + + # add edges/relation + g.V(Bindings.of("id", v1)).addE("knows").to(v2).property("weight", 0.75).iterate() + g.V(Bindings.of("id", v1)).addE("knows").to(v3).property("weight", 0.85).iterate() + + # retrieve all names + names = g.V().values("name").to_list() + + # list all names of persons that know "marko" + marko_knows = g.V("1").outE("knows").inV().values("name").order().to_list() + + # all persons that "marko" know that are older than 30 + marko_knows_older_30 = g.V("1").out("knows").has("age", gt(30)).values("name").to_list() + + # reset everything + g.V().drop().iterate() + + result = { + "names": names, + "marko_knows": marko_knows, + "marko_knows_older_30": marko_knows_older_30, + } + print(result) ``` -For a simple Neptune sample running on LocalStack, please refer to [this Github repository](https://github.com/localstack/localstack-pro-samples/tree/master/neptune-graph-db). +## Examples + +The following code snippets and sample applications provide practical examples of how to use Neptune in LocalStack for various use cases: + +- [Neptune Graph Database Demo](hhttps://github.com/localstack/localstack-pro-samples/tree/master/neptune-graph-db)