Keystone 6: Server-Side Query APIs

[molomby]

In Keystone 5, if you wanted to query the database from in server-side code, you'd probably reach for either:

• keystone.executeQuery()
• context.executeGraphQL()
• Or by talking directly to the adapter, eg. keystone.adapters['KnexAdapter'].knex

Keystone 6 replaces these with several new APIs:

• The Query API at context.query – A typed programmatic API for running CRUD operations against your GraphQL API.
• The Database API at context.db – This looks superficially similar to the query API but deals with the internal item objects. This is what you should use if the result is to be returned via a GraphQL resolvers.
• Some GraphQL helper functions at context.graphql.run and context.graphql.raw – These are more similar to how you'd use the GraphQL API remotely, that is, you supply the full GraphQL query as a string, rather than dealing with a JavaScript API.
• The Prisma API at context.prisma – The raw Prisma Client object used internally by Keystone.

For example, consider this server-side Keystone 5 code that uses keystone.executeQuery() to loads a set of users, based on a partial name match, and retrieves their published posts:

const { errors, data } = await keystone.executeQuery(
  `
    query($partialName: String) {
      allUsers (
        where: { name_starts_with_i: $partialName }
        first: 10
        orderBy: "name_desc"
      ) {
        id
        name
        posts (where: { status: published }) {
          id
          slug
          title
        }
      }
    }
  `,
  { variables: { partialName } }
);
if (errors) {
  throw errors;
}
const users = data.allUsers;

In Keystone 6 you'd likely use the query API instead:

const users = await context.query.User.findMany({
  where: { name: { startsWith: partialName } },
  take: 10,
  orderBy: [{ name: 'desc' }],
  query: `
    id
    name
    posts ( where: { status: { equals: published } }) {
      id
      slug
      title
    }
  `,
});

Note that the GraphQL API itself has also been updated. These changes are described in detail on the Docs site; see also the discussion here on GitHub.