Using The Neo4j-GraphQL Plugin In Neo4j Desktop

Expose A GraphQL Endpoint From Neo4j Without Implementing Resolvers

This post will show how to get started with Neo4j-GraphQL, a database plugin that enables serving a GraphQL endpoint directly from Neo4j by

• generating a GraphQL schema from existing Neo4j data -or-
• serving a GraphQL endpoint based on a user-defined GraphQL schema
• translating GraphQL to Cypher
• automatically generating Query types for querying with GraphQL
• automatically generating Mutation types for write operations
• exposing Cypher through GraphQL as a @cypher schema directive

Neo4j Desktop

Neo4j Desktop is a cross platform (Electron) application for downloading and managing Neo4j graphs for development.

It includes functionality for configuring, administrating, and installing Neo4j plugins.

You can download Neo4j Desktop here.

GraphQL

If you’re not familiar with GraphQL, it’s a relatively new way of building APIs. GraphQL allows us to specify what data is available in the API and then for the client to select exactly the data needed with each request. You can learn more GraphQL at GraphQL.org.

Exposing A GraphQL API Backed By Neo4j

I outlined some of the benefits of using Neo4j with GraphQL in a previous post “Five Common GraphQL Problems And How Neo4j-GraphQL Aims To Solve Them”, so I won’t focus on why to use Neo4j-GraphQL and instead show how to use the Neo4j-GraphQL plugin in this post.

Install The Neo4j-GraphQL Database Plugin

The Neo4j-GraphQL plugin will enable us to serve a GraphQL endpoint directly from Neo4j. The plugin will also translate arbitrary GraphQL requests to Cypher and execute those in Neo4j. This means that we don’t have to implement resolver functions to build our GraphQL service, this is taken care of by the plugin.

You can install the Neo4j-GraphQL plugin from the “Plugins” tab in Neo4j Desktop. Just click “Install and Restart” and the plugin will be installed and loaded.

Once the plugin is loaded a GraphQL endpoint will be served by Neo4j (be default at http://localhost:7474/graphql/ ).

If you’re not using Neo4j Desktop you can install the plugin by downloading the latest release from GitHub, saving the JAR file in the plugins directory for your Neo4j instance and restarting Neo4j. See the instructions here.

Create The GraphQL Schema

Just like building any GraphQL service, the first step is to define a GraphQL schema. With the Neo4j-GraphQL plugin there are two ways to do this:

1. By providing a GraphQL schema, defined using the Schema Definition Language (SDL). Or,
2. Generate a schema automatically from data stored in Neo4j

In either case, QueryType and MutationType entry points for querying the data and mutations for writes are automatically generated based on the schema.

Automatically Generating A GraphQL Schema From Existing Data

Interacting with the Neo4j-GraphQL plugin is done through the use of procedures. You can see the full list of procedures available in the Neo4j-GraphQL plugin documentation. To create a GraphQL schema call the graphql.idl procedure, passing null to use existing data in Neo4j to automatically generate the schema (here we’ll use the sample movie data by running the :play movies query in Neo4j Browser, or use your own data):

This will inspect the data in Neo4j and by applying some simple rules (Node labels become types, relationships become a field on each type, etc), generate a GraphQL schema from the data and serve a GraphQL endpoint directly from the database at /graphql/ .

Using a Custom GraphQL Schema Defined Using GraphQL SDL

If you’re starting a new application and don’t have data in Neo4j yet you can define a GraphQL schema and use that to drive the Neo4j database model. Here’s an example schema defined using GraphQL SDL:

The GraphQL schema above also includes an optional @cypher schema directive which allows us to expose the power of Cypher in GraphQL. In this case the field recommended on the Movie type is now mapped to the result of the specified Cypher query, a simple recommendation query (what movies have the actors of this movie also acted in?).

MATCH (this)-[:ACTED_IN]-(:Person)-[:ACTED_IN]-(rec:Movie) 
RETURN rec LIMIT 10;

To use this schema for our GraphQL endpoint served by Neo4j we call the garphql.idl procedure, this time passing in the schema we defined (as a string):

Querying Neo4j With GraphQL

Regardless of if we generated the schema from existing data in Neo4j or defined one using SDL, we can use GraphiQL (a browser based tool for querying GraphQL APIs) to explore the GraphQL schema, including the API entry points, types, and fields available for querying.

GraphiQL is great for testing and development. To use GraphiQL with Neo4j, just download this GraphiQL app, point it at the GraphQL endpoint served by Neo4j, add authentication headers and you can query Neo4j using GraphQL in GraphiQL.

Authentication is enabled by default in Neo4j, so unless we disabled authentication we need to add Basic Authorization headers to our GraphQL requests. I like to use this web based tool for generating the proper Authorization header values.

Once we’ve added our Authorization header, we can use GraphiQL to query our GraphQL endpoint, served by Neo4j. We can explore the GraphQL schema in GraphiQL to see what data, queries and mutations are available.

Since we started with an empty database, the first operation we should perform is adding some data to Neo4j. We can do this with the use of GraphQL mutations. Mutations are write operations in GraphQL. We can take advantage of the fact that Neo4j-GraphQL automatically generated our mutation operations for creating and updating data and run a few simple mutations to insert a handful of movies and actors into Neo4j using GraphQL:

We can verify the data was created correctly in Neo4j, by running a simple query in Neo4j Browser:

MATCH p=(:Movie)<-[:ACTED_IN]-(:Person) RETURN p;

Instead of writing each mutation manually, we can use graphql-cli-load to load data from CSV or JSON files.

Once we’ve created data we can then query the data in Neo4j using GraphQL. Here’s an example using GraphiQL, but of course we can use any of the other GraphQL clients such as Apollo Client, Urql, or Relay Modern (as explained in a previous post here).

neo4j-graphql-js

There is also a JavaScript variant of the Neo4j-GraphQL integration that is designed to work with all JavaScript GraphQL implementations. This is available on NPM as neo4j-graphql-js.

It works by providing a function that can be called in the top-level resolver for each Query or Mutation type that will translate the GraphQL request to a single Cypher query and handle the database call.

Resources

Here are a few resources to learn more about using GraphQL with Neo4j.

• neo4j.com/developer/graphql/ — The Neo4j developer page for GraphQL provides an overview of the various ways to use GraphQL with Neo4j.
• grandstack.io/ — Build full-stack applications using the GRANDstack (GraphQL, React, Apollo, and Neo4j Database).
• github.com/neo4j-graphql — Github organization for Neo4j-GraphQL tools.
• neo4j.com/slack — The Neo4j Slack channel is a great way to keep in touch with the Neo4j community. Be sure to join the #neo4j-graphql and #grand-stack