diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml
index 484681fc41..1fce7302b9 100644
--- a/.code-samples.meilisearch.yaml
+++ b/.code-samples.meilisearch.yaml
@@ -1508,6 +1508,12 @@ webhooks_patch_1: |-
webhooks_delete_1: |-
curl \
-X DELETE 'MEILISEARCH_URL/webhooks/WEBHOOK_UUID'
+rename_an_index_1: |-
+ curl \
+ -X PATCH 'MEILISEARCH_URL/indexes/INDEX_A' \
+ -H 'Content-Type: application/json' \
+ --data-binary '{ "uid": "INDEX_B" }'
+
### Code samples for experimental features
experimental_get_metrics_1: |-
diff --git a/docs.json b/docs.json
index 2f1b77e821..f802252852 100644
--- a/docs.json
+++ b/docs.json
@@ -277,6 +277,7 @@
{
"group": "Indexing",
"pages": [
+ "learn/indexing/rename_an_index",
"learn/indexing/indexing_best_practices",
"learn/indexing/ram_multithreading_performance",
"learn/indexing/tokenization"
diff --git a/learn/getting_started/indexes.mdx b/learn/getting_started/indexes.mdx
index eedc5c776b..a949ff08dd 100644
--- a/learn/getting_started/indexes.mdx
+++ b/learn/getting_started/indexes.mdx
@@ -37,8 +37,6 @@ While implicit index creation is more convenient, requiring only a single API re
The `uid` is the **unique identifier** of an index. It is set when creating the index and must be an integer or string containing only alphanumeric characters `a-z A-Z 0-9`, hyphens `-` and underscores `_`.
-**Once defined, the `uid` cannot be changed**, and you cannot create another index with the same `uid`.
-
```json
{
"uid": "movies",
@@ -47,6 +45,8 @@ The `uid` is the **unique identifier** of an index. It is set when creating the
}
```
+You can change an index's `uid` using the [`/indexes` API route](/reference/api/indexes#update-an-index).
+
## Primary key
Every index has a primary key: a required attribute that must be present in all documents in the index. Each document must have a unique value associated with this attribute.
@@ -61,19 +61,6 @@ You can set the primary key for an index or let it be inferred by Meilisearch. R
Index settings can be thought of as a JSON object containing many different options for customizing search behavior.
-You can customize the following index settings:
-
-- [Displayed and searchable attributes](#displayed-and-searchable-attributes)
-- [Distinct attribute](#distinct-attribute)
-- [Faceting](#faceting)
-- [Filterable attributes](#filterable-attributes)
-- [Pagination](#pagination)
-- [Ranking rules](#ranking-rules)
-- [Sortable attributes](#sortable-attributes)
-- [Stop words](#stop-words)
-- [Synonyms](#synonyms)
-- [Typo tolerance](#typo-tolerance)
-
To change index settings, use the [update settings endpoint](/reference/api/settings#update-settings) or any of the child routes.
### Displayed and searchable attributes
diff --git a/learn/indexing/rename_an_index.md b/learn/indexing/rename_an_index.md
new file mode 100644
index 0000000000..bb2a954b66
--- /dev/null
+++ b/learn/indexing/rename_an_index.md
@@ -0,0 +1,27 @@
+---
+title: Rename an index
+description: Use the PATCH endpoint of the /indexes route to rename an index
+---
+
+import CodeSamplesRenameAnIndex1 from '/snippets/samples/code_samples_rename_an_index_1.mdx';
+
+This guide shows you how to change the name of an index.
+
+## Requirements
+
+- A Meilisearch project with at least one index
+- A command-line terminal
+
+## Choose the target index and its new name
+
+Decide which index you want to rename and keep note of its `uid`. This guide changes the name of an index called `INDEX_A`.
+
+Also choose the new name you wish to assign the index. This guide uses `INDEX_B` for the new name of the index.
+
+## Query the `/indexes/{index_uid}` route
+
+Send a `PATCH` request targeting the index you want to rename:
+
+
+
+Replace `INDEX_A` with the current name of your index, and `INDEX_B` with its new name.
diff --git a/reference/api/indexes.mdx b/reference/api/indexes.mdx
index 12360407fa..a257206b9b 100644
--- a/reference/api/indexes.mdx
+++ b/reference/api/indexes.mdx
@@ -164,10 +164,6 @@ Update an index's [primary key](/learn/getting_started/primary_key#primary-key).
To change the primary key of an index that already contains documents, you must first delete all documents in that index. You may then change the primary key and index your dataset again.
-
-It is not possible to change an index's `uid`.
-
-
### Path parameters
| Name | Type | Description |
@@ -179,6 +175,7 @@ It is not possible to change an index's `uid`.
| Name | Type | Default value | Description |
| :----------------- | :-------------- | :------------ | :---------------------------------------------------------------------------------------- |
| **`primaryKey`** * | String / `null` | N/A | [`Primary key`](/learn/getting_started/primary_key#primary-field) of the requested index |
+| **`uid`** * | String / `null` | N/A | New `uid` of the requested index |
### Example
@@ -230,15 +227,11 @@ You can use the response's `taskUid` to [track the status of your request](/refe
## Swap indexes
-```http
-POST /swap-indexes
-```
-
-Swap the documents, settings, and task history of two or more indexes. **You can only swap indexes in pairs.** However, a single request can swap as many index pairs as you wish.
+Swap the documents, settings, and task history of two or more indexes. **You can only swap indexes in pairs.** A single request can swap as many index pairs as you wish.
-Swapping indexes is an atomic transaction: **either all indexes are successfully swapped, or none are.**
+Swapping indexes is an atomic transaction: **either all indexes in a request are successfully swapped, or none are.** You can swap multiple pairs of indexes with a single request. To do so, there must be one object for each pair of indexes to be swapped.
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.
@@ -246,17 +239,16 @@ Swapping `indexA` and `indexB` will also replace every mention of `indexA` by `i
### Body
-An array of objects. Each object has only one key: `indexes`.
+An array of objects with the following fields:
-| Name | Type | Default value | Description |
-| :------------- | :--------------- | :------------ | :----------------------------------------- |
-| **`indexes`*** | Array of strings | N/A | Array of the two `indexUid`s to be swapped |
+| Name | Type | Default value | Description |
+| :------------- | :--------------- | :------------ | :------------------------------------------------- |
+| **`indexes`** | Array of strings | N/A | Array of the two `indexUid`s to be swapped |
+| **`rename`** | Boolean | `false` | If `true`, renames an index instead of swapping it |
Each `indexes` array must contain only two elements: the `indexUid`s of the two indexes to be swapped. Sending an empty array (`[]`) is valid, but no swap operation will be performed.
-
-You can swap multiple pairs of indexes with a single request. To do so, there must be one object for each pair of indexes to be swapped.
-
+Use `rename: false` if you are swapping two existing indexes. Use `rename: true` if the second index in your array does not exist.
### Example