API Reference: @apollo/subgraph

Apollo Federation API reference


This API reference documents the exports from the @apollo/subgraph package.

buildSubgraphSchema

This method previously existed in the @apollo/federation package and was renamed from buildFederatedSchema after @apollo/federation v0.28.0 (the previous name still works but might be removed in a future release).

A function that takes a schema module object (or an array of them) and returns a federation-ready subgraph schema:

JavaScript
1const server = new ApolloServer({
2  schema: buildSubgraphSchema({ typeDefs, resolvers })
3});

Used when defining a subgraph in a federated graph.

Each schema module is an object with the following format:

JavaScript
1{
2  typeDefs: DocumentNode,
3  resolvers: ResolverMap
4}

Parameters

Name /
Type
Description
modules
Object or Array
Required. A schema module object (or an array of them) with the structure shown above.

Example

JavaScript
1const typeDefs = gql`
2  type Query {
3    me: User
4  }
5
6  type User @key(fields: "id") {
7    id: ID!
8    username: String
9  }
10`;
11
12const resolvers = {
13  Query: {
14    me() {
15      return { id: "1", username: "@ava" }
16    }
17  },
18  User: {
19    __resolveReference(user, { fetchUserById }){
20      return fetchUserById(user.id)
21    }
22  }
23};
24
25const server = new ApolloServer({
26  schema: buildSubgraphSchema({ typeDefs, resolvers })
27});

__resolveReference

The name of a special reference resolver function you can define for every entity in a resolver map, if that resolver map is part of a subgraph schema .

The __resolveReference function enables your gateway's query planner to resolve a particular entity by whatever unique identifier your other subgraphs use to reference it. For details, see Resolving entities .

The function takes the parameters listed below.

Parameters

Name /
Type
Description
reference
Object
The representation of the entity that's passed from another subgraph.This object includes a __typename field, along with whichever fields the subgraph uses for the entity's @key.
context
Object
An object that's passed to every resolver that executes for a particular operation. This enables resolvers to share helpful context, including any relevant DataSources.For details, see The context argument .
info
Object
Contains information about the operation's execution state, including the field name, the path to the field from the root, and more.This object's core fields are listed in the GraphQL.js source code , and it is extended with additional functionality by other modules, like apollo-cache-control .

Example

JavaScript
1const typeDefs = gql`
2  type User @key(fields: "id") {
3    id: ID!
4    username: String
5  }
6`;
7
8const resolvers = {
9  User: {
10    __resolveReference(user, { datasources }){
11      // user will always have at least the `id` and the `__typename` here
12      return datasources.users.fetchUserById(user.id)
13    }
14  }
15};