Mutations

Grafbase automatically generates mutations based on the types you define in your schema.

These mutations can be used to create, update, delete, link, or unlink data.

Mutations come in the following format, where [modelName] is the name of the model:

• [modelName]Create: [modelName]CreatePayload
• [modelName]CreateMany: [modelName]CreateManyPayload
• [modelName]Update: [modelName]UpdatePayload
• [modelName]UpdateMany: [modelName]UpdateManyPayload
• [modelName]Delete: [modelName]DeletePayload
• [modelName]DeleteMany: [modelName]DeleteManyPayload

Each of the mutations return a [modelName][Action]Payload type.

The create mutation contains a single input argument that is used to capture the fields for the model you want to create data for. If a field is marked as non-nullable in your schema, the generated input type applies that validation, and thus the input must contain a non-null value for that field.

import { g } from '@grafbase/sdk'

g.model('Post', {
  title: g.string()
})

The update mutation contains two arguments that are required to update data:

• by: [modelName]ByInput! — The input [modelName]ByInput type contains id and all other uniques for the model.
• input: [modelName]UpdateInput! — The input type containing the fields for the model you want to update.

The mutation return the type [modelName]UpdatePayload.

import { g } from '@grafbase/sdk'

g.model('Post', {
  title: g.string(),
  slug: g.string().unique()
})

Fields using the type Int have the input type IntOperationsInput that lets you quickly increment, decrement, or set values.

mutation {
  postUpdate(by: { id: "..." }, input: { likes: { increment: 1 } }) {
    post {
      likes
    }
  }
}

Fields using the type Float have the input type FloatOperationsInput that lets you quickly increment, decrement, or set values.

mutation {
  postUpdate(by: { id: "..." }, input: { likes: { increment: 1.0 } }) {
    post {
      likes
    }
  }
}

The delete mutation contains a single argument that is required for deleting data:

• by: [modelName]ByInput! — The input [modelName]ByInput type contains id and all other uniques for the model.

import { g } from '@grafbase/sdk'

g.model('Post', {
  title: g.string(),
  slug: g.string().unique()
})

When your schema contains multiple, related types, nested mutations are then available to create, link, or unlink.

import { g } from '@grafbase/sdk'

const post = g.model('Post', {
  title: g.string(),
  category: g.relation(() => category)
})

const category = g.model('Category', {
  name: g.string(),
  posts: g.relation(post).optional().list().optional()
})

This will automatically generate additional GraphQL mutations for all database models.

The example schema below assumes you have the model Post configured:

mutation {
  postUpdateMany(input: [PostUpdate!]!): PostUpdateManyPayload
  postCreateMany(input: [PostCreate!]!): PostCreateManyPayload
  postDeleteMany(input: [PostDelete!]!): PostDeleteManyPayload
}

To create multiple entries at once, passed an array objects to input:

mutation {
  postCreateMany(
    input: [
      { input: { title: "Batch", slug: "batch" } }
      { input: { title: "Operations", slug: "operations" } }
    ]
  ) {
    postCollection {
      id
      title
      slug
    }
  }
}

To update multiple entries at once, passed an array objects to input that contains by and new input values:

mutation {
  postUpdateMany(
    input: [
      { by: { id: "..." }, input: { title: "Batch!" } }
      { by: { slug: "operations" }, input: { title: "Operations!" } }
    ]
  ) {
    postCollection {
      id
      title
      slug
    }
  }
}

To delete multiple entries at once, passed an array objects to input that contains the by values:

mutation {
  postDeleteMany(input: [{ by: { id: "..." } }, { by: { slug: "batch" } }]) {
    deletedIds
  }
}