{"id":15710242,"url":"https://github.com/aws/amazon-neptune-for-graphql","last_synced_at":"2025-10-08T07:37:43.072Z","repository":{"id":202828488,"uuid":"687774198","full_name":"aws/amazon-neptune-for-graphql","owner":"aws","description":"Amazon Neptune utility for GraphQL™ schemas and resolvers","archived":false,"fork":false,"pushed_at":"2025-03-03T20:51:13.000Z","size":12186,"stargazers_count":18,"open_issues_count":15,"forks_count":5,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-03-07T00:59:33.746Z","etag":null,"topics":["aws","aws-neptune","graphql"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-06T01:27:09.000Z","updated_at":"2025-03-03T20:51:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"8f232e19-a65f-4170-b066-5ec8282e714a","html_url":"https://github.com/aws/amazon-neptune-for-graphql","commit_stats":{"total_commits":69,"total_committers":8,"mean_commits":8.625,"dds":0.4057971014492754,"last_synced_commit":"cccc3709d0f1bfd11b9e46f1f6a76930397ebb91"},"previous_names":["aws/amazon-neptune-for-graphql"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Famazon-neptune-for-graphql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Famazon-neptune-for-graphql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Famazon-neptune-for-graphql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Famazon-neptune-for-graphql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws","download_url":"https://codeload.github.com/aws/amazon-neptune-for-graphql/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243806032,"owners_count":20350773,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-neptune","graphql"],"created_at":"2024-10-03T21:05:04.017Z","updated_at":"2025-10-08T07:37:43.066Z","avatar_url":"https://github.com/aws.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cbr\u003e\n\u003cimg src=\"https://github.com/aws/amazon-neptune-for-graphql/blob/main/doc/images/utilityRunning.gif\" width=\"180\" height=\"100\"\u003e\n\n# **Amazon Neptune utility for GraphQL\u0026trade; schemas and resolvers - v2.0.0**\n\nThe Amazon Neptune utility for GraphQL\u0026trade; is a Node.js command-line utility\nto help with the creation and maintenance of a GraphQL API for the Amazon\nNeptune Database or Neptune Analytics graph. It is a no-code solution for a\nGraphQL resolver when GraphQL queries have a variable number of input parameters\nand return a variable number of nested fields.\n\nIf you **start from a Neptune database with data**, the utility discovers the\ngraph database schema including nodes, edges, properties and edges cardinality.\nThis database schema is then used to generate the GraphQL schema with the\ndirectives required to map the GraphQL types to the graph databases nodes and\nedges, and auto-generate the resolver code. We optimized the resolver code to\nreduce the latency of querying Amazon Neptune by returning only the data\nrequested by the GraphQL query.\n\n\u003e [!NOTE]\n\u003e\n\u003e This utility works for Property Graph databases only. Support for RDF has not\n\u003e yet been added.\n\nYou can also **start with a GraphQL schema with your types and an empty Neptune\ndatabase**. The utility will process your starting GraphQL schema and inference\nthe directives required to map it to the Neptune database graph nodes and edges.\nYou can also **start with a GraphQL schema with the directives**, that you have\nmodified or created.\n\nThe utility has the option to **generate the AWS resources** of the entire\npipeline, including the AWS AppSync API, configuring the roles, data source,\nschema and resolver, and the AWS Lambda that queries Amazon Neptune.\n\nAlternatively, you can also **generate Apollo Server artifacts** through the utility\nas a self-hosted solution that includes a standalone Node.js application with \nall dependencies, resolvers, and Neptune connectivity pre-configured to \nquery Amazon Neptune.\n\nIf you have a **few queries** with a static number of input parameters and\nreturn fields, and you are willing to code your GraphQL resolver, look at these\nblogs:\n\n- [Building Serverless Calorie tracker application with AWS AppSync and Amazon Neptune](https://github.com/aws-samples/aws-appsync-calorie-tracker-workshop)\n- [Integrating alternative data sources with AWS AppSync: Amazon Neptune and Amazon ElastiCache](https://aws.amazon.com/blogs/mobile/integrating-aws-appsync-neptune-elasticache/)\n\n\u003cbr\u003e\n\nIndex:\n\n- [Install and Setup](#install-and-setup)\n- [Starting from a Neptune database with data](#starting-from-a-neptune-database-with-data)\n- [Starting from a Neptune database with data: Air Routes Example](https://github.com/aws/amazon-neptune-for-graphql/blob/main/doc/routesExample.md)\n- [Starting from a GraphQL schema and an empty Neptune database](#starting-from-a-graphql-schema-and-an-empty-neptune-database)\n- [Starting from a GraphQL schema and an empty Neptune database: Todo Example](https://github.com/aws/amazon-neptune-for-graphql/blob/main/doc/todoExample.md)\n- [Starting from GraphQL schema with directives](#starting-from-a-graphql-schema-with-directives)\n- [Customize the GraphQL schema with directives](#customize-the-graphql-schema-with-directives)\n- [AWS resources for the GraphQL API](#aws-resources-for-the-graphql-api)\n- [Generate Apollo Server Artifacts](#generate-apollo-server-artifacts)\n- [Commands reference: utility CLI options](https://github.com/aws/amazon-neptune-for-graphql/blob/main/doc/cliReference.md)\n- [Known Limitations](#known-limitations)\n- [Roadmap](#roadmap)\n- [License](#license)\n- [Contributing](#contributing)\n\n\u003cbr\u003e\n\n# Install and Setup\n\nThe utility requires Node.js to be executed. Some features require reaching to a\nNeptune database, and having access to the AWS CLI with permissions to create\nAWS resources. You can also run the utility just to process input files without\nthe need to connect it directly to a Neptune database or to create AWS\nresources. In this case you will find the GraphQL schemas and the resolver code\nin the local *output* directory.\n\n### Node.js is required in any scenario\n\nNode.js is required to run the utility, v18 or above.\n\n- To install it on macOS or Windows go to\n  the [Node.js website](https://nodejs.org/) to download the installer.\n- To install on an EC2-Instance follow\n  the [AWS documentation](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-up-node-on-ec2-instance.html).\n\n### Install the Amazon Neptune utility for GraphQL\n\nThe utility is available as NPM package. To install it:\n\n`npm install @aws/neptune-for-graphql -g`\n\nAfter the installation run the utility `--help`` command to check if runs:\n\n`neptune-for-graphql --help`\n\n### Reach to a Neptune database endpoint\n\nIf you are starting from a Neptune database with data, you need to enable the\nutility to reach the database endpoint. By default Neptune databases are\naccessible only within a VPC.\n\nThe easiet way is to run the utility from an EC2 instance which network is\nconfigured within your Neptune database VPC. The minimum size instance to run\nthe utility is ***t2.micro*** (free of charge). During the creation of the\ninstance select the Neptune database VPC using the *Common Security Groups*\npulldown menu.\n\n#### Next Step\n\n- Install Node.js.\n- [Install AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)\n  if you need to create the AWS resources, or you need an IAM role to access the\n  Neptune database.\n\n\u003cbr\u003e\n\n# Starting from a Neptune database with data\n\nIndependently if you are familiar with GraphQL or not, the command below is the\nfastest way to create a GraphQL API. Starting from an existing Neptune database\nendpoint, the utility scans the Neptune database discovering the schema of the\nexisting nodes, edges and properties. Based on the graph database schema, it\ninferences a GraphQL schema, queries and mutations. Then, it creates an AppSync\nGraphQL API, and the required AWS resources, like a pair of IAM roles and a\nLambda function with the GraphQL resolver code. As soon as the utility complete\nthe execution, you will find in the AppSync console your new GraphQL API called\n*your-new-GraphQL-API-name*API. To test it, use the AppSync “Queries” from the\nmenu. (*Note: follow the setup instructions below to enable your environment to\nreach the Neptune database and create AWS resources.*)\n\n```\nneptune-for-graphql \\\n  --input-graphdb-schema-neptune-endpoint \u003cyour-neptune-database-endpoint:port\u003e \\\n  --create-update-aws-pipeline \\\n  --create-update-aws-pipeline-name \u003cyour-new-GraphQL-API-name\u003e \\\n  --output-resolver-query-https \\\n```\n\nIf you run the command above a second time, it will look again at the Neptune\ndatabase data and update the AppSync API and the Lambda code.\n\nTo rollback, removing all the AWS resources run:\n\n```\nneptune-for-graphql --remove-aws-pipeline-name \u003cyour-new-GraphQL-API-name\u003e\n```\n\n#### References:\n\n- [Here](/doc/routesExample.md) is an example using the Air Routes data on\n  Amazon Neptune, showing the outputs of the utility.\n- If you are wondering which AWS resources the utility is creating, look at the\n  section below.\n- To customize the GraphQL schema, look at the section below.\n\n\u003cbr\u003e\n\n# Starting from a GraphQL schema and an empty Neptune database\n\nYou can start from an empty Neptune database and use a GraphQL API to create the\ndata and query it. Running the command below, the utility will automate the\ncreation of the AWS resources. Your *your-graphql-schema-file* must include the\nGraphQL schema types, like in the [TODO example](/doc/todoExample.md). The\nutility will analyze your schema and create an extended version based on your\ntypes. It will add queries and mutations for the nodes stored in the graph\ndatabase, and in case your schema have nested types, it will add relationships\nbetween the types stored as edges in the graph database, again see\nthe [TODO example](/doc/todoExample.md). The utility creates an AppSync GraphQL\nAPI and the required AWS resources, like a pair of IAM roles and a Lambda\nfunction with the GraphQL resolver code. As soon as the utility completes the\nexecution, you will find in the AppSync console your new GraphQL API called\n*your-new-GraphQL-API-name*API. To test it, use the AppSync “Queries” from the\nmenu.\n\n\u003e [!TIP]\n\u003e\n\u003e Follow the setup instructions below to enable your environment to reach the\n\u003e Neptune database and create AWS resources.\n\n```\nneptune-for-graphql \\\n  --input-schema-file \u003cyour-graphql-schema-file\u003e \\\n  --create-update-aws-pipeline \\\n  --create-update-aws-pipeline-name \u003cyour-new-GraphQL-API-name\u003e \\\n  --create-update-aws-pipeline-neptune-endpoint \u003cyour-neptune-database-endpoint:port\u003e \\\n  --output-resolver-query-https\n```\n\n#### References:\n\n- [Here](https://github.com/aws/amazon-neptune-for-graphql/blob/main/doc/todoExample.md)\n  is an example using a TODO GraphQL schema, showing the outputs of the utility.\n- If you are wondering which AWS resources the utility is creating, look at the\n  section below.\n- To customize the GraphQL schema, look at the section below.\n\n\u003cbr\u003e\n\n# Starting from a GraphQL schema with directives\n\nYou can start from a GraphQL schema with directives for a graph database. For\nthe list of supported directives see the section\nbelow [Customize the GraphQL schema with directives](#customize-the-graphql-schema-with-directives).\n\n```\nneptune-for-graphql \\\n  --input-schema-file \u003cyour-graphql-schema-file-with-directives\u003e \\\n  --create-update-aws-pipeline \\\n  --create-update-aws-pipeline-name \u003cyour-new-GraphQL-API-name\u003e \\\n  --create-update-aws-pipeline-neptune-endpoint \u003cyour-neptune-database-endpoint:port\u003e \\\n  --output-resolver-query-https\n```\n\n\u003cbr\u003e\n\n# Customize the GraphQL schema with directives\n\nThe utility generates a GraphQL schema with directives, queries and mutations.\nYou might want to use it as is, or change it. Below are ways to change it.\n\n### Please no mutations in my schema\n\nIn case you don't want your Graph API having the option of updating your\ndatabase data, add the CLI option `--output-schema-no-mutations`.\n\n### @alias\n\nThis directive can be applied to GraphQL schema types or fields. It maps\ndifferent names between the graph database and the GraphQL schema. The syntax is\n*@alias(property: your-name)*. In the example below *airport* is the graph\ndatabase node label mapped to the *Airport* GraphQL type, and *desc* is the\nproperty of the graph database node mapped to the field *description*. See\nthe [Air Routes Example](https://github.com/aws/amazon-neptune-for-graphql/blob/main/doc/routesExample.md).\nThe GraphQL guidance is pascal case for types and camel case for fields.\n\n```graphql\ntype Airport @alias(property: \"airport\") {\n    city: String\n    description: String @alias(property: \"desc\")\n}\n```\n\n### @relationship\n\nThis directive maps nested GraphQL types to a graph databases edges. The syntax\nis *@relationship(edgeType: graphdb-edge-name, direction: IN|OUT)*.\n\u003cbr\u003e\nSee\nthe [Todo Example](https://github.com/aws/amazon-neptune-for-graphql/blob/main/doc/todoExample.md)\nand\nthe [Air Routes Example](https://github.com/aws/amazon-neptune-for-graphql/blob/main/doc/routesExample.md).\n\n```graphql\ntype Airport @alias(property: \"airport\") {\n  ...\n  continentContainsIn: Continent @relationship(edgeType: \"contains\", direction: IN)\n  countryContainsIn: Country @relationship(edgeType: \"contains\", direction: IN)\n  airportRoutesOut(filter: AirportInput, options: Options): [Airport] @relationship(edgeType: \"route\", direction: OUT)\n  airportRoutesIn(filter: AirportInput, options: Options): [Airport] @relationship(edgeType: \"route\", direction: IN)\n}\n```\n\n### @graphQuery, @cypher\n\nYou can define your openCypher queries to resolve a field value, add queries or\nmutations.\n\nHere a new field *outboundRoutesCount* is added to the type *Airport* to count\nthe outbound routes:\n\n```graphql\ntype Airport @alias(property: \"airport\") {\n    ...\n    outboundRoutesCount: Int @graphQuery(statement: \"MATCH (this)-[r:route]-\u003e(a) RETURN count(r)\")\n}\n```\n\nHere is an example of new queries and mutations. Note that if you omit the\n*RETURN*, the resolver will assume the keyword *this* is the returning scope.\n\n```graphql\ntype Query {\n    getAirportConnection(fromCode: String!, toCode: String!): Airport @cypher(statement: \"MATCH (:airport{code: '$fromCode'})-[:route]-\u003e(this:airport)-[:route]-\u003e(:airport{code:'$toCode'})\")\n}\n\ntype Mutation {\n    createAirport(input: AirportCreateInput!): Airport @graphQuery(statement: \"CREATE (this:airport {$input}) RETURN this\")\n    addRoute(fromAirportCode:String, toAirportCode:String, dist:Int): Route @graphQuery(statement: \"MATCH (from:airport{code:'$fromAirportCode'}), (to:airport{code:'$toAirportCode'}) CREATE (from)-[this:route{dist:$dist}]-\u003e(to) RETURN this\")\n}\n```\n\nYou can add a custom query to filter nodes based on a connected node's\nproperties. This is an example of a query which can retrieve airports that have\nroutes to a given country.\n\n```graphql\ntype Query {\n    getAirportsWithRoutesToCountry(country: String): [Airport] @graphQuery(statement: \"MATCH (getAirportsWithRoutesToCountry_Airport:`airport`)-[:route]-\u003e(toAirport:`airport` {country: '$country'}) WITH DISTINCT getAirportsWithRoutesToCountry_Airport\")\n}\n```\n\nWith this customized query, you can use a graphQL query to retrieve airports\nthat have routes to CA and the CA airport properties:\n\n```graphql\nquery GetAirportsWithRoutesToCountry {\n    getAirportsWithRoutesToCountry(country: \"CA\") {\n        city\n        code\n        country\n        airportRoutesOut(filter: {country: {eq: \"CA\"}}) {\n            city\n            code\n        }\n    }\n}\n```\n\nYou can add a query or mutation using a Gremlin query. At this time Gremlin\nqueries are limited to return *scalar* values, or *elementMap()* for a single\nnode, or *elementMap().fold()* for a list of nodes.\n\n```graphql\ntype Query {\n    getAirportWithGremlin(code:String): Airport @graphQuery(statement: \"g.V().has('airport', 'code', '$code').elementMap()\") # single node\n    getAirportsWithGremlin: [Airport] @graphQuery(statement: \"g.V().hasLabel('airport').elementMap().fold()\") # list of nodes\n    getCountriesCount: Int @graphQuery(statement: \"g.V().hasLabel('country').count()\")  # scalar example\n}\n```\n\n### @id\n\nThe directive @id identifies the field mapped to the graph database entity id.\nGraph databases like Amazon Neptune always have a unique id for nodes and edges\nassigned during bulk imports or autogenerated. In the example below _id\n\n```graphql\ntype Airport {\n    _id: ID! @id\n    city: String\n    code: String\n}\n```\n\n### Reserved types, queries and mutations names\n\nThe utility auto generates queries and mutations to enable you to have a working\nGraphQL API just after having ran the utility. The pattern of these names are\nrecognized by the resolver and are reserved. Here is an example for the type\n*Airport* and the connecting type *Route*:\n\nThe type *Options* is reserved.\n\n```graphql\ninput Options {\n    limit: Int\n}\n```\n\nThe function parameters *filter*, *options*, and *sort* are reserved.\n\n```graphql\ntype Query {\n    getAirports(filter: AirportInput, options: Options, sort: [AirportSort!]): [Airport]\n}\n```\n\nQueries and mutations are automatically generated with friendly names \nmatching the node \u0026 edge labels.\n\n```graphql\ntype Query {\n    getAirport(id: ID, filter: AirportInput): Airport\n    getAirports(filter: AirportInput, options: Options, sort: [AirportSort!]): [Airport]\n}\n\ntype Mutation {\n    createAirport(input: AirportCreateInput!): Airport\n    updateAirport(id: ID!, input: AirportUpdateInput!): Airport\n    deleteAirport(id: ID!): Boolean\n    connectAirportToAirportThroughRoute(from: ID!, to: ID!, edge: RouteInput!): Route\n    updateRouteConnectionFromAirportToAirport(from: ID!, to: ID!, edge: RouteInput!): Route\n    deleteRouteConnectionFromAirportToAirport(from: ID!, to: ID!): Boolean\n}\n```\n\n### Re-apply your changes with --input-schema-changes-file\n\nYou might want to modify the GraphQL source schema and run the utility again to\nget the latest schema from your Neptune database. Every time the utility\ndiscovers a new graphdb schema, it generates a new GraphQL schema. To inject\nyour changes, you can manually edit the GraphQL source schema and run the\nutility again, using it as input instead of the Neptune database endpoint, or\nwrite your changes in the format below. As you run the utility with the added\noption `--input-schema-changes-file \u003cyour-changes-file\u003e`, your changes will be\napplied at once.\n\n```json\n[\n  {\n    \"type\": \"graphQLTypeName\",\n    \"field\": \"graphQLFieldName\",\n    \"action\": \"remove|add\",\n    \"value\": \"value\"\n  }\n]\n```\n\nFor Example:\n\n```json\n[\n  {\n    \"type\": \"Airport\",\n    \"field\": \"outboundRoutesCountAdd\",\n    \"action\": \"add\",\n    \"value\": \"outboundRoutesCountAdd: Int @graphQuery(statement: \\\"MATCH (this)-[r:route]-\u003e(a) RETURN count(r)\\\")\"\n  },\n  {\n    \"type\": \"Query\",\n    \"field\": \"getAirportsWithRoutesToCountry\",\n    \"action\": \"add\",\n    \"value\": \"getAirportsWithRoutesToCountry(country:String): [Airport] @graphQuery(statement: \\\"MATCH (getAirportsWithRoutesToCountry_Airport:`airport`)-[:route]-\u003e(toAirport:`airport` {country: '$country'}) WITH DISTINCT getAirportsWithRoutesToCountry_Airport\\\")\"\n  },\n  {\n    \"type\": \"Mutation\",\n    \"field\": \"deleteVersion\",\n    \"action\": \"remove\",\n    \"value\": \"\"\n  },\n  {\n    \"type\": \"Mutation\",\n    \"field\": \"createVersion\",\n    \"action\": \"remove\",\n    \"value\": \"\"\n  }\n]\n```\n\n\u003cbr\u003e\n\n# AWS resources for the GraphQL API\n\nYou have three options to create the GraphQL API pipeline:\n\n- Let the utility create the AWS resources\n- Let the utility create a CDK file, then you run it\n- You manually create the AWS resources\n\nIndependently of the method you or the utility will need to create the following\nresources:\n\n- Create an IAM role for Lambda called LambdaExecutionRole\n- Attach to the LambdaExecutionRole the IAM policy AWSLambdaBasicExecutionRole\n- For VPC (default) attach to the LambdaExecutionRole the IAM policy\n  AWSLambdaVPCAccessExecutionRole\n- For IAM create and attach to the LambdaExecutionRole a new IAM policy that\n  only allow to connect and query Neptune\n- Create a Lambda function with the LambdaExecutionRole\n- Create an IAM for AppSync API to call the Lambda called LambdaInvocationRole\n- Attach to the LambdaInvocationRole the policy LambdaInvokePolicy\n- Create the AppSync GraphQL API\n- Add to the AppSync API a Function with the LambdaInvocationRole to call the\n  Lambda\n\n### Let the utility create the resources\n\nWith the CLI option `--create-update-aws-pipeline`, and its accessory\noptions ([see the commands reference](https://github.com/aws/amazon-neptune-for-graphql/blob/main/doc/cliReference.md)),\nthe utility automatically creates the resources.\u003cbr\u003e\nYou need to run the utility from a shell in which you installed the AWS CLI, and\nit is configured for a user with the permission of creating AWS resources. \u003cbr\u003e\nThe utility creates a file with the list of resources named\n*pipeline-name.resources.json*. Then it uses the file to modify the existing\nresources when the user runs the command again, or when the user wants to delete\nthe AWS resources with the command option `--remove-aws-pipeline-name \u003cvalue\u003e`.\nThe code of the utility uses the JavaScript AWS sdk v3, if you'd like to review\nthe code, it is only\nin [this file](https://github.com/aws/amazon-neptune-for-graphql/blob/main/src/pipelineResources.js).\n\n### I prefer a CDK file\n\nThe option to trigger the creation of the CDK file starts with\n`--output-aws-pipeline-cdk`, and its accessory\noptions ([see the commands reference](https://github.com/aws/amazon-neptune-for-graphql/blob/main/doc/cliReference.md)). \u003cbr\u003e\nAfter running, you will find in the *output* folder the file\n*CDK-pipeline-name-cdk.js* and *CDK-pipeline-name.zip*. The ZIP file is the code\nfor the Lambda function. See CDK end to end\nexample [here](https://github.com/aws/amazon-neptune-for-graphql/blob/main/doc/cdk.md).\n\n### Let me setup the resources manually or with my favorite DevOps toolchain\n\n[Here](https://github.com/aws/amazon-neptune-for-graphql/blob/main/doc/resources.md)\nis the detailed list of resources needed to configure the GraphQL API pipeline.\n\u003cbr\u003e\n\n# Generate Apollo Server Artifacts\n\nIf you prefer to use Apollo Server instead of AWS App Sync, the utility can\ngenerate a ZIP file of Apollo Server artifacts with the CLI option\n`--create-update-apollo-server` for a standalone server or\n`--create-update-apollo-server-subgraph` for federated systems.\n\nExample of starting with a neptune database with data from which to determine\nthe graphQL schema:\n\n```\nneptune-for-graphql \\\n  --input-graphdb-schema-neptune-endpoint abc.us-west-2.neptune.amazonaws.com:8182 \\\n  --create-update-apollo-server \\\n  --output-resolver-query-https\n```\n\nExample of starting with a graphQL schema file:\n\n```\nneptune-for-graphql \\\n  --input-schema-file airports.source.schema.graphql \\\n  --create-update-apollo-server-neptune-endpoint abc.us-west-2.neptune.amazonaws.com:8182 \\\n  --create-update-apollo-server \\\n  --output-resolver-query-https\n```\n\nThe example commands above will generate the file\n`apollo-server-\u003cidentifier\u003e-\u003ctimestamp\u003e.zip`, which can then be deployed locally\nby following these steps:\n\n1. unzip `apollo-server-\u003cidentifier\u003e-\u003ctimestamp\u003e.zip`\n2. change directory into the unzipped folder\n3. execute `npm install` to install required dependencies\n4. execute `node index.mjs` to start the Apollo Server\n5. access the graphQL application in a browser by visiting\n   `http://localhost:4000/`\n\n\u003e [!NOTE]\n\u003e Node's default AWS credentials provider is used for authentication with\n\u003e Neptune.\n\u003e See [AWS SDK credential providers](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromnodeproviderchain)\n\u003e for more information.\n\n### Using Custom Scalars with Apollo Server\n\nWhen using custom scalars in your schema (specified via `--input-schema-file`),\nyou should add corresponding scalar resolvers to the index.mjs file in the\ngenerated Apollo Server artifact. Although queries will execute without these\nresolvers, the absence of the custom scalar resolvers will bypass important data\nvalidation for fields using custom scalar types.\nSee [Apollo Custom Scalars](https://www.apollographql.com/docs/apollo-server/schema/custom-scalars)\nfor more details on how to attach custom scalar resolvers with Apollo Server.\n\n### AWS AppSync Scalars\n\nAWS AppSync provides a set of extended scalar types that go beyond the default GraphQL \nscalars like `String`, `Int`, and `Boolean`. \n\nRefer to \n[AWS AppSync scalars](https://docs.aws.amazon.com/appsync/latest/devguide/scalars.html#graph-ql-aws-appsync-scalars)\nfor more details on each of the scalar types.\n\nThese scalar types can be used in your schema (specified via `--input-schema-file`) just\nlike any other standard scalar when working with **AWS AppSync**. You simply reference \nthem in your schema, and AppSync handles the parsing and validation automatically. \nFor example, you can define a field as an `AWSEmail` or `AWSDateTime` without needing to \nimplement any custom logic as AppSync will enforce the correct format at runtime.\n\n```graphql\ntype User {\n  id: ID!\n  email: AWSEmail!\n  createdAt: AWSDateTime!\n  metadata: AWSJSON\n}\n```\n\nHowever, it's important to note that these scalars are specific to AppSync and are not \npart of the official GraphQL specification. Thus, these scalars types are **not automatically\nrecognized by the Apollo Server** as it is with AppSync.\n\n# Known limitations\n\n- @graphQuery using Gremlin works only if the query returns a scalar value, one\n  elementMap(), or list as elementMap().fold(), this feature is under\n  development.\n- Neptune RDF database and SPARQL language is not supported.\n- Querying Neptune via SDK is not yet supported for Apollo Server, only HTTPS is\n  supported.\n- Schemas specified by `--input-schema-file` with `--create-update-aws-pipeline`\n  may not contain custom scalars.\n  See [AWS App Sync Scalar types in GraphQL](https://docs.aws.amazon.com/appsync/latest/devguide/scalars.html)\n  for more information.\n- Schemas specified by `--input-schema-file` with`--create-update-apollo-server`\n  or `--create-update-apollo-server-subgraph`which contain custom scalars\n  require manual steps to add custom scalar resolvers for additional query\n  validation.\n- Query fragments are supported for Apollo Server but not yet for App Sync.\n- Inline fragments are not yet supported.\n- When working with sort values as variables, Apollo Server may not support an\n  array variable but will accept variables inside an array. For example\n  ```sort: $test``` with variable ```{\"test\": [{\"country\": \"ASC\"}]}``` may\n  produce an error but can be modified to ```sort: [$test]``` with variable\n  ```{\"test\": {\"country\": \"ASC\"}}```.  \n  \u003cbr\u003e\n\n# Roadmap\n\n- Gremlin resolver.\n- SPARQL resolver for RDF database.\n- Enhanced configurations for Apollo Server.\n  \u003cbr\u003e\n\n# License\n\nCopyright 2023 Amazon.com, Inc. or its affiliates. All Rights Reserved. Licensed\nunder the Apache License, Version 2.0 (the \"License\"). You may not use this file\nexcept in compliance with the License. A copy of the License is located\nat http://www.apache.org/licenses/LICENSE-2.0\nor in the \"license\" file accompanying this file. This file is distributed on\nan \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express\nor implied. See the License for the specific language governing permissions and\nlimitations under the License. [Full license page](/LICENSE.txt).\n\u003cbr\u003e\n\n# Contributing\n\nFollow AWS open source practices.\n\u003cbr\u003e\n[Contributing page.](/CONTRIBUTING.md)\n\u003cbr\u003e\n[Code of conduct page.](/CODE_OF_CONDUCT.md)\n\u003cbr\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Famazon-neptune-for-graphql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws%2Famazon-neptune-for-graphql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Famazon-neptune-for-graphql/lists"}