Amazon Neptune utility for GraphQL - Amazon Neptune

Amazon Neptune utility for GraphQL

The Amazon Neptune utility for GraphQL is an open-source Node.js command-line tool that can help you create and maintain a GraphQL API for a Neptune property-graph database (it does not yet work with RDF data). It is a no-code way to create a GraphQL resolver for GraphQL queries that have a variable number of input parameters and return a variable number of nested fields.

It has been released as an open-source project located at

You can install the utility using NPM like this (see Installation and Setup for details):

npm i @aws/neptune-for-graphql -g

The utility can discover the graph schema of an existing Neptune property graph, including nodes, edges, properties, and edge cardinality. It then generates a GraphQL schema with the directives needed to map the GraphQL types to the nodes and edges the database, and auto-generates resolver code. The resolver code is designed to minimize latency by returning only the data requested by the GraphQL query.

You can also start with an existing GraphQL schema and an empty Neptune database, and let the utility infer the directives needed to map that GraphQL schema to the nodes and edges of data to be loaded into the database. Or, you can start with a GraphQL schema and directives that you've already created or modified.

The utility is capable of creating all the AWS resources it needs for its pipeline, including the AWS AppSync API, the IAM roles, the data source, schema, and resolver, and the AWS Lambda function that queries Neptune.


Command-line examples here assume a Linux console. If you are using Windows, replace the backslashes ('\') at the end of lines with carets ('^').

Installing and setting up the Amazon Neptune utility for GraphQL

If you're going to use the utility with an existing Neptune database, you need it to be able to connect to the database endpoint. By default, a Neptune database is accessible only from within the VPC where it is located.

Because the utility is a Node.js command-line tool, you must have Node.js (version 18 or above) installed for the utility to run. To install Node.js on an EC2 instance in the same VPC as your Neptune database, follow the instructions here. The minimum size instance to run the utility is t2.micro. During the creation of the instance select the Neptune database VPC from the Common Security Groups pulldown menu.

However, starting with engine version, you can create a public endpoint for your Neptune database that is accessible outside the VPC. If you have created a public endpoint, you can install Node.js and the utility on your local machine. To install Node.js on macOS or Windows, visit the Node.js website to download the installer.

To install the utility itself on an EC2 instance or your local machine, use NPM:

npm install aws-neptune-for-graphql -g

You can then run the utility's help command to check whether it installed properly:

neptune-for-graphql --help

You may also want to install the AWS CLI to manage AWS resources.