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!
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.
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.
Run the Server
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.
Firstly, let’s create Person node Robert Zemeckis by executing this GraphQL mutation in GraphQL Playground:
Now we have our director, let’s create the Movie node and connect a relationship to the already created director node:
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.
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:
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
Register for NODES 2021 today and enjoy the talks from experienced graph developers.
Save My Spot