Skip to content
A GraphQL to Cypher query execution layer for Neo4j and JavaScript GraphQL implementations.
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
example/apollo-server Fix #174 Jan 21, 2019
scripts set upgrade store flag in start script instead of install Dec 5, 2018
.babelrc update deps Oct 3, 2017
.gitignore Cache neo4j based on file hash Jun 22, 2018
.npmignore Initial parameterisation work Jul 19, 2018
LICENSE initial commit Oct 2, 2017
package-lock.json 2.4.2 Mar 5, 2019

CI status npm version Docs link


A GraphQL to Cypher query execution layer for Neo4j and JavaScript GraphQL implementations.

neo4j-graphql-js is in active development. There are rough edges and APIs may change. Please file issues for any bugs that you find or feature requests.

Installation and usage


npm install --save neo4j-graphql-js


Start with GraphQL type definitions:

const typeDefs = `
type Movie {
    title: String
    year: Int
    imdbRating: Float
    genres: [Genre] @relation(name: "IN_GENRE", direction: "OUT")
type Genre {
    name: String
    movies: [Movie] @relation(name: "IN_GENRE", direction: "IN")

Create an executable schema with auto-generated resolvers for Query and Mutation types, ordering, pagination, and support for computed fields defined using the @cypher GraphQL schema directive:

import { makeAugmentedSchema } from 'neo4j-graphql-js';

const schema = makeAugmentedSchema({ typeDefs });

Create a neo4j-javascript-driver instance:

import { v1 as neo4j } from 'neo4j-driver';

const driver = neo4j.driver(
  neo4j.auth.basic('neo4j', 'letmein')

Use your favorite JavaScript GraphQL server implementation to serve your GraphQL schema, injecting the Neo4j driver instance into the context so your data can be resolved in Neo4j:

import { ApolloServer } from 'apollo-server';

const server = new ApolloServer({ schema, context: { driver } });

server.listen(3003, '').then(({ url }) => {
  console.log(`GraphQL API ready at ${url}`);

If you don't want auto-generated resolvers, you can also call neo4jgraphql() in your GraphQL resolver. Your GraphQL query will be translated to Cypher and the query passed to Neo4j.

import { neo4jgraphql } from 'neo4j-graphql-js';

const resolvers = {
  Query: {
    Movie(object, params, ctx, resolveInfo) {
      return neo4jgraphql(object, params, ctx, resolveInfo);

What is neo4j-graphql.js

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.


  • 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 graphql-tools, graphql-js, and apollo-server
  • Support GraphQL servers that need to resolve data from multiple data services/databases
  • Expose the power of Cypher through GraphQL via the @cypher directive


  • Send a single query to the database
  • No need to write queries for each resolver
  • Exposes the power of the Cypher query language through GraphQL


We use the ava test runner.

npm install
npm build
npm test

The npm test script will run unit tests that check GraphQL -> Cypher translation and the schema augmentation features and can be easily run locally without a test environment. Full integration tests can be found in /test and are run on CircleCI as part of the CI process.


See /examples


Full docs can be found on

You can’t perform that action at this time.