Managing tasks tutorial

.code-samples.meilisearch.yaml

@@ -958,27 +958,15 @@ date_guide_sort_1: |-
       "q": "",
       "sort": ["release_timestamp:desc"]
     }'
-async_guide_filter_by_date_1: |-
-  curl \
-    -X GET 'http://localhost:7700/tasks?afterEnqueuedAt=2020-10-11T11:49:53.000Z'
-async_guide_multiple_filters_1: |-
-  curl \
-    -X GET 'http://localhost:7700/tasks?indexUids=movies&types=documentAdditionOrUpdate,documentDeletion&statuses=processing'
-async_guide_filter_by_ids_1: |-
-  curl \
-    -X GET 'http://localhost:7700/tasks?uids=5,10,13'
 async_guide_filter_by_statuses_1: |-
   curl \
-    -X GET 'http://localhost:7700/tasks?statuses=failed,canceled'
-async_guide_filter_by_types_1: |-
-  curl \
-    -X GET 'http://localhost:7700/tasks?types=dumpCreation,indexSwap'
-async_guide_filter_by_index_uids_1: |-
+    -X GET 'http://localhost:7700/tasks?statuses=failed'
+async_guide_filter_by_statuses_2: |-
   curl \
-    -X GET 'http://localhost:7700/tasks?indexUids=movies'
-async_guide_canceled_by_1: |-
+    -X GET 'http://localhost:7700/tasks?statuses=failed,canceled'
+async_guide_multiple_filters_1: |-
   curl \
-    -X GET 'http://localhost:7700/tasks?canceledBy=9,15'
+    -X GET 'http://localhost:7700/tasks?indexUids=movies&types=documentAdditionOrUpdate,documentDeletion&statuses=processing'
 delete_tasks_1: |-
   curl \
     -X DELETE 'http://localhost:7700/tasks?uids=1,2'

config/redirects.json

@@ -149,5 +149,9 @@
   {
     "source": "/docs/learn/experimental/ranking_rule_score_details",
     "destination": "/docs/reference/api/search#ranking_score_details"
+  },
+  {
+    "source": "/docs/learn/async/managing_tasks",
+    "destination": "/docs/learn/async/working_with_tasks"
   }
 ]

config/sidebar-learn.json

@@ -104,23 +104,33 @@
     ]
   },
   {
-    "title": "Tasks and asynchronous workflow",
+    "title": "Tasks and asynchronous operations",
     "slug": "async",
     "routes": [
       {
-        "source": "learn/async/asynchronous_operations.mdx",
-        "label": "Tasks and asynchronous operations",
-        "slug": "asynchronous_operations"
+        "source": "learn/async/working_with_tasks.mdx",
+        "label": "Working with tasks",
+        "slug": "working_with_tasks"
+      },
+      {
+        "source": "learn/async/filtering_tasks.mdx",
+        "label": "Filtering tasks",
+        "slug": "filtering_tasks"
       },
       {
-        "source": "learn/async/managing_tasks.mdx",
-        "label": "Managing the task database",
-        "slug": "managing_tasks"
+        "source": "learn/async/paginating_tasks.mdx",
+        "label": "Paginating tasks",
+        "slug": "paginating_tasks"
       },
       {
         "source": "learn/async/task_webhook.mdx",
         "label": "Using task webhooks",
         "slug": "task_webhook"
+      },
+      {
+        "source": "learn/async/asynchronous_operations.mdx",
+        "label": "Tasks and asynchronous operations",
+        "slug": "asynchronous_operations"
       }
     ]
   },

learn/async/filtering_tasks.mdx

