From 1d0851a0dca52c7e93057392f7afcaa2e9aab8af Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Tue, 2 Sep 2025 19:11:30 +0200 Subject: [PATCH 1/5] add index renaming documentation --- learn/getting_started/indexes.mdx | 31 +++++++++++++++++++------------ reference/api/indexes.mdx | 26 +++++++++----------------- 2 files changed, 28 insertions(+), 29 deletions(-) diff --git a/learn/getting_started/indexes.mdx b/learn/getting_started/indexes.mdx index eedc5c776b..d867e5ce4f 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. @@ -63,16 +63,23 @@ Index settings can be thought of as a JSON object containing many different opti 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) +- [Index creation](#index-creation) + - [Implicit index creation](#implicit-index-creation) + - [Explicit index creation](#explicit-index-creation) +- [Index UID](#index-uid) +- [Primary key](#primary-key) +- [Index settings](#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) +- [Swapping indexes](#swapping-indexes) To change index settings, use the [update settings endpoint](/reference/api/settings#update-settings) or any of the child routes. 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 From 2c05f1f9c54f3b9cde6860aaf80b34d56a33fc2a Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 3 Sep 2025 12:09:53 +0200 Subject: [PATCH 2/5] remove out-of-date index settings ToC --- learn/getting_started/indexes.mdx | 20 -------------------- 1 file changed, 20 deletions(-) diff --git a/learn/getting_started/indexes.mdx b/learn/getting_started/indexes.mdx index d867e5ce4f..a949ff08dd 100644 --- a/learn/getting_started/indexes.mdx +++ b/learn/getting_started/indexes.mdx @@ -61,26 +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: - -- [Index creation](#index-creation) - - [Implicit index creation](#implicit-index-creation) - - [Explicit index creation](#explicit-index-creation) -- [Index UID](#index-uid) -- [Primary key](#primary-key) -- [Index settings](#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) -- [Swapping indexes](#swapping-indexes) - To change index settings, use the [update settings endpoint](/reference/api/settings#update-settings) or any of the child routes. ### Displayed and searchable attributes From 400533af04c6836b2741f4f23108c1e58e880565 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 3 Sep 2025 17:18:34 +0200 Subject: [PATCH 3/5] add short guide --- docs.json | 1 + learn/indexing/rename_an_index.md | 30 ++++++++++++++++++++++++++++++ 2 files changed, 31 insertions(+) create mode 100644 learn/indexing/rename_an_index.md 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/indexing/rename_an_index.md b/learn/indexing/rename_an_index.md new file mode 100644 index 0000000000..9495ea22ab --- /dev/null +++ b/learn/indexing/rename_an_index.md @@ -0,0 +1,30 @@ +--- +title: Rename an index +description: Use the PATCH endpoint of the /indexes route to rename an index +--- + +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: + +```sh +curl \ + -X PATCH 'MEILISEARCH_URL/indexes/INDEX_A' \ + -H 'Content-Type: application/json' \ + --data-binary '{ "uid": "INDEX_B" }' +``` + +Replace `INDEX_A` with the current name of your index, and `INDEX_B` with its new name. \ No newline at end of file From 960827cea7d0567a0919bb38ff8cdc37bf5e72a9 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 3 Sep 2025 17:18:50 +0200 Subject: [PATCH 4/5] add line break --- learn/indexing/rename_an_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/indexing/rename_an_index.md b/learn/indexing/rename_an_index.md index 9495ea22ab..b3e11ab0b0 100644 --- a/learn/indexing/rename_an_index.md +++ b/learn/indexing/rename_an_index.md @@ -27,4 +27,4 @@ curl \ --data-binary '{ "uid": "INDEX_B" }' ``` -Replace `INDEX_A` with the current name of your index, and `INDEX_B` with its new name. \ No newline at end of file +Replace `INDEX_A` with the current name of your index, and `INDEX_B` with its new name. From 0886d89f67dd99193050cb47e254b628cae8022f Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 3 Sep 2025 17:21:15 +0200 Subject: [PATCH 5/5] move code sample to codesamples.yaml --- .code-samples.meilisearch.yaml | 6 ++++++ learn/indexing/rename_an_index.md | 9 +++------ 2 files changed, 9 insertions(+), 6 deletions(-) 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/learn/indexing/rename_an_index.md b/learn/indexing/rename_an_index.md index b3e11ab0b0..bb2a954b66 100644 --- a/learn/indexing/rename_an_index.md +++ b/learn/indexing/rename_an_index.md @@ -3,6 +3,8 @@ 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 @@ -20,11 +22,6 @@ Also choose the new name you wish to assign the index. This guide uses `INDEX_B` Send a `PATCH` request targeting the index you want to rename: -```sh -curl \ - -X PATCH 'MEILISEARCH_URL/indexes/INDEX_A' \ - -H 'Content-Type: application/json' \ - --data-binary '{ "uid": "INDEX_B" }' -``` + Replace `INDEX_A` with the current name of your index, and `INDEX_B` with its new name.