Introduction to document mutations

Sanity's Content Lake offers a variety of methods for creating, editing, and deleting documents.

Document mutations are how you change content in Sanity's Content Lake programmatically. They provide a structured approach to modifying your documents while maintaining data integrity and enabling collaborative editing.

With document mutations, you can:

• Create new documents.
• Delete documents when they're no longer needed.
• Apply targeted patches to specific fields, or replace entire documents.
• Make transactional changes across multiple documents.

The Actions API is the preferred method for mutating documents in Sanity—it’s also the underlying API that powers Sanity Studio’s mutations. It's designed to support an authoring model where drafts and versions of a document are iterated on and eventually published.

The Actions API is transactional, meaning that multiple actions are executed in a single transaction—either all changes are applied, or none of them.

The Mutations API is the traditional way of creating and modifying documents in Sanity. It provides low-level operations that give you precise control over your content.

Available mutation types include:

• create: Create a new document.
• createOrReplace: Create a document or replace it if it exists.
• createIfNotExists: Create a document only if it doesn't already exist.
• delete: Remove a document.
• patch: Apply targeted changes to specific parts of a document.

Like the Actions API, the Mutations API is transactional, ensuring data consistency across multiple operations.

When you submit mutations or dispatch actions to Content Lake, they are processed as part of a transaction—a single unit of work that either succeeds completely or fails entirely. Transactions make up a document’s history and trigger listeners.

The Mutations API, and some actions in the Actions API, use patches to make small, targeted changes to documents. Patches allow you to modify specific parts of a document without having to replace the entire document, which is especially useful for collaborative workflows where multiple changes need to be reconciled.

Common patch operations include:

• set: Update specific fields with new values.
• setIfMissing: Set values only if the fields don't already exist.
• unset: Remove fields from a document.
• insert: Add or replace elements in arrays.
• inc/dec: Increment or decrement numeric values.
• diffMatchPatch: Apply text changes using Google's diff-match-patch algorithm.