GraphQL API

We recently improved this API so it’s easier to program and reason about. If you were using it prior to August 17th 2021, read this guide for info on how to upgrade.

Keystone generates a CRUD (create, read, update, delete) GraphQL API based on the schema definition provided in the system config.

Consider the following system definition:

import { config, createSchema, list } from '@keystone-next/keystone';
import { text } from '@keystone-next/keystone/fields';

export default config({
  lists: createSchema({
    User: list({ fields: { name: text({ isOrderable: true }) } }),
  }),
  /* ... */
});

This system will generate the following GraphQL API.

Note: The names and types of the generated queries and mutations are based on the names of the lists and fields in the system config.

type Query {
  users(
    where: UserWhereInput! = {}
    orderBy: [UserOrderByInput!]! = []
    take: Int
    skip: Int! = 0
  ): [User!]
  user(where: UserWhereUniqueInput!): User
  usersCount(where: UserWhereInput! = {}): Int
}

type User {
  id: ID!
  name: String
}

input UserWhereUniqueInput {
  id: ID
}

input UserWhereInput {
  AND: [UserWhereInput!]
  OR: [UserWhereInput!]
  NOT: [UserWhereInput!]
  id: IDFilter
  name: StringNullableFilter
}

input IDFilter {
  equals: ID
  in: [ID!]
  notIn: [ID!]
  lt: ID
  lte: ID
  gt: ID
  gte: ID
  not: IDFilter
}

input StringNullableFilter {
  equals: String
  in: [String!]
  notIn: [String!]
  lt: String
  lte: String
  gt: String
  gte: String
  contains: String
  startsWith: String
  endsWith: String
  mode: QueryMode
  not: NestedStringNullableFilter
}

enum QueryMode {
  default
  insensitive
}

input NestedStringNullableFilter {
  equals: String
  in: [String!]
  notIn: [String!]
  lt: String
  lte: String
  gt: String
  gte: String
  contains: String
  startsWith: String
  endsWith: String
  not: NestedStringNullableFilter
}

input UserOrderByInput {
  id: OrderDirection
  name: OrderDirection
}

enum OrderDirection {
  asc
  desc
}

type Mutation {
  createUser(data: UserCreateInput!): User
  createUsers(data: [UserCreateInput!]!): [User]
  updateUser(where: UserWhereUniqueInput!, data: UserUpdateInput!): User
  updateUsers(data: [UserUpdateArgs!]!): [User]
  deleteUser(where: UserWhereUniqueInput!): User
  deleteUsers(where: [UserWhereUniqueInput!]!): [User]
}

input UserUpdateInput {
  name: String
}

input UserUpdateArgs {
  where: UserWhereUniqueInput!
  data: UserUpdateInput!
}

input UserCreateInput {
  name: String
}

Queries

user

type Query {
  user(where: UserWhereUniqueInput!): User
}

type User {
  id: ID!
  name: String
}

input UserWhereUniqueInput {
  id: ID
}

users

type Query {
  users(
    where: UserWhereInput! = {}
    orderBy: [UserOrderByInput!]! = []
    take: Int
    skip: Int! = 0
  ): [User!]
}

type User {
  id: ID!
  name: String
}

input UserWhereInput {
  AND: [UserWhereInput!]
  OR: [UserWhereInput!]
  NOT: [UserWhereInput!]
  id: IDFilter
  name: StringNullableFilter
}

input IDFilter {
  equals: ID
  in: [ID!]
  notIn: [ID!]
  lt: ID
  lte: ID
  gt: ID
  gte: ID
  not: IDFilter
}

input StringNullableFilter {
  equals: String
  in: [String!]
  notIn: [String!]
  lt: String
  lte: String
  gt: String
  gte: String
  contains: String
  startsWith: String
  endsWith: String
  mode: QueryMode
  not: NestedStringNullableFilter
}

enum QueryMode {
  default
  insensitive
}

input NestedStringNullableFilter {
  equals: String
  in: [String!]
  notIn: [String!]
  lt: String
  lte: String
  gt: String
  gte: String
  contains: String
  startsWith: String
  endsWith: String
  not: NestedStringNullableFilter
}

input UserOrderByInput {
  id: OrderDirection
  name: OrderDirection
}

enum OrderDirection {
  asc
  desc
}

usersCount

type Query {
  usersCount(where: UserWhereInput! = {}): Int
}

input UserWhereInput {
  AND: [UserWhereInput!]
  OR: [UserWhereInput!]
  NOT: [UserWhereInput!]
  id: IDFilter
  name: StringNullableFilter
}

input IDFilter {
  equals: ID
  in: [ID!]
  notIn: [ID!]
  lt: ID
  lte: ID
  gt: ID
  gte: ID
  not: IDFilter
}

input StringNullableFilter {
  equals: String
  in: [String!]
  notIn: [String!]
  lt: String
  lte: String
  gt: String
  gte: String
  contains: String
  startsWith: String
  endsWith: String
  mode: QueryMode
  not: NestedStringNullableFilter
}

enum QueryMode {
  default
  insensitive
}

input NestedStringNullableFilter {
  equals: String
  in: [String!]
  notIn: [String!]
  lt: String
  lte: String
  gt: String
  gte: String
  contains: String
  startsWith: String
  endsWith: String
  not: NestedStringNullableFilter
}

Mutations

createUser

type Mutation {
  createUser(data: UserCreateInput!): User
}

input UserCreateInput {
  name: String
}

type User {
  id: ID!
  name: String
}

createUsers

type Mutation {
  createUsers(data: [UserCreateInput!]!): [User]
}

input UserCreateInput {
  name: String
}

type User {
  id: ID!
  name: String
}

updateUser

type Mutation {
  updateUser(where: UserWhereUniqueInput!, data: UserUpdateInput!): User
}

input UserWhereUniqueInput {
  id: ID
}

input UserUpdateInput {
  name: String
}

type User {
  id: ID!
  name: String
}

updateUsers

type Mutation {
  updateUsers(data: [UserUpdateArgs!]!): [User]
}

input UserUpdateArgs {
  where: UserWhereUniqueInput!
  data: UserUpdateInput!
}

input UserWhereUniqueInput {
  id: ID
}

input UserUpdateInput {
  name: String
}

type User {
  id: ID!
  name: String
}

deleteUser

type Mutation {
  deleteUser(where: UserWhereUniqueInput!): User
}

input UserWhereUniqueInput {
  id: ID
}

type User {
  id: ID!
  name: String
}

deleteUsers

type Mutation {
  deleteUsers(ids: [UserWhereUniqueInput!]!): [User]
}

input UserWhereUniqueInput {
  id: ID
}

type User {
  id: ID!
  name: String
}

Related resources