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:
const server = new ApolloServer({schema: buildSubgraphSchema({ typeDefs, resolvers }),});
const server = new ApolloServer({schema: buildSubgraphSchema({ typeDefs, resolvers }),});
Used when defining a subgraph in a federated graph.
Each schema module is an object with the following format:
{typeDefs: DocumentNode,resolvers: ResolverMap}
Parameters
| Name / Type | Description |
|---|---|
| Required. A schema module object (or an array of them) with the structure shown above. |
Example
import gql from 'graphql-tag';import { ApolloServer } from '@apollo/server';import { buildSubgraphSchema } from '@apollo/subgraph';const typeDefs = gql`type Query {me: User}type User @key(fields: "id") {id: ID!username: String}`;const resolvers = {Query: {me() {return { id: '1', username: '@ava' };},},User: {__resolveReference(user, { fetchUserById }) {return fetchUserById(user.id);},},};const server = new ApolloServer({schema: buildSubgraphSchema({ typeDefs, resolvers }),});
import gql from 'graphql-tag';import { ApolloServer } from '@apollo/server';import { buildSubgraphSchema } from '@apollo/subgraph';const typeDefs = gql`type Query {me: User}type User @key(fields: "id") {id: ID!username: String}`;const resolvers = {Query: {me() {return { id: '1', username: '@ava' };},},User: {__resolveReference(user, { fetchUserById }) {return fetchUserById(user.id);},},};const server = new ApolloServer({schema: buildSubgraphSchema({ typeDefs, resolvers }),});
__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
| Name / Type | Description |
|---|---|
| The representation of the entity that's passed from another subgraph. This object includes a |
| An object that's passed to every resolver that executes for a particular operation, enabling resolvers to share helpful context. Within resolvers and plugins, this object is named |
| 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. |
Example
const typeDefs = gql`type User @key(fields: "id") {id: ID!username: String}`;const resolvers = {User: {__resolveReference(user, { dataSources }) {// user will always have at least the `id` and the `__typename` herereturn dataSources.users.fetchUserById(user.id);},},};
const typeDefs = gql`type User @key(fields: "id") {id: ID!username: String}`;const resolvers = {User: {__resolveReference(user, { dataSources }) {// user will always have at least the `id` and the `__typename` herereturn dataSources.users.fetchUserById(user.id);},},};