Add documentation for index renaming (#3351)

Author: guimachiavelli

.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: |-

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"

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

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:
+
+<CodeSamplesRenameAnIndex1 />
+
+Replace `INDEX_A` with the current name of your index, and `INDEX_B` with its new name.

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.
 
-<Note>
-It is not possible to change an index's `uid`.
-</Note>
-
 ### 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,33 +227,28 @@ You can use the response's `taskUid` to [track the status of your request](/refe
 
 ## Swap indexes
 
-```http
-POST /swap-indexes
-```
-
 <RouteHighlighter method="POST" path="/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.
 
 [To learn more about index swapping, refer to this short guide.](/learn/getting_started/indexes#swapping-indexes)
 
 ### 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.
 
-<Note>
-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.
-</Note>
+Use `rename: false` if you are swapping two existing indexes. Use `rename: true` if the second index in your array does not exist.
 
 ### Example