Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

v0.30: swap indexes #1992

Merged
merged 12 commits into from
Nov 23, 2022
16 changes: 16 additions & 0 deletions .code-samples.meilisearch.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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'\
maryamsulemani97 marked this conversation as resolved.
Show resolved Hide resolved
-H 'Content-Type: application/json' \
--data-binary '[
{
"indexes":[
"indexA",
"indexB"
],
"indexes":[
"indexX",
"indexY"
]
}
]'
1 change: 1 addition & 0 deletions .vuepress/public/sample-template.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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: |
6 changes: 6 additions & 0 deletions learn/core_concepts/indexes.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,3 +145,9 @@ 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 without any downtime. 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`. The task history of `enqueued` tasks is not modified. Swapping indexes is an atomic transaction, **either all indexes are successfully swapped, or none are**.
maryamsulemani97 marked this conversation as resolved.
Show resolved Hide resolved

You can perform multiple swap operations using the [swap indexes endpoint](/reference/api/indexes.md#swap-indexes).
maryamsulemani97 marked this conversation as resolved.
Show resolved Hide resolved
maryamsulemani97 marked this conversation as resolved.
Show resolved Hide resolved
40 changes: 40 additions & 0 deletions reference/api/indexes.md
Original file line number Diff line number Diff line change
Expand Up @@ -214,3 +214,43 @@ 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.**
maryamsulemani97 marked this conversation as resolved.
Show resolved Hide resolved

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.

### 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`.
maryamsulemani97 marked this conversation as resolved.
Show resolved Hide resolved
:::

You can use the response's `taskUid` to [track the status of your request](/reference/api/tasks.md#get-one-task).
12 changes: 8 additions & 4 deletions reference/api/tasks.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand Down
4 changes: 4 additions & 0 deletions reference/errors/error_codes.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
maryamsulemani97 marked this conversation as resolved.
Show resolved Hide resolved

## `index_already_exists`

An index with this UID already exists, check out our guide on [index creation](/learn/core_concepts/indexes.md).
Expand Down