Announcing The Neo4j GraphQL Library Beta

Hi all! Over the last year engineers inside Neo4j have been planning, building, and refining an official Neo4j GraphQL integration. Today, we’re excited to announce the Beta release of the Neo4j GraphQL Library!

Our Journey

If you have experimented with Neo4j GraphQL in the past, you may know about neo4j-graphql.js. You may be asking yourself: What’s wrong with it? The answer is: nothing.

However, as a “Neo4j Labs” project, support was provided on a “best effort” basis and many of the features and technical decisions were shaped without a clear roadmap.

As a new Product Engineering project, we are now dedicated to the Neo4j GraphQL Library on a full-time, ongoing basis. One of the first things we did was rewrite neo4j-graphql.js in TypeScript. Leveraging TypeScript has massively improved the quality of the project, giving us an uppermhand as the product evolves.

Everything has been built on the foundations established by Neo4j Labs working on Neo4j GraphQL integrations for several years, so existing users should feel right at home with familiar fundamentals and concepts.

Not only did we want to build a robust type-safe codebase but we wanted to position ourselves in line with our users and Neo4j’s goals. With many feature requests, and the anticipation to offer GraphQL as a service, we wanted a clear workbench to implement features that would satisfy everyone’s requirements, such as the new Auth Directive for adding authorization rules to your GraphQL API.

Finally, we know that great support helps make a great product. With the new Official Neo4j Product stamp and the realignments to the implementation, developers and users can expect high-quality support plus continuous improvement.

The Team

Building the new implementation was no one-man job! Here is the team:

Daniel Starns (Engineer)
Darrell Warde (Engineer)
Oskar Hane (Team Lead)
William Lyon (Developer Relations)
Anurag Tandon (Product Manager)

Special thanks to Michael Graham, Andreas Berger, Michael Hunger, and many more members of the community who contributed to the previous Neo4j GraphQL integrations and have helped us get to this stage.🍻

Getting Started with the Neo4j GraphQL Library

In this section, I will take you through setting up a Node.js Neo4j GraphQL API application, using Neo4j Sandbox, mutating data, and then querying that data.

First: Visit Neo4j Sandbox, sign up, and create a new Blank Sandbox project:

Using Neo4j Sandbox means all you need is the ability to run some Node.js code.

If you don’t want to use Sandbox, you can download and install Neo4j Desktop here.

Installing the Neo4j GraphQL Library

In a new folder, start a new npm project:

npm init --y

Then install dependencies:

npm install @neo4j/graphql graphql apollo-server neo4j-driver

CTRL + C, CTRL + V

You can pretty much copy and paste this example into your new project, although you will need to change the 3 references to connect to your Neo4j Sandbox instance. You can find these values in the “Connection Details” tab of Neo4j Sandbox.

YOUR_BOLT_URL
YOUR_BOLT_USER
YOUR_BOLT_PASSWORD

Run the Server

node index.js

Execute the given copy paste job and navigate to https://localhost:4000 in your web browser:

What you’re seeing is GraphQL Playground.

Dissecting the Schema 🧐

One of the goals of Neo4j GraphQL is that given a single set of GraphQL type definitions, we produce a fully functional GraphQL schema ready to be used in your application.

Let’s take a closer look at the GraphQL type definitions you just copied:

These GraphQL type definitions map to a Neo4j property graph model. If you were to represent these type definitions visually, using Arrows.app, it would look something like:

Creating a Movie

Forrest Gump is a pretty cool film! Let’s add that into our database.

Creating Director

Firstly, let’s create Person node Robert Zemeckis by executing this GraphQL mutation in GraphQL Playground:

Creating Movie

Now we have our director, let’s create the Movie node and connect a relationship to the already created director node:

Adding Actors

Tom Hanks and Robin Wright starred in Forrest Gump, so let’s perform an update where we create and connect the actors to the movie:

Adding a Genre

Now we have our Movie and Persons connected together, all we are missing is a Genre:

Reading The Graph

Now all of our Movies, Genres, and People are inserted and connected together, we can perform a query to grab all the data:

Note that we didn’t need to write any Cypher or other data-fetching code like GraphQL resolver functions to build our GraphQL API application. The Neo4j GraphQL Library took care of translating our arbitrary GraphQL operations to Cypher and handling the database request.

What’s Next?

To get the best idea of where to go next, visit the Docs to find out more & come chat with us on Discord. Below is a quick peek at some of the other exciting features that the new library offers.

Auth Directive

Use the brand new Auth directive to secure your GraphQL API using JSON Web Tokens (JWTs). Below is an example of only allowing the director to edit a movie:

OGM

In addition to the approach outlined above, you can also use Type Definitions to power an Object-Graph Mapper or OGM. Below is an example that uses nested mutations to create Movie, Persons, and Genre nodes at once:

Life is like a box of chocolates. You never know what you’re gonna get.

~ Forrest Gump

Learn More About Neo4j GraphQL

The Beta release of the Neo4j GraphQL Library is available today via npm. The 1.0 GA release of the library will be coming later in the quarter, so stay tuned for more updates. If you are a current user of the Labs neo4j-graphql.js library please consider migrating to the new official Neo4j GraphQL Library as neo4j-graphql.js will be sunset sometime this summer.

We’ll be hosting a Neo4j GraphQL Community Call as part of Global Graph Celebration Day on April 15th where the team will dive into more detail about the Neo4j GraphQL Library and answer any questions. Register for an email reminder or see the detailed schedule at GlobalGraphCelebrationDay.com