Vector Database Index Migration Checklist Builder

Create a vector database index migration checklist covering schema changes, embedding model compatibility, backfills, dual writes, retrieval quality tests, rollback, and monitoring.

Prompt Template

You are a senior AI infrastructure engineer helping a team migrate a vector database index safely. Build a migration checklist for:

Current vector store: [Pinecone, Weaviate, Qdrant, Milvus, Chroma, Elasticsearch, pgvector, custom]
Target change: [new index, namespace split, metadata schema change, embedding model upgrade, dimension change, provider migration, shard redesign]
Application use case: [RAG search, recommendations, semantic support search, entity matching, image search]
Embedding model details: [current model, target model, dimensions, normalization, chunking strategy]
Data volume: [documents, vectors, metadata size, update rate, tenant count]
Retrieval path: [API, background jobs, hybrid search, filters, reranker, cache, streaming answer pipeline]
Current quality baseline: [golden queries, recall metrics, click data, human evals, support tickets]
Migration constraints: [zero downtime, tenant isolation, cost limit, compliance, data residency, SLA]
Write path: [batch ingestion, event stream, dual writes, retries, idempotency, delete/update semantics]
Rollback options: [old index retained, traffic switch, feature flag, backup export, rehydration plan]
Monitoring tools: [logs, traces, vector DB metrics, eval dashboard, alerts]

Create:
1. Pre-migration inventory for index settings, schema, embeddings, filters, tenants, and dependencies.
2. Compatibility checklist for dimensions, distance metric, normalization, metadata filters, and chunk IDs.
3. Backfill plan with batching, idempotency, rate limits, cost controls, and verification.
4. Dual-write or shadow-read strategy for zero-downtime migration.
5. Retrieval quality test plan with golden queries, recall, precision, latency, and answer-grounding checks.
6. Data consistency checks for counts, deletes, updates, duplicate chunks, and metadata coverage.
7. Traffic cutover plan with feature flags, canary cohorts, and owner approvals.
8. Rollback plan and conditions that trigger rollback.
9. Monitoring dashboard and alert thresholds for latency, errors, empty results, cost, and quality drift.
10. Post-migration cleanup plan for old indexes, code paths, credentials, and documentation.

Make the checklist implementation-ready for engineers. Call out assumptions and risks instead of treating vector search as a black box.

Example Output

Migration Plan: ada-002 to text-embedding-3-large Index

Compatibility Checks

| Area | Check | Status |

|---|---|---|

| Dimensions | New vectors are 3072 dimensions; old index is 1536 | Requires new index |

| Distance | Both use cosine similarity | Compatible |

| IDs | Chunk IDs remain stable across re-embedding | Required for diff checks |

| Metadata | tenant_id, doc_id, source, updated_at preserved | Blocker if missing |

Backfill Strategy

Run tenant-by-tenant batches with idempotent upserts, record source document hash, and compare vector count to document chunk count after each batch. Cap ingestion rate to stay under provider limits and log failed chunks for retry.

Quality Gate

Run 150 golden queries against old and new indexes. Cutover only if empty-result rate does not increase, P95 retrieval latency stays under 400 ms, and human review finds no critical grounding regressions.

Rollback Trigger

Roll back if P1 search errors exceed 1 percent for 10 minutes, empty-result rate doubles, or customer-facing answer citations fail quality review.

Tips for Best Results

  • 💡Treat embedding model changes as data migrations, not just configuration edits.
  • 💡Keep stable chunk IDs so old and new retrieval results can be compared.
  • 💡Test metadata filters heavily; many vector migrations fail outside pure similarity search.
  • 💡Define rollback before cutover, while the old index is still warm and trusted.