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: '<your-project-id>',
dataset: '<your-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,
});const { dataset } = client.config();
await client.request({
uri: `/data/mutate/${dataset}`,
method: 'POST',
body: {
mutations: [
{
delete: {
id: '123'
}
}
],
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.
Purging requires the editHistory permission on the document, in addition to the permissions a regular delete needs. None of the predefined roles grant editHistory, including Administrator, so a purge request from an Administrator user or token fails with a 403 error: Insufficient permissions; permission "editHistory" required.
To purge history, create a custom role with the Access API that grants the editHistory action on a sanity.document.filter permission matching the documents you want to purge, and assign it to the user or robot token that sends the request. The role editor in Manage doesn't offer this permission. Custom roles are available on the Enterprise plan.
To delete a document without removing its history, leave out purge. A regular delete works with the Administrator role.
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
});const { dataset } = client.config();
await client.request({
uri: `/data/mutate/${dataset}`,
method: 'POST',
body: {
mutations: [
{
delete: {
id: '123',
purge: true
}
}
]
},
});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
A mutation that specifies a query operates on at most 10,000 documents. A mutation based on a query such as *[_type == "article"] runs as if the query were written *[_type == "article"][0...10000].
To mutate larger sets of documents, split the work into multiple transactions and paginate by _id with an explicit sort order, for example *[_type == "article" && _id > $lastId] | order(_id asc). To get the IDs of modified documents back, pass returnIds=true as a query parameter; it defaults to false on the HTTP endpoint, and the @sanity/client mutation methods set it for you. Use the last returned _id as the next lastId parameter. For more on this technique, see Paginating with GROQ.
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',
});const { dataset } = client.config();
await client.request({
uri: `/data/mutate/${dataset}`,
method: 'POST',
body: {
mutations: [
{
delete: {
id: '123'
}
}
],
transactionId: 'custom-transaction-id'
},
});Learn more
For every parameter and option, see the Actions API and Mutation API references.
Was this page helpful?
Feedback submitted, thanks for helping us improve the docs. Have you tried these alternatives?