API

Model-object mapping

t.model will either have field projectors for the Prisma model whose name matches that of the GraphQL Object, or if the GraphQL Object is of a name that does not match any of your Prisma models then t.model becomes a function allowing you to specify the mapping, after which the field projectors become available.

1model User {
2  id String @id @default(cuid())
3}

Enum

Auto-Projection

When a Prisma enum field is projected, the corresponding enum type will be automatically projected too (added to the GraphQL schema).

Member Customization

You can customize the projected enum members by defining the enum yourself in Nexus. nexus-plugin-prisma will treat the name collision as an intent to override and so disable auto-projection.

Option Notes

Currently Prisma enums cannot be aliased (issue). They also cannot be type mapped since enum types cannot be mapped yet (issue).

1type M {
2  MEF: E # ! <-- if not ? or @default
3}
4
5# if not defined by user
6enum E {
7  EV
8}

1model User {
2  role Role
3  mood Mood
4}
5
6enum Mood {
7  HAPPY
8  SAD
9  CONFUSED
10}
11
12enum Role {
13  MEMBER
14  EDITOR
15  ADMIN
16}

Scalar

Scalar Mapping

Prisma scalars are mapped to GraphQL scalars as follows:

1  Prisma       GraphQL
2  ------       -------
3  Boolean   <>  Boolean
4  String    <>  String
5  Int       <>  Int
6  Float     <>  Float
7  Json      <>  Json (custom scalar)
8  DateTime  <>  DateTime (custom scalar)
9  cuid()    <>  ID
10  uuid()    <>  UUID (custom scalar)

Auto-Projection

When a Prisma scalar is encountered that does not map to the standard GraphQL scalar types, it will be automatically projected (custom scalar added to the GraphQL schema). Examples include DateTime and JSON.

Option Notes

It is not possible to use type because there is currently no way for a Prisma scalar to map to a differently named GraphQL scalar.

1type M {
2  MSF: S # ! <-- if not ? or @default
3}
4
5# if not matching a standard GQL scalar
6scalar S

1model User {
2  id               String     @id @default(cuid())
3  email            String
4  scheduledPublish DateTime?
5  rating           Float
6  active           Boolean
7}

Relation

Projecting relational fields only affects the current GraphQL object being defined. That is, the model that the field relates to is not auto-projected. This is a design choice intended to keep the nexus-plugin-prisma system predictable for you. If you forget to project a relation you will receive feedback at build/boot time letting you know.

1type M {
2  MRF: RM # ! <-- if not ?
3}

1model User {
2  latestPost Post?
3}
4
5model Post {
6  title String
7  body String
8}

List Enum

Like enums. It is not possible to order (issue) paginate (issue) or filter (issue) enum lists.

1type M {
2  MLEF: [E!]!
3}
4
5# if not defined by user
6enum E {
7  EV
8}

List Scalar

Like scalars. It is not possible to order (issue) paginate (issue) or filter (issue) scalar lists.

1type M {
2  MLSF: [S!]!
3}

List Relation

Like relations but also supports batch related options.

1type M {
2  MLRF: [RM!]!
3}

Example

1model User {
2  ...
3}

1queryType({
2  definition(t) {
3    t.crud.user()
4    t.crud.users()
5  },
6})
7
8mutationType({
9  definition(t) {
10    t.crud.createOneUser()
11    t.crud.updateOneUser()
12    t.crud.upsertOneUser()
13    t.crud.deleteOneUser()
14
15    t.crud.updateManyUser()
16    t.crud.deleteManyUser()
17  },
18})

Create

1t.crud.createOne<M>

Allow clients to create one record at at time of the respective Prisma model.

Relation fields may be connected with an existing record or a sub-create may be inlined (generally referred to as nested mutations). If the relation is a List then multiple connections or sub-creates are permitted.

Inlined creates are very similar to top-level ones but have the important difference that the sub-create has excluded the field where supplying its relation to the type of parent Object being created would normally be. This is because a sub-create forces its record to relate to the parent one.

Underlying Prisma Client Function

create

