GraphQL Meets Graph Database: A GraphQL + Neo4j Integration

As part of our work on the Neo4j Developer Relations team, we are interested in integrating Neo4j with other technologies and frameworks, ensuring that developers can always use Neo4j with their favorite technologies.

A very interesting development in recent months has been in GraphQL, an API query language especially targeted at front-end and mobile developers developed by Facebook.

The Neo4j-graphql Project

As we want to enable Neo4j users that are interested in using GraphQL with Neo4j to get up and running quickly, we spent the last few weeks working on the neo4j-graphql project. Neo4j-graphql is a Neo4j server extension that allows you to turn GraphQL queries into Cypher and run them against your graph data.

Using the Neo4j Sandbox infrastructure, you can spin up a Neo4j instance hosting your GraphQL schema with the neo4j-graphql-cli command line tool:

npm install -g neo4j-graphql-cli
neo4j-graphql [schema.graphql]

We also allow for Cypher to be embedded in the GraphQL schema, essentially a mapping between a GraphQL field and the results of a Cypher query. You can see more about this in the example movies Neo4j-GraphQL schema.

GraphQL Europe Conference

To gather feedback and learn more about the GraphQL community, we presented our work at the GraphQL Europe conference last Sunday in Berlin. My colleague Michael gave a lightning talk and we had many fruitful discussions with GraphQL users, who were very interested in what we’re doing and learning about Neo4j.

Michael Hunger presenting at GraphQL Europe

GraphQL Community Graph Hackathon

During the conference we organized a hackathon based on the GraphQL Community Graph, asking developers to build apps that queried a GraphQL endpoint that contains data about the activities of the GraphQL community.

The GraphQL Community Graph

A Graph Of The GraphQL Community

Our GraphQL API exposes data from the GraphQL community: GitHub projects, Stack Overflow questions and answers, tweets, and meetups related to GraphQL. The Hackathon challenged participants to build something cool that consumes this endpoint and allows the user to draw insight from the data.



Even if you didn’t have a chance to submit a project to the hackathon in time you can still make use of the GraphQL Community Graph – the GraphQL endpoint is available at graphql.communitygraph.org.

We also wanted to give a special shout out to Sashko from Apollo who built a great starter kit to show how to use Apollo Client with the community graph endpoint. This provided a great starting point for the other participants.

Overview of Hackathon Submissions

We had a number of really cool and interesting projects that people built. We didn’t choose winners but the first 15 valid submissions will receive a pair of Apple AirPods (or equivalent value gift card). We don’t have space here to describe all the projects that folks submitted, but we wanted to highlight a few that we thought were particularly well done and interesting.

GraphQL Daily

Betty and Niclas built GraphQL Daily, an Android app that presents three interesting GraphQL-related links per day, including:

• Unanswered Stack Overflow questions
• GitHub repositories with a high number of open issues to encourage participation
• Highly ranked tweets

GraphQL Daily presents you with three interesting GraphQL-related links per day in a nice and clean UI. The content is focused on helping the GraphQL community to grow and to encourage contributions.

Neo4j → GraphQL → CSV → Google Sheets → Chart Dashboard

Ivan and Roman from APIs Guru wrapped the GraphQL Community Graph API with graphql-lodash, adding the ability to filter, to perform aggregations and to perform projections on the client with Lodash syntax. Further, they used this to create a GraphQL → CSV → Google spreadsheet pipeline with charts to show the top projects, languages and tweets in the GraphQL Community, updated live.

GraphQL Map

Frederick Fogerty created GraphQL Map which uses the GraphQL Community Graph to show GraphQL meetup events on a Google map, using Next.js, React.js, and now for deployment.



Thank you to everyone who participated! We had many great submissions, and we were amazed by the wide variety of technologies used – from Android, React Native, React, Angular, Python, JavaScript, shell scripts and more. This was a great learning experience to see what tools folks are using to quickly build applications that work with GraphQL APIs.

Neo4j-graphql

While GraphQL is designed to be used with any database, existing API or persistence layer, we sought out to build an integration with GraphQL that makes it super simple to spin up Neo4j-backed GraphQL APIs. Further, we wanted to expose the power of Cypher through GraphQL to allow for powerful graph queries.

We’ve built an initial version of this integration that works end-to-end. (The GraphQL Community Graph mentioned above is built with this integration.)

The Neo4j-GraphQL command-line tool enables the user to quickly spin up a Neo4j-backed GraphQL API using a user-defined GraphQL schema, optionally annotated with Cypher queries.

Neo4j-graphql comes it two parts, a command-line tool to quickly spin up Neo4j Sandbox instances with a given schema file (or the movies example) and a Neo4j server extension.

How does the Neo4j-graphql extension work? It’s a Neo4j server extension that can either infer your schema (types, fields, relationships) from your graph schema, or take it from a GraphQL schema file provided by the user.

It then accepts GraphQL queries from the user that are transformed into a single Cypher query using the new map-projection and pattern comprehension features available in Neo4j 3.1. The Cypher query is executed against your graph data and the nested results rendered back to the client.

It was really cool to see how easy it was with Neo4j’s property graph model to represent the GraphQL schema and how well the “tree” input query could be mapped to Cypher.

In our schema interpretation we support almost all features of GraphQL but added @relation directives to represent your relationships. To bring the power of Cypher to GraphQL we also enabled the use of @cypher directives on object types, fields, query types and mutations.

This allows you to provide computed values like aggregations, scores, related entities, recommendations or completely custom queries and data updates with a single line of Cypher. You can find all relevant code in the neo4j-graphql GitHub organization and more details about the GraphQL integration are on our developer pages.

Feedback

We would love to hear what you think about Neo4j and GraphQL working together. How does it work for you? Did you run into any issues? Do you have suggestions for improvements or new features?

Email us devrel@neo4j.com, join us in the #neo4j-graphql channel of Neo4j-Users Discord, or raise an issue on any of the GitHub repositories linked above.