Resolvers

Apollo Server needs to know how to populate data for every field in your schema so that it can respond to requests for that data. To accomplish this, it uses resolvers.

A resolver is a function that's responsible for populating the data for a single field in your schema. It can populate that data in any way you define, such as by fetching data from a back-end database or a third-party API.

Defining a resolver

Base syntax

Let's say our server defines the following (very short) schema:

1
type Query {
2
  numberSix: Int! # Should always return the number 6 when queried
3
  numberSeven: Int! # Should always return 7
4
}

We want to define resolvers for the numberSix and numberSeven fields of the root Query type so that they always return 6 and 7 when they're queried.

Those resolver definitions look like this:

1
const resolvers = {
2
  Query: {
3
    numberSix() {
4
      return 6;
5
    },
6
    numberSeven() {
7
      return 7;
8
    },
9
  },
10
};

As this example shows:

• You define all of your server's resolvers in a single JavaScript object (named resolvers above). This object is called the resolver map.
• The resolver map has top-level fields that correspond to your schema's types (such as Query above).
• Each resolver function belongs to whichever type its corresponding field belongs to.

Handling arguments

Now let's say our server defines this schema:

1
type User {
2
  id: ID!
3
  name: String
4
}
5

6
type Query {
7
  user(id: ID!): User
8
}

We want to be able to query the user field to fetch a user by its id.

To achieve this, our server needs access to user data. For this contrived example, assume our server defines the following hardcoded array:

1
const users = [
2
  {
3
    id: '1',
4
    name: 'Elizabeth Bennet',
5
  },
6
  {
7
    id: '2',
8
    name: 'Fitzwilliam Darcy',
9
  },
10
];

Now we can define a resolver for the user field, like so:

1
const resolvers = {
2
  Query: {
3
    user(parent, args, context, info) {
4
      return users.find((user) => user.id === args.id);
5
    },
6
  },
7
};

As this example shows:

• A resolver can optionally accept four positional arguments: (parent, args, context, info).
  • Learn more about these arguments.
• The args argument is an object that contains all GraphQL arguments that were provided for the field by the GraphQL operation.

Passing resolvers to Apollo Server

After you define all of your resolvers, you pass them to the constructor of ApolloServer (as the resolvers property), along with your schema's definition (as the typeDefs property).

The following example defines a hardcoded data set, a schema, and a resolver map. It then initializes an ApolloServer instance, passing the schema and resolvers to it.

1
import { ApolloServer } from '@apollo/server';
2
import { startStandaloneServer } from '@apollo/server/standalone';
3

4
// Hardcoded data store
5
const books = [
6
  {
7
    title: 'The Awakening',
8
    author: 'Kate Chopin',
9
  },
10
  {
11
    title: 'City of Glass',
12
    author: 'Paul Auster',
13
  },
14
];
15

16
// Schema definition
17
const typeDefs = `#graphql
18
  type Book {
19
    title: String
20
    author: String
21
  }
22

23
  type Query {
24
    books: [Book]
25
  }
26
`;
27

28
// Resolver map
29
const resolvers = {
30
  Query: {
31
    books() {
32
      return books;
33
    },
34
  },
35
};
36

37
// Pass schema definition and resolvers to the
38
// ApolloServer constructor
39
const server = new ApolloServer({
40
  typeDefs,
41
  resolvers,
42
});
43

44
// Launch the server
45
const { url } = await startStandaloneServer(server);
46

47
console.log(`🚀 Server listening at: ${url}`);

Note that you can define your resolvers across as many different files and objects as you want, as long as you merge all of them into a single resolver map that's passed to the ApolloServer constructor.

Resolver chains