1mutation {
2  createOne_M(data: M_CreateInput): M!
3}
4
5input M_CreateInput {
6  MSF: S                       # ! <-- if not ? or @default
7  MRF: RM_CreateManyWithout_M  # ! <-- if not ? or @default
8}
9
10input RM_CreateManyWithout_M_Input {
11  connect: [RM_WhereUniqueInput!]
12  create: [RM_CreateWithout_M_Input!]
13  connectOrCreate: [RM_CreateOrConnectWithout_M_Input]
14}
15
16input RM_WhereUniqueInput {
17  MRF@unique: S
18}
19
20input RM_CreateOrConnectWithout_M_Input {
21  where: RM_WhereUniqueInput!
22  create: RM_CreateWithout_M_Input!
23}
24
25input RM_CreateWithout_M_Input = RM_CreateInput - RMRF: M

1model User {
2  id    Int    @id
3  email String @unique
4  posts Post[]
5}
6
7model Post {
8  id     Int    @id
9  title  String @unique
10  body   String
11  author User
12}

Read

1t.crud.<M>

Allow clients to find one particular record of the respective Prisma model. They may search by any Prisma model field that has been marked with @unique attribute.

The ability for list fields to be filtered, ordered, or paginated depends upon if those features have been enabled for those GraphQL objects via t.model.<ListRelation>.

Underlying Prisma Client function

findOne

1mutation {
2  M(where: M_WhereUniqueInput): M!
3}
4
5input M_WhereUniqueInput {
6  MF: S # if @unique
7}

1model User {
2  id    Int    @id
3  email String @unique
4}

Update

1t.crud.updateOne<M>

Allow clients to update one particular record at a time of the respective Prisma model.

Underlying Prisma Client function

update

1mutation {
2  updateOne_M(data: M_UpdateInput!, where: M_WhereUniqueInput!): M
3}
4
5input M_WhereUniqueInput {
6  MF: S # if @unique
7}
8
9input M_UpdateInput {
10  MFloatF: S_FieldUpdateOperationsInput # or Float if atomic operations are disabled
11  MIntF: S_FieldUpdateOperationsInput # or Int if atomic operations are disabled
12  MSF: S
13  MRF: RM_UpdateManyWithout_M_Input
14}
15
16input RM_UpdateManyWithout_M_Input {
17  connect: [RM_WhereUniqueInput!]
18  connectOrCreate: [RM_CreateOrConnectWithout_M_Input!]
19  create: [RM_CreateWithout_M_Input!]
20  delete: [RM_WhereUniqueInput!]
21  deleteMany: [RM_ScalarWhereInput!] # see batch filtering reference
22  disconnect: [RM_WhereUniqueInput!]
23  set: [RM_WhereUniqueInput!]
24  update: [RM_UpdateWithWhereUniqueWithout_M_Input!]
25  updateMany: [RM_UpdateManyWithWhereNestedInput!]
26  upsert: [RM_UpsertWithWhereUniqueWithout_M_Input!]
27}
28
29input PostCreateOrConnectWithout_M_Input {
30  create: RM_CreateWithout_M_Input!
31  where: RM_WhereUniqueInput!
32}
33
34input RM_WhereUniqueInput {} # recurse pattern like M_WhereUniqueInput
35
36input RM_CreateWithout_M_Input {} # RM_CreateInput - RMRF: M
37
38input RM_UpdateWithWhereUniqueWithout_M_Input {
39  data: RM_UpdateWithout_M_Input!
40  where: RM_WhereUniqueInput!
41}
42input RM_UpdateWithout_M_Input {
43  RMSF: S
44}
45
46input RM_UpdateManyWithWhereNestedInput {
47  data: RM_UpdateManyInput!
48  where: RM_ScalarWhereInput! # see batch filtering reference
49}
50
51input RM_UpsertWithWhereUniqueWithout_M_Input {
52  create: RM_CreateWithout_M_Input!
53  update: RM_UpdateWithout_M_Input!
54  where: RM_WhereUniqueInput!
55}

1model User {
2  id    Int    @id
3  email String @unique
4  posts Post[]
5}
6
7model Post {
8  id     Int    @id
9  title  String @unique
10  body   String
11  author User
12}

