A package to make it easier to use GraphQL and Neo4j together.
neo4j-graphql-js translates GraphQL queries to a single Cypher query, eliminating the need to write queries in GraphQL resolvers and for batching queries. It also exposes the Cypher query language through GraphQL via the
@cypher schema directive.
Goals of neo4j-graphql.js
- Translate GraphQL queries to Cypher to simplify the process of writing GraphQL resolvers
- Allow for custom logic by overriding of any resolver function
- Work with
- Support GraphQL servers that need to resolve data from multiple data services/databases
- Expose the power of Cypher through GraphQL via the
How it works
neo4j-graphql-js aims to simplify the process of building GraphQL APIs backed by Neo4j, embracing the paradigm of GraphQL First Development. Specifically,
- The Neo4j datamodel is defined by a GraphQL schema.
- Inside resolver functions, GraphQL queries are translated to Cypher queries and can be sent to a Neo4j database by including a Neo4j driver instance in the context object of the GraphQL request.
- Any resolver can be overridden by a custom resolver function implementation to allow for custom logic
- Optionally, GraphQL fields can be resolved by a user defined Cypher query through the use of the
Start with a GraphQL schema
GraphQL First Development is all about starting with a well defined GraphQL schema. Here we'll use the GraphQL schema IDL syntax, compatible with graphql-tools (and other libraries) to define a simple schema:
We define two types,
Actor as well as a top level Query
Movie which becomes our entry point. This looks like a standard GraphQL schema, except for the use of two directives
@cypher. In GraphQL directives allow us to annotate fields and provide an extension point for GraphQL. See GraphQL Schema Directive for an overview of all GraphQL schema directives exposed in
@cypherdirective - maps the specified Cypher query to the value of the field. In the Cypher query,
thisis bound to the current object being resolved. See Adding Custom Logic for more information and examples of the
@cypherGraphQL schema directive.
@relationdirective - used to indicate relationships in the data model. The
nameargument specifies the relationship type, and
directionindicates the direction of the relationship (
INfor incoming relationships,
OUTfor outgoing relationships, or
BOTHto match both directions). See the GraphQL Schema Design Guide for more information and examples.
Translate GraphQL To Cypher
Inside each resolver, use
neo4j-graphql() to generate the Cypher required to resolve the GraphQL query, passing through the query arguments, context and resolveInfo objects.
GraphQL to Cypher translation works by inspecting the GraphQL schema, the GraphQL query and arguments. For example, this simple GraphQL query
is translated into the Cypher query
A slightly more complicated traversal
@cypherdirective feature has a dependency on the APOC procedure library, to enable subqueries. If you'd like to make use of the
@cypherfeature you'll need to install the APOC procedure library.
GraphQL is fairly limited when it comes to expressing complex queries such as filtering, or aggregations. We expose the graph querying language Cypher through GraphQL via the
@cypher directive. Annotate a field in your schema with the
@cypher directive to map the results of that query to the annotated GraphQL field. For example:
similar will be resolved using the Cypher query
to find movies with overlapping Genres.
Querying a GraphQL field marked with a
@cypher directive executes that query as a subquery:
This means that the entire GraphQL request is still resolved with a single Cypher query, and thus a single round trip to the database.
Inject a Neo4j driver instance in the context of each GraphQL request and
neo4j-graphql-js will query the Neo4j database and return the results to resolve the GraphQL query.
- Blog post: Five Common GraphQL Problems and How Neo4j-GraphQL Aims To Solve Them - Digging Into the Goals of A Neo4j-GraphQL Integration