neo4j-graphql.js can create an executable GraphQL schema from GraphQL type definitions or augment an existing GraphQL schema, adding
- auto-generated mutations and queries (including resolvers)
- ordering and pagination fields
- filter fields
makeAugmentedSchema - generate executable schema from GraphQL type definitions only
augmentSchema - when you already have a GraphQL schema object
Based on the type definitions provided, fields are added to the Query type for each type defined. For example, the following queries are added based on the type definitions above:
Create, update, delete, and add relationship mutations are also generated for each type. For example:
IDtyped field is specified in the type definition, but not provided when the create mutation is executed then a random UUID will be generated and stored in the database.
In Neo4j, the
MERGEclause ensures that a pattern exists in the graph. Either the pattern already exists, or it needs to be created. See the Cypher manual for more information.
Add / Remove Relationship
Input types are used for relationship mutations.
Add a relationship with no properties:
and return a special payload type specific to the relationship:
Relationship types with properties have an additional
data parameter for specifying relationship properties:
Used to update properties on a relationship type.
See the relationship types section for more information, including how to declare these types in the schema and the relationship type query API.
config.experimental boolean flag is true, input objects are generated for node property selection and input.
For the following variant of the above schema, using the
@index directives on the
This alternative API would be generated for the
For a node type such as
Movie, this API design generates an input object for a node selection
where argument and an input object for a
data node property input argument. Complex filtering arguments, similar to those used for the
filter argument in the query API, are generated for each key field (
@index) on the
Similar to non-experimental API, when no value is provided for the
@id field of a created node type, that field recieves an auto-generated value using apoc.create.uuid():
This mutation API allows for updating key field values:
Because the Cypher
MERGE clause cannot be combined with
WHERE, node merge operations can use multiple key fields for node selection, but do not have complex filtering options:
In the above
MergeMovie mutation, a value is provided for the
movieId argument, which is an
@id key field on the
Movie type. Similar to node creation, the
apoc.create.uuid procedure is used to generate a value for an
@id key, but only when first creating a node (using the Cypher
ON CREATE clause of
MERGE) and if no value is provided in both the
neo4j-graphql-js supports ordering results through the use of an
orderBy parameter. The augment schema process will add
orderBy to fields as well as appropriate ordering enum types (where values are a combination of each field and
_asc for ascending order and
_desc for descending order). For example:
neo4j-graphql-js support pagination through the use of
offset parameters. These parameters are added to the appropriate fields as part of the schema augmentation process.
filter argument is used to support complex field level filtering in queries.
See the Complex GraphQL Filtering section for details.
In our example schema, no value is provided to the
index argument of the
@search directive on the
title field of the
Movie node type. So a default name of
MovieSearch is used.
The below example would query the
MovieSearch search index for the value
river (case-insensitive) on the
title property of
Movie type nodes. Only matching nodes with a score at or above the
threshold argument would be returned.
search argument is used, the query selects from the results of calling the db.index.fulltext.queryNodes procedure:
The remaining translation of the query is then applied to the yielded nodes. If a value for the
threshold argument is provided, only matching nodes with a resulting
score at or above it will be returned.
search argument is not yet available on relationship fields and using multiple named search index arguments at once is not supported.
The GraphQL specification describes using the
extend keyword to represent a type which has been extended from another type. The following subsections describe the available behaviors, such as extending an object type to represent additional fields. When using schema augmentation, type extensions are applied when building the fields and types used for the generated Query and Mutation API.
The schema type can be extended with operation types.
Scalar types can be extended with additional directives.
Objects & Interfaces
A union type can be extended with additional member types or directives.
Enum types can be extended with additional values or directives.
Input object types can be extended with additional input fields or directives.
Configuring Schema Augmentation
You may not want to generate Query and Mutation fields for all types included in your type definitions, or you may not want to generate a Mutation type at all. Both
makeAugmentedSchema can be passed an optional configuration object to specify which types should be included in queries and mutations.
Disabling Auto-generated Queries and Mutations
By default, both Query and Mutation types are auto-generated from type definitions and will include fields for all types in the schema. An optional
config object can be passed to disable generating either the Query or Mutation type.
makeAugmentedSchema, disable generating the Mutation type:
augmentSchema, disable auto-generating mutations:
To exclude specific types from being included in the generated Query and Mutation types, pass those type names in to the config object under
exclude. For example:
To exclude specific relationships between types from being resolved using the generated neo4j resolver, use the
@neo4j_ignore directive. This is useful when combining other data sources with your neo4j graph. Used alongside excluding types from augmentation, it allows data related to graph nodes to be blended with eth neo4j result. For example:
- Blog post: GraphQL API Configuration With neo4j-graphql.js - Excluding Types From The Auto-Generated GraphQL Schema