Upsert

1t.crud.upsertOne<M>

Allow clients to update or create (aka. insert) one particular record at a time of the respective Prisma model. This operation is a combination of create and update. The generated GraphQL mutation matches data and where args to those of update, and create to that of data arg in create. Unlike update, upsert guarantees a return value.

Underlying Prisma Client function

upsert

1mutation {
2  upsertOne_M(
3    create: M_CreateInput!      # like createOne(data ...)
4    data: M_UpdateInput!        # like updateOne(data ...)
5    where: M_WhereUniqueInput!  # like updateOne(where ...)
6  ): M!
7}

Delete

1t.crud.deleteOne<M>

Allow clients to delete one particular record at a time of the respective Prisma model.

Underlying Prisma Client function

delete

1mutation {
2  deleteOne_M(where: M_WhereUniqueInput): M
3}
4
5input M_WhereUniqueInput {
6  MF@unique: S
7}

1model User {
2  id    Int    @id
3  email String @unique
4  posts Post[]
5}
6
7model Post {
8  id     Int    @id
9  title  String @unique
10  body   String
11  author User
12}

Batch Read

1t.crud.<M Pluralized>

Allow clients to fetch multiple records at once of the respective Prisma model.

Underlying Prisma Client Function

findMany

1type Query {
2  M_s: [M!]!
3}

1model User {
2  id    Int    @id
3  email String @unique
4  posts Post[]
5}
6
7model Post {
8  id     Int    @id
9  title  String @unique
10  body   String
11  author User
12}

Batch Update

1t.crud.updateMany<M>

Allow clients to update multiple records of the respective Prisma model at once. Unlike update nested relation-updating is not supported here. Clients get back a BatchPayload object letting them know the number of affected records, but not access to the fields of affected records.

Underlying Prisma Client Function

updateMany

1mutation {
2  updateMany_M(where: M_WhereInput, data:  M_UpdateManyMutationInput): BatchPayload!
3}
4
5input M_UpdateManyMutationInput {
6  MFloatF: S_FieldUpdateOperationsInput # or Float if atomic operations are disabled
7  MIntF: S_FieldUpdateOperationsInput # or Int if atomic operations are disabled
8  MSF: S
9  MEF: E
10  # not possible to batch update relations
11}
12
13type BatchPayload {
14  count: Int!
15}

1mutation updateManyUser(where: {...}, data: { status: ACTIVE }) {
2  count
3}

Batch Delete

1t.crud.deleteMany<M>

Allow clients to delete multiple records of the respective Prisma model at once. Clients get back a BatchPayload object letting them know the number of affected records, but not access to the fields of affected records.

Underlying Prisma Client Function

deleteMany

1mutation {
2  deleteMany_M(where: M_WhereInput): BatchPayload!
3}
4
5type BatchPayload {
6  count: Int!
7}

1mutation {
2  deleteManyUser(where: {...}) {
3    count
4  }
5}

alias

1undefined | String

Applies To

t.crud.<*> t.model.<* - enum, list enum>

About

• undefined (default) By default Prisma model fields project onto GraphQL object fields of the same name.
• string Change which GraphQL object field the Prisma model field projects onto.

1model Post  {
2  body String
3}

type

1undefined | String

Applies To

t.crud.<*> t.model.<Relation> t.model.<ListRelation>

About

• undefined (default) Point Prisma field to a GraphQL object whose name matches that of the Prisma field model type.

• string Point Prisma field to the given GraphQL object. This option can become necessary when you've have done model-object mapping and other Prisma models in your schema have relations to the name-mapped Prisma model. We are interested in developing further the model-object mapping API to automate this better (issue).

1model User {
2  id    String @id @default(cuid())
3  posts Post[]
4}
5
6model Post {
7  id String @id @default(cuid())
8}

resolve

1undefined | (root: Root, args: Args, ctx: Context, info: GraphQLResolverInfo, originalResolve: <T>(root: Root, args: Args, ctx: Context, info: GraphQLResolverInfo): T) => T

