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.

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.

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.

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

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 which uses the GraphQL Community Graph to show GraphQL meetup events on a Google map, using Next.js, React.js, and now for deployment.

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 , join us in the #neo4j-graphql channel of Neo4j-Users Slack, or raise an issue on any of the GitHub repositories linked above.  

If you enjoyed this article and want to learn more about GraphQL, check out this collection of tutorials and articles on all things GraphQL.