@@ -0,0 +1,39 @@
+---
+title: Filtering tasks — Meilisearch documentation
+description: This guide shows you how to use query parameters to filter tasks and obtain a more readable list of asynchronous operations.
+---
+
+# Filtering tasks
+
+Querying the [get tasks endpoint](/reference/api/tasks#get-tasks) returns all tasks that have not been deleted. This unfiltered list may be difficult to parse in large projects.
+
+This guide shows you how to use query parameters to filter tasks and obtain a more readable list of asynchronous operations.
+
+## Requirements
+
+- a command-line terminal
+- a running Meilisearch project
+
+## Filtering tasks with a single parameter
+
+Use the get tasks endpoint to fetch all `cancelled` tasks:
+
+<CodeSamples id="async_guide_filter_by_statuses_1" />
+
+Use a comma to separate multiple values and fetch both `cancelled` and `failed` tasks:
+
+<CodeSamples id="async_guide_filter_by_statuses_2" />
+
+You may filter tasks based on `uid`, `status`, `type`, `indexUid`, `canceledBy`, or date. Consult the API reference for a full list of task filtering parameters.
+
+## Combining filters
+
+Use the ampersand character (`&`) to combine filters, equivalent to a logical `AND`:
+
+<CodeSamples id="async_guide_multiple_filters_1" />
+
+This code sample returns all tasks in the `movies` index that have the type `documentAdditionOrUpdate` or `documentDeletion` and have the `status` of `processing`.
+
+<Capsule intent="warning">
+**`OR` operations between different filters are not supported.** For example, you cannot view tasks which have a type of `documentAddition` **or** a status of `failed`.
+</Capsule>

learn/async/paginating_tasks.mdx

@@ -0,0 +1,56 @@
+---
+title: Managing the task database — Meilisearch documentation
+description: Meilisearch uses a task queue to handle asynchronous operations. This document describes how to navigate long task queues with filters and pagination.
+---
+
+# Paginating tasks
+
+By default, Meilisearch returns a list of 20 tasks for each request when you query the [get tasks endpoint](/reference/api/tasks#get-tasks). This guide shows you how to navigate the task list using query parameters.
+
+## Configuring the number of returned tasks
+
+Use the `limit` parameter to change the number of returned tasks:
+
+<CodeSamples id="get_all_tasks_paginating_1" />
+
+Meilisearch will return a batch of tasks. Each batch of returned tasks is often called a "page" of tasks, and the size of that page is determined by `limit`:  
+
+```json
+{
+  "results": [
+    …
+  ],
+  "total": 50,
+  "limit": 2,
+  "from": 10,
+  "next": 8
+}
+```
+
+It is possible none of the returned tasks are the ones you are looking for. In that case, you will need to use the [get all tasks request response](/reference/api/tasks#response) to navigate the results.
+
+## Navigating the task list with `from` and `next`
+
+Use the `next` value included in the response to your previous query together with `from` to fetch the next set of results:
+
+<CodeSamples id="get_all_tasks_paginating_2" />
+
+This will return a new batch of tasks:
+
+```json
+{
+  "results": [
+    …
+  ],
+  "total": 50,
+  "limit": 2,
+  "from": 8,
+  "next": 6
+}
+```
+
+When the value of `next` is `null`, you have reached the final set of results.
+
+<Capsule intent="tip">
+Use `from` and `limit` together with task filtering parameters to navigate filtered task lists.
+</Capsule>

learn/async/working_with_tasks.mdx

@@ -0,0 +1,95 @@
+---
+title: Working with tasks — Meilisearch documentation
+description: In this tutorial, you'll use the Meilisearch API to add documents to an index, and then monitor its status.
+---
+
+# Working with tasks
+
+[Many Meilisearch operations are processed asynchronously](/learn/async/asynchronous_operations) in a task. Asynchronous tasks allow you to make resource-intensive changes to your Meilisearch project without any downtime for users.
+
+In this tutorial, you'll use the Meilisearch API to add documents to an index, and then monitor its status.
+
+## Requirements
+
+- a running Meilisearch project
+- a command-line console
+
+## Adding a task to the task queue
+
+Operations that require indexing, such as adding and updating documents or changing an index's settings, will always generate a task.
+
+Start by creating an index, then add a large number of documents to this index:
+
+<CodeSamples id="add_movies_json_1" />
+
+Instead of processing your request immediately, Meilisearch will add it to a queue and return a summarized task object:
+
+```json
+{
+  "taskUid": 0,
+  "indexUid": "movies",
+  "status": "enqueued",
+  "type": "documentAdditionOrUpdate",
+  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
+}
+```
+
+The summarized task object is confirmation your request has been accepted. It also gives you information you can use to monitor the status of your request, such as the `taskUid`.
+
+<Capsule intent="note">
+You can add documents to a new Meilisearch Cloud index using the Cloud interface. To get the `taskUid` of this task, visit the "Task" overview and look for a "Document addition or update" task associated with your newly created index.
+</Capsule>
+
+## Monitoring task status
+
+Meilisearch processes tasks in the order they were added to the queue. You can check the status of a task using the Meilisearch Cloud interface or the Meilisearch API.
+
+### Monitoring task status in the Meilisearch Cloud interface
+
+Log into your [Meilisearch Cloud](https://meilisearch.com/cloud?utm_campaign=oss&utm_source=docs&utm_medium=tasks-tutorial) account and navigate to your project. Click the "Tasks" link in the project menu:
+
+![](https://raw.githubusercontent.com/meilisearch/documentation/main/assets/images/cloud-tasks-tutorial/01-tasks-menu.png)
+
+This will lead you to the task overview. Look for your request's `taskUid` in the "Uid" column:
+
+![](https://raw.githubusercontent.com/meilisearch/documentation/main/assets/images/cloud-tasks-tutorial/01-tasks-table.png)
+
+When the task `status` changes to `succeeded`, Meilisearch has finished processing your request.
+
+If the task `status` changes to `failed`, Meilisearch was not able to fulfill your request. Check the task object's `error` field for more information.
+
+### Monitoring task status with the Meilisearch API
+
+Use the `taskUid` from your request's response to check the status of a task:
+
+<CodeSamples id="get_task_1" />
+
+This will return the full task object:
+
+```json
+{
+  "uid": 4,
+  "indexUid" :"movie",
+  "status": "succeeded",
+  "type": "documentAdditionOrUpdate",
+  "canceledBy": null,
+  "details": {
+    …
+  },
+  "error": null,
+  "duration": "PT0.001192S",
+  "enqueuedAt": "2022-08-04T12:28:15.159167Z",
+  "startedAt": "2022-08-04T12:28:15.161996Z",
+  "finishedAt": "2022-08-04T12:28:15.163188Z"
+}
+```
+
+If the task is still `enqueued` or `processing`, wait a few moments and query the database once again. If you are working with a self-hosted Meilisearch instance, you may also [set up a webhook listener](/learn/async/task_webhook).
+
+When `status` changes to `succeeded`, Meilisearch has finished processing your request.
+
+If the task `status` changes to `failed`, Meilisearch was not able to fulfill your request. Check the task object's `error` field for more information.
+
+## Conclusion
+
+You have seen what happens when an API request adds a task to the task queue, and how to check the status of a that task. Consult the [task API reference](/reference/api/tasks) and the [asynchronous operations explanation](/learn/async/asynchronous_operations) for more information on how tasks work.