Whenever a query asks for a field that returns an object type, the query also asks for at least one field of that object (if it didn't, there would be no reason to include the object in the query). A query always "bottoms out" on fields that return a scalar, an enum, or a list of these.

For example, all fields of this Product type "bottom out":

1
type Product {
2
  id: ID!
3
  name: String
4
  variants: [String!]
5
  availability: Availability!
6
}
7

8
enum Availability {
9
  AVAILABLE
10
  DISCONTINUED
11
}

Because of this rule, whenever Apollo Server resolves a field that returns an object type, it always then resolves one or more fields of that object. Those subfields might in turn also contain object types. Depending on your schema, this object-field pattern can continue to an arbitrary depth, creating what's called a resolver chain.

Example

Let's say our server defines the following schema:

1
# A library has a branch and books
2
type Library {
3
  branch: String!
4
  books: [Book!]
5
}
6

7
# A book has a title and author
8
type Book {
9
  title: String!
10
  author: Author!
11
}
12

13
# An author has a name
14
type Author {
15
  name: String!
16
}
17

18
type Query {
19
  libraries: [Library]
20
}

Here's a valid query against that schema:

1
query GetBooksByLibrary {
2
  libraries {
3
    books {
4
      author {
5
        name
6
      }
7
    }
8
  }
9
}

The resulting resolver chain for this query matches the hierarchical structure of the query itself:

These resolvers execute in the order shown above, and they each pass their return value to the next resolver in the chain via the parent argument.

Here's a code sample that can resolve the query above with this resolver chain:

1
import { ApolloServer } from '@apollo/server';
2
import { startStandaloneServer } from '@apollo/server/standalone';
3

4
const libraries = [
5
  {
6
    branch: 'downtown',
7
  },
8
  {
9
    branch: 'riverside',
10
  },
11
];
12

13
// The branch field of a book indicates which library has it in stock
14
const books = [
15
  {
16
    title: 'The Awakening',
17
    author: 'Kate Chopin',
18
    branch: 'riverside',
19
  },
20
  {
21
    title: 'City of Glass',
22
    author: 'Paul Auster',
23
    branch: 'downtown',
24
  },
25
];
26

27
// Schema definition
28
const typeDefs = `#graphql
29
  # A library has a branch and books
30
  type Library {
31
    branch: String!
32
    books: [Book!]
33
  }
34

35
  # A book has a title and author
36
  type Book {
37
    title: String!
38
    author: Author!
39
  }
40

41
  # An author has a name
42
  type Author {
43
    name: String!
44
  }
45

46
  # Queries can fetch a list of libraries
47
  type Query {
48
    libraries: [Library]
49
  }
50
`;
51

52
// Resolver map
53
const resolvers = {
54
  Query: {
55
    libraries() {
56
      // Return our hardcoded array of libraries
57
      return libraries;
58
    },
59
  },
60
  Library: {
61
    books(parent) {
62
      // Filter the hardcoded array of books to only include
63
      // books that are located at the correct branch
64
      return books.filter((book) => book.branch === parent.branch);
65
    },
66
  },
67
  Book: {
68
    // The parent resolver (Library.books) returns an object with the
69
    // author's name in the "author" field. Return a JSON object containing
70
    // the name, because this field expects an object.
71
    author(parent) {
72
      return {
73
        name: parent.author,
74
      };
75
    },
76
  },
77

78
  // Because Book.author returns an object with a "name" field,
79
  // Apollo Server's default resolver for Author.name will work.
80
  // We don't need to define one.
81
};
82

83
// Pass schema definition and resolvers to the
84
// ApolloServer constructor
85
const server = new ApolloServer({
86
  typeDefs,
87
  resolvers,
88
});
89

90
// Launch the server
91
const { url } = await startStandaloneServer(server);
92

93
console.log(`🚀 Server listening at: ${url}`);

If we now update our query to also ask for each book's title:

1
query GetBooksByLibrary {
2
  libraries {
3
    books {
4
      title
5
      author {
6
        name
7
      }
8
    }
9
  }
10
}

Then the resolver chain looks like this:

When a chain "diverges" like this, each subchain executes in parallel.

Resolver arguments

Resolver functions are passed four arguments: parent, args, context, and info (in that order).

The context argument

The context argument is useful for passing things that any resolver might need, like authentication scope, sources for fetching data, database connections, and custom fetch functions. If you're using dataloaders to batch requests across resolvers, you can attach them to the context as well.

Resolvers should never destructively modify the context argument. This ensures consistency across all resolvers and prevents unexpected errors.

To provide an initial context to your resolvers, add an asynchronous context initialization function to your integration function (e.g., expressMiddleware or startStandaloneServer). This function is called with every request, so you can customize the context based on each request's details (such as HTTP headers).

1
import { GraphQLError } from 'graphql';
2

3
const resolvers = {
4
  Query: {
5
  // Example resolver
6
    adminExample: (parent, args, context, info) => {
7
      if (context.authScope !== ADMIN) {
8
        throw new GraphQLError('not admin!', {
9
          extensions: { code: 'UNAUTHENTICATED' }
10
        });
11
      }
12
    },
13
  },
14
};
15

16
interface MyContext { // Context typing
17
  authScope?: String;
18
}
19

20
const server = new ApolloServer<MyContext>({
21
  typeDefs,
22
  resolvers,
23
});
24

25
const { url } = await startStandaloneServer(server, {
26
  // A named context function is required if you are not
27
  // using ApolloServer<BaseContext>
28
  context: async ({req, res}) => ({
29
      authScope: getScope(req.headers.authorization),
30
  })
31
});

1
import { GraphQLError } from 'graphql';
2

3
const resolvers = {
4
  Query: {
5
    // Example resolver
6
    adminExample: (parent, args, context, info) => {
7
      if (context.authScope !== ADMIN) {
8
        throw new GraphQLError('not admin!', {
9
          extensions: { code: 'UNAUTHENTICATED' },
10
        });
11
      }
12
    },
13
  },
14
};
15

16
const server = new ApolloServer({
17
  typeDefs,
18
  resolvers,
19
});
20

21
const { url } = await startStandaloneServer(server, {
22
  // A named context function is required if you are not
23
  // using ApolloServer<BaseContext>
24
  context: async ({ req, res }) => ({
25
    authScope: getScope(req.headers.authorization),
26
  }),
27
});

The context function should be asynchronous and return an object, which is then accessible to your server's resolvers and plugins (via the contextValue field).

Because the context initialization function is asynchronous, you can use it to establish database connections and wait for other operations to complete:

1
context: async () => ({
2
  db: await client.connect(),
3
})
4

5
// Resolver
6
(parent, args, context, info) => {
7
  return context.db.query('SELECT * FROM table_name');
8
}

Throwing errors in context

By default, if your context function throws an error, Apollo Server returns that error to the user in a JSON response with an HTTP status code of 500. If the thrown error is not a GraphQLError, the error's message will be prepended with "Context creation failed: ".

You can control the HTTP status code of an error by throwing a GraphQLError with an http extension. For example:

1
context: async ({ req }) => {
2
  const user = await getUserFromReq(req);
3
  if (!user) {
4
    throw new GraphQLError('User is not authenticated', {
5
      extensions: {
6
        code: 'UNAUTHENTICATED',
7
        http: { status: 401 },
8
      }
9
    });
10
  }
11

12
  // If this throws a non-GraphQLError, it will be rendered with
13
  // `code: "INTERNAL_SERVER_ERROR"` and HTTP status code 500, and
14
  // with a message starting with "Context creation failed: ".
15
  const db = await getDatabaseConnection();
16

17
  return { user, db };
18
},

Return values

A resolver function's return value is treated differently by Apollo Server depending on its type:

Default resolvers

If you don't define a resolver for a particular schema field, Apollo Server defines a default resolver for it.

The default resolver function uses the following logic:

As an example, consider the following schema excerpt:

1
type Book {
2
  title: String
3
}
4

5
type Author {
6
  books: [Book]
7
}

If the resolver for the books field returns an array of objects that each contain a title field, then you can use a default resolver for the title field. The default resolver will correctly return parent.title.

Resolving unions and interfaces

There are GraphQL types that enable you to define a field that returns one of multiple possible object types (i.e., unions and interfaces). To resolve a field that can return different object types, you must define a __resolveType function to inform Apollo Server which type of object is being returned.

Resolving federated entities

See Resolving Entities.

Monitoring resolver performance

As with all code, a resolver's performance depends on its logic. It's important to understand which of your schema's fields are computationally expensive or otherwise slow to resolve, so that you can either improve their performance or make sure you only query them when necessary.

Apollo Studio integrates directly with Apollo Server to provide field-level metrics that help you understand the performance of your graph over time. For more information, see Analyzing performance.