Neo4j GraphQL Database Plugin
This is a GraphQL-Endpoint extension for Neo4j and is part of GRANDstack.
This readme assumes you are somewhat familiar with GraphQL and minimally with Cypher.
Based on your GraphQL schema, it translates GraphQL Queries and Mutations into Cypher statements and executes them on Neo4j.
It offers both an HTTP API, as well as, Neo4j Cypher Procedures to execute and manage your GraphQL API.
Installation
Download and install Neo4j Desktop.
Neo4j Desktop provides a quick install button for neo4j-graphql.
After creating your database you can find it under "Manage" in the "Plugins" tab for a single click install.

Use with neo4j-graphql-cli
This extension is utilized, when you use neo4j-graphql-cli.
This tool
- launches a Neo4j Sandbox with your GraphQL schema
- provides the
/graphql/
endpoint, - a Neo4j server,
- an hosted GraphiQL for it.
Quickstart
To generate some graph data in Neo4j just run :play movie graph
in your Neo4j Browser.
GraphiQL
The best tool to use is GraphiQL the GraphQL UI. Get and install it.
Enter your GraphQL URL, like http://localhost:7474/graphql/
(note the trailing slash).
If your Neo4j Server runs with authentication enabled, add the appropriate Basic-Auth (base64 encoded) username:password
header in the "Edit HTTP Headers" screen.
.Command to generate the Authorization
header value.
Uploading a GraphQL Schema
Here is a small example schema for the movie data. Just a Movie with actors, and a Person with movies.
Simple properties are mapped directly while the relationships are mapped to fields movies
and actors
Movies Schema
You can POST a GraphQL schema to the /graphql/idl/
endpoint or run the CALL graphql.idl('schema-text')
procedure.
The payload is parsed and stored in Neo4j and used subsequently as the backing GraphQL schema for validating and executing queries.
You should then be able to see your schema in the Docs section of GraphiQL.
This also gives you auto-completion, validation and hints when writing queries.
To visualize your GraphQL schema in Neo4j Browser use: call graphql.schema()
.

Auto-Generated Query Types
From that schema, the plugin automatically generate Query Types for each of the declared types.
e.g. Movie(title,released,first,offset,_id,orderBy, filter): [User]
- Each field of the entity is available as query argument, with an equality check (plural for list-contains)
- We also provide a
filter
argument for more complex filtering with nested predicates, also for relation-fields (see graphcool docs) - For ordered results there is a
orderBy
argument - And
first
,offset
allow for pagination
Now you can for instance run this query:
Simple query example

Advanced query example
This query declares query name and parameters (first line), which are passed separately ("Query Parameters box") as JSON.
And get this result:

Auto-Generated Mutations
Additionally Mutations for each type are created, which return update statistics.
e.g. for the Movie
type:
createMovie(title: ID!, released: Int) : String
updateMovie(title: ID!, released: Int) : String
deleteMovie(title: ID!) : String
and for it's relationships:
addMovieActors(title: ID!, actors:[ID]!) : String
deleteMovieActors(title: ID!, actors:[ID]!) : String
Those mutations then allow you to create and update your data with GraphQL.
Single Mutation
Mutation Result
Several Mutations at once
If the same mutations is called multiple times, you need to use alias prefixes to avoid clashes in the returned data, which is keyed on mutation names.

You can use those mutations also to load data from CSV or JSON.
Directives
Directives like @directiveName(param:value)
can be used to augment the schema with additional meta-information that we use for processing.
You have already seen the @relation(name:"ACTED_IN", direction:"IN")
directive to map entity references to graph relationships.
The @cypher
directive is a powerful way of declaring computed fields, query types and mutations with a Cypher statement.
For instance, directors
Register Top-Level Schema Types
A custom query
A custom mutation
Full enhanced Schema
Procedures
This library also comes with Cypher Procedures to execute GraphQL from within Neo4j.
Simple Procedure Query
Advanced Procedure Query with parameters and post-processing

Update with Mutation
Procedures
You can even visualize remote graphql schemas, e.g. here from the GitHub GraphQL API. Make sure to generate the Personal Access Token to use in your account settings.

Examples
Some more examples
Relationship Argument
Nested Relationships
Sorting
Resources
- Read more in the project docs.
- Report an issue on the Github issue tracker.