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'const context = {// Query APIquery,// Database APIdb,// HTTP request objectreq,res,// Session APIsession,sessionStrategy// GraphQL helpersgraphql: {schema,run,raw,},// New context creatorssudo,withRequest,withSession,// Raw Prisma accessprisma,// Images APIimages: {getUrl,getDataFromRef,getDataFromStream,},}
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 Context
object with access control limitations removed, bypassing your access
control configuration.
withRequest(req, res)
: A function which returns a new Context
object with the .session
determined by your sessionStrategy.get
function.
withSession(newSession)
: A function which returns a new Context
object with the .session
object replaced by the newSession
argument.
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
.
Related resources
Query API Reference →
A programmatic API for running CRUD operations against your GraphQL API. For each list in your system you get an API at context.query.<listName>
DB API Reference →
The API for running CRUD operations against the internal GraphQL resolvers in your system. It returns internal item objects, which can be returned from GraphQL resolvers.