Best way to batch remove deprecated field from Sanity dataset

Looking at your situation, the recommended approach for batch removing a deprecated field from your dataset is to use Sanity's migration tooling with the unset() function. Let me walk you through the best practice approach.

Using defineMigration with unset()

First, create a migration script:

npx sanity@latest migration create "Remove deprecated field"

Then in the generated migrations/your-migration-name/index.ts file, use this pattern:

import {defineMigration, at, unset} from 'sanity/migrate'

export default defineMigration({
  title: 'Remove deprecated field',
  documentTypes: ['yourDocumentType'], // specify the document type(s)
  
  migrate: {
    document(doc, context) {
      // Remove the deprecated field
      return at('deprecatedFieldName', unset())
    }
  }
})

Running the Migration

The key to success is following this process:

1. Always dry-run first (this is the default behavior):

sanity migration run your-migration-name

This shows you what would happen without making actual changes.

1. Execute on your dataset once you've verified the dry-run looks correct:

sanity migration run your-migration-name --dataset <your-dataset-name>

Why This Approach Works

The defineMigration API handles several important things automatically:

• Automatic batching to avoid API rate limits
• Document validation against your schema
• Visual feedback during execution
• Safe defaults with dry-run mode

Removing Multiple Fields

If you need to remove multiple deprecated fields at once:

migrate: {
  document(doc, context) {
    return [
      at('deprecatedField1', unset()),
      at('deprecatedField2', unset()),
      at('nested.deprecatedField', unset())
    ]
  }
}

Troubleshooting Tips

If you're still not seeing success:

1. Check document types: Make sure the documentTypes array matches exactly with your schema type names
2. Verify field paths: The field name in at() must match the exact field name in your documents
3. Review dry-run output: Look for any errors or warnings in the terminal output
4. Check for nested fields: If your field is nested, use dot notation like 'parent.child.fieldName'

The migration tooling is specifically designed for this batch patch use case and handles all the complexity of batching mutations automatically, making it more reliable than manual patching scripts. If you're still experiencing issues after following this pattern, double-check that your field names and document types exactly match what's in your dataset.