directive @provides(fields: _FieldSet!) on FIELD_DEFINITION

The @provides directive is used to annotate the expected returned fieldset from a field on a base type that is guaranteed to be selectable by the gateway. This allows you to expose only a subset of fields from the underlying federated object type to be selectable from the federated schema without the need to call other subgraphs. Provided fields specified in the directive field set should correspond to a valid field on the underlying GraphQL interface/object type. @provides directive can only be used on fields returning federated extended objects.

Example 1: We might want to expose only name of the user that submitted a review.

@KeyDirective(FieldSet("id"))
class Review(val id: String) {
  @ProvidesDirective(FieldSet("name"))
  fun user(): User = // implementation goes here
}

@KeyDirective(FieldSet("userId"))
@ExtendsDirective
class User(
  @ExternalDirective val userId: String,
  @ExternalDirective val name: String
)

should generate

type Review @key(fields : "id") {
  id: String!
  user: User! @provides(fields : "name")
}

type User @extends @key(fields : "userId") {
  userId: String! @external
  name: String! @external
}

Example 2: Within our service, one of the queries could resolve all fields locally while other requires resolution from other subgraph

type Query {
  remoteResolution: Foo
  localOnly: Foo @provides("baz")
}

type Foo @key("id") {
  id: ID!
  bar: Bar
  baz: Baz @external
}

In the example above, if user selects baz field, it will be resolved locally from localOnly query but will require another subgraph invocation from remoteResolution query.