Indexes

Headband creates the index on the new engine, placed as a new index of that engine on the same branch would be: your instanceId, else the branch's default engine of that type, made on first use within your plan's engines per type. It copies every document while writes still flow (phase copying). Then it holds writes to the index: they answer 503 index_migrating with Retry-After: 5 for about a minute (draining), then while the last changes are copied and every document is checked (catching_up). The minute lets a write that was already on its way to the old engine land there before the last changes are copied, so it is not lost. An index on a shared engine, or a switch while one of Headband's hosts is out of touch, waits five minutes instead, because a write there can take that long to finish. Settings changed during the copy stop the switch with the error settings_changed: start it again to carry them. The switch happens only when both indexes hold the same number of documents, the same ids, and each document as it was sent. Any mismatch stops it: writes resume on the old engine, the new copy is deleted, and nothing changes. After the switch the old copy is deleted (cleaning). Writes sent straight to an engine endpoint with the engine's own client are not held, so pause them during a switch.

Each engine applies a different part of the settings vocabulary (see engine compatibility). A switch carries what the new engine applies and lists every other setting in settings.drops with a reason. With any drop, the request answers 409 settings_not_portable and the same report until you send acceptDrops: true. A drop with kept: true is stored on the new index but not applied by its search.

An index on your own engine (BYOE) or managed by Sync is not switched. A switch to Typesense needs the primary key id, and copies numeric ids as strings. Typesense types each field by the first value it sees, so a field that mixes whole numbers and decimals would be changed: such a switch stops with content_mismatch and nothing changes. Indexes of any size switch, Elasticsearch ones included. A Visor index over 1000 documents is read by its primary key, which must be filterable and sortable: send declareKey: true to declare it for the read (Visor rebuilds the index), or the request answers 400 primary_key_not_declared. A switch to Visor makes the primary key filterable and sortable there, so the index can move again later. One switch runs per index at a time (409 engine_switch_in_progress).