Migration overview

Most migrations to AACsearch follow the same shape: export your existing data, map your schema to a Typesense-style collection, replay documents into AACsearch, switch your application's read path, and decommission the old stack. The specifics differ by source, but the cutover risk is what each per-source guide focuses on.

This index page is the place to start. Pick the guide for your source, run the checklist on cutover day, and the per-source page handles the rest.

Pick your starting point

If your source isn't listed, the Database search guide is the most general template — extract documents, define a schema, ingest, validate.

What stays the same across migrations

Regardless of source, you will:

1. Map your schema. Field names, types, what is searched (query_by), what is filtered, what is sorted.
2. Export your documents. As NDJSON or CSV. Most sources give you this directly; for SQL, write a query.
3. Pick your tenant model. One index for the whole org, or per-tenant indexes — decided by your data volume and isolation requirements. See Tenant isolation.
4. Replay into AACsearch. Through the ingest buffer. The buffer absorbs the volume and back-pressures cleanly — you don't need to pace.
5. Validate. Spot-check a sample of queries. Compare top-N hits between old and new for the same query. See Validation.
6. Cut over. Switch the client to AACsearch. Keep the old system warm for at least 7 days for rollback.

What changes across migrations

Two things almost always need rework:

Ranking

Every search engine has different defaults. The most common surprises:

• Field weighting. Algolia/Elasticsearch let you put more weight on title vs description; AACsearch does too, but via query_by_weights. Re-tune; don't expect the old weights to translate.
• Boost rules. Time decay, popularity boost — re-encode as sort_by expressions.
• Stop words and stemming. Each engine has its own behavior. Expect to find a corpus of "this query used to return X" cases and fix them as curations.

Tokenizer behavior

The default Typesense tokenizer is good for general text but differs from Elasticsearch analyzers, which are highly configurable. Plan a sprint of validation against your real query log, not just synthetic queries.

Validation

Build a list of 100 representative queries from your existing analytics. For each, compare the top-5 hits before and after. Categorize:

• Identical — top-5 is the same set, possibly in a different order.
• Mostly the same — 3+ of the top-5 match.
• Drift — fewer than 3 match.

Drift cases are where you spend tuning effort. Some of them are bugs in the migration (a field didn't map correctly); some are improvements (the new engine ranks better); some require curations.

Do not skip this step. Migrating without query-level validation is how you end up with "search feels worse after the migration" feedback you can't refute.

Cutover models

There are two cutover patterns. Pick by risk tolerance.

Dark-launch then flip

1. Index into AACsearch in parallel with your existing system.
2. Mirror queries to both systems; log the results.
3. Compare for some period (a day, a week).
4. Flip read traffic to AACsearch.
5. Keep the old system reading for 7 days.

Lower risk, more engineering effort.

Cutover with rollback window

1. Index into AACsearch.
2. Validate against the 100-query sample.
3. Flip read traffic during a quiet window.
4. Keep the old system as a hot fallback for 7 days.
5. Switch the rollback path off after the window.

Less engineering, more deploy-time discipline. Suitable when your search is not a revenue-critical path.

What we don't do

• Automated end-to-end migration. We don't ship a tool that takes Algolia credentials and produces a working AACsearch index. Schema, ranking, and curation choices are too project-specific.
• Promise that the engine is a drop-in replacement. Engines differ. Plan for ~1–2 weeks of post-migration tuning on any non-trivial corpus.
• Migrate your application code for you. SDKs are available — see SDKs — and the per-source guides include the most common client patterns, but client refactoring is on your side.

See also

• The migration checklist — dry run, validation, cutover, rollback
• Reindexing — for post-migration schema changes
• Tenant isolation — decide your tenant model before the migration, not after