API Reference: @apollo/subgraph

This API reference documents the exports from the @apollo/subgraph package. This package enables you to use Apollo Server as a subgraph in a federated supergraph. For more information, see Implementing a subgraph with Apollo Server.

Note, we recommend using @apollo/subgraph with Apollo Server, but it is compatible with any GraphQL server built on graphql-js.

buildSubgraphSchema

This method was renamed from buildFederatedSchema after @apollo/federation v0.28.0 (the previous name still works, but it 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:

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:

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

Parameters

Example

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

__resolveReference

The name of a special reference resolver function you can define for every entity in a subgraph schema's resolver map.

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

If the entity can be resolved, __resolveReference returns the entity. Otherwise, it returns null.

The function takes the parameters listed below.

Parameters

Example

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};