Docs
Launch GraphOS Studio

Resolvers

How Apollo Server processes GraphQL operations


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

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.

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

Defining a resolver

Base syntax

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

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

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

Those definitions look like this:

const resolvers = {
Query: {
numberSix() {
return 6;
},
numberSeven() {
return 7;
},
},
};

As this example shows:

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

Handling arguments

Now let's say our server defines this :

type User {
id: ID!
name: String
}
type Query {
user(id: ID!): User
}

We want to be able to query the user 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:

const users = [
{
id: '1',
name: 'Elizabeth Bennet',
},
{
id: '2',
name: 'Fitzwilliam Darcy',
},
];

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

const resolvers = {
Query: {
user(parent, args, contextValue, info) {
return users.find((user) => user.id === args.id);
},
},
};

As this example shows:

  • A can optionally accept four positional s: (parent, args, contextValue, info).
  • The args is an object that contains all GraphQL s that were provided for the by the GraphQL .

Notice that this example doesn't define s for User s (id and name). That's because the default resolver that Apollo Server creates for these s does the right thing: it obtains the value directly from the object returned by the user .

Passing resolvers to Apollo Server

In the examples below, we use top-level await calls to start our server asynchronously. If you'd like to see how we set this up, check out the Getting Started guide for details.

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

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

Note that you can define your s 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 that returns an , 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 s that return a scalar, an enum, or a list of these.

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

type Product {
id: ID!
name: String
variants: [String!]
availability: Availability!
}
enum Availability {
AVAILABLE
DISCONTINUED
}

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

Example

Let's say our server defines the following :

# A library has a branch and books
type Library {
branch: String!
books: [Book!]
}
# A book has a title and author
type Book {
title: String!
author: Author!
}
# An author has a name
type Author {
name: String!
}
type Query {
libraries: [Library]
}

Here's a valid query against that :

query GetBooksByLibrary {
libraries {
books {
author {
name
}
}
}
}

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

Query.libraries()
Library.books()
Book.author()
Author.name()

These s 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 chain:

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

query GetBooksByLibrary {
libraries {
books {
title
author {
name
}
}
}
}

Then the chain looks like this:

Query.libraries()
Library.books()
Book.title()
Book.author()
Author.name()

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

Resolver arguments

functions are passed four s: parent, args, contextValue, and info (in that order).

You can use any name for each in your code, but the Apollo docs use these names as a convention. Instead of parent, it's also common to use the parent type's name or source.

ArgumentDescription
parent

The return value of the for this 's parent (i.e., the previous resolver in the resolver chain).

For s of top-level s with no parent (such as fields of Query), this value is obtained from the rootValue function passed to Apollo Server's constructor.

args

An object that contains all GraphQL s provided for this .

For example, when executing query{ user(id: "4") }, the args object passed to the user is { "id": "4" }.

contextValue

An object shared across all s that are executing for a particular . Use this to share per-operation state, including authentication information, dataloader instances, and anything else to track across resolvers.

See The contextValue argument for more information.

info

Contains information about the 's execution state, including the name, the path to the field from the root, and more.

Its core s are listed in the GraphQL.js source code. Apollo Server extends it with a cacheControl field.

The contextValue argument

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

Your s can access the shared contextValue object via their third positional . All s that are executing for a particular have access to contextValue:

import { UserAPI } from './datasources/users';
const resolvers = {
Query: {
// Our resolvers can access the fields in contextValue
// from their third argument
currentUser: (_, __, contextValue) => {
return contextValue.dataSources.userApi.findUser(contextValue.token);
},
},
};
interface MyContext {
// Context typing
token?: String;
dataSources: {
userApi: UserAPI;
};
}
const server = new ApolloServer<MyContext>({
typeDefs,
resolvers,
});
const { url } = await startStandaloneServer(server, {
context: async ({ req }) => ({
token: getToken(req.headers.authentication),
dataSources: {
userApi: new UserAPI(),
},
}),
});
import { UserAPI } from './datasources/users';
const resolvers = {
Query: {
// Our resolvers can access the fields in contextValue
// from their third argument
currentUser: (_, __, contextValue) => {
return contextValue.dataSources.userApi.findUser(contextValue.token);
},
},
};
const server = new ApolloServer({
typeDefs,
resolvers,
});
const { url } = await startStandaloneServer(server, {
context: async ({ req }) => ({
token: getToken(req.headers.authentication),
dataSources: {
userApi: new UserAPI(),
},
}),
});

To learn more about manage connections to databases and other s, see Fetching Data.

For more information and examples, see Sharing context.

Return values

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

TypeDescription
Scalar / object

A can return a single value or an object, as shown in Defining a resolver. This return value is passed down to any nested s via the parent .

Array

Return an array if and only if your indicates that the 's associated contains a list.

After you return an array, Apollo Server executes nested s for each item in the array.

null / undefined

Indicates that the value for the could not be found.

If your indicates that this 's is nullable, then the result has a null value at the 's position.

If this 's is not nullable, Apollo Server sets the 's parent to null. If necessary, this process continues up the chain until it reaches a that is nullable. This ensures that a response never includes a null value for a non-nullable . When this happens, the response's errors property will be populated with relevant errors concerning the nullability of that .

Promise

s can be asynchronous and perform async actions, such as fetching from a database or back-end API. To support this, a resolver can return a promise that resolves to any other supported return type.

Default resolvers

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

The default function uses the following logic:

No
Yes
No
Yes
Does the parent argument have a
property with this resolver's exact name?
Return undefined
Is that property's value a function?
Return the property's value
Call the function and
return its return value

As an example, consider the following excerpt:

type Book {
title: String
}
type Author {
books: [Book]
}

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

Resolving unions and interfaces

There are GraphQL types that enable you to define a that returns one of multiple possible s (i.e., unions and interfaces). To resolve a that can return different s, 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 's performance depends on its logic. It's important to understand which of your 's s 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 -level metrics that help you understand the performance of your graph over time. For more information, see Analyzing performance.

Previous
Directives
Next
Sharing context
Edit on GitHubEditForumsDiscord