Understanding how to add and modify fields in Sanity documents

This is a common issue! When you add a new field to an existing schema in Sanity, existing documents won't automatically have that field populated, even if you've set an initialValue. The initialValue only applies when creating new documents, not to documents that already exist in your dataset.

Here's what's happening: Your existing user documents were created before the grade field existed in your schema, so they simply don't have that field in their stored data. When you query them, you're seeing the actual document data, which lacks the grade field.

Solutions

Option 1: Edit documents manually (for small datasets)

The simplest approach is to open each existing document in Sanity Studio and save it. This will apply the initialValue to that document. However, this isn't practical if you have many documents.

Option 2: Run a content migration (recommended for larger datasets)

Use Sanity's migration tooling to add the missing field to all existing documents:

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

export default defineMigration({
  title: 'Add grade field to existing users',
  documentTypes: ['user'],
  
  migrate: {
    document(doc, context) {
      return at('grade', setIfMissing('somethingpls'))
    }
  }
})

Create this migration with:

npx sanity@latest migration create

Then run it with:

npx sanity@latest migration run

Option 3: Use GROQ to provide defaults in queries

You can also handle this in your queries using GROQ's coalesce function to provide a default value when the field is missing:

*[_type == "user"] {
  userName,
  image,
  admin,
  "grade": coalesce(grade, "somethingpls")
}

This doesn't modify your documents but ensures your query results always include a grade value.

The migration approach (Option 2) is generally best because it actually updates your data to match your schema expectations, making your dataset consistent going forward.