Context Overview

The Context object is the primary API entry point for all of the run-time functionality of your Keystone system. In GraphQL, a context is a value which is provided to every resolver and holds important contextual information such as the currently logged in user, or access to a database. Keystone makes a Context object available as the context of all resolvers in the system. The APIs provided by the Context object can be used to write the business logic for things like access control, hooks, testing and GraphQL schema extensions.

The Context object has the following properties, which are documented below.

import type { Context } from '.keystone/types';

context = {
  // HTTP request object
  req,
res,

  // Query API
  query,

  // Internal DB object API
  db,

  // GraphQL helpers
  graphql: {
    schema,
    run,
    raw,
  },

  // Session API
  session,
  sessionStrategy

  // New context creators
  sudo,
  exitSudo,
  withSession,
  withRequest,

  // Database access
  prisma,

  // Images API
  images: {
    getUrl,
    getDataFromRef,
    getDataFromStream,
  },

  // Deprecated
  gqlNames,
};

HTTP request object

req: The IncomingMessage object from the HTTP request. res: The ServerResonse object for HTTP request.

Query API

query: The Query API, which can be used to perform CRUD operations against your GraphQL API and return a queried value.

Database API

db: The Database API, which can be used to perform CRUD operations against your GraphQL API and return database objects suitable for return from mutations in schema extensions.

GraphQL helpers

graphql.schema: The GraphQL Schema object, which can be used directly, or via graphql.raw and graphql.run.

graphql.raw: An async function which takes ({ query, variables }) and executes the query against the GraphQL schema, returning { data, errors }. query can be either a string or a GraphQL Document. variables is an optional object containing the input variables for the query. The returned object is an ExecutionResult. This query uses the current context object as its context.

graphql.run: An async function which takes ({ query, variables }) and executes the query against the GraphQL schema, returning data. query can be either a string or a GraphQL Document. variables is an optional object containing the input variables for the query. The returned object is an ExecutionResult.data. Any errors generated by the query will be thrown as an exception. This query uses the current context object as its context.

See the schema extension guide for examples of using these functions.

Session API

If you configure your Keystone system with session management then you will have access to the following properties. See the session API for more details.

session: The current session data object.

sessionStrategy: an object containing functions(get, start and end) that manipulate a session. See the session API for more details.

New context creators

When using the context.query, context.graphql.run, and context.graphql.raw APIs, access control and session information is passed through to these calls from the context object. The following functions will create a new Context object with this behaviour modified.

sudo(): A function which returns a new elevated Context object with all access control disabled and all filters enabled for subsequent API calls.

withRequest(req, res): A function which returns a new user Context object with a session and access control based on the req given.

withSession(newSession): A function which returns a new Context object with the .session object replaced with newSession.

Database access

The Context object exposes the underlying database driver directly via context.prisma, which is a Prisma Client object.

Images API

If support for image fields is enabled in the system, then an images API will be made available on the context object. This API takes advantage of the following types:

type ImageMode = 'local';

type ImageExtension = 'jpg' | 'png' | 'webp' | 'gif';

type ImageData = {
  mode: ImageMode;
  id: string;
  extension: ImageExtension;
  filesize: number;
  width: number;
  height: number;
};

image.getUrl(mode, id, extension): Given a mode, id, and extension from an ImageData object, returns the src value representing the location from which the image can be accessed over HTTP.

async images.getDataFromRef(ref): Given a ref string, taken from the id field of an existing image, returns an ImageData object.

async images.getDataFromStream(stream): Given a readable data stream, returns an ImageData object. The mode will be taken from config.images.mode, and id will be a uuid value. The other values will be inferred from the data stream itself. The contents of the stream will be written to the filesystem at config.images.local.storagePath.

Deprecated

The following properties are deprecated and should not be used. They will be removed in future releases.

gqlNames: A function which takes a listKey and returns an object containing the GraphQL query, mutation and type names related to that list.

Related resources