About a year ago I wrote a GraphQL to Neo4J mapping layer from our GraphQL implementation in NodeJS. For those that don’t know much about Neo4J, it is a graph database that has it’s own query language called Cypher. Like SQL, Cypher lets you query data from the database but it is specifically designed for querying nodes and relationships between nodes in a Neo4J database.
The GraphQL to Neo4J Mapping Layer
The GraphQL to Neo4J mapping layer I created converted GraphQL type search objects, passed into GraphQL queries as arguments, into Cypher queries executed against a Neo4J database. Cypher results were retrieved and converted back into the shape required by the GraphQL api, including Neo4J properties and labels being mapped back to their GraphQL field names.
- A GraphQL query is called with a search argument describing what to search for. For example: (and: [ { node: { type: { equals: “Person” } } }, { node: { name: { equals: “Joe” } } } ])
- Translate the GraphQL search object into Cypher query: ‘MATCH (Node:Person) WHERE node.fullName = “Joe” RETURN node’
- Translate the Person node returned from Cypher back into a JSON object that has the right property names (fullName -> name)
- Return the resulting list of people from the GraphQL query resolver
GraphQL to Neo4J Impedance Mismatch
All mapping layers have an impedance mismatch. The GraphQL to Neo4J layer I created had these challenges:
Typed GraphQL to Loosely Defined Neo4J Properties
GraphQL is typed and each type has a specific set of properties. You can create Union types that describe the return as one of many types but each item returned will be one of those types and have a specific set of properties.
Neo4J allows each node in the database to have a different set of properties. Even nodes of the same type (think Person). Some people can have a name. Other people can have a fullName. Others still can have a properName. These sort of loosely defined properties presented a conceptual challenge.
In the end, I didn’t have to accommodate these types of loosely defined properties. Our Neo4J data was loaded into the database programmatically so every Person did have the same types of properties. If I had been required to solve these types of problems, I would have had to have a more complicated property map or instead of returning normal GraphQL types, I could have returned a JSON type which would allow for unspecified properties to be used.
Complex Cypher Queries Spanning Several Nodes
We didn’t require queries that spanned several nodes in the database but if we had it would have been similar to a SQL table join that returns data from several tables. Each node returned would be related to each other in some way (described in the query or the results) and therefore could be mapped back to a proper return type and relationship type describing the connection between the two.
Common Mapping Layer Pattern
This mapping layer wasn’t the first mapping layer I’d created from Node or GraphQL and, it probably wasn’t isn’t even the tenth mapping layer I’ve created from some programming language to some database.
Database mapping layers have been around for a long time. This mapping layer followed the patterns I’ve used previously and that we had already used for getting data from MariaDB using SQL and from our REST API building query strings for GET requests. All mapping layers have these things in common:
- Entity Map: Some way to know the mapping of entity names between your local code and the dababase (class to table, or graphql type to table, etc)
- Property Map: Some way to know the mapping of entity field names to database table column names (or database node label/property names, etc)
- Query Generator: Some way to convert a local description of a search into a query that executes that search in the database (search object to SQL or Cypher)
- Helpers: Some helpers that use your entity map and property map and query generator to generate queries and return values with the correct entity types and property names
- Management of the connection to the database (connection pools or creation of database connections)
Conclusions
Mapping From GraphQL to Neo4J mostly followed the database mapping patterns I’ve built before and / or seen before. Like all database mapping layers there were some complexities to deal with but in the case of Neo4J the biggest hurdle I faced was learning how to use Neo4J and the Cypher query language to get data. Once I understood the database and the query language, producing a framework for mapping from GraphQL to Neo4J wasn’t far off and turned out to be pretty fun journey.
Monty Kamath 