Skip to main content

Migration Plan

:::info Source Sourced from services/search-service/MIGRATION_PLAN.md in the documentation repo. :::

1. Rules​

  • Index alias + zero-downtime reindex; existing queries unaffected during reindex.
  • Embedding model changes require full re-embed + alias swap.
  • Document schema versioned; consumer (API) supports multiple versions.

2. Full Reindex Procedure​

  1. Create new index docs_v2_{tenant}_{timestamp}.
  2. Replay document events + fresh embeddings.
  3. Verify document count ± 0.1% of source.
  4. Swap alias atomically.
  5. Keep old index 7 days then delete.

3. Embedding Model Migration​

  • New model: parallel embed; both old and new indices queryable.
  • Gradual traffic shift via weighted query.
  • After full migration, retire old model's embeddings.

4. Event Versioning​

EventvPolicy
search.document.indexed.v1v1Additive
search.reindex.completed.v1v1Additive

5. Schema Evolution​

Add optional fields freely. Remove: deprecate + wait 1 milestone.

6. Analyzer Changes​

  • Per-locale analyzer changes require reindex.
  • Rollout gradual by tenant.

7. Data Residency​

  • Per-tenant index region-pinned.
  • Migration: bulk export + reindex target region.

8. GDPR​

  • Erasure: remove user documents + embeddings.
  • Verify via replay test.

9. Changelog​

New document types, new filters, analyzer versions, embedding model versions.