Applies To

t.crud.<*> t.model.<*>

About

Enable the usage of a custom resolver on any resolver generated by the plugin via t.crud or t.model. You can either entirely replace the generated resolver, or wrap it via the use of the originalResolve parameter.

1queryType({
2  definition(t) {
3    t.crud.posts({
4      async resolve(root, args, ctx, info, originalResolve) {
5        console.log('logic before the resolver')
6        const res = await originalResolve(root, args, ctx, info)
7        console.log('logic after the resolver')
8        return res
9      },
10    })
11  },
12})

ordering

1undefined | true | false | ModelWhitelist

Applies To

t.crud.<BatchRead> t.model.<ListRelation>

About

Allow clients to order the records in a list field. Records can be ordered by their projected scalar fields in ascending or descending order. Ordering by fields on relations is not currently possible (issue).

• undefined (default) Like false
• false Disable ordering
• true Enable ordering by all scalar fields
• ModelWhitelist (Record<string, true>) Enable ordering by just Model scalar fields appearing in the given whitelist.

1# t.crud.<BatchRead>
2M(orderBy: [M_OrderByInput!])
3
4# t.model.<ListRelation>
5type M {
6  MF(orderBy: [M_OrderByInput!])
7}
8
9input M_OrderByInput {
10  MSF: OrderByArg
11  # It is not possible to order by relations
12}
13
14enum OrderByArg {
15  asc
16  desc
17}

1model User {
2  id    Int @id
3  name  String
4  posts Post[]
5}
6
7model Post {
8  id    Int @id
9  title String
10  body  String
11}

pagination

1undefined | true | false

Applies to

t.crud.<BatchRead> t.model.<ListRelation>

About

• undefined (default) Like true
• true Enable pagination
• false Disable pagination

1# t.crud.<BatchRead>
2Ms(
3  # The starting object for the list (typically ID or other unique value).
4  after: M_WhereUniqueInput
5
6  # The last object for the list (typically ID or other unique value)
7  before: M_WhereUniqueInput
8
9  # How many elements, forwards from `after` otherwise head
10  first: Int
11
12  # How many elements, backwards from `before` otherwise tail
13  last: Int
14
15  # The offset
16  # If `first` used, then forwards from `after` (otherwise head)
17  # If `last` used, then backwards from `before` (otherwise tail)
18)
19
20# t.model.<ListRelation>
21type M {
22  MRF(after: M_WhereUniqueInput, before: M_WhereUniqueInput, first: Int, last: Int)
23}
24
25input M_WhereUniqueInput {
26  MSF@unique: S
27}

1model User {
2  id    Int @id
3  posts Post[]
4  // ...
5}
6
7model Post {
8  id    Int @id
9  // ...
10}

filtering

1undefined | true | false | ModelWhitelist

Applies to

t.crud.<BatchRead> t.model.<ListRelation>

About

• undefined (default) Like false
• true Enable filtering for all scalar fields
• false Disable filtering
• ModelWhitelist (Record<string, true>) Enable ordering by just Model scalar fields appearing in the given whitelist.

1model User {
2  id     String     @id @default(cuid())
3  posts  Post[]
4  age    Int
5  status UserStatus
6}
7
8model Post {
9  id       String    @id @default(cuid())
10  author   User
11  comments Comment[]
12  rating   Float
13}
14
15model Comment {
16  id      String     @id @default(cuid())
17  author  User
18  post    Post
19  content String
20}
21
22enum UserStatus {
23  BANNED
24  ACTIVE
25}

description

1undefined | string

Applies to

t.model.<*>

About

Sets a description to be included in the generated SDL for this field.

• undefined (default) No description will be added to the field.
• string A description will be generated with the provided string.

1model User {
2  id  Int @id
3  name String
4}

deprecation

1undefined | string

Applies to

t.model.<*>

About

Adds a @deprecated directive to the generated SDL for this field.

• undefined (default) No deprecation directive will be added to the field.
• string Include a deprecation directive, using the provided string as a reason.

1model User {
2  id  Int @id
3  name String
4}

computedInputs (local)

