How to rename a document in Sanity?

I think you're asking about renaming a document type (like changing "post" to "article"), but let me cover a few scenarios since "document name" could mean different things:

If you want to rename a document type (the schema _type):

This is tricky because the _type field is immutable - it cannot be changed once a document is created. According to the official migration documentation, you cannot use at('_type', set('newType')) in a migration script.

The recommended approach is:

1. Export your dataset:

sanity dataset export production backup.tar.gz

2. Extract and edit the NDJSON file inside the tar.gz archive - manually change the _type values in the documents

3. Delete the old documents from your dataset (those with the old type)

4. Import the modified dataset:

sanity dataset import backup.tar.gz production

5. Update your schema files to use the new document type name

This is admittedly manual, but it's the safest way to handle this since _type, _id, _createdAt, and other underscore-prefixed fields are system-managed and immutable.

If you want to rename a field (like "title" to "heading"):

This is much easier! You can use the migration tooling with defineMigration:

// migrations/rename-title-field/index.ts
import {defineMigration, at, setIfMissing, unset} from 'sanity/migrate'

const from = 'title'
const to = 'heading'

export default defineMigration({
  title: 'Rename title field to heading',
  documentTypes: ['post'], // specify your document type
  
  migrate: {
    document(doc, context) {
      return [
        at(to, setIfMissing(doc[from])),
        at(from, unset())
      ]
    }
  }
})

Then run:

# Test first (dry run)
sanity migration run rename-title-field

# Execute the migration
sanity migration run rename-title-field --no-dry-run

Don't forget to update your schema definition to use the new field name!

If you just want to change the display label:

If you only want to change what's shown in Studio (not the actual field name in your data), just update the title property in your schema:

defineType({
  name: 'post', // this stays the same
  type: 'document',
  title: 'Blog Article', // change this freely - it's just the display name!
})

This requires no migration at all since it's just a UI label.

Check out the content migration cheat sheet for more common migration patterns, and always backup your dataset before running migrations!