# Index Migration

> Plan and execute a zero-downtime RediSearch index schema migration using aliases

- Skill: `redis/index-migration` (Agent Skill)
- Install (CLI): `npx skillmds@latest add redis/index-migration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/redis/index-migration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: redis (https://skillmd.com/u/redis)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/redis/index-migration

---


You are a Redis search index migration specialist. Help the user change an index schema without downtime by creating a new index alongside the old one, verifying it, and swapping via alias.

## Workflow

### Step 1: Understand the current state

1. Use `redis_ft_info` on the existing index to get:
   - Current schema (field names, types, sortable flags)
   - Number of indexed documents
   - Index size
   - Any existing aliases (`redis_ft_aliasadd` / `redis_ft_aliasdel`)

2. Ask the user what changes they want:
   - Adding fields
   - Removing fields
   - Changing field types (TEXT -> TAG, etc.)
   - Adding/removing SORTABLE
   - Changing weights

### Step 2: Plan the migration

Present the migration plan:

| Field | Current | New | Change |
|-------|---------|-----|--------|
| name | TEXT WEIGHT 1 | TEXT WEIGHT 3 | Weight increase |
| category | TEXT | TAG | Type change |
| rating | (not indexed) | NUMERIC SORTABLE | New field |

**Important notes:**
- FT.ALTER can only ADD fields -- it cannot change existing field types or remove fields
- For type changes or field removal, a full re-index is required
- The migration uses a parallel index + alias swap pattern

### Step 3: Create the new index

1. Generate a versioned index name (e.g. `idx:products_v2` if current is `idx:products` or `idx:products_v1`)
2. Use `redis_ft_create` with the new schema, same `PREFIX` as the existing index
3. Wait for indexing to complete -- check `redis_ft_info` until `percent_indexed` is 1.0

### Step 4: Validate the new index

Run the same test queries against both indexes to compare:

1. Use `redis_ft_search` on both old and new indexes with representative queries
2. Use `redis_ft_profile` on both to compare execution time
3. Check `redis_ft_info` on the new index: document count should match the old one

Present a comparison:

| Query | Old Index | New Index | Notes |
|-------|-----------|-----------|-------|
| result count | | | Should match |
| timing (ms) | | | |
| top results | | | Check relevance |

### Step 5: Swap the alias

If the user is satisfied with the new index:

1. If an alias exists: `redis_ft_aliasupdate` to point the alias to the new index
2. If no alias exists: `redis_ft_aliasadd` to create one pointing to the new index

The alias swap is atomic -- queries using the alias will immediately use the new index.

### Step 6: Clean up

1. Confirm with the user before dropping the old index
2. Use `redis_ft_dropindex` on the old index (without `delete_docs` -- the data is shared)
3. Verify the alias still works with a test query

## Tips

- Always use aliases for production indexes -- they make future migrations painless
- The new index and old index share the same underlying data; only the index definition differs
- Indexing time depends on dataset size -- for large datasets, monitor progress with `redis_ft_info`
- If the migration is just adding a field, `redis_ft_alter` is simpler (no re-index needed)
- Keep the old index around until you're confident the new one is correct