GraphQL | GraphQL

The root graphql package re-exports the public GraphQL.js API from its submodules and provides the high-level request pipeline helpers defined in this module.

You can import public exports from GraphQL.js modules through the root graphql package or through their module-specific entry point. For example, these two references resolve to the same parse function:

import { parse } from 'graphql';
import { parse } from 'graphql/language';

Use the root package when you want a single import surface, or use submodules such as graphql/language, graphql/type, graphql/execution, and graphql/utilities when you want module-focused imports. This module also defines root-only APIs, such as request pipeline helpers and version metadata, that do not belong to a narrower submodule.

For documentation purposes, these exports are grouped into the following categories:

Category: Request Pipeline

Functions:
graphql()graphqlSync()

Types:
GraphQLArgs

Functions

graphql()

Parses, validates, and executes a GraphQL document against a schema.

This is the primary entry point for fulfilling GraphQL operations. Use this when you want a single-call request lifecycle that returns a promise in all cases.

More sophisticated GraphQL servers, such as those which persist queries, may wish to separate the validation and execution phases to a static-time tooling step and a server runtime step.

Signature:

graphql(
  args: GraphQLArgs,
): Promise<ExecutionResult>;

Arguments

Name	Type	Description
args	`GraphQLArgs`	Request execution arguments, including schema and source.

Returns

Type	Description
`Promise<ExecutionResult>`	A promise that resolves to an execution result or validation errors.

Example 1

// Execute a complete asynchronous request with variables.
import { graphql, buildSchema } from 'graphql';
 
const schema = buildSchema(`
  type Query {
    greeting(name: String!): String
  }
`);
 
const result = await graphql({
  schema,
  source: 'query SayHello($name: String!) { greeting(name: $name) }',
  rootValue: {
    greeting: ({ name }) => `Hello, ${name}!`,
  },
  variableValues: { name: 'Ada' },
  operationName: 'SayHello',
});
 
result; // => { data: { greeting: 'Hello, Ada!' } }

Example 2

// This variant supplies context plus custom field and type resolvers.
import { graphql, buildSchema } from 'graphql';
 
const schema = buildSchema(`
  interface Named {
    name: String!
  }
 
  type User implements Named {
    name: String!
  }
 
  type Query {
    viewer: Named
  }
`);
 
const result = await graphql({
  schema,
  source: '{ viewer { __typename name } }',
  rootValue: { viewer: { kind: 'user', name: 'Ada' } },
  contextValue: { locale: 'en' },
  fieldResolver: (source, _args, context, info) => {
    context.locale; // => 'en'
    return source[info.fieldName];
  },
  typeResolver: (value) => {
    return value.kind === 'user' ? 'User' : undefined;
  },
});
 
result; // => { data: { viewer: { __typename: 'User', name: 'Ada' } } }

graphqlSync()

Parses, validates, and executes a GraphQL document synchronously.

This function guarantees that execution completes synchronously, or throws an error, assuming that all field resolvers are also synchronous. It throws when any resolver returns a promise.

Signature:

graphqlSync(
  args: GraphQLArgs,
): ExecutionResult;

Arguments

Name	Type	Description
args	`GraphQLArgs`	Request execution arguments, including schema and source.

Returns

Type	Description
`ExecutionResult`	Completed execution output, or request errors if parsing or validation fails.

Example 1

// Execute a complete synchronous request with variables.
import { graphqlSync, buildSchema } from 'graphql';
 
const schema = buildSchema(`
  type Query {
    greeting(name: String!): String
  }
`);
 
const result = graphqlSync({
  schema,
  source: 'query SayHello($name: String!) { greeting(name: $name) }',
  rootValue: {
    greeting: ({ name }) => `Hello, ${name}!`,
  },
  variableValues: { name: 'Ada' },
  operationName: 'SayHello',
});
 
result; // => { data: { greeting: 'Hello, Ada!' } }

Example 2

// This variant uses a synchronous custom field resolver and context.
import { graphqlSync, buildSchema } from 'graphql';
 
const schema = buildSchema(`
  type Query {
    greeting: String
  }
`);
 
const result = graphqlSync({
  schema,
  source: '{ greeting }',
  fieldResolver: (_source, _args, contextValue) => {
    return contextValue.defaultGreeting;
  },
  contextValue: { defaultGreeting: 'Hello' },
});
 
result; // => { data: { greeting: 'Hello' } }

Types

GraphQLArgs

Interface. Describes the input object accepted by graphql and graphqlSync.

These arguments describe the full parse, validate, and execute lifecycle for a GraphQL request.

Members

Name	Type	Description
schema	`GraphQLSchema`	The GraphQL type system to use when validating and executing a query.
source	`string \| Source`	A GraphQL language-formatted string or source object representing the requested operation.
rootValue?	`unknown`	The value provided as the first argument to resolver functions on the top level type, such as the query object type.
contextValue?	`unknown`	Application context value passed to every resolver. Use this for shared request data such as the currently logged in user and connections to databases or other services.
variableValues?	`Maybe<{ readonly [variable: string]: unknown; }>`	A mapping of variable name to runtime value for variables defined by the operation.
operationName?	`Maybe<string>`	The operation to execute when the source contains multiple possible operations. This can be omitted when the source contains only one operation.
fieldResolver?	`Maybe<GraphQLFieldResolver<any, any>>`	A resolver function to use when one is not provided by the schema. If not provided, the default field resolver is used, which looks for a value or method on the source value with the field’s name.
typeResolver?	`Maybe<GraphQLTypeResolver<any, any>>`	A type resolver function to use when none is provided by the schema. If not provided, the default type resolver is used, which looks for a `__typename` field or alternatively calls the `isTypeOf` method.

Category: Version

Constants:
version versionInfo

Constants

version

A string containing the version of the GraphQL.js library

Type

string

versionInfo

An object containing the components of the GraphQL.js version string

Type

Readonly<{
  major: number;
  minor: number;
  patch: number;
  preReleaseTag: string | null;
}>

graphql/error