Content Lake (Datastore)

Document mutation patterns

Common patterns and snippets for mutating documents and data in the Sanity Content Lake.

This guide covers common patterns and options for mutating documents. If you haven’t already, read the introduction to document mutations and the mutate documents with actions guide.

Where both APIs support a technique, the examples show the Actions API and the Mutation API. They use the following client configuration wherever they reference client.

import { createClient } from '@sanity/client'

export const client = createClient({
  projectId: '',
  dataset: '',
  apiVersion: '2025-12-15',
  // A token with write access. Keep it server-side.
  token: process.env.SANITY_API_WRITE_TOKEN,
})

Perform a dry run

To test actions and mutations without applying them, set the dryRun option to true.

await client.action([{
    actionType: 'sanity.action.document.create',
    publishedId: 'example-id',
    attributes: {
      _id: `drafts.example-id`,
      _type: 'article',
      title: 'Title of the document',
    },
    ifExists: 'fail',
  }], 
  // take note of the new object passed as a second value to `action`
  {
    dryRun: true,
  });

Dispatch multiple actions in one transaction

The Actions API is transactional. It accepts an array of actions and runs them in a single transaction, so either all of their effects are applied or none are.

await client.action([
  {
    actionType: 'sanity.action.release.create',
    releaseId: 'custom-release-id',
    metadata: {
      title: 'new release'
    }
  },
  {
    actionType: 'sanity.action.release.schedule',
    releaseId: 'custom-release-id',
    // Use a future time. A time in the past publishes the release immediately.
    publishAt: '2030-01-01T09:00:00.000Z',
  }
])

You can't mix release actions with document or version actions in one request. Send them as separate client.action() calls.

Purge document history when you delete

Set the optional purge flag to fully purge the document’s history from the Content Lake. All transactions related to the document are removed immediately, consistent with our data retention policy, and no longer appear in Studio's history experience or the Content Lake history API endpoint.

The purge option is available on actions and mutations that delete or discard documents.

import {createVersionId} from '@sanity/id-utils'

const documentId = 'document-id'
await client.action({
  actionType: 'sanity.action.document.version.discard',
  versionId: createVersionId('release-id', documentId),
  purge: true, // optionally pass to delete history
});

Delete multiple documents by query

Submit a GROQ query instead of an ID to delete multiple documents in a single mutation.

const { dataset } = client.config();
await client.request({
  uri: `/data/mutate/${dataset}`,
  method: 'POST',
  body: {
    mutations: [
      {
        delete: {
          query: "*[_type == 'feature' && viewCount < $views]",
          params: {
            views: 5
          },
        }
      }
    ]
  },
});

This example deletes all documents of type "feature" where viewCount is less than 5. For valid queries, see the GROQ introduction.

Gotcha

Patch multiple documents by query

Submit a query instead of an ID to patch multiple documents at once. This example subtracts 100 from points and adds 1 to bonuses for every person document with 100 or more points:

const { dataset } = client.config();
await client.request({
  uri: `/data/mutate/${dataset}`,
  method: 'POST',
  body: {
    mutations: [
      {
        patch: {
          query: "*[_type == 'person' && points >= $threshold]",
          params: {
            threshold: 100
          },
          dec: {
            points: 100
          },
          inc: {
            bonuses: 1
          }
        }
      }
    ]
  },
});

Set your own transactionId

Every transaction gets a random ID. To make it predictable, for example so you can find the transaction in listener events or the History API, set your own transactionId when you dispatch actions or post mutations. The ID must be unique in the dataset; reusing one fails with a 409 Conflict error.

await client.action([{
    actionType: 'sanity.action.document.create',
    publishedId: 'example-id',
    attributes: {
      _id: `drafts.example-id`,
      _type: 'article',
      title: 'Title of the document',
    },
    ifExists: 'fail',
  }], 
  // take note of the new object passed as a second value to `action`
  {
    transactionId: 'custom-identifier',
  });

Learn more

For every parameter and option, see the Actions API and Mutation API references.

Was this page helpful?

Sanity logosanity.ioAll Systems Operational© Sanity 2026
Change site theme