New features in version 1.3 and 1.4: from Spring-Boot DGS integration to Type-safe APIs, better pagination and alignment with neo4j/graphql.js
There have been many changes in the last two releases, about which I would like to give some insights here.
Integration with Spring-Boot DGS
With version 1.4 of Neo4j GraphQL Java, we have enabled an easy integration into Spring Boot DGS applications. This integration makes it possible to use the features of DGS in conjunction with schema augmented by Neo4j GraphQL Java.
Example
- Create a schema which should be augmented by the library
2. Create a schema to extend the Neo4j schema by some fields that should be provided through the DGS application
As you can see, the Movie type is extended by some additional fields. New query methods can be added as well.
3. Creating a combined graphql-schema by using some of the extension points provided by the DSG library:
- In the postConstruct method, a SchemaBuilder is created, to augment the simple neo4j.graphql schema
- The registry method ensures, that DSG uses the same TypeDefinitionRegistry as the one used by the SchemaBuilder
- The codeRegistry method is called to register the handlers for all those fields that should be handled by Neo4j GraphQL Java. In the example for the field Movie:title .
- The runtimeWiring method ensures, that all required scalars and interfaces can be handled correctly
4. Extend the remaining fields that are not covered by Neo4j GraphQL Java with some custom logic:
That’s it. Now the schema can be queried to retrieve combined data from the Neo4j database as well as from the DGS application:
Generating a Type-Safe Model to Query the API
In the previous example, we have shown how to combine neo4j-graphql-java with a Spring boot DGS application. DGS also provides a way to generate classes at build time from a grapqhl schema, which can be used to call the GraphQL API in a type-safe manner.
In order to be able to use this feature for the combined schema, we have created a Maven plugin that can be used to generate the fully augmented schema at build time:
It is important that the schemaConfig settings are identical to the one used to configure the Schemabuilder.
Now type-safe projections can be used like in this example:
Complete Example
A complete example is available in our GitHub repository.
Additional New Features
Having Default Values for Paging and Sorting
Default values for paging and sorting can now be defined in the source schema:
Now when the following query is triggered:
A list of movies where each movie contains the first 3 actors sorted by descending name is returned.
API-Alignment with neo4j/graphql
Overview
We have started to align the API of the augmented schema with the official JavaScript version. This is an ongoing process that still requires a lot of work (you can follow the progress at GitHub). The goal is to make the augmented GraphQL schema compatible with the one generated by the JavaScript version.
To make the transition for our users as smooth as possible, any changes to the schema augmentation can be adjusted via a configuration where the default values are set to be compatible with older versions of neo4j GraphQL Java.
Using Scalars for Temporal Types
We had some issues with the previous implementation when using temporal types. These issues were resolved by the introduction of scalar temporal types, wich can be activated via useTemporalScalars = true.
This means that time values are only transmitted as ISO strings, which leaves no room for interpretation. Also for filtering it is now clear about which point in time a comparison should take place.
Separate Sorting and Paging into Own Input Types
Query options can now be configured to be handled as input types (via queryOptionStyle = INPUT_TYPE). Default values can also be defined for paging and sorting at this new input types:
When this query is triggered:
A list of genres sorted by descending name is returned.
Further Improvements
Usage of neo4j-cypher-dsl
In version 1.3, the entire Cypher generation mechanism was migrated to neo4j-cypher-dsl. This allows us to pretty print the generated Cypher statements for our test cases. Furthermore, we can store the values for parameters directly in the DSL model and extract them easily.
Better Testing
Our integration tests have been extended so that they now also test the GraphQL layer. Thus, our test framework also serves as documentation, in which all test-relevant information such as
- graphql-schema
- test-data (data within the neo4 database)
- graphql-request
- generated cypher query
- and graphql-response
can be accessed via an nicely rendered Ascii-doc file. Here is one example from a GitHub issue:
Feedback
I would love if you’d try it out and provide feedback in the form of GitHub issues or via GitHub discussions
What’s New in Neo4j-GraphQL-Java was originally published in Neo4j Developer Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.
