Merge branch 'v0.28' into v0.28-faceting-settings

Author: maryamsulemani97

.code-samples.meilisearch.yaml

@@ -16,10 +16,12 @@ delete_all_documents_1: |-
 delete_one_document_1: |-
 delete_documents_1: |-
 search_post_1: |-
-get_task_by_index_1: |-
 get_all_tasks_1: |-
 get_task_1: |-
-get_all_tasks_by_index_1: |-
+get_all_tasks_filtering_1: |-
+get_all_tasks_filtering_2: |-
+get_all_tasks_paginating_1: |-
+get_all_tasks_paginating_2: |-
 get_one_key_1: |-
 get_all_keys_1: |-
 create_a_key_1: |-
@@ -65,7 +67,7 @@ search_parameter_guide_limit_1: |-
 search_parameter_guide_retrieve_1: |-
 search_parameter_guide_crop_1: |-
 search_parameter_guide_highlight_1: |-
-search_parameter_guide_matches_1: |-
+search_parameter_guide_show_matches_position_1: |-
 settings_guide_synonyms_1: |-
 settings_guide_stop_words_1: |-
 settings_guide_ranking_rules_1: |-
@@ -90,11 +92,10 @@ getting_started_sorting: |-
 getting_started_filtering: |-
 faceted_search_update_settings_1: |-
 faceted_search_filter_1: |-
-faceted_search_facets_distribution_1: |-
+faceted_search_facets_1: |-
 faceted_search_walkthrough_filter_1: |-
 add_movies_json_1: |-
 post_dump_1: |-
-get_dump_status_1: |-
 phrase_search_1: |-
 sorting_guide_update_sortable_attributes_1: |-
 sorting_guide_update_ranking_rules_1: |-
@@ -140,7 +141,6 @@ updating_guide_get_displayed_attributes_old: |-
 updating_guide_reset_displayed_attributes_old: |-
 updating_guide_reset_displayed_attributes_new: |-
 updating_guide_create_dump: |-
-updating_guide_get_dump_status: |-
 updating_guide_get_settings_old: |-
 updating_guide_retrieve_documents_old: |-
 updating_guide_update_settings_old: |-

.vuepress/public/postman/meilisearch-collection.json

@@ -10,32 +10,29 @@ For example, updating the `filterableAttributes` index setting will require as m
 
 Currently, these are Meilisearch's asynchronous operations:
 
-- Updating index settings
-- Adding documents to an index
-- Updating documents in an index
 - Creating an index
 - Updating an index
 - Deleting an index
 - Updating index settings
 - Adding documents to an index
 - Updating documents in an index
 - Deleting documents from an index
