Transactions
How transactions for Content Lake work
Document updates in Sanity are called mutations, and a group of one or more mutations is executed as a single unit called a transaction. You submit transactions through the Mutations API, as groups of actions in the Actions API, and in a few other places throughout the Sanity ecosystem. They may look like the following:
// Import a client configured with apiVersion '2025-02-19' or later
// (required for versions.* document IDs), and the ID helpers
import {client} from './client'
import {createPublishedId, createDraftId, createVersionId} from '@sanity/id-utils'
const { dataset } = client.config();
const documentId = createPublishedId();
const transaction = await client.request({
uri: `/data/actions/${dataset}`,
method: 'POST',
body: {
actions: [
{
actionType: 'sanity.action.document.create',
publishedId: documentId,
document: {
_type: 'post',
_id: createDraftId(documentId),
title: 'new title',
}
},
{
actionType: 'sanity.action.document.publish',
publishedId: documentId,
versionId: createDraftId(documentId)
},
{
actionType: 'sanity.action.document.edit',
publishedId: documentId,
// Replace YOUR_RELEASE_ID with the ID of an active content release
versionId: createVersionId('YOUR_RELEASE_ID', documentId),
patch: {
set: {
title: 'new title 2'
}
}
},
]
}
});{
"mutations":[
{
"create":{
"_id":"alien",
"_type":"movie",
"title":"Alien"
}
},
{
"patch":{
"id":"alien",
"set":{
"year":1979,
"genre":"Science Fiction"
}
}
},
{
"delete":{
"id":"blade-runner"
}
}
]
}Transactions are atomic: either all of the mutations succeed or they all fail.
All transactions are recorded in an internal transaction log. This log is available through the document history API. Once a transaction is committed, any real-time listeners are notified about the changes.
Eventual consistency
Internally, Content Lake consists of two main components: a document store where transactions are executed, and a search store where GROQ queries are executed. Document changes are continuously synced between the document and search stores, but this happens outside of transactions, so there is a delay between a transaction being committed and the changes being visible to queries.
As a result, transactions are strongly consistent (they always see the latest data), but queries are eventually consistent (they may see outdated data, but will eventually see the latest data given enough time). Under normal circumstances the convergence time for queries is generally short (less than 1 second), but during operational anomalies such as network failures or heavy load it can be much longer. Transactions using the query parameter are not strongly consistent, since the query is first executed against the search store, which may see outdated data.
When submitting transactions, the visibility parameter can be used to control how documents should be synced to the search store. sync (the default) causes the transaction request to return only after both the transaction has been committed and the changes have been synced to the search store. async causes the request to return once the transaction has been committed, and then syncs the changes to the search store afterwards (typically within a second). deferred causes the request to return once the transaction has been committed, but does not trigger syncing to the search store at all, and instead relies on a background process to sync the changes at a later time (within seconds to minutes). This allows for much higher throughput when submitting a large number of mutations.
Listeners can be notified before queries see the change
By default, real-time listeners receive change notifications as soon as a transaction has been committed, but before changes have been synced to the search store. This means that a listening client running a GROQ query in response to a change will usually not see the updated document in the query result. The client can specify visibility=query for the listener to receive notifications after they have been synced to the search store, when possible.
ACID compliance
Sanity transactions are ACID-compliant, which means that they have the following properties:
- Atomicity: The transaction constitutes a single unit, such that either all of its mutations succeed or they all fail.
- Consistency: If a transaction succeeds, then the resulting documents are guaranteed to satisfy all Content Lake constraints. That is, the transaction cannot leave the data in an inconsistent state. For example, this guarantees that there cannot exist two documents with the same ID. This is a different concept from the eventual consistency of queries. Sanity schemas are currently only enforced client-side by Sanity Studio, and thus the consistency guarantees do not extend to constraints specified in the schema. Non-studio clients may submit data which does not satisfy the schema, and schema changes may leave old data which no longer satisfies the new schema. To learn more, see Schema validation and the Content Lake.
- Isolation: Transactions have repeatable read isolation through exclusive locks. When a document is first accessed by a transaction it is locked, blocking concurrent transactions from both reading and writing the document until the initial transaction completes. Since locks are acquired on first access and not on transaction start, it is possible for a mutation to see the effects of a concurrent transaction that was committed after the current transaction began but before the document was accessed and locked.
The query option reduces isolation to read committed
When using the query option for mutations, the mutation first executes the given GROQ query against the search store, and then executes mutations against the matching documents. Since the search store is eventually consistent, it is possible for the query to return outdated results, which can cause the mutations to incorrectly affect or ignore documents that have recently been modified. This effectively reduces the transaction isolation level to read committed, and can cause multiple data anomalies including lost updates, non-repeatable reads, phantom reads, and write skew.
- Durability: Once a transaction succeeds, it is guaranteed to have been written to disk. However, it is not guaranteed to have been replicated to other servers. This means it is possible to lose a transaction in the rare scenario where a primary server crashes and is replaced by a replica server after the transaction has been committed but before it has been replicated.
Concurrency control
Transactions use exclusive locks to prevent concurrent transactions from interfering with each other (repeatable read isolation). However, clients often use read-write cycles that run a GROQ query and then submit transactions based on the results. This pattern does not have the same isolation guarantees as transactions. For example, if a different client writes a value after your client has read a document but before your client writes its new value, then the value that the other client wrote may be lost (an anomaly known as a lost update).
Clients can use optimistic locking to prevent these kinds of data anomalies. patch mutations take an optional ifRevisionID parameter containing a document revision ID (typically from the document's _rev attribute), and are only accepted if the given revision ID matches the document's current revision ID. If a different client has modified the document in the meanwhile, then the mutation is rejected with a 409 Conflict HTTP status code, allowing the client to fetch the updated document and retry the operation with fresh data. Optimistic locking also guards against submitting mutations based on outdated query results caused by Content Lake's eventual consistency model.
Was this page helpful?
Feedback submitted, thanks for helping us improve the docs. Have you tried these alternatives?