1Record<string, ({ args, ctx, info }: MutationResolverParams) => unknown>

Note: This is an abbreviated version of the ComputedInputs type. The most important thing to understand is that each of the object's values will be a function that takes an object with "args", "ctx", and "info" keys that represent the runtime values of the corresponding parameters that are passed to your resolver. For the full type, see ComputedInputs Type Details.

Applies to

t.crud.<mutations>

About

Allow clients to omit fields from one mutation's corresponding input type and infer the value of those fields from the resolver's params (args, context, info) at runtime when determining what to pass to Prisma Client.

• ComputedInputs (Record<string, ({ args, ctx, info }: MutationResolverParams) => unknown>) (full type here).

  Keys in the ComputedInputs object will be omitted from the mutation's corresponding input type. When resolving the mutation at runtime, each omitted key will be passed to Prisma Client based on the return value of that key's corresponding function in the ComputedInputs object when passed that resolver's parameters at runtime.

1model User {
2  id  Int @id
3  name String
4  createdWithBrowser String
5}

computedInputs (global)

1Record<string, ({ args, ctx, info}: MutationResolverParams) => any>

Note: This is an abbreviated version of the ComputedInputs type. The most important thing to understand each of the object's values will be a function that takes an object with "args", "ctx", and "info" keys that represent the runtime values of the corresponding parameters that are passed to your resolver. For the full type, see ComputedInputs Type Details.

Applies to

nexusPrismaPlugin()

About

Allow clients to omit fields with a given name across all of their GraphQL schema's inputs and infer the value of those fields from context when determining what to pass to Prisma Client

• ComputedInputs (Record<string, ({ args, ctx, info }: MutationResolverParams) => any>) (full type here).

  Keys in the ComputedInputs object will be omitted from all input types. When resolving any mutation at runtime, that mutation's input type will be recursively searched for the omitted keys. Any time one of those keys would have appeared anywhere in the mutation's input type, a value will be passed to Prisma Client based on the return value of that key's corresponding function in the ComputedInputs object when passed the resolver's parameters at runtime.

1model User {
2  id  Int @id
3  name String
4  nested Nested[]
5  createdWithBrowser String
6}
7
8model Nested {
9  id Int @id
10  name String
11  createdWithBrowser String
12}

1nexusPrismaPlugin({
2  ...other config...
3  computedInputs: {
4    createdWithBrowser: ({ctx}) => ctx.browser,
5    user: ({ctx}) => ({ connect: { where: { id: ctx.userId } } }),
6  },
7})

1mutation createOneNested {
2  createOneNested({data: {name: "Moony"}}) {
3    id
4    name
5    createdWithBrowser
6  }
7}

1/**
2 *  Represents arguments required by Prisma Client that will
3 *  be derived from a request's input (root, args, and context)
4 *  and omitted from the GraphQL API. The object itself maps the
5 *  names of these args to a function that takes an object representing
6 *  the request's input and returns the value to pass to the Prisma Client
7 *  arg of the same name.
8 */
9export type LocalComputedInputs<MethodName extends MutationMethodName> = Record<
10  string,
11  (params: LocalMutationResolverParams<MethodName>) => unknown
12>
13
14export type GlobalComputedInputs = Record<string, (params: GlobalMutationResolverParams) => unknown>
15
16type BaseMutationResolverParams = {
17  info: GraphQLResolveInfo
18  ctx: Context
19}
20
21export type GlobalMutationResolverParams = BaseMutationResolverParams & {
22  args: Record<string, any> & {
23    data: unknown
24  }
25}
26
27export type LocalMutationResolverParams<
28  MethodName extends MutationMethodName
29> = BaseMutationResolverParams & {
30  args: core.GetGen<'argTypes'>['Mutation'][MethodName]
31}
32
33export type MutationMethodName = keyof core.GetGen<'argTypes'>['Mutation']
34
35export type Context = core.GetGen<'context'>

Null-Free Lists

Projection for Prisma list types always project as a fully non-nullable GraphQL type. This is because Prisma list fields (and list member type) can themselves never be null, and because Prisma does not support @default on list types.

