Share the article
Rebuilding a production index without taking search down is a standing problem for anyone running a search engine. Meilisearch solves it with index swapping: you build the new version alongside the live one, then swap them atomically.
This post explains the approaches people reach for first, why they fall short, and how the swap works.
Why updating a live index is hard
Suppose you have changes in your database that you need to synchronize with your Meilisearch index in production. Without index swapping, your options are all bad:
Update your index in place
Simple, and a trap. Updating a production index while it is serving search queries produces inconsistent results and, briefly, missing documents. Users notice.
Delete the index, create a new index with the same name, and re-index the data
Each step takes time, and that time is downtime. It is also at least three requests, and on a large dataset the re-index alone can run for minutes.
Create a new index with another name, stage the changes there, then modify all the clients to point to the new index
Not the worst option, but updating the clients is itself a deploy, and sometimes not one you control. An iOS app has to clear App Store review before the new index name reaches users.
Create an intermediate redirection layer to avoid downtime
This works, but it means designing, deploying, and maintaining another piece of infrastructure purely to rename an index.
How does index swapping work?
It exchanges the contents of two indexes atomically, so you can build the new version alongside the live one and switch them in a single operation. Search traffic never sees a partial state, and the index names your clients use never change.
Here is how it works.
Say you have an index in production, indexA, that your clients search. You want to sync changes from your primary database into it. Here are the steps.
Step 1: Create a new index with up-to-date data
First, create an index, say indexA_new, representing the new version of indexA that you want to deploy to your search clients. Add up-to-date documents from your database, and update the index settings if necessary.
Don’t forget to check that all the tasks related to the index creation have successfully completed, including indexCreation, settingsUpdate, and documentAdditionOrUpdate task types. You can use the /tasks route to get information about their progress.
Step 2: Test the new index
Before sending your index to production, you want to be sure everything is working as expected.
Make sure to update the settings for any new fields you may have introduced with the updated data. For example, you may want to add new fields to searchableAttributes, filterableAttributes, and/or sortableAttributes. Don't forget to double-check the relevancy of search results any time you add new data!
Keep in mind that the searchableAttributes list not only designates the fields that are searchable, but also dictates the attribute ranking order. Make sure any new fields you may have introduced are added to the list in the right order.
Step 3: Swap indexes
Once your indexA_new has been successfully created, filled with data, and tested, it’s ready to be deployed with an index swap. To do so, send a POST request to the /swap-indexes endpoint. Specify the indexes you want to swap in the payload. Since it’s a swap, the order doesn’t matter.
In a protected Meilisearch instance, the API key used to swap indexes must have access to the indexes.swap action as well as the indexes you want to swap. If not, Meilisearch will throw an invalid_api_key error. For more information about creating API keys with specific permissions, see the documentation.
You can use the response's taskUid to track the status of your request with the GET /tasks/{task_uid} endpoint. A successful index swap should look like this:
Your indexes have been swapped without any downtime! The documents, settings, and task history of indexA, except for any enqueued tasks, have been swapped with those of indexA_new. Every mention of indexA in the task history has been replaced by indexA_new and vice-versa (enqueued tasks are left unmodified).
After the swap, indexA_new holds the outdated content. You can delete it or keep it as a backup, should something go wrong and you need to swap back. Better safe than sorry!
And that’s it. Three steps, two if you skip the testing.
Swapping several indexes at once
A single request can swap as many index pairs as you like. Meilisearch can deploy all changes at the same time. Clients will access the new version of all indexes at once without any downtime.
In the example above, three swap operations will occur simultaneously and atomically.
Wait, what?
Yes, you can read that again. It’s atomic! Either all indexes are successfully swapped, or none are. Either all the content is swapped, or none is.
Why is that important? It prevents partial changes in the database, ensuring consistency and, thus, a top-notch search experience.
Conclusion
As I mentioned earlier, this feature has been in the works for several months, and it all started with user feedback. The “swap indexes” card on our roadmap got 38 votes and almost as many comments explaining use cases where this feature is a must-have. Here are some of our favorites:
- “It would be very useful when trying to change rules on production database to tweak for the best results”
- “Would help if index was accidentally created with wrong name or need to rename/change it for various reasons.”
- “We need it to clean out all deleted items.”
These are just a few examples. This kind of insight is extremely helpful for our team, as it allows us to shape the product to fit the users' needs.
The roadmap gives an overall view of feature ideas submitted, in progress, and released, but it is only one way to give feedback.
The product discussions on GitHub are, in my opinion, one of the best places to explain your needs. You can have direct contact with the Meilisearch product team, and, being public, it allows anyone to participate and enrich the process.
The last option is our Discord server. Don’t hesitate to join us and talk about what you’ve built with Meilisearch, your use case, and your specific needs.
No matter which option you choose, we look forward to hearing from you.
If you would rather not operate the engine yourself, Meilisearch Cloud runs it for you, with a 14-day free trial and no credit card required. Index swapping works exactly the same way there.
Frequently asked questions (FAQs)
How do I update a Meilisearch index without downtime?
Build the new version in a separate index, verify it, then swap the two with a POST to /swap-indexes. The swap is atomic, so search traffic moves from the old index to the new one without ever seeing a partial state.
What exactly gets swapped?
Documents, settings, and task history. Enqueued tasks are left untouched, and every reference to each index in the task history is rewritten to point at the other. The index names stay the same from your clients' point of view, which is what makes the operation invisible to them.
Can I swap more than one index at a time?
Yes, and you should when the indexes are related. A single request can carry several index pairs, and the whole request is atomic: either every pair swaps or none does. That keeps related indexes from drifting out of sync mid-deploy.
What happens to the old index after the swap?
It still exists, under the other name, holding the previous content. Keep it as a rollback path, since swapping back is another single request, or delete it once you are confident in the new data.
Which permissions does an index swap need?
The API key must carry the indexes.swap action and cover both indexes involved. Without that, Meilisearch returns an invalid_api_key error.
