Define the provenance field before changing the catalog index
A municipal archive has an Azure AI Search index used to find repair manuals. Staff want each result to show the source document’s approved revision and a link to its provenance record. The current schema already contains a title, body text, and stable document key. Adding provenance looks like a small feature, yet an index schema is also a physical storage design. The migration must preserve live search, document identity, and access checks.
Describe the desired field first: for example, `source_revision`, a string populated only from the authoritative catalog. Decide whether the interface merely displays it or also filters and sorts on it. Document the current index definition and a rollback path before submitting a schema update. This example is hypothetical; the diagrams show a conceptual index and not a customer Azure portal or tested deployment.
Separate additive changes from structural changes
Microsoft’s index-update guidance allows several changes without rebuilding an existing index, including adding a new field. It also states that existing documents receive null values for a newly introduced field until content is updated. By contrast, changing a field’s name, type, or many attributes such as `searchable`, `filterable`, `sortable`, and `facetable` requires a rebuild. Changing analyzer assignments and suggester membership can also involve rebuilding.
Use this difference to make the schema decision explicit. Adding a new display-only `source_revision` field is not equivalent to modifying an established field so that it becomes filterable. If the eventual interface needs a filter, specify the appropriate attribute when creating the field. Do not promise an in-place attribute flip later. Keep an untouched snapshot of the approved original schema for comparison and recovery.
Inspect the existing definition and permission boundary
Retrieve the current index definition using an authorized administrator or deployment identity, then compare required fields, types, analyzers, keys, and security-related metadata. Note any application dependencies such as search results that select only a known subset of fields. The new provenance field must be bound to the same stable document key as the manual; a title match or nearest-neighbor result is insufficient for this purpose.
Separately check the system that authorizes readers. A field named `visibility` or `approved` is only data until the application and search layer enforce it consistently. Adding provenance metadata does not automatically repair access control. Test with public and staff-only identities and with documents that have been withdrawn. Never put a private provenance URL into a response merely because the index stores it.
Add a field and plan the null-value interval
For a permitted additive change, update the schema through the supported API or management interface and then reload or merge content so the new field receives actual values. Immediately after a field is introduced, legacy documents may have null provenance. A user interface that interprets null as “approved” can now make a harmful claim, even though the schema update itself completed successfully.
Design a neutral interim state such as “revision not verified” and suppress links until the value is backed by an authoritative catalog row. An indexer-based workflow and a direct document push workflow have different update controls, so document which one owns the new values. Compare counts before and after backfill, spot-check documents with multiple editions, and retain the original document IDs during the transition.
Test search behavior rather than just the schema response
A successful schema update proves neither correct retrieval nor correct provenance. Query for a known recent manual, a superseded manual, a missing or null revision, and a document a public reader should not see. Inspect the returned document key, selected revision, and whether the interface links to the proper authorized source. Verify that ordinary keyword and vector search behavior has not shifted unintentionally.
Keep the tests concrete and repeatable. A fictional sample might contain guide `RM-204` in revisions A and C; the expected result is the approved C record, not whichever text happens to rank first. Note that search results can vary as indexing updates become visible. Treat transient disagreement as a signal to investigate rather than as a cue to silently rewrite the catalog’s source of truth.
Use a side-by-side rebuild when a field definition must change
If the change requires a new data type, a different analyzer, or a new filterable attribute on an existing field, plan an index rebuild. Microsoft’s guidance recommends creating and testing a new version side by side when capacity allows, then switching an alias to the new index. This is distinct from casually deleting the production index and hoping an automated reindex will finish quickly.
Build the replacement from authorized source records, validate its schema and document count, run private and public queries, then decide who may switch the alias. Confirm a rollback index is still available and has the correct permissions. An alias helps change the target of queries, but it does not automatically migrate data, fix source permissions, or certify the content. Keep the switch controlled and observable.
Audit the backfill and the missing-record cases
Reconcile a source ledger against the new index by stable keys and revision values. A dashboard showing that an indexer succeeded is not enough: item-level failures, mapping mistakes, or skipped source records may leave a guide missing. Check expected versus indexed counts, especially for records carrying safety notes or legal restrictions. Review logs using identifiers rather than copying full sensitive documents into diagnostics.
Do not add a private field to make it public by accident. Test the `select` projection on both permitted and denied results, and confirm that downstream generated answers cannot cite unpublished revisions. If a manual is withdrawn during migration, its removal must be reflected in both the source workflow and every serving index. Record the sign-off for the new index only after those cases have been exercised.
Release with a named rollback and review owner
A production change plan should state the exact intended schema, where the values come from, which queries are sensitive to it, who can deploy, and what would trigger rollback. Use a brief read-only verification window to confirm results after the change, then retire obsolete index copies under the organization’s retention policy. Document the final schema version and date of cutover without inventing live performance or success-rate measurements.
If the archive later wants to change the field’s attributes, consult Microsoft’s current matrix again rather than assuming every property remains editable. The aim is to expose provenance, not to create a new source of historical truth. A correctly migrated search index supports staff judgment when it returns traceable results; the authoritative archive and its permissions remain outside the model’s control.
How We Research
For this November 2026 guide, we reviewed named primary documentation: Microsoft: Update or rebuild an index; Microsoft: Create a search index. We checked documented settings, limits, and failure conditions against a fictional institutional use case. We did not run live vendor API tests, process actual private records, verify real-world speech or translations, measure latency, or collect permissions. All images are original conceptual instructional drawings rather than screenshots or observations. Claims about source revisions, speaker wording, ownership, and access must be checked against the authoritative records by qualified staff. Vendor capabilities, eligible plans, regions and logging behavior can change; check current documentation and institutional policy before deploying any workflow.
Frequently Asked Questions
Yes, many additive field changes are supported, but existing documents initially have null values in the new field.
Not generally. Changing the index attributes of an existing field usually requires a rebuild and testing.
No. Access authorization must be enforced separately and tested for every reader role.
Create and validate a new index beside the old one where capacity permits, then use a controlled alias switch and rollback plan.
Reconcile source IDs, revisions, missing rows, visible fields and access denials against the authoritative catalog.