v0.30: swap indexes

.code-samples.meilisearch.yaml

@@ -1043,3 +1043,19 @@ async_guide_filter_by_date: |
 async_guide_multiple_filters: |
   curl \
     -X POST 'http://localhost:7700/tasks?indexUid=movies&type=documentAdditionOrUpdate,documentDeletion&status=processing,enqueued'
+swap_indexes_1: |
+  curl \
+    -X POST 'http://localhost:7700/swap-indexes'\
+    -H 'Content-Type: application/json' \
+    --data-binary '[
+   {
+      "indexes":[
+         "indexA",
+         "indexB"
+      ],
+      "indexes":[
+         "indexX",
+         "indexY"
+      ]
+   }
+  ]'

.vuepress/public/sample-template.yaml

@@ -161,3 +161,4 @@ date_guide_sortable_attributes_1: |
 date_guide_sort_1: |
 async_guide_filter_by_date: |
 async_guide_multiple_filters: |
+swap_indexes_1: |

learn/core_concepts/indexes.md

@@ -145,3 +145,15 @@ Typo tolerance is a built-in feature that helps you find relevant results even w
 You can update the typo tolerance settings using the [update settings endpoint](/reference/api/settings.md#update-settings) or the [update typo tolerance endpoint](/reference/api/settings.md#update-typo-tolerance-settings).
 
 [Learn more about typo tolerance.](/learn/configuration/typo_tolerance.md)
+
+## Swapping indexes
+
+Suppose you want to deploy a new version of your `movies` index in production. This `movies` index is where your users are currently making search requests. The changes you made are in `movies_new`. To sync `movies_new` with Meilisearch in production, you will use index swapping.
+
+This means that the schema, settings, and task history of  `movies` will be swapped with the schema, settings, and task history of `movies_new` **without any downtime for the search clients**. The task history of `enqueued` tasks is not modified.
+
+Once swapped, your users will still be making search requests to the `movies` index but it will contain the data of `movies_new`. You can delete `movies_new` after the swap or keep it in case something goes wrong and you want to swap back.
+
+Swapping indexes is an atomic transaction: **either all indexes are successfully swapped, or none are**.
+
+You can perform multiple swap operations using the [swap indexes endpoint](/reference/api/indexes.md#swap-indexes).

reference/api/indexes.md

@@ -214,3 +214,45 @@ Delete an index.
 ```
 
 You can use the response's `taskUid` to [track the status of your request](/reference/api/tasks.md#get-one-task).
+
+## Swap indexes
+
+<RouteHighlighter method="POST" route="/indexes/swap-indexes"/>
+
+Swap indexes. **You can only swap indexes in pairs.** Swapping indexes is an atomic transaction: **either all indexes are successfully swapped, or none are.**
+
+Swapping `indexA` and `indexB` will also replace every mention of `indexA` by `indexB` and vice-versa in the task history. `enqueued` tasks are left unmodified.
+
+[To learn more about index swapping, refer to our dedicated guide.](/learn/core_concepts/indexes.md#swapping-indexes)
+
+### Body
+
+| Name           | Type             | Default value | Description                                |
+| :------------- | :--------------- | :------------ | :----------------------------------------- |
+| **`indexes`*** | Array of strings | N/A           | Array of the two `indexUid`s to be swapped |
+
+::: note
+Sending `[]` is valid but no swap operation will be performed.
+:::
+
+### Example
+
+<CodeSamples id='swap_indexes_1' />
+
+#### Response
+
+```json
+{
+  "taskUid": 3,
+  "indexUid": null,
+  "status": "enqueued",
+  "type": "indexSwap",
+  "enqueuedAt": "2021-08-12T10:00:00.000000Z"
+}
+```
+
+::: note
+Since `indexSwap` is a [global task](/learn/advanced/asynchronous_operations.md#global-tasks), the `indexUid` is `null`.
+:::
+
+You can use the response's `taskUid` to [track the status of your request](/reference/api/tasks.md#get-one-task).

reference/api/tasks.md

@@ -119,17 +119,21 @@ This value is always `null` for `dumpCreation` tasks.
 
 #### `indexSwap`
 
+| Name        | Description                                            |
+| :---------- | :----------------------------------------------------- |
+| **`swaps`** | Object containing the payload for the `indexSwap` task |
+
 ### `error`
 
 **Type**: Object
 **Description**: Error details and context. Only present when a task has the `failed` [status](#status)
 
-| Name          | Description                                         |
-| :------------ | :-------------------------------------------------- |
-| **`message`** | A human-readable description of the error           |
+| Name          | Description                                            |
+| :------------ | :----------------------------------------------------- |
+| **`message`** | A human-readable description of the error              |
 | **`code`**    | The [error code](/reference/errors/error_codes.md)     |
 | **`type`**    | The [error type](/reference/errors/overview.md#errors) |
-| **`link`**    | A link to the relevant section of the documentation |
+| **`link`**    | A link to the relevant section of the documentation    |
 
 ### `duration`
 

reference/errors/error_codes.md

@@ -34,6 +34,10 @@ The requested dump could not be found.
 
 An error occurred during dump creation process, task aborted.
 
+## `duplicate_index_found`
+
+The indexes used in the `indexes` array have been declared multiple times. You must declare each index only once.
+
 ## `index_already_exists`
 
 An index with this UID already exists, check out our guide on [index creation](/learn/core_concepts/indexes.md).