We’re overhauling Dgraph’s docs to make them clearer and more approachable. If
you notice any issues during this transition or have suggestions, please
let us know.
Support for Apollo federation directives
The current implementation supports the following five directives:@key
,
@extends
, @external
, @provides
, and @requires
.
@key
directive
This directive takes one field argument inside it: the @key
field. There are
few limitations on how to use @key
directives:
- Users can define the
@key
directive only once for a type - Support for multiple key fields isn’t currently available.
- Since the
@key
field acts as a foreign key to resolve entities from the service where it’s extended, the field provided as an argument inside the@key
directive should be ofID
type or have the@id
directive on it.
@extends
directive
This directive provides support for extended definitions. For example, if the
User
type is defined in some other service, you can extend it in Dgraph’s
GraphQL service by using the @extends
directive, as follows:
extend
keyword. Either syntax to extend a
type into your Dgraph GraphQL service works: extend type User ...
or
type User @extends ...
.
@external
directive
You use this directive when the given field isn’t stored in this service. It can
only be used on extended type definitions. For instance, it’s used in this
example on the id
field of the User
type.
@provides
directive
You use this directive on a field that tells the gateway to return a specific
set of fields from the base type while fetching the field.
For example -
Review.product
from the review
service, and if the name
or
price
is also queried, the gateway fetches these from the review
service
itself. So, the review
service also resolves these fields, even though both
fields are @external
.
@requires
directive
You use this directive on a field to annotate the fields of the base type. You
can use it to develop a query plan where the required fields may not be needed
by the client, but the service may need additional information from other
services.
For example -
user.reviews
from the review
service, the gateway
gets user.email
from the User
service and provides it as an argument to the
_entities
query.
Using @requires
alone on a field doesn’t make much sense. In cases where you
need to use @requires
, you should also add some custom logic on that field.
You can add such logic using the @lambda
or @custom(http: {...})
directives.
Here’s an example -
-
Schema:
-
Lambda script:
Generated queries and mutations
In this section, you’ll see what queries and mutations are available to individual service and to the Apollo gateway. Let’s take the below schema as an example:Astronaut
aren’t exposed to the gateway because they resolve
through the _entities
resolver. However, these queries are available on the
Dgraph GraphQL API endpoint.
Mutation for extended
types
If you want to add an object of Astronaut
type which is extended in this
service. The mutation addAstronaut
takes AddAstronautInput
, which is
generated as follows:
id
field is of ID
type, which is usually generated internally by Dgraph.
But, In this case, it’s provided as an input. The user should provide the same
id
value present in the GraphQL service where the type Astronaut
is defined.
For example, let’s assume that the type Astronaut
is defined in some other
service, AstronautService
, as follows:
Astronaut
, you should first add it to the
AstronautService
service. Then, you can call the addAstronaut
mutation with
the value of id
provided as an argument that must be equal to the value in
AstronautService
service.