diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index dd0833219b..3cc756e451 100644 --- a/.code-samples.meilisearch.yaml +++ b/.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' diff --git a/assets/images/cloud-tasks-tutorial/01-tasks-menu.png b/assets/images/cloud-tasks-tutorial/01-tasks-menu.png new file mode 100644 index 0000000000..e91dbf37e7 Binary files /dev/null and b/assets/images/cloud-tasks-tutorial/01-tasks-menu.png differ diff --git a/assets/images/cloud-tasks-tutorial/02-tasks-table.png b/assets/images/cloud-tasks-tutorial/02-tasks-table.png new file mode 100644 index 0000000000..52f15a1424 Binary files /dev/null and b/assets/images/cloud-tasks-tutorial/02-tasks-table.png differ diff --git a/config/redirects.json b/config/redirects.json index ecfc331389..08f4dccb81 100644 --- a/config/redirects.json +++ b/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" } ] diff --git a/config/sidebar-learn.json b/config/sidebar-learn.json index 78cbc28fae..52fbbbb7e4 100644 --- a/config/sidebar-learn.json +++ b/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" } ] }, diff --git a/learn/async/filtering_tasks.mdx b/learn/async/filtering_tasks.mdx new file mode 100644 index 0000000000..00380340fa --- /dev/null +++ b/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: + + + +Use a comma to separate multiple values and fetch both `cancelled` and `failed` tasks: + + + +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`: + + + +This code sample returns all tasks in the `movies` index that have the type `documentAdditionOrUpdate` or `documentDeletion` and have the `status` of `processing`. + + +**`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`. + \ No newline at end of file diff --git a/learn/async/managing_tasks.mdx b/learn/async/managing_tasks.mdx deleted file mode 100644 index 4291425539..0000000000 --- a/learn/async/managing_tasks.mdx +++ /dev/null @@ -1,103 +0,0 @@ ---- -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. -sidebarDepth: 3 ---- - -# Managing the task database - -## Filtering tasks - -Querying the [get tasks endpoint](/reference/api/tasks#get-tasks) returns all tasks that have not been deleted. Use query parameters to filter tasks based on `uid`, `status`, `type`, `indexUid`, `canceledBy`, or date. Separate multiple values with a comma (`,`). - -### Filter by `uid` - -The following code sample returns tasks with `uid`s `5`, `10`, and `13`: - - - -### Filter by `status` - -The following code sample returns tasks with the `failed` and `canceled` statuses: - - - -### Filter by `type` - -The following code sample returns `dumpCreation` and `indexSwap` tasks: - - - -### Filter by `indexUid` - -The following command returns all tasks belonging to the index `movies`. Note that the `indexUid` is case-sensitive: - - - -### Filter by `canceledBy` - -Use the `canceledBy` filter to view all tasks canceled by one or more `taskCancelation` tasks: - - - -### Filter by date - -You can filter tasks by their `enqueuedAt`, `startedAt`, and `finishedAt` fields. To do so, prepend either `before` or `after` to each field name: - -- `enqueuedAt` → `beforeEnqueuedAt` or `afterEnqueuedAt` -- `startedAt` → `beforeStartedAt` or `afterStartedAt` -- `finishedAt` →`beforeFinishedAt` or `afterFinishedAt` - -This filter accepts dates formatted according to [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt): - -- `YYYY-MM-DD` -- `YYYY-MM-DDTHH:MM:SSZ` -- `YYYY-MM-DDTHH:MM:SS+01:00` - - - -The above code sample will return all tasks `enqueued` **after** 11:49:53:00 on 11 Oct 2020. - - -Date filters are equivalent to `<` or `>` operations and do not include the specified value. It is not possible to perform `≤` or `≥` operations with a task date filter. - - -### Combine filters - -You can combine task filters. Use the ampersand character (`&`) to combine filters, equivalent to a logical `AND`. - -The following code sample returns all tasks in the `movies` index that have the type `documentAdditionOrUpdate` or `documentDeletion` and have the `status` of `processing`. - - - -**`OR` operations between different filters are not supported.** For example, you cannot view only tasks which have a type of `documentAddition` **or** a status of `failed`. - -## Paginating tasks - -By default, Meilisearch returns a list of 20 tasks for each request. You can adjust the number of tasks returned using the `limit` parameter, and control where the list begins using the `from` parameter. - -For each call to this endpoint, the response will include the `next` field. When you call the endpoint again, pass this value as the `from` parameter to view the next set of results. - -The following command returns two tasks at a time, starting from task `uid` `10`: - - - -**Response:** - -```json -{ - "results": [ - … - ], - "total": 50, - "limit": 2, - "from": 10, - "next": 8 -} -``` - -To view the next set of results, you would repeat the same query, replacing the value of `from` with the value of `next`: - - - -When the returned value of `next` is `null`, you have reached the final set of results. diff --git a/learn/async/paginating_tasks.mdx b/learn/async/paginating_tasks.mdx new file mode 100644 index 0000000000..6806976cf4 --- /dev/null +++ b/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: + + + +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: + + + +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. + + +Use `from` and `limit` together with task filtering parameters to navigate filtered task lists. + diff --git a/learn/async/working_with_tasks.mdx b/learn/async/working_with_tasks.mdx new file mode 100644 index 0000000000..ed9cc7c94e --- /dev/null +++ b/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: + + + +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`. + + +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. + + +## 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: + + + +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. diff --git a/reference/api/tasks.mdx b/reference/api/tasks.mdx index ce02a2dd9a..dc60e8fb62 100644 --- a/reference/api/tasks.mdx +++ b/reference/api/tasks.mdx @@ -213,7 +213,7 @@ List all tasks globally, regardless of index. The `task` objects are contained i Tasks are always returned in descending order of `uid`. This means that by default, **the most recently created `task` objects appear first**. -Task results are [paginated](/learn/async/managing_tasks#paginating-tasks) and can be [filtered](/learn/async/managing_tasks#filtering-tasks). +Task results are [paginated](/learn/async/paginating_tasks) and can be [filtered](/learn/async/filtering_tasks). ### Query parameters @@ -221,17 +221,17 @@ Task results are [paginated](/learn/async/managing_tasks#paginating-tasks) and c | :--------------------- | :----------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`limit`** | `20` | Number of tasks to return | | **`from`** | `uid` of the last created task | `uid` of the first task returned | -| **`uids`** | `*` (all uids) | [Filter tasks](/learn/async/managing_tasks#filtering-tasks) by their `uid`. Separate multiple task `uids` with a comma (`,`) | -| **`statuses`** | `*` (all statuses) | [Filter tasks](/learn/async/managing_tasks#filtering-tasks) by their `status`. Separate multiple task `statuses` with a comma (`,`) | -| **`types`** | `*` (all types) | [Filter tasks](/learn/async/managing_tasks#filtering-tasks) by their `type`. Separate multiple task `types` with a comma (`,`) | -| **`indexUids`** | `*` (all indexes) | [Filter tasks](/learn/async/managing_tasks#filtering-tasks) by their `indexUid`. Separate multiple task `indexUids` with a comma (`,`). Case-sensitive | -| **`canceledBy`** | N/A | [Filter tasks](/learn/async/managing_tasks#filter-by-canceledby) by their `canceledBy` field. Separate multiple task `uids` with a comma (`,`) | -| **`beforeEnqueuedAt`** | `*` (all tasks) | [Filter tasks](/learn/async/managing_tasks#filter-by-date) by their `enqueuedAt` field | -| **`beforeStartedAt`** | `*` (all tasks) | [Filter tasks](/learn/async/managing_tasks#filter-by-date) by their `startedAt` field | -| **`beforeFinishedAt`** | `*` (all tasks) | [Filter tasks](/learn/async/managing_tasks#filter-by-date) by their `finishedAt` field | -| **`afterEnqueuedAt`** | `*` (all tasks) | [Filter tasks](/learn/async/managing_tasks#filter-by-date) by their `enqueuedAt` field | -| **`afterStartedAt`** | `*` (all tasks) | [Filter tasks](/learn/async/managing_tasks#filter-by-date) by their `startedAt` field | -| **`afterFinishedAt`** | `*` (all tasks) | [Filter tasks](/learn/async/managing_tasks#filter-by-date) by their `finishedAt` field | +| **`uids`** | `*` (all uids) | [Filter tasks](/learn/async/filtering_tasks) by their `uid`. Separate multiple task `uids` with a comma (`,`) | +| **`statuses`** | `*` (all statuses) | [Filter tasks](/learn/async/filtering_tasks) by their `status`. Separate multiple task `statuses` with a comma (`,`) | +| **`types`** | `*` (all types) | [Filter tasks](/learn/async/filtering_tasks) by their `type`. Separate multiple task `types` with a comma (`,`) | +| **`indexUids`** | `*` (all indexes) | [Filter tasks](/learn/async/filtering_tasks) by their `indexUid`. Separate multiple task `indexUids` with a comma (`,`). Case-sensitive | +| **`canceledBy`** | N/A | [Filter tasks](/learn/async/filtering_tasks) by their `canceledBy` field. Separate multiple task `uids` with a comma (`,`) | +| **`beforeEnqueuedAt`** | `*` (all tasks) | [Filter tasks](/learn/async/filtering_tasks) by their `enqueuedAt` field | +| **`beforeStartedAt`** | `*` (all tasks) | [Filter tasks](/learn/async/filtering_tasks) by their `startedAt` field | +| **`beforeFinishedAt`** | `*` (all tasks) | [Filter tasks](/learn/async/filtering_tasks) by their `finishedAt` field | +| **`afterEnqueuedAt`** | `*` (all tasks) | [Filter tasks](/learn/async/filtering_tasks) by their `enqueuedAt` field | +| **`afterStartedAt`** | `*` (all tasks) | [Filter tasks](/learn/async/filtering_tasks) by their `startedAt` field | +| **`afterFinishedAt`** | `*` (all tasks) | [Filter tasks](/learn/async/filtering_tasks) by their `finishedAt` field | ### Response @@ -374,7 +374,7 @@ A valid `uids`, `statuses`, `types`, `indexUids`, or date(`beforeXAt` or `afterX Date filters are equivalent to `<` or `>` operations. At this time, there is no way to perform a `≤` or `≥` operations with a date filter. -[To learn more about filtering tasks, refer to our dedicated guide.](/learn/async/managing_tasks#filtering-tasks) +[To learn more about filtering tasks, refer to our dedicated guide.](/learn/async/filtering_tasks) ### Example @@ -438,7 +438,7 @@ A valid `uids`, `statuses`, `types`, `indexUids`, `canceledBy`, or date(`beforeX Date filters are equivalent to `<` or `>` operations. At this time, there is no way to perform a `≤` or `≥` operations with a date filter. -[To learn more about filtering tasks, refer to our dedicated guide.](/learn/async/managing_tasks#filtering-tasks) +[To learn more about filtering tasks, refer to our dedicated guide.](/learn/async/filtering_tasks) ### Example