-- [Creating a dump](#dumps)
+- Creating a dump
 
 ## Understanding tasks
 
-Most of Meilisearch's asynchronous operations belong to a category called "tasks". After you have requested an asynchronous operation, you can use the [task API](/reference/api/tasks.md) to find the detailed status of your request. To do so, you will need your task's `uid`.
+All of Meilisearch's asynchronous operations belong to a category called "tasks". After you have requested an asynchronous operation, you can use the [task API](/reference/api/tasks.md) to find the detailed status of your request. To do so, you will need the task's unique identifier.
 
-### Response
+### Task API response
 
 The response from the [task API](/reference/api/tasks.md) will always include the following fields in the stated order:
 
 | Field        | Type    | Description                                                                                                      |
 |--------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------|
 | `uid`        | integer | The unique sequential identifier of the task                                                                     |
-| `indexUid`   | string  | The unique index identifier                                                                                      |
+| `indexUid`   | string  | The unique index identifier (always `null` for dumps)                                                                                      |
 | `status`     | string  | The status of the task. Possible values are `enqueued`, `processing`, `succeeded`, `failed`                                                                                                                                    |
-| `type`       | string  | The type of task. Possible values are `indexCreation`, `indexUpdate`, `indexDeletion`, `documentAddition`, `documentPartial`, `documentDeletion`, `settingsUpdate`, `clearAll`                                                                       |
+| `type`       | string  | The type of task. Possible values are `indexCreation`, `indexUpdate`, `indexDeletion`, `documentAdditionOrUpdate`, `documentPartial`, `documentDeletion`, `settingsUpdate`, `clearAll`, `dumpCreation`                                                                       |
 | `details`    | object  | Detailed information on the task payload                                                               |
 | `error`      | object  | Error details and context. Only present when a task has the `failed` status                                                |
 | `duration`   | string  | The total elapsed time the task spent in the `processing` state, in ISO 8601 format     |
@@ -47,17 +44,17 @@ If a task fails due to an error, all error fields will be appended to the task r
 
 ### Summarized task objects
 
-All asynchronous operations return a summarized version of the [`task` object](#response). It contains the following fields in the stated order:
+All asynchronous operations return a summarized version of [the full `task` object](#task-api-response). It contains the following fields in the stated order:
 
 | Field      | Type    | Description                              |
 |------------|---------|---------------------------------         |
 | `uid`        | integer | Unique sequential identifier             |
-| `indexUid`   | string  | Unique index identifier                  |
+| `indexUid`   | string  | Unique index identifier (always `null` for dumps)                  |
 | `status`     | string  | Status of the task. Value is `enqueued`  |
 | `type`       | string  | Type of task                             |
 | `enqueuedAt` | string  | Represents the date and time in the RFC 3339 format when the task has been `enqueued`                                                        |
 
-You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task).
+You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task).
 
 ### Task `status`
 
@@ -70,16 +67,16 @@ Task responses always contain a field indicating the request's current `status`.
 
 ### Examples
 
-Suppose you add a new document to your instance using the [add documents endpoint](/reference/api/documents.md#add-or-replace-documents) and receive a `uid` in response.
+Suppose you add a new document to your instance using the [add documents endpoint](/reference/api/documents.md#add-or-replace-documents) and receive a `taskUid` in response.
 
-When you query the task endpoint using this `uid`, you see that it has been enqueued:
+When you query the [get task endpoint](/reference/api/tasks.md#get-one-task) using this value, you see that it has been enqueued:
 
 ```json
 {
     "uid": 1,
     "indexUid": "movies",
     "status": "enqueued",
-    "type": "documentAddition",
+    "type": "documentAdditionOrUpdate",
     "details": { 
         "receivedDocuments": 67493,
         "indexedDocuments": null
@@ -98,7 +95,7 @@ Later, you check the request's status one more time. It was successfully process
     "uid": 1,
     "indexUid": "movies",
     "status": "succeeded",
-    "type": "documentAddition",
+    "type": "documentAdditionOrUpdate",
     "details": { 
             "receivedDocuments": 67493,
             "indexedDocuments": 67493
@@ -117,7 +114,7 @@ Had the task failed, the response would have included an `error` object:
     "uid": 1,
     "indexUid": "movies",
     "status": "failed",
-    "type": "documentAddition",
+    "type": "documentAdditionOrUpdate",
     "details": { 
             "receivedDocuments": 67493,
             "indexedDocuments": 0
@@ -137,16 +134,12 @@ Had the task failed, the response would have included an `error` object:
 
 ## Task workflow
 
-1. When you make a task request, Meilisearch puts it in the task queue, sets the task's `status` to `enqueued` and returns a [`task` object](/learn/advanced/asynchronous_operations.md#response)
+1. When you make an [asynchronous request](#which-operations-are-async), Meilisearch puts it in the task queue, sets the task's `status` to `enqueued` and returns a [summarized `task` object](/learn/advanced/asynchronous_operations.md#summarized-task-objects)
 2. When your task reaches the front of the queue, Meilisearch begins working on it and changes the request `status` to `processing`
 3. Once the task has completed processing, Meilisearch marks it as `succeeded`, if it was successful, or `failed`, if there was an error.
-4. Tasks marked as `succeeded` or `failed` are not deleted and will remain visible in [the task list](/reference/api/tasks.md#get-all-tasks)
-
-### Dumps
-
-While dumps and tasks are both asynchronous operations, they use separate queues and behave differently. For instance, creating a new dump will freeze the task queue until the dump has been generated.
+4. Tasks marked as `succeeded` or `failed` are not deleted and will remain visible in [the task list](/reference/api/tasks.md#get-tasks)
 
-[You can read more about dumps in our dedicated guide.](/learn/advanced/dumps.md)
+Tasks are processed in the order they were enqueued, with one exception: `dumpCreation`. Dumps are prioritized over all other tasks in the queue. Their task `uid` still reflects when they were enqueued relative to other tasks.
 
 ## Terminate Meilisearch while a task is being processed
 
@@ -156,8 +149,8 @@ Meilisearch's asynchronous tasks are atomic. This means that all operations conc
 
 What happens to an asynchronous operation when Meilisearch is terminated changes depending on the request's `status`:
 
-- `enqueued`: the task will remain enqueued and will be processed as usual once is restarted
-- `processing`: there will be no consequences, since no part of the task has been committed to the database. After restarting, will treat the task as `enqueued`
+- `enqueued`: the task will remain enqueued and will be processed as usual once Meilisearch has been restarted
+- `processing`: there will be no consequences, since no part of the task has been committed to the database. After restarting, the task will be treated as `enqueued`
 - `succeeded`: there will be no data loss since the request was successfully completed
 - `failed`: the task failed and nothing has been altered in the database
 

.vuepress/public/sample-template.yaml

@@ -1,64 +1,61 @@
 # Dumps
 
-A dump is a compressed file containing an export of your Meilisearch instance. It contains all your indexes, documents, and settings, but in a raw unprocessed form. A dump isn't an exact copy of your database—it is closer to a blueprint that allows you to create an identical dataset. A dump can be imported when launching Meilisearch, but be advised that it may take some time to index all the documents within.
+A dump is a compressed file containing an export of your Meilisearch instance. It contains all your indexes, documents, and settings, but in a raw unprocessed form. A dump isn't an exact copy of your database—it is closer to a blueprint that allows you to create an identical dataset.
+
+A dump can be imported when launching Meilisearch, but be advised that it may take some time to index.
 
 ## Creating a dump
 
 To create a dump of your dataset, you need to use the appropriate HTTP route: [`POST /dumps`](/reference/api/dump.md#create-a-dump). The dump creation process is an asynchronous task that takes time proportional to the size of your dataset.
 
 <CodeSamples id="post_dump_1" />
 
-The above code triggers a dump creation process. It also returns an object containing information about the dump:
+The above code triggers a dump creation process. It also returns a [summarized task object](/learn/advanced/asynchronous_operations.md#summarized-task-objects) that you can use to check the status of your dump.
 
-```
+```json
 {
-  "uid": "20200929-114144097",
-  "status": "in_progress",
-  "startedAt": "2020-09-29T11:41:44.392327Z"
+  "taskUid": 1,
+  "indexUid": null,
+  "status": "enqueued",
+  "type": "dumpCreation",
+  "enqueuedAt": "2022-06-21T16:10:29.217688Z"
 }
 ```
 
-You can use the returned `uid` (unique identifier indicating when the dump was triggered) to track its progress with the [get dump status route](/reference/api/dump.md#get-dump-status). The returned status could be:
-
-- `in_progress`: Dump creation is in progress
-- `failed`: An error occurred during dump process, and the task was aborted
-- `done`: Dump creation is finished and was successful
+In the below command, replace `1` with the `taskUid` returned by the previous command.
 
-<CodeSamples id="get_dump_status_1" />
+<CodeSamples id="get_task_1" />
 
-The above code sample returns an object with the following details about the dump:
+This command should return an object with detailed information about the dump operation:
 
-```
+```json
 {
-  "uid": "20200929-114144097",
-  "status": "done",
-  "startedAt": "2020-09-29T11:41:44.392327Z",
-  "finishedAt": "2020-09-29T11:41:50.792147Z"
+  "uid": 1,
+  "indexUid": null,
+  "status": "succeeded",
+  "type": "dumpCreation",
+  "details": {
+    "dumpUid": "20220621-161029217"
+  },
+  "duration": "PT0.025872S",
+  "enqueuedAt": "2022-06-21T16:10:29.217688Z",
+  "startedAt": "2022-06-21T16:10:29.218297Z",
+  "finishedAt": "2022-06-21T16:10:29.244169Z"
 }
 ```
 
-After dump creation is finished, the dump file is added to the dump directory. By default, this folder is named `dumps` and can be found in the same directory as your Meilisearch binary. You can customize [this using the `--dumps-dir` configuration option](/learn/configuration/instance_options.md#dumps-destination). **If the dump directory does not already exist when the dump creation process is called, Meilisearch will create it.**
+After dump creation is finished—when `status` is `succeeded`—the dump file is added to the dump directory. By default, this folder is named `dumps` and can be found in the same directory as your Meilisearch binary. You can customize [this using the `--dumps-dir` configuration option](/learn/configuration/instance_options.md#dumps-destination). **If the dump directory does not already exist when the dump creation process is called, Meilisearch will create it.**
 
 If a dump file is visible in the file system, the dump process was successfully completed. **Meilisearch will never create a partial dump file**, even if you interrupt an instance while it is generating a dump.
 
-::: note
-Unlike [tasks](/learn/advanced/asynchronous_operations.md), dumps have no queue. **Meilisearch only processes one dump at a time.** If you attempt to create a dump while another dump is still processing, Meilisearch will throw an [error](/reference/api/error_codes.md#dump-already-processing).
-
-Meilisearch does not process tasks during dump creation, but you can still add new requests to the task queue. This is also true for [snapshots](/learn/advanced/snapshots.md#snapshots).
-:::
-
-::: warning
-If you restart Meilisearch after creating a dump, you will not be able to use the dumps endpoint to find out that dump's `status`. This has no effect on the dump file itself.
-:::
-
 ## Importing a dump
 
 When a dump is being imported, the API is not available to the task queue. As a result, no read or write operations can be performed until the importing process is complete.
 
-Dumps in v0.20.0 and below are no longer compatible with the new versions. Before you start importing, check your [Meilisearch version](/reference/api/version.md#example) and proceed accordingly.
+Dumps from v0.20.0 and below are no longer compatible with the new versions. Before you start importing, check your [Meilisearch version](/reference/api/version.md#example) and proceed accordingly.
 
 ::: note
-We do not recommend using dumps from a new Meilisearch version to import an older version.
+We do not recommend using dumps to migrate from a new Meilisearch version to an older one.
 
 For example, you can import a dump from Meilisearch v0.21 into v0.22 without any problems. Importing a dump generated in v0.22 into a v0.21 instance, however, can lead to unexpected behavior.
 :::
@@ -79,4 +76,4 @@ If you are using Meilisearch v0.20 or below, migration should be done in two ste
 
 ## Use cases
 
-Dumps are used to restore your database after [updating Meilisearch](/learn/advanced/updating.md) or to copy your database to other Meilisearch instances without having to worry about their respective versions.
+Dumps are used to restore your database after [updating Meilisearch](/learn/advanced/updating.md) or to copy your database to other Meilisearch instances without having to worry about their respective versions. For more on this subject, see a [comparison of snapshots and dumps](/learn/advanced/snapshots_vs_dumps.md).