Who this is for. The developer who changed a model, imported content or refreshed an environment, and needs to know whether search is now out of date. Afterwards you can tell which changes reindex themselves, which do not, and which of Reindex and Rebuild to run.
What updates the index on its own
- Saving, publishing, unpublishing or deleting an indexed record in a web request, in the admin or through the API. The record's document is rewritten in the background shortly afterwards, or removed when the record is no longer published, public and indexable (What happens between publish and searchable).
- A scheduled publish or expiry. A platform task that runs once a minute for each site picks up records whose publish date has passed, and pages whose unpublish date has arrived, and queues their indexing as if they had been saved.
- A change to the mapping. Pointing an area at a search field, changing which field it fills, and renaming or deleting a search field each queue a reindex of every site on the account.
- Product descriptions are written to the facets index as well as to site search, from the same events.
What leaves the index stale
Each of these changes what a search ought to return without touching the documents that hold the old values: save the affected records again, or reindex, to bring the results up to date.
- Saves made by background processes. Only a save in a web request queues the record event that indexing waits for. An asynchronous or scheduled job, an import or a script run on the server writes records that are never indexed.
- Editing a global component. Its text is copied into the document of every page that uses it, at the time that page is indexed, and those pages are not reindexed when the component changes.
- Renaming a tag or a category. Their names and slugs are copied into each record's document too.
- Changing a product's price or stock. These belong to the product or variant, not to its description, and only descriptions are indexed. A facet value computed from them, such as a price band, stays as it was until the description is saved or the facets index is reindexed.
- Saving the facets mapping template, or changing its indexing scope. The Configure screen says so: nothing is reindexed until you choose to.
- Adding a facet. A new facet stays empty until the mapping template sets it and the facets index is reindexed.
Reindex or Rebuild
Search › Indices, which only administrators see, lists both indices, Site Search and Faceted Search, each with a Reindex and a Rebuild button for the current site and for all sites.
| Reindex | Rebuild | |
|---|---|---|
| What it does | Rewrites every document in place, then removes the documents that were not rewritten | Deletes the index with all its documents, creates it again, then reindexes |
| Search while it runs | Keeps answering from the old documents until each is replaced | Returns partial results, filling up as the batches complete |
| Use it for | Stale content: any case in the list above, a bulk change, a new environment, a restored database | A change to the index's structure: a search field's or a facet's type, or a facet's Case Sensitive or Fulltext switch |
A structural change to the index needs a Rebuild to take effect. Making one shows a Rebuild required banner on the Indices page and an admin notification, The master search index needs to be rebuilt to apply your changes (or facets), so you know to run it. Until Rebuild runs, results keep reflecting the old structure.
How long it takes
Both operations queue their work and return at once. A reindex walks each record type of the site in batches of 100 records, and each batch is a job on the platform's background queue, sharing it with the rest of the platform's background work. Ten thousand pages and products make about a hundred batches, so the time depends on how busy the queue is more than on the number of records. Fifteen minutes after the batches are queued, a final job removes every document that was not rewritten, and the reindex is complete. Until then the Indices page shows when it started.
So, on a large site:
- Prefer Reindex whenever it is enough. It never empties the index.
- Run Rebuild out of hours. Search is incomplete until every batch has run.
- Do not start a second run while the first is listed as started. The second run moves the start time forward, and the first run's clean-up then removes every document written before it, including those the second run has not rewritten yet. Search has holes until the second run catches up.
- Allow for other background work. A reindex during a large import or a busy job run is slowed by it, and slows it in turn.
Environments
The index's name and settings, including the facets mapping template and its indexing scope, are kept in a .search-indices folder in the site's folder on the server: not in the database, and not in the repository. Two consequences:
- A deploy reindexes nothing, and an environment whose database has been replaced, or a new one, starts with an index that does not match its records. Run Reindex there once.
- The facets mapping template has to be entered on each environment. Keep a copy in the repository so the environments can be compared and restored, outside
templates/and under a name the site does not serve as a page, such assearch-config/facets-mapping.tpl.