For consistency we also apply the same pattern for t.crud.<BatchRead>.

1model User {
2  posts Post[]
3}

Where Does it Appear?

1query {
2  # When filtering option is enabled
3  Ms(where: M_WhereInput, ...): [M!]!
4}
5
6mutation {
7  updateMany_M(where: M_WhereInput, ...) BatchPayload!
8  deleteMany_M(where: M_WhereInput): BatchPayload!
9}
10
11type M {
12  # When filtering option is enabled
13  MRF: RM(where: RM_WhereInput): [RM!]!
14}
15
16# Nested InputObjects from t.crud.update<M>
17
18# Nested InputObjects from t.crud.upsert<M>

What Structure Does it Have?

1input M_WhereInput {
2  AND: [M_WhereInput!]
3  NOT: [M_WhereInput!]
4  OR: [M_WhereInput!]
5  MSF: S_Filter
6  MRF: RM_ListRelationFilter
7}
8
9input RM_ListRelationFilter {
10  every: RM_WhereInput # recurse -> M_WhereInput
11  none: RM_WhereInput # recurse -> M_WhereInput
12  some: RM_WhereInput # recurse -> M_WhereInput
13}
14
15# This type shows up in the context of t.crud.update<M> and t.crud.upsert<M>
16
17input RM_ScalarWhereInput {
18  AND: [RM_ScalarWhereInput!]
19  NOT: [RM_ScalarWhereInput!]
20  OR: [RM_ScalarWhereInput!]
21  RMSF: S_Filter
22}

Patterns

There are few different scalar filter patterns. Some scalars share the same filter pattern.

1input S_Filter {
2  contains: S
3  endsWith: S
4  equals: S
5  gt: S
6  gte: S
7  in: [S!]
8  lt: S
9  lte: S
10  not: Nested_S_Filter
11  notIn: [S!]
12  startsWith: S
13}

1input S_Filter {
2  equals: S
3  gt: S
4  gte: S
5  in: [S!]
6  lt: S
7  lte: S
8  not: Nested_S_Filter
9  notIn: [S!]
10}

1input S_Filter {
2  equals: S
3  not: Nested_S_Filter
4}

Scalars

1# S = Float | Int
2# Only one operation can be done per field at a time.
3input S_FieldUpdateOperationsInput {
4  # Sets the value to S
5  set: S
6  # These fields only appear if "atomicNumberOperations" prisma client preview feature is enabled
7  # Adds S to the current value
8  increment: S
9  # Subtracts S from the current value
10  decrement: S
11  # Multiplies the current value by S
12  multiply: S
13  # Divides the current value by S
14  divide: S
15}

How to read

Throughout this document you will see abbreviations used in GraphQL SDL syntax to signify how Nexus Prisma plugin contributes to the shape of your GraphQL schema. Each single capital letter is an abbreviation for one of the following things. When multiple capital letters are adjacent it means they combine the below.

1M = model   F = field   L = list   S = scalar   R = relation   E = enum   V = value

For example take this:

1input M_UpdateManyMutationInput { # 1
2  MFloatF: S_FieldUpdateOperationsInput # 2, 3
3  MIntF: S_FieldUpdateOperationsInput # 4, 5
4  MSF: S # 6, 7
5  MEF: E # 8, 9
6}

1. M_UpdateManyMutationInput means a GraphQL object whose name is your model name with the suffixed with UpdateManyMutationInput.
2. MFloatF means a model field of float type
3. S_FieldUpdateOperationsInput means a GraphQL object type reference. The name will be the name of the scalar type of the field suffixed with FieldUpdateOperationsInput. Since the field here is Float that means the object type name will be FloatFieldUpdateOperationsInput.
4. Like point 2 but for Int
5. Like point 3 but for Int
6. MSF means a field name matching the field name of a model scalar field. Note it comes after Float and Int types have been explicitly listed, which means this excludes model fields of those types.
7. S means the type of this field will match the kind of model scalar that it is (see the Scalar mapping table to see what it will really be if in doubt)
8. Like (6) but for Enums
9. Like (9) but for Enums