Adding custom logic to our GraphQL API is necessary any time our application requires logic beyond simple CRUD operations (which are auto-generated by
There are two options for adding custom logic to your API using neo4j-graphql.js:
- Using the
@cypherGraphQL schema directive to express your custom logic using Cypher, or
- By implementing custom resolvers and attaching them to the GraphQL schema
@cypher GraphQL Schema Directive
We expose Cypher through GraphQL via the
@cypher directive. Annotate a field in your schema with the
@cypher directive to map the results of that query to the annotated GraphQL field. The
@cypher directive takes a single argument
statement which is a Cypher statement. Parameters are passed into this query at runtime, including
this which is the currently resolved node as well as any field-level arguments defined in the GraphQL type definition.
@cypherdirective feature requires the use of the APOC standard library plugin. Be sure you've followed the steps to install APOC in the Project Setup section of this chapter.
Computed Scalar Fields
We can use the
@cypher directive to define a custom scalar field, defining a computed field in our schema. Here we add an
averageStars field to the
Business type which calculates the average stars of all reviews for the business using the
Now we can include the
averageStars field in our GraphQL query:
And we see in the results that the computed value for
averageStars is now included.
The generated Cypher query includes the annotated Cypher query as a sub-query, preserving the single database call to resolve the GraphQL request.
Computed Object And Array Fields
We can also use the
@cypher schema directive to resolve object and array fields. Let's add a recommended business field to the
Business type. We'll use a simple Cypher query to find common businesses that other users reviewed. For example, if a user likes "Market on Front", we could recommend other businesses that users who reviewed "Market on Front" also reviewed.
We can make use of this Cypher query in our GraphQL schema by including it in a
@cypher directive on the
recommended field in our
Business type definition.
We also define a
first field argument, which is passed to the Cypher query included in the
@cypher directive and acts as a limit on the number of recommended businesses returned.
Custom Top-Level Query Fields
Another helpful way to use the
@cypher directive is as a custom query or mutation field. For example, let's see how we can add full-text query support to search for businesses. Applications often use full-text search to correct for things like misspellings in user input using fuzzy matching.
In Neo4j we can use full-text search by first creating a full-text index.
Then to query the index, in this case we misspell "coffee" but including the
~ character enables fuzzy matching, ensuring we still find what we're looking for.
Wouldn't it be nice to include this fuzzy matching full-text search in our GraphQL API? To do that let's create a Query field called
fuzzyBusinessByName that takes a search string and searches for businesses.
We can now search for business names using this fuzzy matching.
Since we are using full-text search, even though we spell "library" incorrectly, we still find matching results.
@cypher schema directive is a powerful way to add custom logic and advanced functionality to our GraphQL API. We can also use the
@cypher directive for authorization features, accessing values such as authorization tokens from the request object, a pattern that is discussed in the GraphQL authorization page.
Implementing Custom Resolvers
@cypher directive is one way to add custom logic, in some cases we may need to implement custom resolvers that implement logic not able to be expressed in Cypher. For example, we may need to fetch data from another system, or apply some custom validation rules. In these cases we can implement a custom resolver and attach it to the GraphQL schema so that resolver is called to resolve our custom field instead of relying on the generated Cypher query by neo4j-graphql.js to resolve the field.
In our example let's imagine there is an external system that can be used to determine current wait times at businesses. We want to add an additional
waitTime field to the
Business type in our schema and implement the resolver logic for this field to use this external system.
To do this, we first add the field to our schema, adding the
@neo4j_ignore directive to ensure the field is excluded from the generated Cypher query. This is our way of telling neo4j-graphql.js that a custom resolver will be responsible for resolving this field and we don't expect it to be fetched from the database automatically.
Next we create a resolver map with our custom resolver. We didn't have to create this previously because neo4j-graphql.js generated our resolvers for us. Our wait time calculation will be just selecting a value at random, but we could implement any custom logic here to determine the
waitTime value, such as making a request to a 3rd party API.
Then we add this resolver map to the parameters passed to
Now, let's search for restaurants and see what their wait times are by including the
waitTime field in the selection set.
In the results we now see a value for the wait time. Your results will of course vary since the value is randomized.
- Using Neo4j’s Full-Text Search With GraphQL Defining Custom Query Fields Using The Cypher GraphQL Schema Directive