What’s new in version 2?
Today, we’re excited to announce the stable release of the Neo4j GraphQL Library 2.0.0! ? This has been in the pipeline pretty much since the day of the 1.0.0 release, and culminates not only the work on some amazing new features, but several learnings from that first release.
Thank you to everyone who has tried out the 2.0.0 prereleases, engaged with the RFC process or contributed to the project during this period - we wouldn’t be where we are now if it wasn’t for your involvement. I would like to especially thank Nick Sethi (@litewarp) for his work on cursor-based pagination - it’s a great feature which I’m sure will see a lot of use.
Here’s a summary of what’s new with links to any relevant documentation:
- Relationship properties
- Cursor-based pagination
- Count queries
- Improvements to the developer experience with union relationship fields
- More comprehensive validation of type definitions
- Internal refactoring and bug fixes
Before diving into the detail of the new features in this release, I’d like to talk a bit about the design decisions which guided their development.
Connections, Edges, and Nodes
When thinking about how to add support for relationship properties, we had a few goals in mind:
- Low friction to add relationship properties to existing type definitions
- Easy to understand how type definitions map onto the generated schema
- Familiar constructs used for the representation of relationship properties
On the familiarity side of things, our minds turned to Relay and the GraphQL Cursor Connections Specification, with its concept of edges and nodes, almost perfectly mapping over to Neo4j’s relationships and nodes. When digging out the following sentence from the specification, we knew we were on the right track for our relationship properties problem:
Edge types must have fields namednodeandcursor. They may have additional fields related to the edge, as the schema designer sees fit.
By adding fields to the edge types, we could represent relationship properties where they conceptually belong, on the traversal between two nodes. Running with this specification would also open the door to cursor-based pagination in the future, a feature which had been suggested, so it seemed like a no brainer to take this approach.
Whilst this release doesn’t cover Object Identification needed to make the library fully Relay compliant, discussions around this topic are underway and it’s definitely something we want to implement.
What’s New?
Relationship Properties
The original goal of this release, the Neo4j GraphQL Library now has support for relationship properties. Relationships are the “special sauce” of Neo4j which add a real richness to your graph datasets, which combined with the accessibility of GraphQL, will enable users to easily build applications on top of highly complex, interconnected data.
Adding relationship properties into your existing @neo4j/graphql type definitions is easy - just add a new interface containing your properties and point to it in your existing @relationship directive:
Cursor-Based Pagination
Cursor-based pagination if often the preferred method of pagination when building infinitely scrolling applications, and with today’s release, it will be automatically available for all relationship fields in your schema.
To get started with cursor-based pagination, you query the connection field of a relationship, passing in the cursor string which you want to start navigation after, for example, getting the actors of a movie 10 at a time:
Count Queries
Cursor-based pagination doesn’t tickle your fancy? We realize that page-based pagination wasn’t so easy in the 1.x releases, with a lack of any count queries making it difficult to calculate how many pages are available in total. So, we’ve added count queries to the root Query type for all defined nodes, which will allow you to better paginate with pages.
These accept the same where arguments which you’re familiar with, for example, getting a count of movies which Robin Williams has acted in:
What’s Changed?
Goodbye “Skip”, Hello “Offset”
Since we released version 1.0.0 of the Neo4j GraphQL Library, Apollo Client 3.0 was released. In this release, Apollo Client has become a bit more opinionated, favouring offset and limit over skip and limit for pagination. Acknowledging that Apollo Client is by far the most popular GraphQL client library, we have updated the page-based pagination arguments in the Neo4j GraphQL Library to align with this change.
Changing Union Input Types
From day one, union relationship fields have been a lot more popular than we’d anticipated! As such, we wanted to take the opportunity of this release to restructure input types for a better developer experience using unions.
You can read about these changes in our migration guide.
What Are You Waiting for?
Does all of the above sound good to you? Not only does the 2.0.0 release contain all of these great features, but also a great deal of non-functional improvements which will improve your experience with the library. Being a major release, there are several breaking changes which will need to be addressed as you upgrade. We have written a handy migration guide to point of these out, and you can find us in the #graphql channel on Discord if you have any questions.
If you want to see these features in action, Will Lyon (@lyonwj) and I will be taking a look at the new release of the library in a livestream today (10th August 2021) - tune in at 16:00 UTC!
Also, keep an eye out for a blog from Dan Starns (@danstarns1) in the coming days, in which he will go through an example of how you can take advantage of the features in today’s release.
