Add index settings tutorials (#2711)

.code-samples.meilisearch.yaml

@@ -1167,3 +1167,17 @@ update_proximity_precision_settings_1: |-
 reset_proximity_precision_settings_1: |-
   curl \
     -X DELETE 'http://localhost:7700/indexes/books/settings/proximity-precision'
+index_settings_tutorial_api_get_setting_1: |-
+  curl \
+    -X GET 'http://localhost:7700/indexes/INDEX_NAME/settings/searchable-attributes'
+index_settings_tutorial_api_put_setting_1: |-
+  curl \
+    -X PUT 'http://localhost:7700/indexes/INDEX_NAME/settings/searchable-attributes' \
+    -H 'Content-Type: application/json' \
+    --data-binary '[
+      "title",
+      "overview"
+    ]'
+index_settings_tutorial_api_task_1: |-
+curl \
+  -X GET 'http://localhost:7700/tasks/TASK_UID'

config/sidebar-learn.json

@@ -132,6 +132,16 @@
         "source": "learn/configuration/instance_options.mdx",
         "label": "Configure Meilisearch at launch",
         "slug": "instance_options"
+      },
+      {
+        "source": "learn/configuration/configuring_index_settings.mdx",
+        "label": "Configuring index settings",
+        "slug": "configuring_index_settings"
+      },
+      {
+        "source": "learn/configuration/configuring_index_settings_api.mdx",
+        "label": "Configuring index settings with the Meilisearch API",
+        "slug": "configuring_index_settings_api"
       }
     ]
   },

learn/configuration/configuring_index_settings.mdx

