Reindexing

Reindexing is what you do when the schema of an index changes — a new field, a different sort key, a different default ranking. For most day-to-day data updates you do not reindex. You enqueue documents, the buffer flushes them, and the existing index keeps serving traffic.

This page is about the alias-swap reindex flow: when to use it, how it behaves, and how to recover when it doesn't.

The model: versioned collection + alias

Every logical index points at a physical collection through a Typesense alias.

Alias:    org_abc__products
Targets:  org_abc__products__v3   ← currently serving search traffic

When you reindex, the search package:

1. Reads the current alias target and computes the next version number (v4).
2. Calls createPhysicalCollection("org_abc__products__v4", fields).
3. Streams every document from the source (PostgreSQL queries, connector pull, or your data) into v4 via bulkUpsert.
4. Calls swapAliasToVersion(alias, "v4") — atomic alias retarget.
5. Optionally drops older versions (v2, v1, …), keeping a retention buffer.

No search request ever sees a half-built collection. The swap is one Typesense operation; it either succeeds or fails. If it fails, the alias stays pointed at v3 and v4 is left for cleanup.

When to reindex

You must reindex when:

• You add a new field to the schema.
• You remove a field.
• You change a field's type (string → string[], int32 → int64, etc.).
• You change default_sorting_field.
• You change tokenizer settings (token_separators, symbols_to_index).
• You change ranking that depends on field weights baked into the collection.

You don't need to reindex when:

• You add or update a document. (Enqueue into the ingest buffer.)
• You add a synonym. (Synonyms live outside the collection.)
• You add a curation. (Curations are query-time.)
• You change a search API key's scopes or origin allow-list.

Triggering a reindex

From the dashboard:

1. Project → Indexes → Reindex.
2. Pick the source: From database (re-emit every active document from your PostgreSQL data source) or From snapshot (use the last committed Typesense snapshot of the index).
3. Confirm. The reindex runs in the background. The dashboard shows a progress bar with documents-per-second and ETA.

Programmatically:

POST /api/orpc/searchIndex.reindex
Content-Type: application/json
Authorization: Bearer ss_search_…  (scope: admin)

{ "indexId": "idx_…" }

The response is immediate; the work is enqueued. Poll searchIndex.getReindexStatus for progress.

What happens during a reindex

The current alias keeps serving until the swap. If you cancel mid-build, the partial collection is cleaned up and search traffic continues uninterrupted.

Sizing and time estimates

Reindex throughput is governed by Typesense bulk import speed and the source of truth (PostgreSQL or external). Rough estimates for the shared cluster:

If you're approaching the upper end, contact support before kicking off a reindex during business hours. We can pre-warm the destination collection and give you a dedicated worker.

Rollback

You can roll back to the previous version any time before the old version is dropped:

1. Project → Indexes → Versions.
2. The retention buffer (default: previous 2 versions) is listed with timestamps and document counts.
3. Click Promote next to the version you want. The alias is swapped back atomically.

After the retention buffer is purged, rollback is not possible — you would need to reindex from your source of truth.

To extend the retention buffer for a specific index, set Settings → Versions to keep. The maximum on the shared cluster is 5 versions. Dedicated clusters can keep more.

When reindex fails

A failed reindex leaves you in one of two states:

State A: alias still points at the old version

This is the safe failure mode. Search traffic is unaffected. The new (partial) collection is automatically dropped after 24 hours, or you can drop it manually from Versions → Discard.

Causes:

• Typesense ran out of RAM during the build. Action: open a ticket with the index size and error message.
• A field in the new schema rejected real document values (e.g. int32 overflow, string shorter than min length). Action: fix the schema or the document, then retry.
• The source ran out of documents to emit. Action: verify the source query returns the expected number of rows.

State B: alias was swapped but the new collection is unhealthy

This is rare — the swap is atomic, but if a configuration step after the swap fails (e.g. a synonym set couldn't be applied), you may see degraded search results.

Action:

1. Roll back to the previous version (procedure above).
2. Open a ticket with the request ID from reindex_failed audit row.

Reindex during a deploy

If your deploy includes a schema change, the recommended order is:

1. Deploy your application code with the new schema definition.
2. Trigger the reindex.
3. Wait for reindex_completed (poll or watch the dashboard).
4. Switch traffic to the deployed application.

Reindexing before deploying the application that uses the new fields wastes effort if your migration changes. Reindexing after deploying the application creates a window where the application expects fields that don't exist yet. The order above avoids both.

Common mistakes

• Reindexing as a fix for stale data. If documents are out of date, the issue is in your ingest pipeline, not the index version. Check the ingest buffer status. A reindex masks the symptom, not the cause.
• Reindexing too often. Each reindex burns CPU and disk on the shared cluster. If you're reindexing more than once a week without a schema change, something is wrong.
• Promoting an old version "to test rollback". Promotion is one atomic swap; it isn't free of cost. Test rollback in a staging project.

See also

• Monitoring — what "yellow / red" badges mean
• Status and incidents — when the cluster itself is the issue
• Audit logs — finding when and why a reindex was triggered