Neo4j graph database and GraphQL: A perfect match

  • Michelle Sanver

As a graph database enthusiast I often got asked the question “So, as one of our graph expert, can you answer this GraphQL question?”.

Every time I have said that a graph database is not the same as GraphQL, and that I was unable to answer the question.

Another colleague of mine, Xavier, had the same experience. So we decided to learn about GraphQL so that we could answer the questions, and because it seemed like a really cool way to write API’s.

So before we dig into this any further, a quick overview of what a graph database is and what GraphQL is:

  • A graph database is a database storing data in a graph, which is super performant when it comes to data which has relations to other data, which is a lot of our modern complex data sets.
  • GraphQL is a way to query data. A flexible API protocol that lets you query just the data that you need and get that in return. Any storage can be behind this data, GraphQL is not responsible for storage.

It was me and Emanuele on the innoday, where we decided to try out Neo4j with the GraphQL extension.

Emanuele had never tried Neo4j before, and was amazed at how easy it is to get going. GraphQL was also super easy to install. Basically what you do is:

  1. Download Neo4j desktop
  2. Go trough the very obvious setup
  3. Click “install” on the plugin GraphQL which is already listed
  4. Use “browser” to populate data
  5. Query the data with GraphQL that automatically, thanks to the plugin, has a schema for you

With this technology we aim to solve a problem that we currently have. The problem is one of our REST API’s which has a LOT of data. When a consumer queries for something that they need, they will get a lot of things that they don’t need, that another consumer may need. We end up wasting bandwidth.

How does GraphQL solve this? And where does Neo4j come in?
In GraphQL we query only for the data that we need, making a POST request. A request may look like:

  Product {

If we have a graph database with a single node with the label “Product” and the properties “title” and “product_id” we would get this behaviour out of the box with the GraphQL plugin. Tada! A simple API is created, all you had to do was add the data! DONE.

This makes it very easy for the consumer to query JUST for the data that they need. They can also see the entire schema where we can write descriptions in the form of comments, so that the consumer knows what to do with it.

How does Neo4j work, and how do you add data? It is super simple! With Neo4j desktop, you click “manage” on your database and then “Open Browser”, in browser you can browse your data and execute queries in a graphical way.

desktop browser

You can use browser to click trough and start learning, it is also a great tool for learning and experimenting, so as for learning Neo4j I leave you with browser to try your own hands on experience. Have fun playing with it! They explain it really well.


Ok, so simple graphs are very easy to query for, but how do we query for relationships with GraphQL and Neo4j? Let’s say we have a node called “Product” again, the node does not have the “title” directly on the product, but in a node labeled “TranslatedProductProperties”. This node will have all the translated properties that the product may need. Such as the title. The relation is called “in_language”. The relation itself has a property called “language”. This is how the actual graph looks like in browser:


In GraphQL we would need a custom IDL (schema) for that to be queried nicely. Our goal would be to query it the following way, we simply give it the title and the language, and we as GraphQL don’t need to know about the actual relations:

  Product {
    title(language: "de")

A simple IDL for that could look like:

type Product {
  product_id: String
    # The title in your provided language =D
  title(language: String = "de"): String @cypher(statement: "MATCH(this)-[:in_language {language:$language}]-(pp:ProductProperties) return pp.title")

So here you can see that with the help of the GraphQL plugin we could make a cypher query to get whatever data we want for that field. Cypher is the query language for Neo4j.

These things together being able to get any nodes and relationships, which are already decoupled unless you choose to couple them, and the querying flexibility makes Neo4j + GraphQL an API as flexible as... Rubber? An awesome match!

Tell us what you think