@@ -0,0 +1,67 @@
+---
+title: Configuring index settings — Meilisearch documentation
+description: This tutorial shows how to check and change an index setting using the Meilisearch Cloud interface.
+---
+
+# Configuring index settings with the Meilisearch Cloud interface
+
+This tutorial will show you how to check and change an index setting using the [Meilisearch Cloud](https://cloud.meilisearch.com/projects/?utm_campaign=oss&utm_source=docs&utm_medium=settings-tutorial) interface.
+
+## Requirements
+
+- an active [Meilisearch Cloud](https://cloud.meilisearch.com/projects/?utm_campaign=oss&utm_source=docs&utm_medium=settings-tutorial) account
+- a Meilisearch Cloud project with at least one index
+
+## Accessing a project's index settings
+
+Log into your Meilisearch account and navigate to your project. Then, click on "Indexes":
+
+![The main menu of the project view in the Meilisearch Cloud interface. Menu itmes include "Indexes" among other options such as "Settings" and "Analytics".](https://raw.githubusercontent.com/meilisearch/documentation/cloud-index-settings/assets/images/cloud-index-settings/01-indexes-tab.png)
+
+Find the index you want to configure and click on its "Settings" button:
+
+![A list of indexes in a Meilisearch Cloud project. It shows an index named "books" along with a few icons and buttons. One of these buttons is "Settings."](https://raw.githubusercontent.com/meilisearch/documentation/cloud-index-settings/assets/images/cloud-index-settings/02-index-settings.png)
+
+## Checking a setting's current value
+
+Using the menu on the left-hand side, click on "Attributes":
+
+![The index configuration overview together with a menu with links to pages dedicated to various index settings.](https://raw.githubusercontent.com/meilisearch/documentation/cloud-index-settings/assets/images/cloud-index-settings/03-general-settings.png)
+
+Scroll and look for "Searchable attributes":
+
+![The "Searchable attributes" configuration section showing the default setting value.](https://raw.githubusercontent.com/meilisearch/documentation/cloud-index-settings/assets/images/cloud-index-settings/04-searchable-attributes-default.png)
+
+If this is a new index, you should see the default value, `["*"]`. This indicates Meilisearch looks through all document attributes when searching.
+
+## Updating a setting
+
+All documents include a primary key attribute. In most cases, this attribute does not contain any relevant data, so you can improve your application search experience by explicitly removing it from your searchable attributes list.
+
+Click on the input box with the current value. Then, replace it with an array of strings containing all attributes in your index except the primary key:
+
+![The "Searchable attributes" configuration section showing the new setting value: \["title","author","genre","price"\].](https://raw.githubusercontent.com/meilisearch/documentation/cloud-index-settings/assets/images/cloud-index-settings/05-searchable-attributes-filled.png)
+
+Two buttons will appear on the bottom of the screen when you start editing a field. Once you're finished editing a setting, click on "Save":
+
+![The "Searchable attributes" configuration section showing two buttons at the bottom of the screen: "Cancel changes" and "Save".](https://raw.githubusercontent.com/meilisearch/documentation/cloud-index-settings/assets/images/cloud-index-settings/06-save.png)
+
+The button icon will change to a spinning wheel to indicate Meilisearch is processing the changes. Depending on the size of your dataset and the setting you have edited, this might take some time:
+
+![The "Searchable attributes" configuration section showing two buttons at the bottom of the screen. The "Save" button now has a spinning loading icon.](https://raw.githubusercontent.com/meilisearch/documentation/cloud-index-settings/assets/images/cloud-index-settings/07-saving.png)
+
+Once Meilisearch is ready, the button should change to a green color. You will also see a notification pop-up on the right-hand side of your screen.
+
+![The "Searchable attributes" configuration section showing two buttons at the bottom of the screen. The "Save" button has changed color and now reads "Saved".](https://raw.githubusercontent.com/meilisearch/documentation/cloud-index-settings/assets/images/cloud-index-settings/08-saved.png)
+
+## Conclusion
+
+You have used the Meilisearch Cloud interface to check the value of an index setting. This revealed an opportunity to improve your project's performance, so you updated this index setting to make your application better and more responsive.
+
+This tutorial used the searchable attributes setting, but the procedure is the same no matter which index setting you are editing.
+
+## What's next
+
+If you prefer to access the settings API directly through your console, you can also [configure index settings using the Meilisearch Cloud API](/learn/configuration/configuring_index_settings_api).
+
+For a comprehensive reference of all index settings, consult the [settings API reference](/reference/api/settings).

learn/configuration/configuring_index_settings_api.mdx

@@ -0,0 +1,94 @@
+---
+title: Configuring index settings with the Meilisearch API — Meilisearch documentation
+description: This tutorial shows how to check and change an index setting using the Meilisearch API.
+---
+
+# Configuring index settings with the Meilisearch API
+
+This tutorial shows how to check and change an index setting using one of the setting subroutes of the Meilisearch API.
+
+If you are Meilisearch Cloud user, you may also [configure index settings using the Meilisearch Cloud interface](/learn/configuration/configuring_index_settings).
+
+## Requirements
+
+- a new [Meilisearch Cloud](https://cloud.meilisearch.com/projects/?utm_campaign=oss&utm_source=docs&utm_medium=settings-api-tutorial) project or a self-hosted Meilisearch instance with at least one index
+- a command-line terminal with `curl` installed
+
+## Getting the value of a single index setting
+
+Start by checking the value of the searchable attributes index setting.
+
+Use the `GET` endpoint of the `/settings/searchable-attributes` subroute, replacing `INDEX_NAME` with your index:
+
+<CodeSamples id="index_settings_tutorial_api_get_setting_1" />
+
+Depending on your setup, you might also need to replace `localhost:7700` with the appropriate address and port.
+
+You should receive a response immediately:
+
+```json
+[
+  "*"
+]
+```
+
+If this is a new index, you should see the default value, `["*"]`. This indicates Meilisearch looks through all document attributes when searching.
+
+## Updating an index setting
+
+All documents include a primary key attribute. In most cases, this attribute does not contain any relevant data, so you can improve your application search experience by explicitly removing it from your searchable attributes list.
+
+Use the `PUT` endpoint of the `/settings/searchable-attributes` subroute, replacing `INDEX_NAME` with your index and the sample attributes `"title"` and `"overview"` with attributes present in your dataset:
+
+<CodeSamples id="index_settings_tutorial_api_put_setting_1" />
+
+This time, Meilisearch will not process your request immediately. Instead, you will receive a summarized task object while the search engine works on updating your index setting as soon as it has enough resources:
+
+```json
+{
+  "taskUid": 1,
+  "indexUid": "INDEX_NAME",
+  "status": "enqueued",
+  "type": "settingsUpdate",
+  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
+}
+```
+
+Processing the index setting change might take some time, depending on how many documents you have in your index. Wait a few seconds and use the task object's `taskUid` to monitor the status of your request:
+
+<CodeSamples id="index_settings_tutorial_api_task_1" />
+
+Meilisearch will respond with a task object:
+
+```json
+{
+  "uid":1,
+  "indexUid":"INDEX_NAME",
+  "status":"succeeded",
+  "type":"settingsUpdate",
+  …
+}
+```
+
+If `status` is `enqueued` or `processed`, wait a few more moments and check the task status again. If `status` is `failed`, make sure you have used a valid index and attributes, then try again.
+
+If task `status` is `succeeded`, you successfully updated your index's searchable attributes. Use the subroute to check the new setting's value:
+
+<CodeSamples id="index_settings_tutorial_api_get_setting_1" />
+
+Meilisearch should return an array with the new values:
+
+```json
+[
+  "title",
+  "overview"
+]
+```
+
+## Conclusion
+
+You have used the Meilisearch API to check the value of an index setting. This revealed an opportunity to improve your project's performance, so you updated this index setting to make your application better and more responsive.
+
+This tutorial used the searchable attributes setting, but the procedure is the same no matter which index setting you are editing.
+
+For a comprehensive reference of all index settings, consult the [settings API reference](/reference/api/settings).

reference/api/settings.mdx

@@ -6,9 +6,13 @@ sidebarDepth: 3
 
 # Settings
 
-The `/settings` route allows you to customize search settings for the given index. You can either modify all of an index's settings at once using the [update settings endpoint](#update-settings), or modify each one individually using the child routes.
+Use the `/settings` route to customize search settings for a given index. You can either modify all index settings at once using the [update settings endpoint](#update-settings), or use a child route to configure a single setting.
 
-For a conceptual overview of index settings, refer to our [indexes guide](/learn/core_concepts/indexes#index-settings).
+For a conceptual overview of index settings, refer to the [indexes explanation](/learn/core_concepts/indexes#index-settings). To learn more about the basics of index configuration, refer to the [index configuration tutorial](/learn/configuration/configuring_index_settings_api).
+
+## Settings interface
+
+[Meilisearch Cloud](https://cloud.meilisearch.com/projects/?utm_campaign=oss&utm_source=docs&utm_medium=settings-reference) users can manage index settings through the indexes interface and the `/settings` route. Users hosting their own Meilisearch instance can only manage index settings through the `/settings` route.
 
 ## Settings object