---
title: graphql/execution
---

{/* title can be removed in Nextra 4, since sidebar title will take from first h1 */}

# `graphql/execution`

The `graphql/execution` module is responsible for the execution phase of
fulfilling a GraphQL request. You can import either from the `graphql/execution` module, or from the root `graphql` module. For example:

```js
import { execute } from 'graphql';
```

## Overview

<ul className="apiIndex">
  <li>
    <a href="#execute">
      `function execute` Executes a GraphQL request on the provided schema.
    </a>
  </li>
</ul>

## Execution

### execute

```ts
export function execute({
  schema,
  document
  rootValue,
  contextValue,
  variableValues,
  operationName,
  options,
}: ExecutionParams): MaybePromise<ExecutionResult>;

type ExecutionParams = {
  schema: GraphQLSchema;
  document: Document;
  rootValue?: unknown;
  contextValue?: unknown;
  variableValues?: Record<string, unknown>;
  operationName?: string;
  options?: {
    /** Set the maximum number of errors allowed for coercing (defaults to 50). */
    maxCoercionErrors?: number;
  }
};

type MaybePromise<T> = Promise<T> | T;

interface ExecutionResult<
  TData = ObjMap<unknown>,
  TExtensions = ObjMap<unknown>,
> {
  errors?: ReadonlyArray<GraphQLError>;
  data?: TData | null;
  extensions?: TExtensions;
}
```

We have another approach with positional arguments, this is however deprecated and set
to be removed in v17.

```ts
export function execute(
  schema: GraphQLSchema,
  documentAST: Document,
  rootValue?: unknown,
  contextValue?: unknown,
  variableValues?: Record<string, unknown>,
  operationName?: string,
): MaybePromise<ExecutionResult>;
```

Implements the "Evaluating requests" section of the GraphQL specification.

Returns a Promise that will eventually be resolved and never rejected.

If the arguments to this function do not result in a legal execution context,
a GraphQLError will be thrown immediately explaining the invalid input.

`ExecutionResult` represents the result of execution. `data` is the result of
executing the query, `errors` is null if no errors occurred, and is a
non-empty array if an error occurred.

### executeSync

This is a short-hand method that will call `execute` and when the response can
be returned synchronously it will be returned, when a `Promise` is returned this
method will throw an error.

```ts
export function executeSync({
  schema,
  document,
  rootValue,
  contextValue,
  variableValues,
  operationName,
  options,
}: ExecutionParams): MaybePromise<ExecutionResult>;

type ExecutionParams = {
  schema: GraphQLSchema;
  document: Document;
  rootValue?: unknown;
  contextValue?: unknown;
  variableValues?: Record<string, unknown>;
  operationName?: string;
  options?: {
    /** Set the maximum number of errors allowed for coercing (defaults to 50). */
    maxCoercionErrors?: number;
  }
};

type MaybePromise<T> = Promise<T> | T;

interface ExecutionResult<
  TData = ObjMap<unknown>,
  TExtensions = ObjMap<unknown>,
> {
  errors?: ReadonlyArray<GraphQLError>;
  data?: TData | null;
  extensions?: TExtensions;
}
```

We have another approach with positional arguments, this is however deprecated and set
to be removed in v17.

```ts
export function executeSync(
  schema: GraphQLSchema,
  documentAST: Document,
  rootValue?: unknown,
  contextValue?: unknown,
  variableValues?: Record<string, unknown>,
  operationName?: string,
): ExecutionResult;
```

#### Execution options

##### maxCoercionErrors

Set the maximum number of errors allowed for coercing variables, this implements a default limit of 50 errors.
