Compatibility boundary: index rebuilds during FaunaDB schema field renames

Direct answer

FaunaDB does not publish a hard real-time guarantee that an index stays fully available with unchanged performance while it is rebuilt after a schema field rename. Treat the rebuild as asynchronous background work that can cause temporary latency or throughput pressure. The two-phase field-rename pattern can avoid downtime, but only if you keep the legacy field readable until the rebuilt index is confirmed active and validated, and you point the index at the new field before removing the old one.

Confirmed facts versus likely behavior

Confirmed behaviors:

• Additive schema changes are generally safe for zero-downtime deployments.
• Breaking changes such as field renames require old and new fields to coexist during a two-phase rollout.
• Driver and HTTP API backward compatibility covers request shape, not index rebuild latency or temporary resource contention.

Likely, version-dependent behavior that you should verify against your active FaunaDB release:

• Queries typically continue reading from the previous index version until the new build completes and is swapped in.
• Index metadata transitions from a building state to active when the rebuild finishes.

Migration steps for this case

1. Deploy application code that writes to both the old field and the new field.
2. Backfill existing documents so the new field is populated.
3. Update the index definition to reference the new field path.
4. Wait for index metadata to report the rebuilt index as active.
5. Run canary reads against the new field path and check error rate and p95 latency.
6. Stop writing to the legacy field only after reads are stable, then remove it.

Observable completion signals

• Index metadata state changes from building to active.
• Read latency returns to baseline and remains stable.
• Queries using the new field path succeed without errors referencing the old field path.

Verification commands

// Example shape only; verify exact syntax against your FaunaDB driver version.
// Inspect index metadata before and after the definition change.
// Run canary reads against the index using the new field path.
// Monitor p95 read latency and error rate during the rebuild window.

Missing diagnostic detail

Does your application query the index directly, or through a FaunaDB UDF or abstraction layer that hides the field path? This changes the point at which clients observe the rename and whether you need to update the abstraction before removing the legacy field.

Assumptions and uncertainty

• The index references the field directly in terms or values. Computed expressions or stored fields change rebuild behavior.
• Rebuild duration depends on collection size and cluster load; small collections may finish quickly, large ones may take minutes to hours.
• Behavior can vary across FaunaDB releases. Verify against the active version before production use.

This draft requires current verification against your active FaunaDB version before production use.