From a37c3a36d1fffbd48cb09a06a8c8010c46c81d50 Mon Sep 17 00:00:00 2001 From: alallema Date: Tue, 25 Oct 2022 18:17:24 +0200 Subject: [PATCH 01/76] Add cancel to task spec --- text/0060-tasks-api.md | 373 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 337 insertions(+), 36 deletions(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 1ac6b069..642622cd 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -4,11 +4,11 @@ ### I. Summary -This specification describes the API endpoints for viewing asynchronous tasks. +This specification describes the API endpoints for handling asynchronous tasks. ### II. Motivation -As writing is asynchronous for most of Meilisearch's operations, this API makes it possible to track the progress of asynchronous tasks, to know and understand why a task failed and also serves as consulting the history of operations that happened. +As writing is asynchronous for most of Meilisearch's operations, this API allows you to track the progress of asynchronous tasks, know and understand why a task has failed, and cancel specific tasks in progress by consulting the history of operations that happened. ### III. Explanation @@ -22,8 +22,8 @@ As writing is asynchronous for most of Meilisearch's operations, this API makes |------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | uid | integer | Unique sequential identifier | | indexUid | string | Unique index identifier. This field is `null` when the task type is `dumpCreation`. | -| status | string | Status of the task. Possible values are `enqueued`, `processing`, `succeeded`, `failed` | -| type | string | Type of the task. Possible values are `indexCreation`, `indexUpdate`, `indexDeletion`, `documentAdditionOrUpdate`, `documentDeletion`, `settingsUpdate`, `dumpCreation` | +| status | string | Status of the task. Possible values are `enqueued`, `processing`, `succeeded`, `failed`, `canceled` | +| type | string | Type of the task. Possible values are `indexCreation`, `indexUpdate`, `indexDeletion`, `documentAdditionOrUpdate`, `documentDeletion`, `settingsUpdate`, `dumpCreation`, `taskCancelation` | | details | object | Details information for a task payload. See Task Details part. | | error | object | Error object containing error details and context when a task has a `failed` status. See [0061-error-format-and-definitions.md](0061-error-format-and-definitions.md) | | duration | string | Total elapsed time the engine was in processing state expressed as an `ISO-8601` duration format. Times below the second can be expressed with the `.` notation, e.g., `PT0.5S` to express `500ms`. Default is set to `null`. | @@ -56,6 +56,7 @@ As writing is asynchronous for most of Meilisearch's operations, this API makes | processing | | succeeded | | failed | +| canceled | #### 3. `type` field enum @@ -68,6 +69,7 @@ As writing is asynchronous for most of Meilisearch's operations, this API makes | documentDeletion | | settingsUpdate | | dumpCreation | +| taskCancelation | > 👍 Type values follow a `camelCase` naming convention. @@ -132,6 +134,14 @@ Since the creation of a dump is not a task associated with a particular index, i Fully qualified and summarized task objects related to a dump creation display a `null` `indexUid` field. +##### taskCancelation + +| Name | Description | +| --- | --- | +| matchedTasks | The number of tasks that can be canceled based on the request. If the API key doesn’t have access to any of the indexes specified in the request, those tasks will not be included in matchedTasks. | +| canceledTasks | The number of tasks successfully canceled. If the task fails, this will be 0. | +| originalQuery | The filter used in the /tasks/cancel request. | + #### 5. Examples e.g. A fully qualified `task` object in an `enqueued` state. @@ -241,6 +251,31 @@ e.g. A fully qualified `task` object in a `failed` state. } ``` +e.g. A fully qualified `task` object in a `canceled` state. + +```json +{ + "uid": 0, + "indexUid": "movies", + "status": "canceled", + "type": "settingsUpdate", + "details": { + "rankingRules": [ + "typo", + "ranking:desc", + "words", + "proximity", + "attribute", + "exactness" + ] + }, + "canceledBy": 1, + "enqueuedAt": "2021-08-10T14:29:17.000000Z", + "startedAt": "2021-08-10T14:29:18.000000Z", + "finishedAt": "2021-08-10T14:29:19.000000Z" +} +``` + e.g. A summarized `task` object in a `202 Accepted` HTTP response returned at index creation. ```json @@ -257,9 +292,9 @@ e.g. A summarized `task` object in a `202 Accepted` HTTP response returned at in #### 6. APIs endpoints -**Get all tasks** | `GET` - `/tasks` +##### 6.1. Get all tasks | `GET` - `/tasks` -##### Goals +##### 6.1.1. Goals Allows users to list tasks globally regardless of the indexes involved. Particularly useful to visualize all the tasks. @@ -296,7 +331,7 @@ Allows users to list tasks globally regardless of the indexes involved. Particul } ``` -##### Requirements +##### 6.1.2. Requirements > 💡 `task` objects are contained in a `results` array. > @@ -306,7 +341,7 @@ Allows users to list tasks globally regardless of the indexes involved. Particul > > 💡 When an index is deleted, its tasks remain accessible on the global `/tasks` endpoint. -##### Errors +##### 6.1.3. Errors The auth layer can return the following errors if Meilisearch is secured (a master-key is defined). @@ -315,9 +350,9 @@ The auth layer can return the following errors if Meilisearch is secured (a mast --- -**Get a task by uid** | `GET` - `/tasks/{uid}` +##### 6.2. Get a task by uid | `GET` - `/tasks/{uid}` -##### Goals +##### 6.2.1. Goals Allows users to get a detailed `task` object retrieved by the `uid` field regardless of the index involved. @@ -336,7 +371,7 @@ Allows users to get a detailed `task` object retrieved by the `uid` field regard } ``` -##### Errors +##### 6.2.2. Errors - 🔴 If the task does not exist, the API returns a `404 Not Found` - `task_not_found` error. @@ -347,7 +382,56 @@ The auth layer can return the following errors if Meilisearch is secured (a mast --- -#### 6. `task_not_found` error +##### 6.3. Cancel tasks | `POST` - `/tasks` + +##### 6.3.1. Goals + +Allows users to cancel an `enqueued` or `processing` task. Particularly useful if a long or heavy task blocks the queue. + +`202` - Response body - `/tasks/cancels` + +```json +{ + "taskUid": 0, + "indexUid": "movies", + "status": "enqueued", + "type": "taskCancelation", + "enqueuedAt": "2021-08-12T10:00:00.000000Z" +} +``` + +##### 6.3.2. Response Definition + +When the request is successful, Meilisearch returns the HTTP code 202 Accepted. The response's content is the summarized representation of the received asynchronous task. + +##### 6.3.3. Errors + +If a user tries canceling a `succeeded`, `failed`, or `canceled` task, it won’t throw an error. Task cancelation is an atomic transaction; all tasks are successfully canceled, or none aren't. + +- 🔴 Sending a task cancelation without filtering query parameters returns a `missing_filters` error. + + ```json + { + "message": "Query parameters to filter the tasks to cancel are missing. Available query parameters are: `uid`, `indexUid`, `status`, `type`, `beforeEnqueuedAt`, `afterEnqueudAt`, `beforeStartedAt`, afterStartedAt`", + "code": "missing_filters", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#missing_filters" + } + ``` + +- 🔴 If the `type` parameter value is not consistent with one of the task types, an `[invalid_task_type](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalidtasktype)` error is returned. +- 🔴 If the `status` parameter value is not consistent with one of the task statuses, an `[invalid_task_status](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalidtaskstatus)` error is returned. +- ? (value type format error for every query parameters) +- ? (sending a query parameter that does not exists error) + +The auth layer can return the following errors if Meilisearch is secured (a master-key is defined). + +- 🔴 Accessing this route without the `Authorization` header returns a [missing_authorization_header](0061-error-format-and-definitions.md#missing_authorization_header) error. +- 🔴 Accessing this route with a key that does not have the required permissions (i.e. other than the master-key) returns an [invalid_api_key](0061-error-format-and-definitions.md#invalid_api_key) error. + +--- + +#### 7. `task_not_found` error ##### Context @@ -368,23 +452,23 @@ HTTP Code: `404 Not Found` - The `:taskUid` is inferred when the message is generated. -#### 7. `MEILI_MAX_TASK_DB_SIZE` env var and `--max-task-db-size` CLI option +#### 8. `MEILI_MAX_TASK_DB_SIZE` env var and `--max-task-db-size` CLI option See [0119-instance-options](0119-instance-options.md##3312-max-taskdb-size) -#### 8. Asynchronous Write Operations on Index resource +#### 9. Asynchronous Write Operations on Index resource - 💡 Automatic index creation using the `/indexes/:indexToCreate/documents` route generates a `documentAdditionOrUpdate` task that also handles index creation. -#### 9. Paginate `task` resource lists +#### 10. Paginate `task` resource lists The API endpoint `/tasks` is browsable using a keyset-based pagination. -##### 9.1 Why a Seek/Keyset based pagination? +##### 10.1. Why a Seek/Keyset based pagination? Keyset-based pagination is more appropriate when the data can grow or shrink quickly in terms of magnitude. -###### 9.1.1 Pros +###### 10.1.1. Pros The performance is better than the not-so-good but old pagination with `offset`/`limit`. @@ -392,11 +476,11 @@ Seek/Keyset pagination keeps the results consistent between each page as the dat Moreover, the performance is superior to traditional pagination since the computational complexity remains constant to reach the identifier marking the beginning of the new slice to be returned from a hash table. -###### 9.1.2 Cons +###### 10.1.2. Cons The main drawback of this type of pagination is that it does not navigate within a finite number of pages. It is also limited to a precise sorting criterion on unique identifiers ordered sequentially. -##### 9.2 Response attributes +##### 10.2. Response attributes | field | type | description | |-------|------|--------------------------------------| @@ -404,14 +488,14 @@ The main drawback of this type of pagination is that it does not navigate within | from | integer | The first task uid returned | | next | integer - nullable | Represents the value to send in `from` to fetch the next slice of the results. The first item for the next slice starts at this exact number. When the returned value is null, it means that all the data have been browsed in the given order. | -##### 9.3 GET query parameters +##### 10.3. GET query parameters | field | type | required | description | |-------|------|----------|--------------| | limit | integer | No | Default `20`. Limit on the number of tasks to be returned. | | from | integer | No | Limit results to tasks with uids equal to and lower than this uid. | -##### 9.4 Usage examples +##### 10.4. Usage examples This part demonstrates keyset paging in action on `/tasks`. The items `uid` remains sorted sequentially and can be used to navigate a list of `tasks` objects. @@ -500,26 +584,28 @@ This part demonstrates keyset paging in action on `/tasks`. The items `uid` rema - 💡 `next` response parameter is null because there are no more `tasks` to fetch. It means that the response represents the last slice of results for the given resource list. -##### 9.5 Behaviors for `limit` and `from` query parameters +##### 10.5. Behaviors for `limit` and `from` query parameters -###### 9.5.1 `limit` +###### 10.5.1. `limit` - If `limit` is not set, the default value is chosen. -###### 9.5.2 `from` +###### 10.5.2. `from` - If `from` is set with an out of bounds task `uid`, the response returns the tasks that are the nearest to the specified uid, the `next` field is set to the next page. It will be equivalent to call the `/tasks` route without any parameter. -###### 9.5.3 Errors +###### 10.5.3. Errors - 🔴 Sending a value with a different type than `Integer` for `limit` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. - 🔴 Sending a value with a different type than `Integer` for `from` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. -#### 10. Filtering task resources +#### 11. Filtering task resources + +##### 11.1. Filtering task to get The `/tasks` endpoint is filterable by `indexUid`, `type` and `status` query parameters. -##### 10.1. Query parameters definition +##### 11.1.1 Query parameters definition | parameter | type | required | description | |-----------|--------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -527,7 +613,7 @@ The `/tasks` endpoint is filterable by `indexUid`, `type` and `status` query par | status | string | No | Permits to filter tasks by their status. By default, when `status` query parameter is not set, all task statuses are returned. It's possible to specify several types by separating them with the `,` character. | | type | string | No | Permits to filter tasks by their related type. By default, when `type` query parameter is not set, all task types are returned. It's possible to specify several types by separating them with the `,` character. | -##### 10.2. Usages examples +##### 11.1.2. Usages examples This part demonstrates filtering on `/tasks`. @@ -614,6 +700,35 @@ This part demonstrates filtering on `/tasks`. } ``` +**Filter `canceled` tasks by `canceledBy` parameter** + +`GET` `tasks?canceledBy=1` + +```json +{ + "results": [ + { + "uid": 1350, + "indexUid": "movies", + "status": "failed", + "type": "documentAdditionOrUpdate", + "canceledBy": 1, + ..., + }, + ..., + { + "uid": 1343, + "indexUid": "movies", + "type": "succeeded", + "type": "documentAdditionOrUpdate", + "canceledBy": 1, + ..., + } + ], + ... +} +``` + **Filter `tasks` that are of `documentAdditionOrUpdate` type and have a `failed` status** `GET` - `/tasks?type=documentAdditionOrUpdate&status=failed` @@ -659,9 +774,9 @@ This part demonstrates filtering on `/tasks`. --- -##### 10.3. Behaviors for `indexUid`, `status` and `type` query parameters. +##### 11.1.3. Behaviors for `indexUid`, `status`and `type` query parameters. -###### 10.3.1. `indexUid` +###### 11.1.3.1. `indexUid` - Type: String - Required: False @@ -669,17 +784,15 @@ This part demonstrates filtering on `/tasks`. `indexUid` is **case-sensitive**. -###### 10.3.2. `status` +###### 11.1.3.2. `status` - Type: String - Required: False - Default: `*` -`status ` is **case-insensitive**. - - 🔴 If the `status` parameter value is not consistent with one of the task statuses, an [`invalid_task_status`](0061-error-format-and-definitions.md#invalidtaskstatus) error is returned. -###### 10.3.3. `type` +###### 11.1.3.3. `type` - Type: String - Required: False @@ -689,16 +802,204 @@ This part demonstrates filtering on `/tasks`. - 🔴 If the `type` parameter value is not consistent with one of the task types, an [`invalid_task_type`](0061-error-format-and-definitions.md#invalidtasktype) error is returned. -###### 10.3.4. Select multiple values for the same filter +###### 11.1.3.6. Select multiple values for the same filter It is possible to specify multiple values for a filter using the `,` character. For example, to select the `enqueued` and `processing` tasks of the `movies` and `movie_reviews` indexes, it is possible to express it like this: `/tasks?indexUid=movies,movie_reviews&status=enqueued,processing` -##### 10.4. Empty `results` +##### 11.1.4. Empty `results` If no results match the filters. A response is returned with an empty `results` array. +##### 11.2. Filtering task to cancel + +The `/tasks/cancel` endpoint is filterable by `uid`, `indexUid`, `type` and `status` query parameters. + +##### 11.2.1 Query parameters definition + +| parameter | type | required | description | +|-----------|--------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| uid | string | No | Permits to filter tasks by their related unique identifier. By default, when `uid` query parameter is not set, all the tasks are concerned. It is possible to specify several uid by separating them with the `,` character. | +| indexUid | string | No | Permits to filter tasks by their related index. By default, when `indexUid` query parameter is not set, the tasks of all the indexes are concerned. It is possible to specify several indexes by separating them with the `,` character. | +| status | string | No | Permits to filter tasks by their status. By default, when `status` query parameter is not set, all task statuses are concerned. It's possible to specify several types by separating them with the `,` character. | +| type | string | No | Permits to filter tasks by their related type. By default, when `type` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | +| date | string | No | Permits to filter tasks by their started or launched time. By default, when `afterXAt` or `beforeXAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | + +##### 11.2.2. Usages examples + +This part demonstrates filtering on `/tasks/cancel`. + +--- + +**No filtering** + +Users will not be allowed to use this route without any filters (POST /tasks/cancel), as it may result in canceling everything by mistake. If the request contains no filters, the user will get an error asking them to be more specific. + +**Filter `tasks` to cancel based on `uid`** + +`POST` `/tasks/cancel?uid=1,2` + +```json +{ + "taskUid": 3, + "indexUid": null, + "status": "enqueued", + "type": "taskCancelation", + "enqueuedAt": "2021-08-12T10:00:00.000000Z" +} +``` + +**Filter `tasks` to cancel based on `indexUid`** + +`POST` `/tasks/cancel?indexUid=movies` + +```json +{ + "taskUid": 1, + "indexUid": "movies", + "status": "enqueued", + "type": "taskCancelation", + "enqueuedAt": "2021-08-12T10:00:00.000000Z" +} +``` + +**Filter `tasks` to cancel based on `status`** + +`POST` - `/tasks/cancel?status=processing` + +```json +{ + "taskUid": 1, + "indexUid": "movies", + "status": "enqueued", + "type": "taskCancelation", + "enqueuedAt": "2021-08-12T10:00:00.000000Z" +} +``` + +**Filter `tasks` to cancel based on `type`** + +`POST` - `/tasks/cancel?type=documentAdditionOrUpdate` + +```json +{ + "taskUid": 1, + "indexUid": "movies", + "status": "enqueued", + "type": "taskCancelation", + "enqueuedAt": "2021-08-12T10:00:00.000000Z" +} +``` + +**Filter `tasks` to cancel using date filters** + +`POST` - `/tasks/cancel?afterenqueuedAt>2020-10-11T11:49:53.000Z` + +```json +{ + "taskUid": 1, + "indexUid": "movies", + "status": "enqueued", + "type": "taskCancelation", + "enqueuedAt": "2021-08-12T10:00:00.000000Z" +} +``` +**Filter `tasks` to cancel that are of multiple type and have a `indexUid`** + +`POST` - `/tasks/cancel?indexUid=movies&(AND)type=documentAdditionOrUpdate,(OR)documentDeletion` + +```json +{ + "taskUid": 1, + "indexUid": "movies", + "status": "enqueued", + "type": "taskCancelation", + "enqueuedAt": "2021-08-12T10:00:00.000000Z" +} +``` + +- 💡 Filters can be used together. Both parameters are accumulated and `AND` and `OR` operations are performed between the filters. +- `type` and `indexUid` query parameters can be read as is `type=documentsAdditionOrUpdate OR documentDeletion AND indexUid=movies`. + +**Cancel all the tasks with filter** + +`POST` - `/taskscancel?status=processing,enqueued` + +```json +{ + "taskUid": 1, + "indexUid": "movies", + "status": "enqueued", + "type": "taskCancelation", + "enqueuedAt": "2021-08-12T10:00:00.000000Z" +} +``` + +--- + +##### 11.2.3. Behaviors for `uid`, `indexUid`, `status`, `type` and `date` query parameters. + +###### 11.2.3.1. `uid` + +- Type: String +- Required: False +- Default: `*` + +`uid` is **case-sensitive**. + +###### 11.2.3.2. `indexUid` + +- Type: String +- Required: False +- Default: `*` + +`indexUid` is **case-sensitive**. + +###### 11.2.3.3. `status` + +- Type: String +- Required: False +- Default: `*` + +- 🔴 If the `status` parameter value is not consistent with one of the task statuses, an [`invalid_task_status`](0061-error-format-and-definitions.md#invalidtaskstatus) error is returned. + +###### 11.2.3.4. `type` + +- Type: String +- Required: False +- Default: `*` + +`type` is **case-insensitive**. + +- 🔴 If the `type` parameter value is not consistent with one of the task types, an [`invalid_task_type`](0061-error-format-and-definitions.md#invalidtasktype) error is returned. + +###### 11.2.3.5. `date` + +You can cancel tasks using `afterXAt` and `beforeXAt`. You can use the following fields: + +- `enqueuedAt` → `afterenqueuedAt` or `beforeanqueuedAt` +- `startedAt` → `afterstartedAt` or `beforestartedAt` +- `finishedAt` →`afterfinishedAt` or `before` `finishedAt` + +The filter accepts the RFC 3339 format. The following syntaxes are valid: + +- `Y-M-D` +- `Y-M-DTH:M:SZ` +- `Y-M-DTH:M:S+01:00` + +- Type: String +- Required: False +- Default: `*` + +- 🔴 The date filters are exclusive. You can cancel tasks before or after a specified date, meaning it will not be included, `>=` and `<=` are not valid. + +###### 11.2.3.6. Select multiple values for the same filter + +It is possible to specify multiple values for a filter using the `,` character. + +For example, to select the `enqueued` and `processing` tasks of the `movies` and `movie_reviews` indexes, it is possible to express it like this: `/tasks/cancel?indexUid=movies,movie_reviews&status=enqueued,processing`. + ## 2. Technical details n/a From afc62a853bcc7efe00dba4121415b8daf45a1e03 Mon Sep 17 00:00:00 2001 From: alallema Date: Tue, 25 Oct 2022 19:00:27 +0200 Subject: [PATCH 02/76] Remove missing error --- text/0060-tasks-api.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 642622cd..a659e1d2 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -421,8 +421,6 @@ If a user tries canceling a `succeeded`, `failed`, or `canceled` task, it won’ - 🔴 If the `type` parameter value is not consistent with one of the task types, an `[invalid_task_type](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalidtasktype)` error is returned. - 🔴 If the `status` parameter value is not consistent with one of the task statuses, an `[invalid_task_status](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalidtaskstatus)` error is returned. -- ? (value type format error for every query parameters) -- ? (sending a query parameter that does not exists error) The auth layer can return the following errors if Meilisearch is secured (a master-key is defined). @@ -980,7 +978,6 @@ You can cancel tasks using `afterXAt` and `beforeXAt`. You can use the following - `enqueuedAt` → `afterenqueuedAt` or `beforeanqueuedAt` - `startedAt` → `afterstartedAt` or `beforestartedAt` -- `finishedAt` →`afterfinishedAt` or `before` `finishedAt` The filter accepts the RFC 3339 format. The following syntaxes are valid: From 7f5435da4796aaa1168f4ca6a2565d62a38e9101 Mon Sep 17 00:00:00 2001 From: alallema Date: Tue, 25 Oct 2022 19:05:22 +0200 Subject: [PATCH 03/76] Fix typo on cancels --- text/0060-tasks-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index a659e1d2..132f8031 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -382,13 +382,13 @@ The auth layer can return the following errors if Meilisearch is secured (a mast --- -##### 6.3. Cancel tasks | `POST` - `/tasks` +##### 6.3. Cancel tasks | `POST` - `/tasks/cancel` ##### 6.3.1. Goals Allows users to cancel an `enqueued` or `processing` task. Particularly useful if a long or heavy task blocks the queue. -`202` - Response body - `/tasks/cancels` +`202` - Response body - `/tasks/cancel` ```json { From a6f7d8f3b1253f322e7a56e79447904f414a3dac Mon Sep 17 00:00:00 2001 From: alallema Date: Wed, 26 Oct 2022 10:57:49 +0200 Subject: [PATCH 04/76] Fix IndexUid always null --- text/0060-tasks-api.md | 42 ++++++++++++++++++++++++++++++++---------- 1 file changed, 32 insertions(+), 10 deletions(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 132f8031..fdafbd73 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -607,9 +607,11 @@ The `/tasks` endpoint is filterable by `indexUid`, `type` and `status` query par | parameter | type | required | description | |-----------|--------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| indexUid | string | No | Permits to filter tasks by their related index. By default, when `indexUid` query parameter is not set, the tasks of all the indexes are returned. It is possible to specify several indexes by separating them with the `,` character. | -| status | string | No | Permits to filter tasks by their status. By default, when `status` query parameter is not set, all task statuses are returned. It's possible to specify several types by separating them with the `,` character. | -| type | string | No | Permits to filter tasks by their related type. By default, when `type` query parameter is not set, all task types are returned. It's possible to specify several types by separating them with the `,` character. | +| uid | string | No | Permits to filter tasks by their related unique identifier. By default, when `uid` query parameter is not set, all the tasks are concerned. It is possible to specify several uid by separating them with the `,` character. | +| indexUid | string | No | Permits to filter tasks by their related index. By default, when `indexUid` query parameter is not set, the tasks of all the indexes are concerned. It is possible to specify several indexes by separating them with the `,` character. | +| status | string | No | Permits to filter tasks by their status. By default, when `status` query parameter is not set, all task statuses are concerned. It's possible to specify several types by separating them with the `,` character. | +| type | string | No | Permits to filter tasks by their related type. By default, when `type` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | +| date | string | No | Permits to filter tasks by their started or launched time. By default, when `afterXAt` or `beforeXAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | ##### 11.1.2. Usages examples @@ -800,7 +802,27 @@ This part demonstrates filtering on `/tasks`. - 🔴 If the `type` parameter value is not consistent with one of the task types, an [`invalid_task_type`](0061-error-format-and-definitions.md#invalidtasktype) error is returned. -###### 11.1.3.6. Select multiple values for the same filter +###### 11.1.3.4. `date` + +You can cancel tasks using `afterXAt` and `beforeXAt`. You can use the following fields: + +- `enqueuedAt` → `afterenqueuedAt` or `beforeanqueuedAt` +- `startedAt` → `afterstartedAt` or `beforestartedAt` +- `finishedAt` → `afterFinishedAt` or `beforeFinishedAt` + +The filter accepts the RFC 3339 format. The following syntaxes are valid: + +- `Y-M-D` +- `Y-M-DTH:M:SZ` +- `Y-M-DTH:M:S+01:00` + +- Type: String +- Required: False +- Default: `*` + +- 🔴 The date filters are exclusive. You can cancel tasks before or after a specified date, meaning it will not be included, `>=` and `<=` are not valid. + +###### 11.1.3.5. Select multiple values for the same filter It is possible to specify multiple values for a filter using the `,` character. @@ -855,7 +877,7 @@ Users will not be allowed to use this route without any filters (POST /tasks/can ```json { "taskUid": 1, - "indexUid": "movies", + "indexUid": null, "status": "enqueued", "type": "taskCancelation", "enqueuedAt": "2021-08-12T10:00:00.000000Z" @@ -869,7 +891,7 @@ Users will not be allowed to use this route without any filters (POST /tasks/can ```json { "taskUid": 1, - "indexUid": "movies", + "indexUid": null, "status": "enqueued", "type": "taskCancelation", "enqueuedAt": "2021-08-12T10:00:00.000000Z" @@ -883,7 +905,7 @@ Users will not be allowed to use this route without any filters (POST /tasks/can ```json { "taskUid": 1, - "indexUid": "movies", + "indexUid": null, "status": "enqueued", "type": "taskCancelation", "enqueuedAt": "2021-08-12T10:00:00.000000Z" @@ -897,7 +919,7 @@ Users will not be allowed to use this route without any filters (POST /tasks/can ```json { "taskUid": 1, - "indexUid": "movies", + "indexUid": null, "status": "enqueued", "type": "taskCancelation", "enqueuedAt": "2021-08-12T10:00:00.000000Z" @@ -910,7 +932,7 @@ Users will not be allowed to use this route without any filters (POST /tasks/can ```json { "taskUid": 1, - "indexUid": "movies", + "indexUid": null, "status": "enqueued", "type": "taskCancelation", "enqueuedAt": "2021-08-12T10:00:00.000000Z" @@ -927,7 +949,7 @@ Users will not be allowed to use this route without any filters (POST /tasks/can ```json { "taskUid": 1, - "indexUid": "movies", + "indexUid": null, "status": "enqueued", "type": "taskCancelation", "enqueuedAt": "2021-08-12T10:00:00.000000Z" From ec98300976864255c178ee6906def56df26bf212 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Wed, 26 Oct 2022 14:39:20 +0200 Subject: [PATCH 05/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index fdafbd73..ca8b70c5 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -8,7 +8,7 @@ This specification describes the API endpoints for handling asynchronous tasks. ### II. Motivation -As writing is asynchronous for most of Meilisearch's operations, this API allows you to track the progress of asynchronous tasks, know and understand why a task has failed, and cancel specific tasks in progress by consulting the history of operations that happened. +As writing is asynchronous for most of Meilisearch's operations, this API allows you to track the progress of asynchronous tasks, know and understand why a task has failed, and cancel specific tasks being enqueued or processing by consulting the history of operations that happened. ### III. Explanation From c0b651e73b02810e58e5823cbfc7cf07cd16bc20 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Wed, 26 Oct 2022 14:39:29 +0200 Subject: [PATCH 06/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index ca8b70c5..cda46d8c 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -140,7 +140,7 @@ Fully qualified and summarized task objects related to a dump creation display a | --- | --- | | matchedTasks | The number of tasks that can be canceled based on the request. If the API key doesn’t have access to any of the indexes specified in the request, those tasks will not be included in matchedTasks. | | canceledTasks | The number of tasks successfully canceled. If the task fails, this will be 0. | -| originalQuery | The filter used in the /tasks/cancel request. | +| originalQuery | The filter query used in the /tasks/cancel request. | #### 5. Examples From b83508fc2b575830ce8102df30ecc1d57b045bb8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Wed, 26 Oct 2022 14:39:47 +0200 Subject: [PATCH 07/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index cda46d8c..2917fdab 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -256,9 +256,9 @@ e.g. A fully qualified `task` object in a `canceled` state. ```json { "uid": 0, - "indexUid": "movies", - "status": "canceled", - "type": "settingsUpdate", + "indexUid": "movies", + "status": "canceled", + "type": "settingsUpdate", "details": { "rankingRules": [ "typo", @@ -271,11 +271,9 @@ e.g. A fully qualified `task` object in a `canceled` state. }, "canceledBy": 1, "enqueuedAt": "2021-08-10T14:29:17.000000Z", - "startedAt": "2021-08-10T14:29:18.000000Z", + "startedAt": "2021-08-10T14:29:18.000000Z", "finishedAt": "2021-08-10T14:29:19.000000Z" } -``` - e.g. A summarized `task` object in a `202 Accepted` HTTP response returned at index creation. ```json From 29fe887ee3fc4a54e6e868f2e73341c5dbb7d260 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Wed, 26 Oct 2022 14:39:54 +0200 Subject: [PATCH 08/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 2917fdab..ded968f2 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -391,7 +391,7 @@ Allows users to cancel an `enqueued` or `processing` task. Particularly useful i ```json { "taskUid": 0, - "indexUid": "movies", + "indexUid": null, "status": "enqueued", "type": "taskCancelation", "enqueuedAt": "2021-08-12T10:00:00.000000Z" From bbe0d4b7e007b7f7e5dcd48f683e0621c1a2114c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Wed, 26 Oct 2022 14:40:11 +0200 Subject: [PATCH 09/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index ded968f2..add08b35 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -818,7 +818,7 @@ The filter accepts the RFC 3339 format. The following syntaxes are valid: - Required: False - Default: `*` -- 🔴 The date filters are exclusive. You can cancel tasks before or after a specified date, meaning it will not be included, `>=` and `<=` are not valid. +- 🔴 The date filters are exclusive. You can cancel tasks before or after a specified date, meaning it will not be included. ###### 11.1.3.5. Select multiple values for the same filter From 6b7c70e547476b1669068d7c653c52677d84c3fe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Wed, 26 Oct 2022 14:40:41 +0200 Subject: [PATCH 10/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index add08b35..18e1e2ee 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -599,7 +599,7 @@ This part demonstrates keyset paging in action on `/tasks`. The items `uid` rema ##### 11.1. Filtering task to get -The `/tasks` endpoint is filterable by `indexUid`, `type` and `status` query parameters. +The `/tasks` endpoint is filterable by `uid`, `indexUid`, `type`, `status`, `beforeEnqueuedAt`, `afterEnqueuedAt`, `beforeStartedAt`, `afterStartedAt`, `beforeFinishedAt`, `afterFinishedAt` query parameters. ##### 11.1.1 Query parameters definition From 44a59b3a7e2a9a98b51fd3c8959544ff8c2caa8e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Wed, 26 Oct 2022 14:41:00 +0200 Subject: [PATCH 11/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 18e1e2ee..db84455b 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -708,7 +708,7 @@ This part demonstrates filtering on `/tasks`. { "uid": 1350, "indexUid": "movies", - "status": "failed", + "status": "canceled", "type": "documentAdditionOrUpdate", "canceledBy": 1, ..., From 5c94d5efedff89258d0d21eba9f0713b8c82660d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Wed, 26 Oct 2022 14:41:49 +0200 Subject: [PATCH 12/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index db84455b..5ba942a9 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -717,7 +717,7 @@ This part demonstrates filtering on `/tasks`. { "uid": 1343, "indexUid": "movies", - "type": "succeeded", + "status": "canceled", "type": "documentAdditionOrUpdate", "canceledBy": 1, ..., From 532636334ef265ae906430a23b217be50492e813 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Wed, 26 Oct 2022 14:42:10 +0200 Subject: [PATCH 13/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 5ba942a9..c67b1446 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -772,7 +772,7 @@ This part demonstrates filtering on `/tasks`. --- -##### 11.1.3. Behaviors for `indexUid`, `status`and `type` query parameters. +##### 11.1.3. Query Parameters Behaviors ###### 11.1.3.1. `indexUid` From dfcf97ff88041af81a51eadd748e441eebe9916a Mon Sep 17 00:00:00 2001 From: alallema Date: Wed, 26 Oct 2022 15:09:17 +0200 Subject: [PATCH 14/76] Add canceledBy and missing_filters error --- text/0060-tasks-api.md | 13 ++----------- text/0061-error-format-and-definitions.md | 23 +++++++++++++++++++++++ 2 files changed, 25 insertions(+), 11 deletions(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index c67b1446..dfbb1185 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -24,6 +24,7 @@ As writing is asynchronous for most of Meilisearch's operations, this API allows | indexUid | string | Unique index identifier. This field is `null` when the task type is `dumpCreation`. | | status | string | Status of the task. Possible values are `enqueued`, `processing`, `succeeded`, `failed`, `canceled` | | type | string | Type of the task. Possible values are `indexCreation`, `indexUpdate`, `indexDeletion`, `documentAdditionOrUpdate`, `documentDeletion`, `settingsUpdate`, `dumpCreation`, `taskCancelation` | +| canceledBy | integer | Unique identifier of the `taskCancelation` task that cancelled the given task. | | details | object | Details information for a task payload. See Task Details part. | | error | object | Error object containing error details and context when a task has a `failed` status. See [0061-error-format-and-definitions.md](0061-error-format-and-definitions.md) | | duration | string | Total elapsed time the engine was in processing state expressed as an `ISO-8601` duration format. Times below the second can be expressed with the `.` notation, e.g., `PT0.5S` to express `500ms`. Default is set to `null`. | @@ -406,17 +407,7 @@ When the request is successful, Meilisearch returns the HTTP code 202 Accepted. If a user tries canceling a `succeeded`, `failed`, or `canceled` task, it won’t throw an error. Task cancelation is an atomic transaction; all tasks are successfully canceled, or none aren't. -- 🔴 Sending a task cancelation without filtering query parameters returns a `missing_filters` error. - - ```json - { - "message": "Query parameters to filter the tasks to cancel are missing. Available query parameters are: `uid`, `indexUid`, `status`, `type`, `beforeEnqueuedAt`, `afterEnqueudAt`, `beforeStartedAt`, afterStartedAt`", - "code": "missing_filters", - "type": "invalid_request", - "link": "https://docs.meilisearch.com/errors#missing_filters" - } - ``` - +- 🔴 Sending a task cancelation without filtering query parameters returns a `[missing_filters](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#missing_filters)` error. - 🔴 If the `type` parameter value is not consistent with one of the task types, an `[invalid_task_type](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalidtasktype)` error is returned. - 🔴 If the `status` parameter value is not consistent with one of the task statuses, an `[invalid_task_status](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalidtaskstatus)` error is returned. diff --git a/text/0061-error-format-and-definitions.md b/text/0061-error-format-and-definitions.md index 31b88ef0..534cccc1 100644 --- a/text/0061-error-format-and-definitions.md +++ b/text/0061-error-format-and-definitions.md @@ -1086,6 +1086,29 @@ HTTP Code: `400 Bad Request` --- +## missing_filters + +`Synchronous` + +### Context + +This error occurs when the request does not contain any filters and they are mandatory. + +### Error Definition + +HTTP Code: `400 Bad Request` + +```json +{ + "message": "Query parameters to filter the tasks to cancel are missing. Available query parameters are: `uid`, `indexUid`, `status`, `type`, `beforeEnqueuedAt`, `afterEnqueudAt`, `beforeStartedAt`, afterStartedAt`", + "code": "missing_filters", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#missing_filters" +} +``` + +--- + # internal type ## internal From 376b0133205a493a29b9fe34dbacfaddd88f5b17 Mon Sep 17 00:00:00 2001 From: alallema Date: Wed, 26 Oct 2022 15:34:07 +0200 Subject: [PATCH 15/76] Merge 11.1 filter iwth get and 11.2 filter with post --- text/0060-tasks-api.md | 219 +++++------------------------------------ 1 file changed, 26 insertions(+), 193 deletions(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index dfbb1185..b00105e9 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -588,11 +588,9 @@ This part demonstrates keyset paging in action on `/tasks`. The items `uid` rema #### 11. Filtering task resources -##### 11.1. Filtering task to get +The `/tasks` and `/tasks/cancel` endpoints are filterable by `uid`, `indexUid`, `type`, `status`, `beforeEnqueuedAt`, `afterEnqueuedAt`, `beforeStartedAt`, `afterStartedAt`, `beforeFinishedAt`, `afterFinishedAt` query parameters. -The `/tasks` endpoint is filterable by `uid`, `indexUid`, `type`, `status`, `beforeEnqueuedAt`, `afterEnqueuedAt`, `beforeStartedAt`, `afterStartedAt`, `beforeFinishedAt`, `afterFinishedAt` query parameters. - -##### 11.1.1 Query parameters definition +##### 11.1 Query parameters definition | parameter | type | required | description | |-----------|--------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -600,9 +598,11 @@ The `/tasks` endpoint is filterable by `uid`, `indexUid`, `type`, `status`, `be | indexUid | string | No | Permits to filter tasks by their related index. By default, when `indexUid` query parameter is not set, the tasks of all the indexes are concerned. It is possible to specify several indexes by separating them with the `,` character. | | status | string | No | Permits to filter tasks by their status. By default, when `status` query parameter is not set, all task statuses are concerned. It's possible to specify several types by separating them with the `,` character. | | type | string | No | Permits to filter tasks by their related type. By default, when `type` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | -| date | string | No | Permits to filter tasks by their started or launched time. By default, when `afterXAt` or `beforeXAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | +| beforeEnqueuedAt afterEnqueuedAt | string | No | Permits to filter tasks by the time before or after they are queued. By default, when `beforeEnqueuedAt` or `afterEnqueuedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | +| beforeStartedAt afterStartedAt | string | No | Permits to filter tasks by their started time. By default, when `beforeStartedAt` or `afterStartedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | +| beforeFinishedAt afterFinishedAt | string | No | Permits to filter tasks by their finished time. By default, when `beforeFinishedAt` or `afterFinishedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | -##### 11.1.2. Usages examples +##### 11.2. Usages examples This part demonstrates filtering on `/tasks`. @@ -635,6 +635,8 @@ This part demonstrates filtering on `/tasks`. } ``` +Users will not be allowed to use this route without any filters on `POST` `/tasks/cancel`, as it may result in canceling everything by mistake. If the request contains no filters, the user will get an error asking them to be more specific. + **Filter `tasks` that have a `failed` `status`** `GET` - `/tasks?status=failed` @@ -761,176 +763,6 @@ This part demonstrates filtering on `/tasks`. - If the `indexUid` parameter value contains an inexistent index, it returns an empty `results` array. ---- - -##### 11.1.3. Query Parameters Behaviors - -###### 11.1.3.1. `indexUid` - -- Type: String -- Required: False -- Default: `*` - -`indexUid` is **case-sensitive**. - -###### 11.1.3.2. `status` - -- Type: String -- Required: False -- Default: `*` - -- 🔴 If the `status` parameter value is not consistent with one of the task statuses, an [`invalid_task_status`](0061-error-format-and-definitions.md#invalidtaskstatus) error is returned. - -###### 11.1.3.3. `type` - -- Type: String -- Required: False -- Default: `*` - -`type` is **case-insensitive**. - -- 🔴 If the `type` parameter value is not consistent with one of the task types, an [`invalid_task_type`](0061-error-format-and-definitions.md#invalidtasktype) error is returned. - -###### 11.1.3.4. `date` - -You can cancel tasks using `afterXAt` and `beforeXAt`. You can use the following fields: - -- `enqueuedAt` → `afterenqueuedAt` or `beforeanqueuedAt` -- `startedAt` → `afterstartedAt` or `beforestartedAt` -- `finishedAt` → `afterFinishedAt` or `beforeFinishedAt` - -The filter accepts the RFC 3339 format. The following syntaxes are valid: - -- `Y-M-D` -- `Y-M-DTH:M:SZ` -- `Y-M-DTH:M:S+01:00` - -- Type: String -- Required: False -- Default: `*` - -- 🔴 The date filters are exclusive. You can cancel tasks before or after a specified date, meaning it will not be included. - -###### 11.1.3.5. Select multiple values for the same filter - -It is possible to specify multiple values for a filter using the `,` character. - -For example, to select the `enqueued` and `processing` tasks of the `movies` and `movie_reviews` indexes, it is possible to express it like this: `/tasks?indexUid=movies,movie_reviews&status=enqueued,processing` - -##### 11.1.4. Empty `results` - -If no results match the filters. A response is returned with an empty `results` array. - -##### 11.2. Filtering task to cancel - -The `/tasks/cancel` endpoint is filterable by `uid`, `indexUid`, `type` and `status` query parameters. - -##### 11.2.1 Query parameters definition - -| parameter | type | required | description | -|-----------|--------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| uid | string | No | Permits to filter tasks by their related unique identifier. By default, when `uid` query parameter is not set, all the tasks are concerned. It is possible to specify several uid by separating them with the `,` character. | -| indexUid | string | No | Permits to filter tasks by their related index. By default, when `indexUid` query parameter is not set, the tasks of all the indexes are concerned. It is possible to specify several indexes by separating them with the `,` character. | -| status | string | No | Permits to filter tasks by their status. By default, when `status` query parameter is not set, all task statuses are concerned. It's possible to specify several types by separating them with the `,` character. | -| type | string | No | Permits to filter tasks by their related type. By default, when `type` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | -| date | string | No | Permits to filter tasks by their started or launched time. By default, when `afterXAt` or `beforeXAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | - -##### 11.2.2. Usages examples - -This part demonstrates filtering on `/tasks/cancel`. - ---- - -**No filtering** - -Users will not be allowed to use this route without any filters (POST /tasks/cancel), as it may result in canceling everything by mistake. If the request contains no filters, the user will get an error asking them to be more specific. - -**Filter `tasks` to cancel based on `uid`** - -`POST` `/tasks/cancel?uid=1,2` - -```json -{ - "taskUid": 3, - "indexUid": null, - "status": "enqueued", - "type": "taskCancelation", - "enqueuedAt": "2021-08-12T10:00:00.000000Z" -} -``` - -**Filter `tasks` to cancel based on `indexUid`** - -`POST` `/tasks/cancel?indexUid=movies` - -```json -{ - "taskUid": 1, - "indexUid": null, - "status": "enqueued", - "type": "taskCancelation", - "enqueuedAt": "2021-08-12T10:00:00.000000Z" -} -``` - -**Filter `tasks` to cancel based on `status`** - -`POST` - `/tasks/cancel?status=processing` - -```json -{ - "taskUid": 1, - "indexUid": null, - "status": "enqueued", - "type": "taskCancelation", - "enqueuedAt": "2021-08-12T10:00:00.000000Z" -} -``` - -**Filter `tasks` to cancel based on `type`** - -`POST` - `/tasks/cancel?type=documentAdditionOrUpdate` - -```json -{ - "taskUid": 1, - "indexUid": null, - "status": "enqueued", - "type": "taskCancelation", - "enqueuedAt": "2021-08-12T10:00:00.000000Z" -} -``` - -**Filter `tasks` to cancel using date filters** - -`POST` - `/tasks/cancel?afterenqueuedAt>2020-10-11T11:49:53.000Z` - -```json -{ - "taskUid": 1, - "indexUid": null, - "status": "enqueued", - "type": "taskCancelation", - "enqueuedAt": "2021-08-12T10:00:00.000000Z" -} -``` -**Filter `tasks` to cancel that are of multiple type and have a `indexUid`** - -`POST` - `/tasks/cancel?indexUid=movies&(AND)type=documentAdditionOrUpdate,(OR)documentDeletion` - -```json -{ - "taskUid": 1, - "indexUid": null, - "status": "enqueued", - "type": "taskCancelation", - "enqueuedAt": "2021-08-12T10:00:00.000000Z" -} -``` - -- 💡 Filters can be used together. Both parameters are accumulated and `AND` and `OR` operations are performed between the filters. -- `type` and `indexUid` query parameters can be read as is `type=documentsAdditionOrUpdate OR documentDeletion AND indexUid=movies`. - **Cancel all the tasks with filter** `POST` - `/taskscancel?status=processing,enqueued` @@ -947,9 +779,9 @@ Users will not be allowed to use this route without any filters (POST /tasks/can --- -##### 11.2.3. Behaviors for `uid`, `indexUid`, `status`, `type` and `date` query parameters. +##### 11.3. Query Parameters Behaviors -###### 11.2.3.1. `uid` +###### 11.3.1. `uid` - Type: String - Required: False @@ -957,7 +789,7 @@ Users will not be allowed to use this route without any filters (POST /tasks/can `uid` is **case-sensitive**. -###### 11.2.3.2. `indexUid` +###### 11.3.2. `indexUid` - Type: String - Required: False @@ -965,7 +797,7 @@ Users will not be allowed to use this route without any filters (POST /tasks/can `indexUid` is **case-sensitive**. -###### 11.2.3.3. `status` +###### 11.3.3. `status` - Type: String - Required: False @@ -973,7 +805,7 @@ Users will not be allowed to use this route without any filters (POST /tasks/can - 🔴 If the `status` parameter value is not consistent with one of the task statuses, an [`invalid_task_status`](0061-error-format-and-definitions.md#invalidtaskstatus) error is returned. -###### 11.2.3.4. `type` +###### 11.3.4. `type` - Type: String - Required: False @@ -983,12 +815,11 @@ Users will not be allowed to use this route without any filters (POST /tasks/can - 🔴 If the `type` parameter value is not consistent with one of the task types, an [`invalid_task_type`](0061-error-format-and-definitions.md#invalidtasktype) error is returned. -###### 11.2.3.5. `date` - -You can cancel tasks using `afterXAt` and `beforeXAt`. You can use the following fields: +###### 11.3.5. `afterXAt` and `beforeXAt` -- `enqueuedAt` → `afterenqueuedAt` or `beforeanqueuedAt` -- `startedAt` → `afterstartedAt` or `beforestartedAt` +- Type: String +- Required: False +- Default: `*` The filter accepts the RFC 3339 format. The following syntaxes are valid: @@ -996,17 +827,19 @@ The filter accepts the RFC 3339 format. The following syntaxes are valid: - `Y-M-DTH:M:SZ` - `Y-M-DTH:M:S+01:00` -- Type: String -- Required: False -- Default: `*` - -- 🔴 The date filters are exclusive. You can cancel tasks before or after a specified date, meaning it will not be included, `>=` and `<=` are not valid. +- 🔴 The date filters are exclusive. You can cancel tasks before or after a specified date, meaning it will not be included. -###### 11.2.3.6. Select multiple values for the same filter +###### 11.3.6. Select multiple values for the same filter It is possible to specify multiple values for a filter using the `,` character. -For example, to select the `enqueued` and `processing` tasks of the `movies` and `movie_reviews` indexes, it is possible to express it like this: `/tasks/cancel?indexUid=movies,movie_reviews&status=enqueued,processing`. +For example, to select the `enqueued` and `processing` tasks of the `movies` and `movie_reviews` indexes, it is possible to express it like this: `/tasks?indexUid=movies,movie_reviews&status=enqueued,processing` + +##### 11.4. Empty `results` + +If no results match the filters. A response is returned with an empty `results` array. + +--- ## 2. Technical details From c737c9594d8e9015a32210bf958a4590a7b6c3ac Mon Sep 17 00:00:00 2001 From: alallema Date: Wed, 26 Oct 2022 15:41:02 +0200 Subject: [PATCH 16/76] Specified every date filter --- text/0060-tasks-api.md | 41 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 36 insertions(+), 5 deletions(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index b00105e9..326fab88 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -598,9 +598,12 @@ The `/tasks` and `/tasks/cancel` endpoints are filterable by `uid`, `indexUid`, | indexUid | string | No | Permits to filter tasks by their related index. By default, when `indexUid` query parameter is not set, the tasks of all the indexes are concerned. It is possible to specify several indexes by separating them with the `,` character. | | status | string | No | Permits to filter tasks by their status. By default, when `status` query parameter is not set, all task statuses are concerned. It's possible to specify several types by separating them with the `,` character. | | type | string | No | Permits to filter tasks by their related type. By default, when `type` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | -| beforeEnqueuedAt afterEnqueuedAt | string | No | Permits to filter tasks by the time before or after they are queued. By default, when `beforeEnqueuedAt` or `afterEnqueuedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | -| beforeStartedAt afterStartedAt | string | No | Permits to filter tasks by their started time. By default, when `beforeStartedAt` or `afterStartedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | -| beforeFinishedAt afterFinishedAt | string | No | Permits to filter tasks by their finished time. By default, when `beforeFinishedAt` or `afterFinishedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | +| beforeEnqueuedAt | string | No | Permits to filter tasks based on the time before they are queued. By default, when `beforeEnqueuedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | +| afterEnqueuedAt | string | No | Permits to filter tasks based on the time after they are queued. By default, when `afterEnqueuedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | +| beforeStartedAt | string | No | Permits to filter tasks by the time before they were started. By default, when `beforeStartedAt` or `afterStartedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | +| afterStartedAt | string | No | Permits to filter tasks by the time after they were started. By default, when `beforeStartedAt` or `afterStartedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | +| beforeFinishedAt | string | No | Permits to filter tasks by the time before they were finished. By default, when `beforeFinishedAt` or `afterFinishedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | +| afterFinishedAt | string | No | Permits to filter tasks by the time after they were finished. By default, when `beforeFinishedAt` or `afterFinishedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | ##### 11.2. Usages examples @@ -815,7 +818,7 @@ Users will not be allowed to use this route without any filters on `POST` `/task - 🔴 If the `type` parameter value is not consistent with one of the task types, an [`invalid_task_type`](0061-error-format-and-definitions.md#invalidtasktype) error is returned. -###### 11.3.5. `afterXAt` and `beforeXAt` +###### 11.3.5. `beforeEnqueuedAt` and `afterEnqueuedAt` - Type: String - Required: False @@ -829,7 +832,35 @@ The filter accepts the RFC 3339 format. The following syntaxes are valid: - 🔴 The date filters are exclusive. You can cancel tasks before or after a specified date, meaning it will not be included. -###### 11.3.6. Select multiple values for the same filter +###### 11.3.6. `beforeStartedAt` and `afterStartedAt` + +- Type: String +- Required: False +- Default: `*` + +The filter accepts the RFC 3339 format. The following syntaxes are valid: + +- `Y-M-D` +- `Y-M-DTH:M:SZ` +- `Y-M-DTH:M:S+01:00` + +- 🔴 The date filters are exclusive. You can cancel tasks before or after a specified date, meaning it will not be included. + +###### 11.3.7. `beforeFinishedAt` and `afterFinishedAt` + +- Type: String +- Required: False +- Default: `*` + +The filter accepts the RFC 3339 format. The following syntaxes are valid: + +- `Y-M-D` +- `Y-M-DTH:M:SZ` +- `Y-M-DTH:M:S+01:00` + +- 🔴 The date filters are exclusive. You can cancel tasks before or after a specified date, meaning it will not be included. + +###### 11.3.8. Select multiple values for the same filter It is possible to specify multiple values for a filter using the `,` character. From 168aee8efc00855d31d642453ca7533b23484d6e Mon Sep 17 00:00:00 2001 From: alallema Date: Wed, 26 Oct 2022 15:44:01 +0200 Subject: [PATCH 17/76] Change uid as integer and not as string --- text/0060-tasks-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 326fab88..0f05ec1d 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -594,7 +594,7 @@ The `/tasks` and `/tasks/cancel` endpoints are filterable by `uid`, `indexUid`, | parameter | type | required | description | |-----------|--------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| uid | string | No | Permits to filter tasks by their related unique identifier. By default, when `uid` query parameter is not set, all the tasks are concerned. It is possible to specify several uid by separating them with the `,` character. | +| uid | integer | No | Permits to filter tasks by their related unique identifier. By default, when `uid` query parameter is not set, all the tasks are concerned. It is possible to specify several uid by separating them with the `,` character. | | indexUid | string | No | Permits to filter tasks by their related index. By default, when `indexUid` query parameter is not set, the tasks of all the indexes are concerned. It is possible to specify several indexes by separating them with the `,` character. | | status | string | No | Permits to filter tasks by their status. By default, when `status` query parameter is not set, all task statuses are concerned. It's possible to specify several types by separating them with the `,` character. | | type | string | No | Permits to filter tasks by their related type. By default, when `type` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | @@ -786,7 +786,7 @@ Users will not be allowed to use this route without any filters on `POST` `/task ###### 11.3.1. `uid` -- Type: String +- Type: Integer - Required: False - Default: `*` From fa84b90256f2d8725bbd8c52e78934ddc174d3ef Mon Sep 17 00:00:00 2001 From: alallema Date: Wed, 26 Oct 2022 15:49:09 +0200 Subject: [PATCH 18/76] Add auto-batching and error --- text/0060-tasks-api.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 0f05ec1d..fc2ba461 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -403,13 +403,30 @@ Allows users to cancel an `enqueued` or `processing` task. Particularly useful i When the request is successful, Meilisearch returns the HTTP code 202 Accepted. The response's content is the summarized representation of the received asynchronous task. -##### 6.3.3. Errors +##### 6.3.3. Auto-batching + +If the task you’re canceling is part of a batch, **the whole batch is stopped.** Meilisearch automatically creates a new batch once the current one is stopped and the specified tasks are canceled. The canceled tasks will not be part of the new batch. + +This means: +- When the new batch is created, it may contain tasks that have been requested to be canceled in the meantime +- Any progress the batch made before being canceled is lost + +##### 6.3.4. Errors If a user tries canceling a `succeeded`, `failed`, or `canceled` task, it won’t throw an error. Task cancelation is an atomic transaction; all tasks are successfully canceled, or none aren't. - 🔴 Sending a task cancelation without filtering query parameters returns a `[missing_filters](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#missing_filters)` error. - 🔴 If the `type` parameter value is not consistent with one of the task types, an `[invalid_task_type](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalidtasktype)` error is returned. - 🔴 If the `status` parameter value is not consistent with one of the task statuses, an `[invalid_task_status](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalidtaskstatus)` error is returned. +- 🔴 If the `type` parameter value is not consistent with one of the task types, an `[invalid_task_type](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalidtasktype)` error is returned. +- 🔴 If the `status` parameter value is not consistent with one of the task statuses, an `[invalid_task_status](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalidtaskstatus)` error is returned. +- 🔴 Sending values with a different type than `Integer` being separated by `,` for the `uid` parameter returns an `invalid_task_uid` error. +- 🔴 Sending an invalid value for the `beforeEnqueuedAt` parameter returns an `invalid_task_date` error. +- 🔴 Sending an invalid value for the `afterEnqueuedAt` parameter returns an `invalid_task_date` error. +- 🔴 Sending an invalid value for the `beforeStartedAt` parameter returns an `invalid_task_date` error. +- 🔴 Sending an invalid value for the `afterStartedAt` parameter returns an `invalid_task_date` error. +- 🔴 Sending an invalid value for the `beforeFinishedAt` parameter returns an `invalid_task_date` error. +- 🔴 Sending an invalid value for the `afterFinishedAt` parameter returns an `invalid_task_date` error. The auth layer can return the following errors if Meilisearch is secured (a master-key is defined). From 773acc9e2d6918df2111d29d87adaee9bb59a882 Mon Sep 17 00:00:00 2001 From: alallema Date: Wed, 26 Oct 2022 15:54:12 +0200 Subject: [PATCH 19/76] Add new route task/cancel api-key --- text/0085-api-keys.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/0085-api-keys.md b/text/0085-api-keys.md index 3bd8793b..9e16126d 100644 --- a/text/0085-api-keys.md +++ b/text/0085-api-keys.md @@ -312,6 +312,7 @@ Create an API key. | indexes.update | Provides access to `PUT` `/indexes/:authorizedIndexes`. | | indexes.delete | Provides access to `DELETE` `/indexes/:authorizedIndexes`. | | tasks.get | Provides access to `GET` `/tasks`. **⚠️Non-authorized `indexes` are omitted from the response on `/tasks`**. Also add access to `GET` `/indexes/:authorizedIndexes/tasks` routes. | +| tasks.cancel | Provides access to `POST` `/tasks/cancel`. route. | | settings.get | Provides access to `GET` `/indexes/:authorizedIndexes/settings` and `/indexes/:authorizedIndexes/settings/*` routes. | | settings.update | Provides access to `POST / DELETE` `/indexes/:authorizedIndexes/settings` and `/indexes/:authorizedIndexes/settings/*` routes. | | stats.get | Provides access to `GET` `/stats/`. **⚠️Non-authorized `indexes` are omitted from the response on `/stats`**. Also add access to `GET` `/indexes/:authorizedIndexes/stats`. | From 5c7fa20987a7df023ac1b85b70fe65fba4d9f97e Mon Sep 17 00:00:00 2001 From: alallema Date: Wed, 26 Oct 2022 16:17:45 +0200 Subject: [PATCH 20/76] Add global task note --- text/0060-tasks-api.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index fc2ba461..554c574c 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -21,7 +21,7 @@ As writing is asynchronous for most of Meilisearch's operations, this API allows | field | type | description | |------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | uid | integer | Unique sequential identifier | -| indexUid | string | Unique index identifier. This field is `null` when the task type is `dumpCreation`. | +| indexUid | string | Unique index identifier. This field is `null` when the task is a global task. | | status | string | Status of the task. Possible values are `enqueued`, `processing`, `succeeded`, `failed`, `canceled` | | type | string | Type of the task. Possible values are `indexCreation`, `indexUpdate`, `indexDeletion`, `documentAdditionOrUpdate`, `documentDeletion`, `settingsUpdate`, `dumpCreation`, `taskCancelation` | | canceledBy | integer | Unique identifier of the `taskCancelation` task that cancelled the given task. | @@ -34,14 +34,24 @@ As writing is asynchronous for most of Meilisearch's operations, this API allows > 💡 The order of the fields must be returned in this order. +###### Global task + +Some specific tasks are not associated with any particular index and apply to all. + +The fully qualified and summarized task objects linked to this kind of task display a `null` `indexUid` field. + +List of global tasks by `type`: +- `dumpCreation` +- `taskCancelation` + ##### Summarized `task` Object for `202 Accepted` | field | type | description | |------------|---------|---------------------------------| | taskUid | integer | Unique sequential identifier | -| indexUid | string | Unique index identifier. This field is `null` when the task type is `dumpCreation`. | +| indexUid | string | Unique index identifier. This field is `null` when the task is a global task | | status | string | Status of the task. Value is `enqueued` | -| type | string | Type of the task. | +| type | string | Type of the task | | enqueuedAt | string | Represent the date and time as `RFC 3339` format when the task has been enqueued | @@ -131,10 +141,6 @@ As writing is asynchronous for most of Meilisearch's operations, this API allows | ----- | ------------ | | dumpUid | The generated uid of the dump | -Since the creation of a dump is not a task associated with a particular index, it is only present on the `GET` - `/tasks` and `GET` - `tasks/:task_uid` endpoints. - -Fully qualified and summarized task objects related to a dump creation display a `null` `indexUid` field. - ##### taskCancelation | Name | Description | From de5388d53fbb5e0d053cdae3df4989e3b8ab93cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Thu, 27 Oct 2022 12:08:37 +0200 Subject: [PATCH 21/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 554c574c..66133809 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -21,7 +21,7 @@ As writing is asynchronous for most of Meilisearch's operations, this API allows | field | type | description | |------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | uid | integer | Unique sequential identifier | -| indexUid | string | Unique index identifier. This field is `null` when the task is a global task. | +| indexUid | string | Unique index identifier. This field is `null` when the task is a [global task](). | | status | string | Status of the task. Possible values are `enqueued`, `processing`, `succeeded`, `failed`, `canceled` | | type | string | Type of the task. Possible values are `indexCreation`, `indexUpdate`, `indexDeletion`, `documentAdditionOrUpdate`, `documentDeletion`, `settingsUpdate`, `dumpCreation`, `taskCancelation` | | canceledBy | integer | Unique identifier of the `taskCancelation` task that cancelled the given task. | From a181465bcb9d6d7a313e067a1088a592d41ec0d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Thu, 27 Oct 2022 12:08:49 +0200 Subject: [PATCH 22/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 66133809..23e1963a 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -24,7 +24,7 @@ As writing is asynchronous for most of Meilisearch's operations, this API allows | indexUid | string | Unique index identifier. This field is `null` when the task is a [global task](). | | status | string | Status of the task. Possible values are `enqueued`, `processing`, `succeeded`, `failed`, `canceled` | | type | string | Type of the task. Possible values are `indexCreation`, `indexUpdate`, `indexDeletion`, `documentAdditionOrUpdate`, `documentDeletion`, `settingsUpdate`, `dumpCreation`, `taskCancelation` | -| canceledBy | integer | Unique identifier of the `taskCancelation` task that cancelled the given task. | +| canceledBy | integer | Unique identifier of the `taskCancelation` task that canceled the given task. | | details | object | Details information for a task payload. See Task Details part. | | error | object | Error object containing error details and context when a task has a `failed` status. See [0061-error-format-and-definitions.md](0061-error-format-and-definitions.md) | | duration | string | Total elapsed time the engine was in processing state expressed as an `ISO-8601` duration format. Times below the second can be expressed with the `.` notation, e.g., `PT0.5S` to express `500ms`. Default is set to `null`. | From 6ade97395a6a35a6881bbfa4930c264cf50a955e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Thu, 27 Oct 2022 12:09:21 +0200 Subject: [PATCH 23/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 23e1963a..5f08f9ed 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -38,7 +38,7 @@ As writing is asynchronous for most of Meilisearch's operations, this API allows Some specific tasks are not associated with any particular index and apply to all. -The fully qualified and summarized task objects linked to this kind of task display a `null` `indexUid` field. +The fully qualified and summarized task objects linked to this kind of task display a `null` value for the `indexUid` field. List of global tasks by `type`: - `dumpCreation` From fc5386f52c952e8f84b917cf94fec1dffbb56a73 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Thu, 27 Oct 2022 12:09:29 +0200 Subject: [PATCH 24/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 5f08f9ed..6b88c457 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -49,7 +49,7 @@ List of global tasks by `type`: | field | type | description | |------------|---------|---------------------------------| | taskUid | integer | Unique sequential identifier | -| indexUid | string | Unique index identifier. This field is `null` when the task is a global task | +| indexUid | string | Unique index identifier. This field is `null` when the task is a [global task]() | | status | string | Status of the task. Value is `enqueued` | | type | string | Type of the task | | enqueuedAt | string | Represent the date and time as `RFC 3339` format when the task has been enqueued | From b9fcc7545234bd9cfb0bcaf81efabd4c2760b44b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Thu, 27 Oct 2022 12:09:47 +0200 Subject: [PATCH 25/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 6b88c457..b73101ac 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -145,7 +145,7 @@ List of global tasks by `type`: | Name | Description | | --- | --- | -| matchedTasks | The number of tasks that can be canceled based on the request. If the API key doesn’t have access to any of the indexes specified in the request, those tasks will not be included in matchedTasks. | +| matchedTasks | The number of tasks that can be canceled based on the request. If the API key doesn’t have access to any of the indexes specified in the request, those tasks will not be included in `matchedTasks`. | | canceledTasks | The number of tasks successfully canceled. If the task fails, this will be 0. | | originalQuery | The filter query used in the /tasks/cancel request. | From fcbc34429456abe2fae1f397519406815bfae6ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Thu, 27 Oct 2022 12:09:59 +0200 Subject: [PATCH 26/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index b73101ac..c0f7905c 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -624,7 +624,7 @@ The `/tasks` and `/tasks/cancel` endpoints are filterable by `uid`, `indexUid`, | beforeEnqueuedAt | string | No | Permits to filter tasks based on the time before they are queued. By default, when `beforeEnqueuedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | | afterEnqueuedAt | string | No | Permits to filter tasks based on the time after they are queued. By default, when `afterEnqueuedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | | beforeStartedAt | string | No | Permits to filter tasks by the time before they were started. By default, when `beforeStartedAt` or `afterStartedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | -| afterStartedAt | string | No | Permits to filter tasks by the time after they were started. By default, when `beforeStartedAt` or `afterStartedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | +| afterStartedAt | string | No | Filter tasks based on their startedAt time. Retrieve tasks started after the given filter value. | | beforeFinishedAt | string | No | Permits to filter tasks by the time before they were finished. By default, when `beforeFinishedAt` or `afterFinishedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | | afterFinishedAt | string | No | Permits to filter tasks by the time after they were finished. By default, when `beforeFinishedAt` or `afterFinishedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | From 00ffee11be11b667b60793d34758f2855321d4fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Thu, 27 Oct 2022 12:10:06 +0200 Subject: [PATCH 27/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index c0f7905c..82b17d7f 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -625,7 +625,7 @@ The `/tasks` and `/tasks/cancel` endpoints are filterable by `uid`, `indexUid`, | afterEnqueuedAt | string | No | Permits to filter tasks based on the time after they are queued. By default, when `afterEnqueuedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | | beforeStartedAt | string | No | Permits to filter tasks by the time before they were started. By default, when `beforeStartedAt` or `afterStartedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | | afterStartedAt | string | No | Filter tasks based on their startedAt time. Retrieve tasks started after the given filter value. | -| beforeFinishedAt | string | No | Permits to filter tasks by the time before they were finished. By default, when `beforeFinishedAt` or `afterFinishedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | +| beforeFinishedAt | string | No | Filter tasks based on their finishedAt time. Retrieve tasks finished before the given filter value. | | afterFinishedAt | string | No | Permits to filter tasks by the time after they were finished. By default, when `beforeFinishedAt` or `afterFinishedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | ##### 11.2. Usages examples From 7bdac55563e29e46e6878329bda9909bf03a2506 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Thu, 27 Oct 2022 12:10:44 +0200 Subject: [PATCH 28/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 82b17d7f..261f4e5e 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -626,7 +626,7 @@ The `/tasks` and `/tasks/cancel` endpoints are filterable by `uid`, `indexUid`, | beforeStartedAt | string | No | Permits to filter tasks by the time before they were started. By default, when `beforeStartedAt` or `afterStartedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | | afterStartedAt | string | No | Filter tasks based on their startedAt time. Retrieve tasks started after the given filter value. | | beforeFinishedAt | string | No | Filter tasks based on their finishedAt time. Retrieve tasks finished before the given filter value. | -| afterFinishedAt | string | No | Permits to filter tasks by the time after they were finished. By default, when `beforeFinishedAt` or `afterFinishedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | +| afterFinishedAt | string | No | Filter tasks based on their finishedAt time. Retrieve tasks finished after the given filter value. | ##### 11.2. Usages examples From 817ad825632cb6f362acc44d446701f56113a43b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Thu, 27 Oct 2022 12:11:15 +0200 Subject: [PATCH 29/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 261f4e5e..c282e838 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -146,7 +146,7 @@ List of global tasks by `type`: | Name | Description | | --- | --- | | matchedTasks | The number of tasks that can be canceled based on the request. If the API key doesn’t have access to any of the indexes specified in the request, those tasks will not be included in `matchedTasks`. | -| canceledTasks | The number of tasks successfully canceled. If the task fails, this will be 0. | +| canceledTasks | The number of tasks successfully canceled. If the task fails, this will be `0`. | | originalQuery | The filter query used in the /tasks/cancel request. | #### 5. Examples From 1ddb80230b1f64ec1069141f50a470fb10269907 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Thu, 27 Oct 2022 12:11:36 +0200 Subject: [PATCH 30/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index c282e838..20f6b071 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -147,7 +147,7 @@ List of global tasks by `type`: | --- | --- | | matchedTasks | The number of tasks that can be canceled based on the request. If the API key doesn’t have access to any of the indexes specified in the request, those tasks will not be included in `matchedTasks`. | | canceledTasks | The number of tasks successfully canceled. If the task fails, this will be `0`. | -| originalQuery | The filter query used in the /tasks/cancel request. | +| originalQuery | The extracted URL query parameters used in the originating task cancelation request. | #### 5. Examples From 0d7c782b3802fb3691b08675fca140d35c205364 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Thu, 27 Oct 2022 12:12:01 +0200 Subject: [PATCH 31/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 20f6b071..203cebbb 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -414,7 +414,7 @@ When the request is successful, Meilisearch returns the HTTP code 202 Accepted. If the task you’re canceling is part of a batch, **the whole batch is stopped.** Meilisearch automatically creates a new batch once the current one is stopped and the specified tasks are canceled. The canceled tasks will not be part of the new batch. This means: -- When the new batch is created, it may contain tasks that have been requested to be canceled in the meantime +- When the new batch is created, it may contain tasks that have been enqueued between the batch cancelation and recreation. - Any progress the batch made before being canceled is lost ##### 6.3.4. Errors From b38fffe80a332cb6b1ffed081c487d96cfde2115 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Thu, 27 Oct 2022 12:12:17 +0200 Subject: [PATCH 32/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 203cebbb..bc781a10 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -415,7 +415,7 @@ If the task you’re canceling is part of a batch, **the whole batch is stopped. This means: - When the new batch is created, it may contain tasks that have been enqueued between the batch cancelation and recreation. -- Any progress the batch made before being canceled is lost +- Any progress the batch made before being canceled is lost. ##### 6.3.4. Errors From f766bc5dfbdad4ea5ff16a6e6b262d4a9cbd6dcb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Thu, 27 Oct 2022 12:12:44 +0200 Subject: [PATCH 33/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index bc781a10..309b1750 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -422,7 +422,7 @@ This means: If a user tries canceling a `succeeded`, `failed`, or `canceled` task, it won’t throw an error. Task cancelation is an atomic transaction; all tasks are successfully canceled, or none aren't. - 🔴 Sending a task cancelation without filtering query parameters returns a `[missing_filters](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#missing_filters)` error. -- 🔴 If the `type` parameter value is not consistent with one of the task types, an `[invalid_task_type](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalidtasktype)` error is returned. +- 🔴 If the `type` parameter value is not consistent with one of the task types, an `[invalid_task_type](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_type)` error is returned. - 🔴 If the `status` parameter value is not consistent with one of the task statuses, an `[invalid_task_status](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalidtaskstatus)` error is returned. - 🔴 If the `type` parameter value is not consistent with one of the task types, an `[invalid_task_type](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalidtasktype)` error is returned. - 🔴 If the `status` parameter value is not consistent with one of the task statuses, an `[invalid_task_status](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalidtaskstatus)` error is returned. From a613c431c59987f277bc2cf9f620903fe62d883b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Thu, 27 Oct 2022 12:12:57 +0200 Subject: [PATCH 34/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 309b1750..bf0a946f 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -423,7 +423,7 @@ If a user tries canceling a `succeeded`, `failed`, or `canceled` task, it won’ - 🔴 Sending a task cancelation without filtering query parameters returns a `[missing_filters](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#missing_filters)` error. - 🔴 If the `type` parameter value is not consistent with one of the task types, an `[invalid_task_type](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_type)` error is returned. -- 🔴 If the `status` parameter value is not consistent with one of the task statuses, an `[invalid_task_status](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalidtaskstatus)` error is returned. +- 🔴 If the `status` parameter value is not consistent with one of the task statuses, an `[invalid_task_status](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_status)` error is returned. - 🔴 If the `type` parameter value is not consistent with one of the task types, an `[invalid_task_type](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalidtasktype)` error is returned. - 🔴 If the `status` parameter value is not consistent with one of the task statuses, an `[invalid_task_status](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalidtaskstatus)` error is returned. - 🔴 Sending values with a different type than `Integer` being separated by `,` for the `uid` parameter returns an `invalid_task_uid` error. From 69c64518a702d88065d2d186505f4dd04745dbe4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Thu, 27 Oct 2022 12:14:05 +0200 Subject: [PATCH 35/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index bf0a946f..cc08df1a 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -611,7 +611,7 @@ This part demonstrates keyset paging in action on `/tasks`. The items `uid` rema #### 11. Filtering task resources -The `/tasks` and `/tasks/cancel` endpoints are filterable by `uid`, `indexUid`, `type`, `status`, `beforeEnqueuedAt`, `afterEnqueuedAt`, `beforeStartedAt`, `afterStartedAt`, `beforeFinishedAt`, `afterFinishedAt` query parameters. +The tasks API endpoints are filterable by `uid`, `indexUid`, `type`, `status`, `beforeEnqueuedAt`, `afterEnqueuedAt`, `beforeStartedAt`, `afterStartedAt`, `beforeFinishedAt`, `afterFinishedAt` query parameters. ##### 11.1 Query parameters definition From f0a86bece1bcf6273d5232b3ba01dfa32044bf43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Thu, 27 Oct 2022 12:16:41 +0200 Subject: [PATCH 36/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index cc08df1a..189542f3 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -618,7 +618,7 @@ The tasks API endpoints are filterable by `uid`, `indexUid`, `type`, `status`, | parameter | type | required | description | |-----------|--------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | uid | integer | No | Permits to filter tasks by their related unique identifier. By default, when `uid` query parameter is not set, all the tasks are concerned. It is possible to specify several uid by separating them with the `,` character. | -| indexUid | string | No | Permits to filter tasks by their related index. By default, when `indexUid` query parameter is not set, the tasks of all the indexes are concerned. It is possible to specify several indexes by separating them with the `,` character. | +| indexUid | string | No | Permits to filter tasks by their related index. By default, when `indexUid` query parameter is not set, the tasks of all the indexes are concerned. It is possible to specify several indexUids by separating them with the `,` character. | | status | string | No | Permits to filter tasks by their status. By default, when `status` query parameter is not set, all task statuses are concerned. It's possible to specify several types by separating them with the `,` character. | | type | string | No | Permits to filter tasks by their related type. By default, when `type` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | | beforeEnqueuedAt | string | No | Permits to filter tasks based on the time before they are queued. By default, when `beforeEnqueuedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | From dedf5b52681ceed37633ad26ce55c13f6c702793 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Thu, 27 Oct 2022 12:17:17 +0200 Subject: [PATCH 37/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 189542f3..63cb40a8 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -619,7 +619,7 @@ The tasks API endpoints are filterable by `uid`, `indexUid`, `type`, `status`, |-----------|--------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | uid | integer | No | Permits to filter tasks by their related unique identifier. By default, when `uid` query parameter is not set, all the tasks are concerned. It is possible to specify several uid by separating them with the `,` character. | | indexUid | string | No | Permits to filter tasks by their related index. By default, when `indexUid` query parameter is not set, the tasks of all the indexes are concerned. It is possible to specify several indexUids by separating them with the `,` character. | -| status | string | No | Permits to filter tasks by their status. By default, when `status` query parameter is not set, all task statuses are concerned. It's possible to specify several types by separating them with the `,` character. | +| status | string | No | Permits to filter tasks by their status. By default, when `status` query parameter is not set, all task statuses are concerned. It's possible to specify several statuses by separating them with the `,` character. | | type | string | No | Permits to filter tasks by their related type. By default, when `type` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | | beforeEnqueuedAt | string | No | Permits to filter tasks based on the time before they are queued. By default, when `beforeEnqueuedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | | afterEnqueuedAt | string | No | Permits to filter tasks based on the time after they are queued. By default, when `afterEnqueuedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | From e7924a7c8ba52e4299216425b42e2944aaec1016 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Thu, 27 Oct 2022 12:18:25 +0200 Subject: [PATCH 38/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 63cb40a8..0f221a97 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -621,7 +621,7 @@ The tasks API endpoints are filterable by `uid`, `indexUid`, `type`, `status`, | indexUid | string | No | Permits to filter tasks by their related index. By default, when `indexUid` query parameter is not set, the tasks of all the indexes are concerned. It is possible to specify several indexUids by separating them with the `,` character. | | status | string | No | Permits to filter tasks by their status. By default, when `status` query parameter is not set, all task statuses are concerned. It's possible to specify several statuses by separating them with the `,` character. | | type | string | No | Permits to filter tasks by their related type. By default, when `type` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | -| beforeEnqueuedAt | string | No | Permits to filter tasks based on the time before they are queued. By default, when `beforeEnqueuedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | +| beforeEnqueuedAt | string | No | Filter tasks based on their enqueuedAt time. Retrieve tasks enqueued before the given filter value. | | afterEnqueuedAt | string | No | Permits to filter tasks based on the time after they are queued. By default, when `afterEnqueuedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | | beforeStartedAt | string | No | Permits to filter tasks by the time before they were started. By default, when `beforeStartedAt` or `afterStartedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | | afterStartedAt | string | No | Filter tasks based on their startedAt time. Retrieve tasks started after the given filter value. | From 1f5f38b285da78457ed45592187e028b75203d45 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Thu, 27 Oct 2022 12:18:48 +0200 Subject: [PATCH 39/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 0f221a97..703fa9a1 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -622,7 +622,7 @@ The tasks API endpoints are filterable by `uid`, `indexUid`, `type`, `status`, | status | string | No | Permits to filter tasks by their status. By default, when `status` query parameter is not set, all task statuses are concerned. It's possible to specify several statuses by separating them with the `,` character. | | type | string | No | Permits to filter tasks by their related type. By default, when `type` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | | beforeEnqueuedAt | string | No | Filter tasks based on their enqueuedAt time. Retrieve tasks enqueued before the given filter value. | -| afterEnqueuedAt | string | No | Permits to filter tasks based on the time after they are queued. By default, when `afterEnqueuedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | +| afterEnqueuedAt | string | No | Filter tasks based on their enqueuedAt time. Retrieve tasks enqueued after the given filter value. | | beforeStartedAt | string | No | Permits to filter tasks by the time before they were started. By default, when `beforeStartedAt` or `afterStartedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | | afterStartedAt | string | No | Filter tasks based on their startedAt time. Retrieve tasks started after the given filter value. | | beforeFinishedAt | string | No | Filter tasks based on their finishedAt time. Retrieve tasks finished before the given filter value. | From d5dc59042a3c55a1669d87f1fdf0c04ff9c07824 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Thu, 27 Oct 2022 12:19:20 +0200 Subject: [PATCH 40/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 703fa9a1..81bd9c01 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -623,7 +623,7 @@ The tasks API endpoints are filterable by `uid`, `indexUid`, `type`, `status`, | type | string | No | Permits to filter tasks by their related type. By default, when `type` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | | beforeEnqueuedAt | string | No | Filter tasks based on their enqueuedAt time. Retrieve tasks enqueued before the given filter value. | | afterEnqueuedAt | string | No | Filter tasks based on their enqueuedAt time. Retrieve tasks enqueued after the given filter value. | -| beforeStartedAt | string | No | Permits to filter tasks by the time before they were started. By default, when `beforeStartedAt` or `afterStartedAt` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | +| beforeStartedAt | string | No | Filter tasks based on their startedAt time. Retrieve tasks started before the given value. | | afterStartedAt | string | No | Filter tasks based on their startedAt time. Retrieve tasks started after the given filter value. | | beforeFinishedAt | string | No | Filter tasks based on their finishedAt time. Retrieve tasks finished before the given filter value. | | afterFinishedAt | string | No | Filter tasks based on their finishedAt time. Retrieve tasks finished after the given filter value. | From cf055af4926cf44936c5ed60326c664e391a472c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Thu, 27 Oct 2022 12:19:42 +0200 Subject: [PATCH 41/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 81bd9c01..ca8d0d5f 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -813,7 +813,7 @@ Users will not be allowed to use this route without any filters on `POST` `/task - Required: False - Default: `*` -`uid` is **case-sensitive**. +`uid` is **case-unsensitive**. ###### 11.3.2. `indexUid` From 7320ce161eb61740cd1f7fbf1a347d6bdaa2b198 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Thu, 27 Oct 2022 12:20:07 +0200 Subject: [PATCH 42/76] Update text/0060-tasks-api.md Co-authored-by: Guillaume Mourier --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index ca8d0d5f..5031dcf1 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -809,7 +809,7 @@ Users will not be allowed to use this route without any filters on `POST` `/task ###### 11.3.1. `uid` -- Type: Integer +- Type: String - Required: False - Default: `*` From d87cc96790513da7dc9c1e2ef405a9075c37cc32 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Am=C3=A9lie?= Date: Thu, 27 Oct 2022 12:20:32 +0200 Subject: [PATCH 43/76] Update text/0061-error-format-and-definitions.md Co-authored-by: Guillaume Mourier --- text/0061-error-format-and-definitions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0061-error-format-and-definitions.md b/text/0061-error-format-and-definitions.md index 534cccc1..859ffc46 100644 --- a/text/0061-error-format-and-definitions.md +++ b/text/0061-error-format-and-definitions.md @@ -1100,7 +1100,7 @@ HTTP Code: `400 Bad Request` ```json { - "message": "Query parameters to filter the tasks to cancel are missing. Available query parameters are: `uid`, `indexUid`, `status`, `type`, `beforeEnqueuedAt`, `afterEnqueudAt`, `beforeStartedAt`, afterStartedAt`", + "message": "Query parameters to filter the tasks to cancel are missing. Available query parameters are: `uid`, `indexUid`, `status`, `type`, `beforeEnqueuedAt`, `afterEnqueudAt`, `beforeStartedAt`, afterStartedAt`, `beforeFinishedAt`, `afterFinishedAt`.", "code": "missing_filters", "type": "invalid_request", "link": "https://docs.meilisearch.com/errors#missing_filters" From 4f5502f886878598ac76ab6cd776e04f407c9990 Mon Sep 17 00:00:00 2001 From: alallema Date: Thu, 27 Oct 2022 12:29:09 +0200 Subject: [PATCH 44/76] Modification due to review --- text/0060-tasks-api.md | 180 ++++++++++++++++++++--------------------- 1 file changed, 90 insertions(+), 90 deletions(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 5031dcf1..c503674d 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -281,6 +281,8 @@ e.g. A fully qualified `task` object in a `canceled` state. "startedAt": "2021-08-10T14:29:18.000000Z", "finishedAt": "2021-08-10T14:29:19.000000Z" } +``` + e.g. A summarized `task` object in a `202 Accepted` HTTP response returned at index creation. ```json @@ -421,11 +423,9 @@ This means: If a user tries canceling a `succeeded`, `failed`, or `canceled` task, it won’t throw an error. Task cancelation is an atomic transaction; all tasks are successfully canceled, or none aren't. -- 🔴 Sending a task cancelation without filtering query parameters returns a `[missing_filters](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#missing_filters)` error. +- 🔴 Sending a task cancelation without filtering query parameters returns a `[missing_task_filter](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#missing_task_filter)` error. - 🔴 If the `type` parameter value is not consistent with one of the task types, an `[invalid_task_type](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_type)` error is returned. - 🔴 If the `status` parameter value is not consistent with one of the task statuses, an `[invalid_task_status](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_status)` error is returned. -- 🔴 If the `type` parameter value is not consistent with one of the task types, an `[invalid_task_type](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalidtasktype)` error is returned. -- 🔴 If the `status` parameter value is not consistent with one of the task statuses, an `[invalid_task_status](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalidtaskstatus)` error is returned. - 🔴 Sending values with a different type than `Integer` being separated by `,` for the `uid` parameter returns an `invalid_task_uid` error. - 🔴 Sending an invalid value for the `beforeEnqueuedAt` parameter returns an `invalid_task_date` error. - 🔴 Sending an invalid value for the `afterEnqueuedAt` parameter returns an `invalid_task_date` error. @@ -628,7 +628,93 @@ The tasks API endpoints are filterable by `uid`, `indexUid`, `type`, `status`, | beforeFinishedAt | string | No | Filter tasks based on their finishedAt time. Retrieve tasks finished before the given filter value. | | afterFinishedAt | string | No | Filter tasks based on their finishedAt time. Retrieve tasks finished after the given filter value. | -##### 11.2. Usages examples +##### 11.2. Query Parameters Behaviors + +###### 11.2.1. `uid` + +- Type: String +- Required: False +- Default: `*` + +`uid` is **case-unsensitive**. + +###### 11.2.2. `indexUid` + +- Type: String +- Required: False +- Default: `*` + +`indexUid` is **case-sensitive**. + +###### 11.2.3. `status` + +- Type: String +- Required: False +- Default: `*` + +- 🔴 If the `status` parameter value is not consistent with one of the task statuses, an [`invalid_task_status`](0061-error-format-and-definitions.md#invalidtaskstatus) error is returned. + +###### 11.2.4. `type` + +- Type: String +- Required: False +- Default: `*` + +`type` is **case-insensitive**. + +- 🔴 If the `type` parameter value is not consistent with one of the task types, an [`invalid_task_type`](0061-error-format-and-definitions.md#invalidtasktype) error is returned. + +###### 11.2.5. `beforeEnqueuedAt` and `afterEnqueuedAt` + +- Type: String +- Required: False +- Default: `*` + +The filter accepts the RFC 3339 format. The following syntaxes are valid: + +- `Y-M-D` +- `Y-M-DTH:M:SZ` +- `Y-M-DTH:M:S+01:00` + +- 🔴 The date filters are exclusive. You can cancel tasks before or after a specified date, meaning it will not be included. + +###### 11.2.6. `beforeStartedAt` and `afterStartedAt` + +- Type: String +- Required: False +- Default: `*` + +The filter accepts the RFC 3339 format. The following syntaxes are valid: + +- `Y-M-D` +- `Y-M-DTH:M:SZ` +- `Y-M-DTH:M:S+01:00` + +- 🔴 The date filters are exclusive. You can cancel tasks before or after a specified date, meaning it will not be included. + +###### 11.2.7. `beforeFinishedAt` and `afterFinishedAt` + +- Type: String +- Required: False +- Default: `*` + +The filter accepts the RFC 3339 format. The following syntaxes are valid: + +- `Y-M-D` +- `Y-M-DTH:M:SZ` +- `Y-M-DTH:M:S+01:00` + +- 🔴 The date filters are exclusive. You can cancel tasks before or after a specified date, meaning it will not be included. + +###### 11.2.8. Select multiple values for the same filter + +It is possible to specify multiple values for a filter using the `,` character. + +For example, to select the `enqueued` and `processing` tasks of the `movies` and `movie_reviews` indexes, it is possible to express it like this: `/tasks?indexUid=movies,movie_reviews&status=enqueued,processing` + +--- + +##### 11.3. Usages examples This part demonstrates filtering on `/tasks`. @@ -661,8 +747,6 @@ This part demonstrates filtering on `/tasks`. } ``` -Users will not be allowed to use this route without any filters on `POST` `/tasks/cancel`, as it may result in canceling everything by mistake. If the request contains no filters, the user will get an error asking them to be more specific. - **Filter `tasks` that have a `failed` `status`** `GET` - `/tasks?status=failed` @@ -805,90 +889,6 @@ Users will not be allowed to use this route without any filters on `POST` `/task --- -##### 11.3. Query Parameters Behaviors - -###### 11.3.1. `uid` - -- Type: String -- Required: False -- Default: `*` - -`uid` is **case-unsensitive**. - -###### 11.3.2. `indexUid` - -- Type: String -- Required: False -- Default: `*` - -`indexUid` is **case-sensitive**. - -###### 11.3.3. `status` - -- Type: String -- Required: False -- Default: `*` - -- 🔴 If the `status` parameter value is not consistent with one of the task statuses, an [`invalid_task_status`](0061-error-format-and-definitions.md#invalidtaskstatus) error is returned. - -###### 11.3.4. `type` - -- Type: String -- Required: False -- Default: `*` - -`type` is **case-insensitive**. - -- 🔴 If the `type` parameter value is not consistent with one of the task types, an [`invalid_task_type`](0061-error-format-and-definitions.md#invalidtasktype) error is returned. - -###### 11.3.5. `beforeEnqueuedAt` and `afterEnqueuedAt` - -- Type: String -- Required: False -- Default: `*` - -The filter accepts the RFC 3339 format. The following syntaxes are valid: - -- `Y-M-D` -- `Y-M-DTH:M:SZ` -- `Y-M-DTH:M:S+01:00` - -- 🔴 The date filters are exclusive. You can cancel tasks before or after a specified date, meaning it will not be included. - -###### 11.3.6. `beforeStartedAt` and `afterStartedAt` - -- Type: String -- Required: False -- Default: `*` - -The filter accepts the RFC 3339 format. The following syntaxes are valid: - -- `Y-M-D` -- `Y-M-DTH:M:SZ` -- `Y-M-DTH:M:S+01:00` - -- 🔴 The date filters are exclusive. You can cancel tasks before or after a specified date, meaning it will not be included. - -###### 11.3.7. `beforeFinishedAt` and `afterFinishedAt` - -- Type: String -- Required: False -- Default: `*` - -The filter accepts the RFC 3339 format. The following syntaxes are valid: - -- `Y-M-D` -- `Y-M-DTH:M:SZ` -- `Y-M-DTH:M:S+01:00` - -- 🔴 The date filters are exclusive. You can cancel tasks before or after a specified date, meaning it will not be included. - -###### 11.3.8. Select multiple values for the same filter - -It is possible to specify multiple values for a filter using the `,` character. - -For example, to select the `enqueued` and `processing` tasks of the `movies` and `movie_reviews` indexes, it is possible to express it like this: `/tasks?indexUid=movies,movie_reviews&status=enqueued,processing` - ##### 11.4. Empty `results` If no results match the filters. A response is returned with an empty `results` array. From 809ccb50d09598adf699ed52a79909598baed29a Mon Sep 17 00:00:00 2001 From: alallema Date: Thu, 27 Oct 2022 12:50:07 +0200 Subject: [PATCH 45/76] Modification due to review --- text/0060-tasks-api.md | 26 +++---- text/0061-error-format-and-definitions.md | 92 +++++++++++++++++------ 2 files changed, 82 insertions(+), 36 deletions(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index c503674d..e169e1d3 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -20,8 +20,8 @@ As writing is asynchronous for most of Meilisearch's operations, this API allows | field | type | description | |------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| uid | integer | Unique sequential identifier | -| indexUid | string | Unique index identifier. This field is `null` when the task is a [global task](). | +| uid | string | Unique sequential identifier | +| indexUid | string | Unique index identifier. This field is `null` when the task is a [global task](# global-task). | | status | string | Status of the task. Possible values are `enqueued`, `processing`, `succeeded`, `failed`, `canceled` | | type | string | Type of the task. Possible values are `indexCreation`, `indexUpdate`, `indexDeletion`, `documentAdditionOrUpdate`, `documentDeletion`, `settingsUpdate`, `dumpCreation`, `taskCancelation` | | canceledBy | integer | Unique identifier of the `taskCancelation` task that canceled the given task. | @@ -49,7 +49,7 @@ List of global tasks by `type`: | field | type | description | |------------|---------|---------------------------------| | taskUid | integer | Unique sequential identifier | -| indexUid | string | Unique index identifier. This field is `null` when the task is a [global task]() | +| indexUid | string | Unique index identifier. This field is `null` when the task is a [global task](# global-task) | | status | string | Status of the task. Value is `enqueued` | | type | string | Type of the task | | enqueuedAt | string | Represent the date and time as `RFC 3339` format when the task has been enqueued | @@ -426,13 +426,13 @@ If a user tries canceling a `succeeded`, `failed`, or `canceled` task, it won’ - 🔴 Sending a task cancelation without filtering query parameters returns a `[missing_task_filter](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#missing_task_filter)` error. - 🔴 If the `type` parameter value is not consistent with one of the task types, an `[invalid_task_type](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_type)` error is returned. - 🔴 If the `status` parameter value is not consistent with one of the task statuses, an `[invalid_task_status](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_status)` error is returned. -- 🔴 Sending values with a different type than `Integer` being separated by `,` for the `uid` parameter returns an `invalid_task_uid` error. -- 🔴 Sending an invalid value for the `beforeEnqueuedAt` parameter returns an `invalid_task_date` error. -- 🔴 Sending an invalid value for the `afterEnqueuedAt` parameter returns an `invalid_task_date` error. -- 🔴 Sending an invalid value for the `beforeStartedAt` parameter returns an `invalid_task_date` error. -- 🔴 Sending an invalid value for the `afterStartedAt` parameter returns an `invalid_task_date` error. -- 🔴 Sending an invalid value for the `beforeFinishedAt` parameter returns an `invalid_task_date` error. -- 🔴 Sending an invalid value for the `afterFinishedAt` parameter returns an `invalid_task_date` error. +- 🔴 Sending values with a different type than `Integer` being separated by `,` for the `uid` parameter returns an `[invalid_task_uid](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_uid))` error. +- 🔴 Sending an invalid value for the `beforeEnqueuedAt` parameter returns an `[invalid_task_date](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_date)` error. +- 🔴 Sending an invalid value for the `afterEnqueuedAt` parameter returns an `[invalid_task_date](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_date)` error. +- 🔴 Sending an invalid value for the `beforeStartedAt` parameter returns an `[invalid_task_date](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_date)` error. +- 🔴 Sending an invalid value for the `afterStartedAt` parameter returns an `[invalid_task_date](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_date)` error. +- 🔴 Sending an invalid value for the `beforeFinishedAt` parameter returns an `[invalid_task_date](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_date)` error. +- 🔴 Sending an invalid value for the `afterFinishedAt` parameter returns an `[invalid_task_date](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_date)` error. The auth layer can return the following errors if Meilisearch is secured (a master-key is defined). @@ -617,15 +617,15 @@ The tasks API endpoints are filterable by `uid`, `indexUid`, `type`, `status`, | parameter | type | required | description | |-----------|--------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| uid | integer | No | Permits to filter tasks by their related unique identifier. By default, when `uid` query parameter is not set, all the tasks are concerned. It is possible to specify several uid by separating them with the `,` character. | +| uid | string | No | Permits to filter tasks by their related unique identifier. By default, when `uid` query parameter is not set, all the tasks are concerned. It is possible to specify several uid by separating them with the `,` character. | | indexUid | string | No | Permits to filter tasks by their related index. By default, when `indexUid` query parameter is not set, the tasks of all the indexes are concerned. It is possible to specify several indexUids by separating them with the `,` character. | | status | string | No | Permits to filter tasks by their status. By default, when `status` query parameter is not set, all task statuses are concerned. It's possible to specify several statuses by separating them with the `,` character. | | type | string | No | Permits to filter tasks by their related type. By default, when `type` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | -| beforeEnqueuedAt | string | No | Filter tasks based on their enqueuedAt time. Retrieve tasks enqueued before the given filter value. | +| beforeEnqueuedAt | string | No | Filter tasks based on their enqueuedAt time. Retrieve tasks enqueued before the given filter value. | | afterEnqueuedAt | string | No | Filter tasks based on their enqueuedAt time. Retrieve tasks enqueued after the given filter value. | | beforeStartedAt | string | No | Filter tasks based on their startedAt time. Retrieve tasks started before the given value. | | afterStartedAt | string | No | Filter tasks based on their startedAt time. Retrieve tasks started after the given filter value. | -| beforeFinishedAt | string | No | Filter tasks based on their finishedAt time. Retrieve tasks finished before the given filter value. | +| beforeFinishedAt | string | No | Filter tasks based on their finishedAt time. Retrieve tasks finished before the given filter value. | | afterFinishedAt | string | No | Filter tasks based on their finishedAt time. Retrieve tasks finished after the given filter value. | ##### 11.2. Query Parameters Behaviors diff --git a/text/0061-error-format-and-definitions.md b/text/0061-error-format-and-definitions.md index 859ffc46..08da3bde 100644 --- a/text/0061-error-format-and-definitions.md +++ b/text/0061-error-format-and-definitions.md @@ -912,6 +912,75 @@ HTTP Code: `404 Not Found` --- +## missing_task_filter + +`Synchronous` + +### Context + +This error occurs when the request does not contain any filters and they are mandatory. + +### Error Definition + +HTTP Code: `400 Bad Request` + +```json +{ + "message": "The required query parameters to cancel tasks are missing. Available query parameters are: `uid`, `indexUid`, `status`, `type`, `beforeEnqueuedAt`, `afterEnqueudAt`, `beforeStartedAt`, afterStartedAt`.", + "code": "missing_task_filter", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#missing_task_filter" +} +``` + +--- + +## invalid_task_uid + +`Synchronous` + +### Context + +This error occurs when the request does not contain any filters and they are mandatory. + +### Error Definition + +HTTP Code: `400 Bad Request` + +```json +{ + "message": "", + "code": "invalid_task_uid", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#invalid_task_uid" +} +``` + +--- + +## invalid_task_date + +`Synchronous` + +### Context + +This error occurs when the request does not contain any filters and they are mandatory. + +### Error Definition + +HTTP Code: `400 Bad Request` + +```json +{ + "message": "", + "code": "invalid_task_date", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#invalid_task_date" +} +``` + +--- + ## invalid_task_status ### Context @@ -1086,29 +1155,6 @@ HTTP Code: `400 Bad Request` --- -## missing_filters - -`Synchronous` - -### Context - -This error occurs when the request does not contain any filters and they are mandatory. - -### Error Definition - -HTTP Code: `400 Bad Request` - -```json -{ - "message": "Query parameters to filter the tasks to cancel are missing. Available query parameters are: `uid`, `indexUid`, `status`, `type`, `beforeEnqueuedAt`, `afterEnqueudAt`, `beforeStartedAt`, afterStartedAt`, `beforeFinishedAt`, `afterFinishedAt`.", - "code": "missing_filters", - "type": "invalid_request", - "link": "https://docs.meilisearch.com/errors#missing_filters" -} -``` - ---- - # internal type ## internal From 3be2aeba293efaa063aceb51605ab483256ed72a Mon Sep 17 00:00:00 2001 From: alallema Date: Thu, 27 Oct 2022 13:00:37 +0200 Subject: [PATCH 46/76] Modification due to review --- text/0060-tasks-api.md | 34 ++++++++++++++-------------------- 1 file changed, 14 insertions(+), 20 deletions(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index e169e1d3..6d48417f 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -638,6 +638,9 @@ The tasks API endpoints are filterable by `uid`, `indexUid`, `type`, `status`, `uid` is **case-unsensitive**. +- 🔴 Sending values with a different type than `Integer` being separated by `,` for the `uid` parameter returns an `[invalid_task_uid](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_uid))` error. + + ###### 11.2.2. `indexUid` - Type: String @@ -664,49 +667,40 @@ The tasks API endpoints are filterable by `uid`, `indexUid`, `type`, `status`, - 🔴 If the `type` parameter value is not consistent with one of the task types, an [`invalid_task_type`](0061-error-format-and-definitions.md#invalidtasktype) error is returned. -###### 11.2.5. `beforeEnqueuedAt` and `afterEnqueuedAt` +###### 11.2.5. Date Parameters + +###### 11.2.5.1. `beforeEnqueuedAt` and `afterEnqueuedAt` - Type: String - Required: False - Default: `*` -The filter accepts the RFC 3339 format. The following syntaxes are valid: - -- `Y-M-D` -- `Y-M-DTH:M:SZ` -- `Y-M-DTH:M:S+01:00` - -- 🔴 The date filters are exclusive. You can cancel tasks before or after a specified date, meaning it will not be included. - -###### 11.2.6. `beforeStartedAt` and `afterStartedAt` +###### 11.2.5.2. `beforeStartedAt` and `afterStartedAt` - Type: String - Required: False - Default: `*` -The filter accepts the RFC 3339 format. The following syntaxes are valid: - -- `Y-M-D` -- `Y-M-DTH:M:SZ` -- `Y-M-DTH:M:S+01:00` - -- 🔴 The date filters are exclusive. You can cancel tasks before or after a specified date, meaning it will not be included. - -###### 11.2.7. `beforeFinishedAt` and `afterFinishedAt` +###### 11.2.5.3. `beforeFinishedAt` and `afterFinishedAt` - Type: String - Required: False - Default: `*` +###### 11.2.5.4. Date Format + The filter accepts the RFC 3339 format. The following syntaxes are valid: - `Y-M-D` - `Y-M-DTH:M:SZ` - `Y-M-DTH:M:S+01:00` +###### 11.2.5.5. Date Errors + - 🔴 The date filters are exclusive. You can cancel tasks before or after a specified date, meaning it will not be included. +- 🔴 Sending an invalid value for the date parameter returns an `[invalid_task_date](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_date)` error. -###### 11.2.8. Select multiple values for the same filter +###### 11.2.6. Select multiple values for the same filter It is possible to specify multiple values for a filter using the `,` character. From 0578265fb8a655aed5facdf51dadadc36caf67c9 Mon Sep 17 00:00:00 2001 From: alallema Date: Thu, 27 Oct 2022 13:06:04 +0200 Subject: [PATCH 47/76] Modification due to review --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 6d48417f..04f805ef 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -36,7 +36,7 @@ As writing is asynchronous for most of Meilisearch's operations, this API allows ###### Global task -Some specific tasks are not associated with any particular index and apply to all. +Some specific tasks are not associated with a particular index and apply to all. They are considered global. The fully qualified and summarized task objects linked to this kind of task display a `null` value for the `indexUid` field. From e584dec67121fcedcf8abaf699ac41bbe51759b3 Mon Sep 17 00:00:00 2001 From: alallema Date: Thu, 27 Oct 2022 13:08:05 +0200 Subject: [PATCH 48/76] Fix global task link --- text/0060-tasks-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 04f805ef..bcf4a5ee 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -21,7 +21,7 @@ As writing is asynchronous for most of Meilisearch's operations, this API allows | field | type | description | |------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | uid | string | Unique sequential identifier | -| indexUid | string | Unique index identifier. This field is `null` when the task is a [global task](# global-task). | +| indexUid | string | Unique index identifier. This field is `null` when the task is a [global task](#global-task). | | status | string | Status of the task. Possible values are `enqueued`, `processing`, `succeeded`, `failed`, `canceled` | | type | string | Type of the task. Possible values are `indexCreation`, `indexUpdate`, `indexDeletion`, `documentAdditionOrUpdate`, `documentDeletion`, `settingsUpdate`, `dumpCreation`, `taskCancelation` | | canceledBy | integer | Unique identifier of the `taskCancelation` task that canceled the given task. | @@ -49,7 +49,7 @@ List of global tasks by `type`: | field | type | description | |------------|---------|---------------------------------| | taskUid | integer | Unique sequential identifier | -| indexUid | string | Unique index identifier. This field is `null` when the task is a [global task](# global-task) | +| indexUid | string | Unique index identifier. This field is `null` when the task is a [global task](#global-task) | | status | string | Status of the task. Value is `enqueued` | | type | string | Type of the task | | enqueuedAt | string | Represent the date and time as `RFC 3339` format when the task has been enqueued | From 7d445be606fa2af2351c8018864d28557b33cc99 Mon Sep 17 00:00:00 2001 From: alallema Date: Thu, 27 Oct 2022 13:11:31 +0200 Subject: [PATCH 49/76] Fix format link --- text/0060-tasks-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index bcf4a5ee..3daeef77 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -638,7 +638,7 @@ The tasks API endpoints are filterable by `uid`, `indexUid`, `type`, `status`, `uid` is **case-unsensitive**. -- 🔴 Sending values with a different type than `Integer` being separated by `,` for the `uid` parameter returns an `[invalid_task_uid](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_uid))` error. +- 🔴 Sending values with a different type than `Integer` being separated by `,` for the `uid` parameter returns an [`invalid_task_uid`](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_uid)) error. ###### 11.2.2. `indexUid` @@ -698,7 +698,7 @@ The filter accepts the RFC 3339 format. The following syntaxes are valid: ###### 11.2.5.5. Date Errors - 🔴 The date filters are exclusive. You can cancel tasks before or after a specified date, meaning it will not be included. -- 🔴 Sending an invalid value for the date parameter returns an `[invalid_task_date](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_date)` error. +- 🔴 Sending an invalid value for the date parameter returns an [`invalid_task_date`](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_date) error. ###### 11.2.6. Select multiple values for the same filter From 178c051475d540b900fa6253b51a70f59b742e62 Mon Sep 17 00:00:00 2001 From: alallema Date: Thu, 27 Oct 2022 14:26:08 +0200 Subject: [PATCH 50/76] Add open-api modification --- open-api.yaml | 112 +++++++++++++++++++++- text/0061-error-format-and-definitions.md | 4 +- 2 files changed, 113 insertions(+), 3 deletions(-) diff --git a/open-api.yaml b/open-api.yaml index c688362c..04281d4e 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -313,6 +313,7 @@ components: - indexDeletion - settingsUpdate - dumpCreation + - taskCancelation details: type: object description: Details information of the task payload. @@ -328,7 +329,7 @@ components: description: Number of document ids received for documentDeletion task. deletedDocuments: type: integer - description: 'Number of documents finally deleted for documentDeletion and indexDeletion tasks.' + description: Number of documents finally deleted for documentDeletion and indexDeletion tasks. primaryKey: type: string description: Value for the primaryKey field encountered if any for indexCreation or indexUpdate task. @@ -337,6 +338,15 @@ components: dumpUid: type: string description: Identifier generated for the dump for dumpCreation task. + matchedTasks: + type: integer + description: Number of tasks that match the request. + canceledTasks: + type: integer + description: Number of tasks canceled. + originalQuery: + type: string + description: Original filter query. error: description: Error object containing error details and context when a task has a failed status. $ref: '#/components/schemas/error' @@ -393,6 +403,7 @@ components: - indexDeletion - settingsUpdate - dumpCreation + - taskCancelation enqueuedAt: description: Represent the date and time as a `RFC 3339` format when the task has been enqueued $ref: '#/components/schemas/timestamp' @@ -641,6 +652,7 @@ components: - indexes.update - indexes.delete - tasks.get + - tasks.cancel - settings.get - settings.update - stats.get @@ -734,6 +746,48 @@ components: required: false schema: type: string + taskBeforeEnqueuedAt: + name: beforeEnqueuedAt + in: query + description: Permits to filter tasks based on their enqueuedAt time. Retrieve tasks enqueued before the given filter value. + required: false + schema: + type: string + taskAfterEnqueuedAt: + name: afterEnqueuedAt + in: query + description: Permits to filter tasks based on their enqueuedAt time. Retrieve tasks enqueued before the given filter value. + required: false + schema: + type: string + taskBeforeStartedAt: + name: beforeStartedAt + in: query + description: Permits to filter tasks based on their startedAt time. Retrieve tasks started before the given value. + required: false + schema: + type: string + taskAfterStartedAt: + name: afterStartedAt + in: query + description: Permits to filter tasks based on their startedAt time. Retrieve tasks started before the given value. + required: false + schema: + type: string + taskBeforeFinishedAt: + name: beforeFinishedAt + in: query + description: Permits to filter tasks based on their finishedAt time. Retrieve tasks finished before the given filter value. + required: false + schema: + type: string + taskAfterFinishedAt: + name: afterFinishedAt + in: query + description: Permits to filter tasks based on their finishedAt time. Retrieve tasks finished before the given filter value. + required: false + schema: + type: string primaryKey: name: primaryKey in: query @@ -1013,6 +1067,14 @@ components: status: enqueued type: dumpCreation enqueuedAt: '2021-01-01T09:39:00.000000Z' + 202_taskCancelation: + summary: 202 Accepted taskCancelation response example + value: + taskUid: 0 + indexUid: null + status: enqueued + type: taskCancelation + enqueuedAt: '2021-01-01T09:39:00.000000Z' tags: - name: Indexes description: | @@ -3408,6 +3470,54 @@ paths: parameters: [] security: - apiKey: [] + '/tasks/cancel': + post: + summary: Cancel a task + description: 'Cancel a [task](https://docs.meilisearch.com/learn/advanced/asynchronous_operations.html) ' + tags: + - tasks + responses: + '202': + description: Accepted + content: + application/json: + schema: + $ref: '#/components/schemas/summarizedTask' + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/error' + examples: + Missing Task Filter: + value: + message: 'The required query parameters to cancel tasks are missing. Available query parameters are: `uid`, `indexUid`, `status`, `type`, `beforeEnqueuedAt`, `afterEnqueudAt`, `beforeStartedAt`, afterStartedAt`' + code: missing_task_filter + type: invalid_request + link: 'https://docs.meilisearch.com/errors#missing_task_filter' + Invalid Task Uid: + value: + message: '`uid` is not a valid task uid. Task uid can be an integer or a string containing only numeric characters.' + code: invalid_task_uid + type: invalid_request + link: 'https://docs.meilisearch.com/errors#invalid_task_uid' + '401': + $ref: '#/components/responses/401' + operationId: tasks.cancel + parameters: + - $ref: '#/components/parameters/taskUid' + - $ref: '#/components/parameters/taskIndexUid' + - $ref: '#/components/parameters/taskStatus' + - $ref: '#/components/parameters/taskType' + - $ref: '#/components/parameters/taskBeforeEnqueuedAt' + - $ref: '#/components/parameters/taskAfterEnqueuedAt' + - $ref: '#/components/parameters/taskBeforeStartedAt' + - $ref: '#/components/parameters/taskAfterStartedAt' + - $ref: '#/components/parameters/taskBeforeFinishedAt' + - $ref: '#/components/parameters/taskAfterFinishedAt' + security: + - apiKey: [] parameters: - $ref: '#/components/parameters/taskUid' security: [] diff --git a/text/0061-error-format-and-definitions.md b/text/0061-error-format-and-definitions.md index 08da3bde..98970d99 100644 --- a/text/0061-error-format-and-definitions.md +++ b/text/0061-error-format-and-definitions.md @@ -949,7 +949,7 @@ HTTP Code: `400 Bad Request` ```json { - "message": "", + "message": "`uid` is not a valid task uid. Task uid can be an integer or a string containing only numeric characters.", "code": "invalid_task_uid", "type": "invalid_request", "link": "https://docs.meilisearch.com/errors#invalid_task_uid" @@ -972,7 +972,7 @@ HTTP Code: `400 Bad Request` ```json { - "message": "", + "message": "`beforeEnqueuedAt` field value `:value` is invalid. It should follow the RFC 3339 format to represents a date or datetime in the future or specified as a null value. e.g. 'YYYY-MM-DD' or 'YYYY-MM-DD HH:MM:SS'.", "code": "invalid_task_date", "type": "invalid_request", "link": "https://docs.meilisearch.com/errors#invalid_task_date" From 933ed5b48c0f1cfe060b06695d50f0462a9c5210 Mon Sep 17 00:00:00 2001 From: alallema Date: Thu, 27 Oct 2022 14:29:58 +0200 Subject: [PATCH 51/76] Remove trailing space --- open-api.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/open-api.yaml b/open-api.yaml index 04281d4e..6277874e 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -749,28 +749,28 @@ components: taskBeforeEnqueuedAt: name: beforeEnqueuedAt in: query - description: Permits to filter tasks based on their enqueuedAt time. Retrieve tasks enqueued before the given filter value. + description: Permits to filter tasks based on their enqueuedAt time. Retrieve tasks enqueued before the given filter value. required: false schema: type: string taskAfterEnqueuedAt: name: afterEnqueuedAt in: query - description: Permits to filter tasks based on their enqueuedAt time. Retrieve tasks enqueued before the given filter value. + description: Permits to filter tasks based on their enqueuedAt time. Retrieve tasks enqueued before the given filter value. required: false schema: type: string taskBeforeStartedAt: name: beforeStartedAt in: query - description: Permits to filter tasks based on their startedAt time. Retrieve tasks started before the given value. + description: Permits to filter tasks based on their startedAt time. Retrieve tasks started before the given value. required: false schema: type: string taskAfterStartedAt: name: afterStartedAt in: query - description: Permits to filter tasks based on their startedAt time. Retrieve tasks started before the given value. + description: Permits to filter tasks based on their startedAt time. Retrieve tasks started before the given value. required: false schema: type: string From fa33ffcbf2c1db2d08d9297e8e752271ac2c9043 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Wed, 2 Nov 2022 11:44:29 +0100 Subject: [PATCH 52/76] Add clarification --- text/0060-tasks-api.md | 123 +++++++++++++++++++++++++---------------- 1 file changed, 75 insertions(+), 48 deletions(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 3daeef77..a0f02cf1 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -8,7 +8,7 @@ This specification describes the API endpoints for handling asynchronous tasks. ### II. Motivation -As writing is asynchronous for most of Meilisearch's operations, this API allows you to track the progress of asynchronous tasks, know and understand why a task has failed, and cancel specific tasks being enqueued or processing by consulting the history of operations that happened. +As writing is asynchronous for most of Meilisearch's operations, this API allows users to track the progress of asynchronous tasks, know and understand why a task has failed, and cancel specific tasks being enqueued or processing. ### III. Explanation @@ -24,13 +24,13 @@ As writing is asynchronous for most of Meilisearch's operations, this API allows | indexUid | string | Unique index identifier. This field is `null` when the task is a [global task](#global-task). | | status | string | Status of the task. Possible values are `enqueued`, `processing`, `succeeded`, `failed`, `canceled` | | type | string | Type of the task. Possible values are `indexCreation`, `indexUpdate`, `indexDeletion`, `documentAdditionOrUpdate`, `documentDeletion`, `settingsUpdate`, `dumpCreation`, `taskCancelation` | -| canceledBy | integer | Unique identifier of the `taskCancelation` task that canceled the given task. | +| canceledBy | integer | Unique identifier of the `taskCancelation` task that canceled the given task. Default is set to `null`. | | details | object | Details information for a task payload. See Task Details part. | -| error | object | Error object containing error details and context when a task has a `failed` status. See [0061-error-format-and-definitions.md](0061-error-format-and-definitions.md) | +| error | object | Error object containing error details and context when a task has a `failed` status. See [0061-error-format-and-definitions.md](0061-error-format-and-definitions.md). Default is set to `null`. | | duration | string | Total elapsed time the engine was in processing state expressed as an `ISO-8601` duration format. Times below the second can be expressed with the `.` notation, e.g., `PT0.5S` to express `500ms`. Default is set to `null`. | | enqueuedAt | string | Represent the date and time as `RFC 3339` format when the task has been enqueued | -| startedAt | string | Represent the date and time as `RFC 3339` format when the task has been dequeued and started to be processed. Default is set to `null` | -| finishedAt | string | Represent the date and time as `RFC 3339` format when the task has `failed` or `succeeded`. Default is set to `null` | +| startedAt | string | Represent the date and time as `RFC 3339` format when the task has been dequeued and started to be processed. Default is set to `null`. | +| finishedAt | string | Represent the date and time as `RFC 3339` format when the task has a `failed`, `succeeded` or `canceled` status. Default is set to `null`. | > 💡 The order of the fields must be returned in this order. @@ -41,6 +41,7 @@ Some specific tasks are not associated with a particular index and apply to all. The fully qualified and summarized task objects linked to this kind of task display a `null` value for the `indexUid` field. List of global tasks by `type`: + - `dumpCreation` - `taskCancelation` @@ -79,7 +80,7 @@ List of global tasks by `type`: | documentAdditionOrUpdate | | documentDeletion | | settingsUpdate | -| dumpCreation | +| dumpCreation | | taskCancelation | > 👍 Type values follow a `camelCase` naming convention. @@ -91,14 +92,14 @@ List of global tasks by `type`: | name | description | |-------------------|--------------------------------------| | receivedDocuments | Number of documents received. | -| indexedDocuments | Number of documents finally indexed. | +| indexedDocuments | Number of documents finally indexed. `null` when the task status is enqueued or processing. | ##### documentDeletion | name | description | |---------------------|--------------------------------------| | receivedDocumentIds | Number of document ids received. | -| deletedDocuments | Number of documents finally deleted. | +| deletedDocuments | Number of documents finally deleted. `null` when the task status is enqueued or processing. | ##### indexCreation @@ -117,7 +118,7 @@ List of global tasks by `type`: | name | description | |------------------|--------------------------------------------------------------------------------------| -| deletedDocuments | Number of deleted documents. Should be all documents contained in the deleted index. | +| deletedDocuments | Number of deleted documents. Should be all documents contained in the deleted index. `null` when the task status is enqueued or processing. | ##### settingsUpdate @@ -139,14 +140,14 @@ List of global tasks by `type`: | name | description | | ----- | ------------ | -| dumpUid | The generated uid of the dump | +| dumpUid | The generated uid of the dump. `null` when the task status is enqueued or processing. | ##### taskCancelation -| Name | Description | -| --- | --- | -| matchedTasks | The number of tasks that can be canceled based on the request. If the API key doesn’t have access to any of the indexes specified in the request, those tasks will not be included in `matchedTasks`. | -| canceledTasks | The number of tasks successfully canceled. If the task fails, this will be `0`. | +| Name | Description | +| ------------- | ----------- | +| matchedTasks | The number of tasks that can be canceled based on the request. If the API key doesn’t have access to any of the indexes specified in the request via the `indexUid` query parameter, those tasks will not be included in `matchedTasks`. `null` when the task status is enqueued. | +| canceledTasks | The number of tasks successfully canceled. If the task fails, `0` is displayed. `null` when the task status is enqueud or processing. | | originalQuery | The extracted URL query parameters used in the originating task cancelation request. | #### 5. Examples @@ -159,6 +160,7 @@ e.g. A fully qualified `task` object in an `enqueued` state. "indexUid": "movies", "status": "enqueued", "type": "settingsUpdate", + "canceledBy": null, "details": { "rankingRules": [ "typo", @@ -169,6 +171,7 @@ e.g. A fully qualified `task` object in an `enqueued` state. "exactness" ] }, + "error": null, "duration": null, "enqueuedAt": "2021-08-10T14:29:17.000000Z", "startedAt": null, @@ -184,6 +187,7 @@ e.g. A fully qualified `task` object in a `processing` state. "indexUid": "movies", "status": "processing", "type": "settingsUpdate", + "canceledBy": null, "details": { "rankingRules": [ "typo", @@ -194,6 +198,7 @@ e.g. A fully qualified `task` object in a `processing` state. "exactness" ] }, + "error": null, "duration": null, "enqueuedAt": "2021-08-10T14:29:17.000000Z", "startedAt": "2021-08-10T14:29:18.000000Z", @@ -209,6 +214,7 @@ e.g. A fully qualified `task` object in a `succeeded` state. "indexUid": "movies", "status": "succeeded", "type": "settingsUpdate", + "canceledBy": null, "details": { "rankingRules": [ "typo", @@ -219,6 +225,7 @@ e.g. A fully qualified `task` object in a `succeeded` state. "exactness" ] }, + "error": null, "duration": "PT1S", "enqueuedAt": "2021-08-10T14:29:17.000000Z", "startedAt": "2021-08-10T14:29:18.000000Z", @@ -234,6 +241,7 @@ e.g. A fully qualified `task` object in a `failed` state. "indexUid": "movies", "status": "failed", "type": "settingsUpdate", + "canceledBy": null, "details": { "rankingRules": [ "typo", @@ -266,6 +274,7 @@ e.g. A fully qualified `task` object in a `canceled` state. "indexUid": "movies", "status": "canceled", "type": "settingsUpdate", + "canceledBy": 1, "details": { "rankingRules": [ "typo", @@ -276,7 +285,8 @@ e.g. A fully qualified `task` object in a `canceled` state. "exactness" ] }, - "canceledBy": 1, + "error": null, + "duration": "PT1S", "enqueuedAt": "2021-08-10T14:29:17.000000Z", "startedAt": "2021-08-10T14:29:18.000000Z", "finishedAt": "2021-08-10T14:29:19.000000Z" @@ -315,6 +325,12 @@ Allows users to list tasks globally regardless of the indexes involved. Particul "indexUid": "movies_reviews", "status": "enqueued", "type": "documentAdditionOrUpdate", + "canceledBy": null, + "details": { + "receivedDocuments": 100, + "indexedDocuments": null + }, + "error": null, "duration": null, "enqueuedAt": "2021-08-12T10:00:00.000000Z", "startedProcessingAt": null, @@ -324,11 +340,13 @@ Allows users to list tasks globally regardless of the indexes involved. Particul "uid": 0, "indexUid": "movies", "status": "succeeded", - "type": "documentAdditionOrUpdate", + "type": "documentAdditionOrUpdate", + "canceledBy": null, "details": { "receivedDocuments": 100, "indexedDocuments": 100 }, + "error": null, "duration": "PT16S", "enqueuedAt": "2021-08-11T09:25:53.000000Z", "startedAt": "2021-08-11T10:03:00.000000Z", @@ -371,6 +389,11 @@ Allows users to get a detailed `task` object retrieved by the `uid` field regard "indexUid": "movies", "status": "enqueued", "type": "documentAdditionOrUpdate", + "canceledBy": null, + "details": { + ... + }, + "error": null, "duration": null, "enqueuedAt": "2021-08-12T10:00:00.000000Z", "startedAt": null, @@ -424,15 +447,6 @@ This means: If a user tries canceling a `succeeded`, `failed`, or `canceled` task, it won’t throw an error. Task cancelation is an atomic transaction; all tasks are successfully canceled, or none aren't. - 🔴 Sending a task cancelation without filtering query parameters returns a `[missing_task_filter](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#missing_task_filter)` error. -- 🔴 If the `type` parameter value is not consistent with one of the task types, an `[invalid_task_type](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_type)` error is returned. -- 🔴 If the `status` parameter value is not consistent with one of the task statuses, an `[invalid_task_status](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_status)` error is returned. -- 🔴 Sending values with a different type than `Integer` being separated by `,` for the `uid` parameter returns an `[invalid_task_uid](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_uid))` error. -- 🔴 Sending an invalid value for the `beforeEnqueuedAt` parameter returns an `[invalid_task_date](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_date)` error. -- 🔴 Sending an invalid value for the `afterEnqueuedAt` parameter returns an `[invalid_task_date](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_date)` error. -- 🔴 Sending an invalid value for the `beforeStartedAt` parameter returns an `[invalid_task_date](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_date)` error. -- 🔴 Sending an invalid value for the `afterStartedAt` parameter returns an `[invalid_task_date](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_date)` error. -- 🔴 Sending an invalid value for the `beforeFinishedAt` parameter returns an `[invalid_task_date](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_date)` error. -- 🔴 Sending an invalid value for the `afterFinishedAt` parameter returns an `[invalid_task_date](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_date)` error. The auth layer can return the following errors if Meilisearch is secured (a master-key is defined). @@ -617,10 +631,11 @@ The tasks API endpoints are filterable by `uid`, `indexUid`, `type`, `status`, | parameter | type | required | description | |-----------|--------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| uid | string | No | Permits to filter tasks by their related unique identifier. By default, when `uid` query parameter is not set, all the tasks are concerned. It is possible to specify several uid by separating them with the `,` character. | +| uid | integer | No | Permits to filter tasks by their related unique identifier. By default, when `uid` query parameter is not set, all the tasks are concerned. It is possible to specify several uid by separating them with the `,` character. | | indexUid | string | No | Permits to filter tasks by their related index. By default, when `indexUid` query parameter is not set, the tasks of all the indexes are concerned. It is possible to specify several indexUids by separating them with the `,` character. | | status | string | No | Permits to filter tasks by their status. By default, when `status` query parameter is not set, all task statuses are concerned. It's possible to specify several statuses by separating them with the `,` character. | | type | string | No | Permits to filter tasks by their related type. By default, when `type` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | +| canceledBy | integer | No | Permits to filter tasks by the `taskCancelation` uid that canceled them. | | beforeEnqueuedAt | string | No | Filter tasks based on their enqueuedAt time. Retrieve tasks enqueued before the given filter value. | | afterEnqueuedAt | string | No | Filter tasks based on their enqueuedAt time. Retrieve tasks enqueued after the given filter value. | | beforeStartedAt | string | No | Filter tasks based on their startedAt time. Retrieve tasks started before the given value. | @@ -632,14 +647,13 @@ The tasks API endpoints are filterable by `uid`, `indexUid`, `type`, `status`, ###### 11.2.1. `uid` -- Type: String +- Type: Integer - Required: False - Default: `*` `uid` is **case-unsensitive**. -- 🔴 Sending values with a different type than `Integer` being separated by `,` for the `uid` parameter returns an [`invalid_task_uid`](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_uid)) error. - +- 🔴 Sending values with a different type than `Integer` being separated by `,` for the `uid` parameter returns an [`invalid_task_uid`](0061-error-format-and-definitions.md#invalid_task_uid) error. ###### 11.2.2. `indexUid` @@ -655,7 +669,7 @@ The tasks API endpoints are filterable by `uid`, `indexUid`, `type`, `status`, - Required: False - Default: `*` -- 🔴 If the `status` parameter value is not consistent with one of the task statuses, an [`invalid_task_status`](0061-error-format-and-definitions.md#invalidtaskstatus) error is returned. +- 🔴 If the `status` parameter value is not consistent with one of the task statuses, an [`invalid_task_status`](0061-error-format-and-definitions.md#invalid_task_status) error is returned. ###### 11.2.4. `type` @@ -665,42 +679,55 @@ The tasks API endpoints are filterable by `uid`, `indexUid`, `type`, `status`, `type` is **case-insensitive**. -- 🔴 If the `type` parameter value is not consistent with one of the task types, an [`invalid_task_type`](0061-error-format-and-definitions.md#invalidtasktype) error is returned. +- 🔴 If the `type` parameter value is not consistent with one of the task types, an [`invalid_task_type`](0061-error-format-and-definitions.md#invalid_task_type) error is returned. -###### 11.2.5. Date Parameters +###### 11.2.5. `canceledBy` -###### 11.2.5.1. `beforeEnqueuedAt` and `afterEnqueuedAt` - -- Type: String +- Type: Integer - Required: False -- Default: `*` +- Default: `null` -###### 11.2.5.2. `beforeStartedAt` and `afterStartedAt` +`canceledBy` is **case-insensitive**. + +- 🔴Sending a value with a different type than `Integer` for the `canceledBy` parameter returns an [`invalid_task_canceled_by`](0061-error-format-and-definitions.md#invalid_task_canceled_by) error. + +###### 11.2.6. Date Parameters + +Date filters accepts the RFC 3339 format. The following syntaxes are valid: + +- `Y-M-D` +- `Y-M-DTH:M:SZ` +- `Y-M-DTH:M:S+01:00` + +###### 11.2.6.1. `beforeEnqueuedAt` and `afterEnqueuedAt` - Type: String - Required: False - Default: `*` -###### 11.2.5.3. `beforeFinishedAt` and `afterFinishedAt` +- 🔴 The date filters are exclusive. It means the given value will not be included. +- 🔴 Sending an invalid value for the date parameter returns an [`invalid_task_date`](0061-error-format-and-definitions.md#invalid_task_date) error. + +###### 11.2.6.2. `beforeStartedAt` and `afterStartedAt` - Type: String - Required: False - Default: `*` -###### 11.2.5.4. Date Format +- 🔴 The date filters are exclusive. It means the given value will not be included. +- 🔴 Sending an invalid value for the date parameter returns an [`invalid_task_date`](0061-error-format-and-definitions.md#invalid_task_date) error. -The filter accepts the RFC 3339 format. The following syntaxes are valid: +###### 11.2.6.3. `beforeFinishedAt` and `afterFinishedAt` -- `Y-M-D` -- `Y-M-DTH:M:SZ` -- `Y-M-DTH:M:S+01:00` +- Type: String +- Required: False +- Default: `*` -###### 11.2.5.5. Date Errors +- 🔴 The date filters are exclusive. It means the given value will not be included. +- 🔴 Sending an invalid value for the date parameter returns an [`invalid_task_date`](0061-error-format-and-definitions.md#invalid_task_date) error.###### 11.2.6.4. Date Format -- 🔴 The date filters are exclusive. You can cancel tasks before or after a specified date, meaning it will not be included. -- 🔴 Sending an invalid value for the date parameter returns an [`invalid_task_date`](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#invalid_task_date) error. -###### 11.2.6. Select multiple values for the same filter +###### 11.2.7. Select multiple values for the same filter It is possible to specify multiple values for a filter using the `,` character. @@ -898,4 +925,4 @@ n/a - Use Hateoas capability to give direct access to a `task` resource. - Add dedicated task type names modifying a sub-setting. e.g. `SearchableAttributesUpdate`. - Add an archived state for old `tasks`. -- Add the `API Key` identity that added a `task`. \ No newline at end of file +- Add the `API Key` identity that added a `task`. From 1af2b07aa380099ebfe92e0f90efecf2d77c8ba7 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Wed, 2 Nov 2022 12:22:01 +0100 Subject: [PATCH 53/76] Add errors definition --- text/0061-error-format-and-definitions.md | 91 ++++++++++++++++------- 1 file changed, 64 insertions(+), 27 deletions(-) diff --git a/text/0061-error-format-and-definitions.md b/text/0061-error-format-and-definitions.md index 98970d99..21dc0fae 100644 --- a/text/0061-error-format-and-definitions.md +++ b/text/0061-error-format-and-definitions.md @@ -912,36 +912,13 @@ HTTP Code: `404 Not Found` --- -## missing_task_filter - -`Synchronous` - -### Context - -This error occurs when the request does not contain any filters and they are mandatory. - -### Error Definition - -HTTP Code: `400 Bad Request` - -```json -{ - "message": "The required query parameters to cancel tasks are missing. Available query parameters are: `uid`, `indexUid`, `status`, `type`, `beforeEnqueuedAt`, `afterEnqueudAt`, `beforeStartedAt`, afterStartedAt`.", - "code": "missing_task_filter", - "type": "invalid_request", - "link": "https://docs.meilisearch.com/errors#missing_task_filter" -} -``` - ---- - ## invalid_task_uid `Synchronous` ### Context -This error occurs when the request does not contain any filters and they are mandatory. +This error occurs when the `uid` query parameter contains invalid values. ### Error Definition @@ -949,13 +926,15 @@ HTTP Code: `400 Bad Request` ```json { - "message": "`uid` is not a valid task uid. Task uid can be an integer or a string containing only numeric characters.", + "message": "Task uid `:uid` is invalid. It should only contains numeric characters separated by `,` character.", "code": "invalid_task_uid", "type": "invalid_request", "link": "https://docs.meilisearch.com/errors#invalid_task_uid" } ``` +- `:uid` is inferred when the message is generated. + --- ## invalid_task_date @@ -964,7 +943,7 @@ HTTP Code: `400 Bad Request` ### Context -This error occurs when the request does not contain any filters and they are mandatory. +This error occurs when a task date filter contains an invalid value. ### Error Definition @@ -972,17 +951,22 @@ HTTP Code: `400 Bad Request` ```json { - "message": "`beforeEnqueuedAt` field value `:value` is invalid. It should follow the RFC 3339 format to represents a date or datetime in the future or specified as a null value. e.g. 'YYYY-MM-DD' or 'YYYY-MM-DD HH:MM:SS'.", + "message": "Task `:dateFilterName` `:value` is invalid. It should follow the RFC 3339 format. e.g. 'YYYY-MM-DD' or 'YYYY-MM-DD HH:MM:SS'.", "code": "invalid_task_date", "type": "invalid_request", "link": "https://docs.meilisearch.com/errors#invalid_task_date" } ``` +- `:dateFilterName` is inferred when the message is generated. +- `:value` is inferred when the message is generated. + --- ## invalid_task_status +`Synchronous` + ### Context This error happens when a requested task status is invalid. @@ -1007,6 +991,8 @@ HTTP Code: `400 Bad Request` ## invalid_task_type +`Synchronous` + ### Context This error happens when a requested task type is invalid. @@ -1029,6 +1015,57 @@ HTTP Code: `400 Bad Request` --- +## invalid_task_canceled_by + +`Synchronous` + +### Context + +This error happens when the `canceledBy` query parameter contains an invalid value. + +### Error Definition + +HTTP Code: `400 Bad Request` + +```json +{ + "message": "Task canceledBy `:canceledBy` is invalid. It should only contains numeric characters.", + "code": "invalid_task_type", + "type": "invalid_request", + "link":"https://docs.meilisearch.com/errors#invalid_task_canceled_by" +} +``` + +- `:canceledBy` is inferred when the message is generated. + +--- + +## missing_task_filters + +`Synchronous` + +### Context + +This error happens when no query parameters are given when a task cancelation request is send. + +### Error Definition + +HTTP Code: `400 Bad Request` + +```json +{ + "message": "Query parameters to filter the tasks to `:operation` are missing. Available query parameters are: `queryParametersNames`", + "code": "missing_task_filters", + "type": "invalid_request", + "link":"https://docs.meilisearch.com/errors#missing_task_filters" +} +``` + +- `:operation` is inferred when the message is generated. +- `:queryParameterNames` is inferred when the message is generated. + +--- + ## api_key_not_found `Synchronous` From e0671d7430efa9c1f8436481fb46f2cc75c183e2 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Wed, 2 Nov 2022 13:44:58 +0100 Subject: [PATCH 54/76] Update open-api.yml --- open-api.yaml | 57 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 34 insertions(+), 23 deletions(-) diff --git a/open-api.yaml b/open-api.yaml index 6277874e..97c41155 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -279,6 +279,7 @@ components: indexUid: movies status: succeeded type: documentAdditionOrUpdate + canceledBy: null details: receivedDocuments: 10 indexedDocuments: 10 @@ -314,6 +315,9 @@ components: - settingsUpdate - dumpCreation - taskCancelation + canceledBy: + type: integer + description: The uid if of the related taskCancelation if the task has been canceled. details: type: object description: Details information of the task payload. @@ -340,13 +344,13 @@ components: description: Identifier generated for the dump for dumpCreation task. matchedTasks: type: integer - description: Number of tasks that match the request. + description: Number of tasks that match the request for taskCancelation task. canceledTasks: type: integer - description: Number of tasks canceled. + description: Number of tasks canceled for taskCancelation task. originalQuery: type: string - description: Original filter query. + description: Original filter query for taskCancelation task. error: description: Error object containing error details and context when a task has a failed status. $ref: '#/components/schemas/error' @@ -370,6 +374,9 @@ components: - indexUid - status - type + - canceledBy + - details + - error - enqueuedAt - startedAt - finishedAt @@ -721,8 +728,8 @@ components: taskUid: name: taskUid in: path - description: The task unique identifier - required: true + description: Permits to filter tasks by their uid. By default, when `uid` query parameter is not set, all task uids are returned. It's possible to specify several uids by separathing them with the `,` character. + required: false schema: type: number taskIndexUid: @@ -756,7 +763,7 @@ components: taskAfterEnqueuedAt: name: afterEnqueuedAt in: query - description: Permits to filter tasks based on their enqueuedAt time. Retrieve tasks enqueued before the given filter value. + description: Permits to filter tasks based on their enqueuedAt time. Retrieve tasks enqueued after the given filter value. required: false schema: type: string @@ -770,7 +777,7 @@ components: taskAfterStartedAt: name: afterStartedAt in: query - description: Permits to filter tasks based on their startedAt time. Retrieve tasks started before the given value. + description: Permits to filter tasks based on their startedAt time. Retrieve tasks started after the given value. required: false schema: type: string @@ -784,7 +791,14 @@ components: taskAfterFinishedAt: name: afterFinishedAt in: query - description: Permits to filter tasks based on their finishedAt time. Retrieve tasks finished before the given filter value. + description: Permits to filter tasks based on their finishedAt time. Retrieve tasks finished after the given filter value. + required: false + schema: + type: string + taskCanceledBy: + name: canceledBy + in: query + description: Permits to filter tasks that have been canceled by the given taskCancelation uid. required: false schema: type: string @@ -3389,9 +3403,11 @@ paths: indexUid: movies status: succeeded type: documentAdditionOrUpdate + canceledBy: null details: receivedDocuments: 79000 indexedDocuments: 79000 + error: null duration: PT1S enqueuedAt: '2021-01-01T09:39:00.000000Z' startedAt: '2021-01-01T09:39:01.000000Z' @@ -3400,6 +3416,7 @@ paths: indexUid: movies_Review status: failed type: documentAdditionOrUpdate + canceledBy: null details: receivedDocuments: 67493 indexedDocuments: 0 @@ -3419,9 +3436,17 @@ paths: parameters: - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/from' + - $ref: '#/components/parameters/taskUid' - $ref: '#/components/parameters/taskIndexUid' - $ref: '#/components/parameters/taskStatus' - $ref: '#/components/parameters/taskType' + - $ref: '#/components/parameters/taskCanceledBy' + - $ref: '#/components/parameters/taskBeforeEnqueuedAt' + - $ref: '#/components/parameters/taskAfterEnqueuedAt' + - $ref: '#/components/parameters/taskBeforeStartedAt' + - $ref: '#/components/parameters/taskAfterStartedAt' + - $ref: '#/components/parameters/taskBeforeFinishedAt' + - $ref: '#/components/parameters/taskAfterFinishedAt' security: - apiKey: [] '/tasks/:taskUid': @@ -3489,19 +3514,6 @@ paths: application/json: schema: $ref: '#/components/schemas/error' - examples: - Missing Task Filter: - value: - message: 'The required query parameters to cancel tasks are missing. Available query parameters are: `uid`, `indexUid`, `status`, `type`, `beforeEnqueuedAt`, `afterEnqueudAt`, `beforeStartedAt`, afterStartedAt`' - code: missing_task_filter - type: invalid_request - link: 'https://docs.meilisearch.com/errors#missing_task_filter' - Invalid Task Uid: - value: - message: '`uid` is not a valid task uid. Task uid can be an integer or a string containing only numeric characters.' - code: invalid_task_uid - type: invalid_request - link: 'https://docs.meilisearch.com/errors#invalid_task_uid' '401': $ref: '#/components/responses/401' operationId: tasks.cancel @@ -3510,6 +3522,7 @@ paths: - $ref: '#/components/parameters/taskIndexUid' - $ref: '#/components/parameters/taskStatus' - $ref: '#/components/parameters/taskType' + - $ref: '#/components/parameters/taskCanceledBy' - $ref: '#/components/parameters/taskBeforeEnqueuedAt' - $ref: '#/components/parameters/taskAfterEnqueuedAt' - $ref: '#/components/parameters/taskBeforeStartedAt' @@ -3518,6 +3531,4 @@ paths: - $ref: '#/components/parameters/taskAfterFinishedAt' security: - apiKey: [] - parameters: - - $ref: '#/components/parameters/taskUid' security: [] From a9dfceaa64b3574bd5a8b342ca9ba88490eac598 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Wed, 2 Nov 2022 14:04:55 +0100 Subject: [PATCH 55/76] fix task uid query parameter name --- open-api.yaml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/open-api.yaml b/open-api.yaml index 97c41155..07d693e4 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -726,7 +726,7 @@ components: schema: type: any taskUid: - name: taskUid + name: uid in: path description: Permits to filter tasks by their uid. By default, when `uid` query parameter is not set, all task uids are returned. It's possible to specify several uids by separathing them with the `,` character. required: false @@ -3492,7 +3492,6 @@ paths: type: invalid_request link: 'https://docs.meilisearch.com/errors/#task_not_found' operationId: tasks.get - parameters: [] security: - apiKey: [] '/tasks/cancel': From e8b34edc0779bac5a9ab826821f6e8528782051c Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Wed, 2 Nov 2022 14:16:35 +0100 Subject: [PATCH 56/76] Fix collission between url path and query parameters --- open-api.yaml | 81 +++++++++++++++++++++++++++++---------------------- 1 file changed, 46 insertions(+), 35 deletions(-) diff --git a/open-api.yaml b/open-api.yaml index 07d693e4..6eeda43e 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -726,76 +726,83 @@ components: schema: type: any taskUid: - name: uid + name: taskUid in: path + description: The task identifier + required: true + schema: + type: integer + taskFilterUid: + name: uid + in: query description: Permits to filter tasks by their uid. By default, when `uid` query parameter is not set, all task uids are returned. It's possible to specify several uids by separathing them with the `,` character. required: false schema: type: number - taskIndexUid: + taskFilterIndexUid: name: indexUid in: query description: Permits to filter tasks by their related index. By default, when `indexUid` query parameter is not set, the tasks of all the indexes are returned. It is possible to specify several indexes by separating them with the `,` character. required: false schema: type: string - taskType: + taskFilterType: name: type in: query description: Permits to filter tasks by their related type. By default, when `type` query parameter is not set, all task types are returned. It's possible to specify several types by separating them with the `,` character. required: false schema: type: string - taskStatus: + taskFilterStatus: name: status in: query description: Permits to filter tasks by their status. By default, when `status` query parameter is not set, all task statuses are returned. It's possible to specify several types by separating them with the `,` character. required: false schema: type: string - taskBeforeEnqueuedAt: + taskFilterBeforeEnqueuedAt: name: beforeEnqueuedAt in: query description: Permits to filter tasks based on their enqueuedAt time. Retrieve tasks enqueued before the given filter value. required: false schema: type: string - taskAfterEnqueuedAt: + taskFilterAfterEnqueuedAt: name: afterEnqueuedAt in: query description: Permits to filter tasks based on their enqueuedAt time. Retrieve tasks enqueued after the given filter value. required: false schema: type: string - taskBeforeStartedAt: + taskFilterBeforeStartedAt: name: beforeStartedAt in: query description: Permits to filter tasks based on their startedAt time. Retrieve tasks started before the given value. required: false schema: type: string - taskAfterStartedAt: + taskFilterAfterStartedAt: name: afterStartedAt in: query description: Permits to filter tasks based on their startedAt time. Retrieve tasks started after the given value. required: false schema: type: string - taskBeforeFinishedAt: + taskFilterBeforeFinishedAt: name: beforeFinishedAt in: query description: Permits to filter tasks based on their finishedAt time. Retrieve tasks finished before the given filter value. required: false schema: type: string - taskAfterFinishedAt: + taskFilterAfterFinishedAt: name: afterFinishedAt in: query description: Permits to filter tasks based on their finishedAt time. Retrieve tasks finished after the given filter value. required: false schema: type: string - taskCanceledBy: + taskFilterCanceledBy: name: canceledBy in: query description: Permits to filter tasks that have been canceled by the given taskCancelation uid. @@ -3436,17 +3443,17 @@ paths: parameters: - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/from' - - $ref: '#/components/parameters/taskUid' - - $ref: '#/components/parameters/taskIndexUid' - - $ref: '#/components/parameters/taskStatus' - - $ref: '#/components/parameters/taskType' - - $ref: '#/components/parameters/taskCanceledBy' - - $ref: '#/components/parameters/taskBeforeEnqueuedAt' - - $ref: '#/components/parameters/taskAfterEnqueuedAt' - - $ref: '#/components/parameters/taskBeforeStartedAt' - - $ref: '#/components/parameters/taskAfterStartedAt' - - $ref: '#/components/parameters/taskBeforeFinishedAt' - - $ref: '#/components/parameters/taskAfterFinishedAt' + - $ref: '#/components/parameters/taskFilterUid' + - $ref: '#/components/parameters/taskFilterIndexUid' + - $ref: '#/components/parameters/taskFilterStatus' + - $ref: '#/components/parameters/taskFilterType' + - $ref: '#/components/parameters/taskFilterCanceledBy' + - $ref: '#/components/parameters/taskFilterBeforeEnqueuedAt' + - $ref: '#/components/parameters/taskFilterAfterEnqueuedAt' + - $ref: '#/components/parameters/taskFilterBeforeStartedAt' + - $ref: '#/components/parameters/taskFilterAfterStartedAt' + - $ref: '#/components/parameters/taskFilterBeforeFinishedAt' + - $ref: '#/components/parameters/taskFilterAfterFinishedAt' security: - apiKey: [] '/tasks/:taskUid': @@ -3469,9 +3476,11 @@ paths: indexUid: movies status: succeeded type: documentAdditionOrUpdate + canceledBy: null details: receivedDocuments: 79000 indexedDocuments: 79000 + error: null duration: PT1S enqueuedAt: '2021-01-01T09:39:00.000000Z' startedAt: '2021-01-01T09:39:01.000000Z' @@ -3492,12 +3501,14 @@ paths: type: invalid_request link: 'https://docs.meilisearch.com/errors/#task_not_found' operationId: tasks.get + parameters: + - $ref: '#/components/parameters/taskUid' security: - apiKey: [] '/tasks/cancel': post: - summary: Cancel a task - description: 'Cancel a [task](https://docs.meilisearch.com/learn/advanced/asynchronous_operations.html) ' + summary: Cancel tasks + description: 'Cancel enqueued and/or processing [tasks](https://docs.meilisearch.com/learn/advanced/asynchronous_operations.html) ' tags: - tasks responses: @@ -3517,17 +3528,17 @@ paths: $ref: '#/components/responses/401' operationId: tasks.cancel parameters: - - $ref: '#/components/parameters/taskUid' - - $ref: '#/components/parameters/taskIndexUid' - - $ref: '#/components/parameters/taskStatus' - - $ref: '#/components/parameters/taskType' - - $ref: '#/components/parameters/taskCanceledBy' - - $ref: '#/components/parameters/taskBeforeEnqueuedAt' - - $ref: '#/components/parameters/taskAfterEnqueuedAt' - - $ref: '#/components/parameters/taskBeforeStartedAt' - - $ref: '#/components/parameters/taskAfterStartedAt' - - $ref: '#/components/parameters/taskBeforeFinishedAt' - - $ref: '#/components/parameters/taskAfterFinishedAt' + - $ref: '#/components/parameters/taskFilterUid' + - $ref: '#/components/parameters/taskFilterIndexUid' + - $ref: '#/components/parameters/taskFilterStatus' + - $ref: '#/components/parameters/taskFilterType' + - $ref: '#/components/parameters/taskFilterCanceledBy' + - $ref: '#/components/parameters/taskFilterBeforeEnqueuedAt' + - $ref: '#/components/parameters/taskFilterAfterEnqueuedAt' + - $ref: '#/components/parameters/taskFilterBeforeStartedAt' + - $ref: '#/components/parameters/taskFilterAfterStartedAt' + - $ref: '#/components/parameters/taskFilterBeforeFinishedAt' + - $ref: '#/components/parameters/taskFilterAfterFinishedAt' security: - apiKey: [] security: [] From 9056f3f6ea46cf9fe807951a047fdcc7fe532d62 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Wed, 2 Nov 2022 14:19:04 +0100 Subject: [PATCH 57/76] fmt open-api.yml --- open-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/open-api.yaml b/open-api.yaml index 6eeda43e..9101fc17 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -729,7 +729,7 @@ components: name: taskUid in: path description: The task identifier - required: true + required: true schema: type: integer taskFilterUid: From b4d3f75fc33559a68cc8dd22dd1b21915b1f71e0 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Wed, 2 Nov 2022 14:54:47 +0100 Subject: [PATCH 58/76] Add telemetry details --- text/0034-telemetry-policies.md | 48 ++++++++++++++++++++++++++++----- 1 file changed, 41 insertions(+), 7 deletions(-) diff --git a/text/0034-telemetry-policies.md b/text/0034-telemetry-policies.md index 27f27579..ac89c104 100644 --- a/text/0034-telemetry-policies.md +++ b/text/0034-telemetry-policies.md @@ -1,4 +1,4 @@ -- Title: Anonymous Analytics Policy +- title: Anonymous analytics policy - Started At: 2021-04-16 - Updated At: 2021-10-13 @@ -58,6 +58,7 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat | Faceting Updated | Occurs when faceting settings are updated via `PATCH` — `/indexes/:indexUid/settings/faceting`. | | Dump Created | Occurs when a dump is created via `POST` - `/dumps`. | | Tasks Seen | Occurs when tasks are fetched globally via `GET` - `/tasks`. | +| Tasks Canceled | Occurs when tasks are requested to be canceled via `POST` - `/tasks/cancel`. | | Stats Seen | Occurs when stats are fetched via `GET` - `/stats` or `/indexes/:indexUid/stats`. | ---- @@ -131,9 +132,17 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat | `pagination.max_total_hits` | The defined value for `pagination.maxTotalHits` property | `1000` | `Settings Updated`, `Pagination Updated` | | `faceting.max_values_per_facet` | The defined value for `faceting.maxValuesPerFacet` property | `100` | `Settings Updated`, `Faceting Updated` | | `per_task_uid` | `true` if an uid is used to fetch a particular task resource, otherwise `false` | true | `Tasks Seen` | -| `filtered_by_index_uid` | `true` if `GET /tasks` endpoint is filered by `indexUid`, otherwise `false` | false | `Tasks Seen` | -| `filtered_by_type` | `true` if `GET /tasks` endpoint is filered by `type`, otherwise `false` | false | `Tasks Seen` | -| `filtered_by_status` | `true` if `GET /tasks` endpoint is filered by `status`, otherwise `false` | false | `Tasks Seen` | +| `filteted_by_uid` | `true` if tasks are filtered by the `uid` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | +| `filtered_by_index_uid` | `true` if tasks are filtered by the `indexUid` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | +| `filtered_by_type` | `true` if tasks are filtered by the `type` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | +| `filtered_by_status` | `true` if tasks are filtered by the `status` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | +| `filtered_by_canceled_by` | `true` if tasks are filtered by the `canceledBy` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | +| `filtered_by_before_enqueued_at` | `true` if tasks are filtered by the `beforeEnqueuedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | +| `filtered_by_after_enqueued_at ` | `true` if tasks are filtered by the `afterEnqueuedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | +| `filtered_by_before_started_at` | `true` if tasks are filtered by the `beforeStartedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | +| `filtered_by_after_started_at` | `true` if tasks are filtered by the `afterStartedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | +| `filtered_by_before_finished_at` | `true` if tasks are filtered by the `beforeFinishedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | +| `filtered_by_after_finished_at` | `true` if tasks are filtered by the `afterFinishedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | | `per_index_uid` | `true` if an uid is used to fetch an index stat resource, otherwise `false` | false | `Stats Seen` | | `most_used_matching_strategy` | Most used word matching strategy among all search requests in this batch | `last` | `Documents Searched POST`, `Documents Searched GET` | @@ -387,9 +396,34 @@ This property allows us to gather essential information to better understand on |---------------|-------------|---------| | user_agent | Represents the user-agent encountered on this call. | `["Meilisearch Ruby (v2.1)", "Ruby (3.0)"]` | | per_task_uid | `true` if an uid is used to fetch a particular task resource, otherwise `false` | `true` | -| filtered_by_index_uid | `true` if `GET /tasks` endpoint is filered by `indexUid`, otherwise `false` | `false` | -| filtered_by_type | `true` if `GET /tasks` endpoint is filered by `type`, otherwise `false` | `false` | -| filtered_by_status | `true` if `GET /tasks` endpoint is filered by `status`, otherwise `false` | `false` | +| filteted_by_uid | `true` if tasks are filtered by the `uid` query parameter, otherwise `false` | false | +| filtered_by_index_uid | `true` if tasks are filtered by the `indexUid` query parameter, otherwise `false` | false | +| filtered_by_type | `true` if tasks are filtered by the `type` query parameter, otherwise `false` | false | +| filtered_by_status | `true` if tasks are filtered by the `status` query parameter, otherwise `false` | false | +| filtered_by_canceled_by | `true` if tasks are filtered by the `canceledBy` query parameter, otherwise `false` | false | +| filtered_by_before_enqueued_at | `true` if tasks are filtered by the `beforeEnqueuedAt` query parameter, otherwise `false` | false | +| filtered_by_after_enqueued_at | `true` if tasks are filtered by the `afterEnqueuedAt` query parameter, otherwise `false` | false | +| filtered_by_before_started_at | `true` if tasks are filtered by the `beforeStartedAt` query parameter, otherwise `false` | false | +| filtered_by_after_started_at | `true` if tasks are filtered by the `afterStartedAt` query parameter, otherwise `false` | false | +| filtered_by_before_finished_at | `true` if tasks are filtered by the `beforeFinishedAt` query parameter, otherwise `false` | false | +| filtered_by_after_finished_at | `true` if tasks are filtered by the `afterFinishedAt` query parameter, otherwise `false` | false | + +## `Tasks Canceled` + +| Property name | Description | Example | +|---------------|-------------|---------| +| user_agent | Represents the user-agent encountered on this call. | `["Meilisearch Ruby (v2.1)", "Ruby (3.0)"]` | +| filteted_by_uid | `true` if tasks are filtered by the `uid` query parameter, otherwise `false` | false | +| filtered_by_index_uid | `true` if tasks are filtered by the `indexUid` query parameter, otherwise `false` | false | +| filtered_by_type | `true` if tasks are filtered by the `type` query parameter, otherwise `false` | false | +| filtered_by_status | `true` if tasks are filtered by the `status` query parameter, otherwise `false` | false | +| filtered_by_canceled_by | `true` if tasks are filtered by the `canceledBy` query parameter, otherwise `false` | false | +| filtered_by_before_enqueued_at | `true` if tasks are filtered by the `beforeEnqueuedAt` query parameter, otherwise `false` | false | +| filtered_by_after_enqueued_at | `true` if tasks are filtered by the `afterEnqueuedAt` query parameter, otherwise `false` | false | +| filtered_by_before_started_at | `true` if tasks are filtered by the `beforeStartedAt` query parameter, otherwise `false` | false | +| filtered_by_after_started_at | `true` if tasks are filtered by the `afterStartedAt` query parameter, otherwise `false` | false | +| filtered_by_before_finished_at | `true` if tasks are filtered by the `beforeFinishedAt` query parameter, otherwise `false` | false | +| filtered_by_after_finished_at | `true` if tasks are filtered by the `afterFinishedAt` query parameter, otherwise `false` | false | ## `Stats Seen` From aa6f9d76490923ed0437e7f99755a9cf2feb6173 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Wed, 2 Nov 2022 18:49:49 +0100 Subject: [PATCH 59/76] Add 202_taskCancelation example --- open-api.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/open-api.yaml b/open-api.yaml index 9101fc17..296a4990 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -3518,6 +3518,9 @@ paths: application/json: schema: $ref: '#/components/schemas/summarizedTask' + examples: + '202': + $ref: '#/components/examples/202_taskCancelation' '400': description: Bad Request content: From 65dbac4511f87d0fd8e074052c3f752c8c88aea7 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Thu, 3 Nov 2022 14:03:56 +0100 Subject: [PATCH 60/76] Update originalQuery to originalFilters and update missing_task_filter to missing_task_filters --- open-api.yaml | 2 +- text/0060-tasks-api.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/open-api.yaml b/open-api.yaml index 296a4990..7accf486 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -348,7 +348,7 @@ components: canceledTasks: type: integer description: Number of tasks canceled for taskCancelation task. - originalQuery: + originalFilters: type: string description: Original filter query for taskCancelation task. error: diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index a0f02cf1..1b4edc66 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -148,7 +148,7 @@ List of global tasks by `type`: | ------------- | ----------- | | matchedTasks | The number of tasks that can be canceled based on the request. If the API key doesn’t have access to any of the indexes specified in the request via the `indexUid` query parameter, those tasks will not be included in `matchedTasks`. `null` when the task status is enqueued. | | canceledTasks | The number of tasks successfully canceled. If the task fails, `0` is displayed. `null` when the task status is enqueud or processing. | -| originalQuery | The extracted URL query parameters used in the originating task cancelation request. | +| originalFilters | The extracted URL query parameters used in the originating task cancelation request. | #### 5. Examples @@ -446,7 +446,7 @@ This means: If a user tries canceling a `succeeded`, `failed`, or `canceled` task, it won’t throw an error. Task cancelation is an atomic transaction; all tasks are successfully canceled, or none aren't. -- 🔴 Sending a task cancelation without filtering query parameters returns a `[missing_task_filter](https://github.com/meilisearch/specifications/blob/main/text/0061-error-format-and-definitions.md#missing_task_filter)` error. +- 🔴 Sending a task cancelation without filtering query parameters returns a [missing_task_filters](0061-error-format-and-definitions.md#missing_task_filters) error. The auth layer can return the following errors if Meilisearch is secured (a master-key is defined). From ae44e1803cd8c63e5932a475f2d3d9a1a3994aad Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Thu, 3 Nov 2022 14:27:24 +0100 Subject: [PATCH 61/76] matchedTasks is computed when the task is enqueued --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 1b4edc66..2056fe08 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -146,7 +146,7 @@ List of global tasks by `type`: | Name | Description | | ------------- | ----------- | -| matchedTasks | The number of tasks that can be canceled based on the request. If the API key doesn’t have access to any of the indexes specified in the request via the `indexUid` query parameter, those tasks will not be included in `matchedTasks`. `null` when the task status is enqueued. | +| matchedTasks | The number of tasks that can be canceled based on the request. If the API key doesn’t have access to any of the indexes specified in the request via the `indexUid` query parameter, those tasks will not be included in `matchedTasks`. | | canceledTasks | The number of tasks successfully canceled. If the task fails, `0` is displayed. `null` when the task status is enqueud or processing. | | originalFilters | The extracted URL query parameters used in the originating task cancelation request. | From 7b3734fe436c8b2ba147dfe28e559ff92a44138f Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Thu, 3 Nov 2022 15:38:55 +0100 Subject: [PATCH 62/76] Apply suggestions from code review Co-authored-by: cvermand <33010418+bidoubiwa@users.noreply.github.com> --- open-api.yaml | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/open-api.yaml b/open-api.yaml index 7accf486..65f3e167 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -317,7 +317,7 @@ components: - taskCancelation canceledBy: type: integer - description: The uid if of the related taskCancelation if the task has been canceled. + description: The uid of the task that performed the taskCancelation if the task has been canceled. details: type: object description: Details information of the task payload. @@ -344,13 +344,13 @@ components: description: Identifier generated for the dump for dumpCreation task. matchedTasks: type: integer - description: Number of tasks that match the request for taskCancelation task. + description: Number of tasks that match the task cancelation request. canceledTasks: type: integer - description: Number of tasks canceled for taskCancelation task. + description: Number of tasks canceled. originalFilters: type: string - description: Original filter query for taskCancelation task. + description: Filters used for the cancelation task. error: description: Error object containing error details and context when a task has a failed status. $ref: '#/components/schemas/error' @@ -735,7 +735,7 @@ components: taskFilterUid: name: uid in: query - description: Permits to filter tasks by their uid. By default, when `uid` query parameter is not set, all task uids are returned. It's possible to specify several uids by separathing them with the `,` character. + description: Permits to filter tasks by their uid. By default, when the `uid` query parameter is not set, all task uids are returned. It's possible to specify several uids by separathing them with the `,` character. required: false schema: type: number @@ -763,49 +763,49 @@ components: taskFilterBeforeEnqueuedAt: name: beforeEnqueuedAt in: query - description: Permits to filter tasks based on their enqueuedAt time. Retrieve tasks enqueued before the given filter value. + description: Permits to filter tasks based on their enqueuedAt time. Matches tasks enqueued before the given date. required: false schema: type: string taskFilterAfterEnqueuedAt: name: afterEnqueuedAt in: query - description: Permits to filter tasks based on their enqueuedAt time. Retrieve tasks enqueued after the given filter value. + description: Permits to filter tasks based on their enqueuedAt time. Matches tasks enqueued after the given date. required: false schema: type: string taskFilterBeforeStartedAt: name: beforeStartedAt in: query - description: Permits to filter tasks based on their startedAt time. Retrieve tasks started before the given value. + description: Permits to filter tasks based on their startedAt time. Matches tasks started before the given date. required: false schema: type: string taskFilterAfterStartedAt: name: afterStartedAt in: query - description: Permits to filter tasks based on their startedAt time. Retrieve tasks started after the given value. + description: Permits to filter tasks based on their startedAt time. Matches tasks started after the given date. required: false schema: type: string taskFilterBeforeFinishedAt: name: beforeFinishedAt in: query - description: Permits to filter tasks based on their finishedAt time. Retrieve tasks finished before the given filter value. + description: Permits to filter tasks based on their finishedAt time. Matches tasks finished before the given date. required: false schema: type: string taskFilterAfterFinishedAt: name: afterFinishedAt in: query - description: Permits to filter tasks based on their finishedAt time. Retrieve tasks finished after the given filter value. + description: Permits to filter tasks based on their finishedAt time. Matches tasks finished after the given date. required: false schema: type: string taskFilterCanceledBy: name: canceledBy in: query - description: Permits to filter tasks that have been canceled by the given taskCancelation uid. + description: Permits to filter tasks using the uid of the task that canceled them. required: false schema: type: string From 6d8ee3a4eeec6a56ebf16581890272b8c3616c6d Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Thu, 3 Nov 2022 16:12:59 +0100 Subject: [PATCH 63/76] Apply suggestions from code review Co-authored-by: cvermand <33010418+bidoubiwa@users.noreply.github.com> --- text/0060-tasks-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 2056fe08..b910b5d4 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -24,7 +24,7 @@ As writing is asynchronous for most of Meilisearch's operations, this API allows | indexUid | string | Unique index identifier. This field is `null` when the task is a [global task](#global-task). | | status | string | Status of the task. Possible values are `enqueued`, `processing`, `succeeded`, `failed`, `canceled` | | type | string | Type of the task. Possible values are `indexCreation`, `indexUpdate`, `indexDeletion`, `documentAdditionOrUpdate`, `documentDeletion`, `settingsUpdate`, `dumpCreation`, `taskCancelation` | -| canceledBy | integer | Unique identifier of the `taskCancelation` task that canceled the given task. Default is set to `null`. | +| canceledBy | integer | Unique identifier of the task that canceled this task. Default is set to `null`. | | details | object | Details information for a task payload. See Task Details part. | | error | object | Error object containing error details and context when a task has a `failed` status. See [0061-error-format-and-definitions.md](0061-error-format-and-definitions.md). Default is set to `null`. | | duration | string | Total elapsed time the engine was in processing state expressed as an `ISO-8601` duration format. Times below the second can be expressed with the `.` notation, e.g., `PT0.5S` to express `500ms`. Default is set to `null`. | @@ -436,7 +436,7 @@ When the request is successful, Meilisearch returns the HTTP code 202 Accepted. ##### 6.3.3. Auto-batching -If the task you’re canceling is part of a batch, **the whole batch is stopped.** Meilisearch automatically creates a new batch once the current one is stopped and the specified tasks are canceled. The canceled tasks will not be part of the new batch. +If the task you’re canceling is part of a batch, **the whole batch is stopped.** Once it is stopped, Meilisearch automatically creates a new batch with the remaining tasks. The canceled tasks are not part of the new batch. This means: - When the new batch is created, it may contain tasks that have been enqueued between the batch cancelation and recreation. From 9859dc6b7ec71aa3cce692d72512e39039f287cf Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Thu, 3 Nov 2022 16:35:17 +0100 Subject: [PATCH 64/76] Recall explanation for filter query parameter and mentions that limit and from are valid on --- text/0060-tasks-api.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index b910b5d4..d7d98e6b 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -486,7 +486,7 @@ See [0119-instance-options](0119-instance-options.md##3312-max-taskdb-size) #### 10. Paginate `task` resource lists -The API endpoint `/tasks` is browsable using a keyset-based pagination. +The API endpoint `GET /tasks` is browsable using a keyset-based pagination. ##### 10.1. Why a Seek/Keyset based pagination? @@ -647,16 +647,20 @@ The tasks API endpoints are filterable by `uid`, `indexUid`, `type`, `status`, ###### 11.2.1. `uid` + Filter tasks by their related unique identifier. By default, when `uid` query parameter is not set, all the tasks are concerned. It is possible to specify several uid by separating them with the `,` character. + - Type: Integer - Required: False - Default: `*` `uid` is **case-unsensitive**. -- 🔴 Sending values with a different type than `Integer` being separated by `,` for the `uid` parameter returns an [`invalid_task_uid`](0061-error-format-and-definitions.md#invalid_task_uid) error. +- 🔴 Sending values with a different type than `Integer` being separated by `,` for the `uid` parameter returns an [`invalid_task_uid`](0061-error-format-and-definitions.md#invalid_task_uid) error. ###### 11.2.2. `indexUid` +Filter tasks by their related index. By default, when `indexUid` query parameter is not set, the tasks of all the indexes are concerned. It is possible to specify several indexUids by separating them with the `,` character. + - Type: String - Required: False - Default: `*` @@ -665,6 +669,8 @@ The tasks API endpoints are filterable by `uid`, `indexUid`, `type`, `status`, ###### 11.2.3. `status` +Filter tasks by their status. By default, when `status` query parameter is not set, all task statuses are concerned. It's possible to specify several statuses by separating them with the `,` character. + - Type: String - Required: False - Default: `*` @@ -673,6 +679,8 @@ The tasks API endpoints are filterable by `uid`, `indexUid`, `type`, `status`, ###### 11.2.4. `type` +Filter tasks by their related type. By default, when `type` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. + - Type: String - Required: False - Default: `*` @@ -683,6 +691,8 @@ The tasks API endpoints are filterable by `uid`, `indexUid`, `type`, `status`, ###### 11.2.5. `canceledBy` +Filter tasks by the `taskCancelation` uid that canceled them. + - Type: Integer - Required: False - Default: `null` @@ -701,6 +711,8 @@ Date filters accepts the RFC 3339 format. The following syntaxes are valid: ###### 11.2.6.1. `beforeEnqueuedAt` and `afterEnqueuedAt` +Filter tasks based on their enqueuedAt time. Retrieve tasks enqueued before/after the given filter value. + - Type: String - Required: False - Default: `*` @@ -710,6 +722,8 @@ Date filters accepts the RFC 3339 format. The following syntaxes are valid: ###### 11.2.6.2. `beforeStartedAt` and `afterStartedAt` +Filter tasks based on their startedAt time. Retrieve tasks started before/after the given filter value. + - Type: String - Required: False - Default: `*` @@ -719,6 +733,8 @@ Date filters accepts the RFC 3339 format. The following syntaxes are valid: ###### 11.2.6.3. `beforeFinishedAt` and `afterFinishedAt` +Filter tasks based on their finishedAt time. Retrieve tasks finished before/after the given filter value. + - Type: String - Required: False - Default: `*` From c0bf5bff401819be72d736542f981bd2148976f6 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Thu, 3 Nov 2022 16:37:37 +0100 Subject: [PATCH 65/76] Fix typo in property name --- text/0034-telemetry-policies.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/text/0034-telemetry-policies.md b/text/0034-telemetry-policies.md index ac89c104..eea50b65 100644 --- a/text/0034-telemetry-policies.md +++ b/text/0034-telemetry-policies.md @@ -132,7 +132,7 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat | `pagination.max_total_hits` | The defined value for `pagination.maxTotalHits` property | `1000` | `Settings Updated`, `Pagination Updated` | | `faceting.max_values_per_facet` | The defined value for `faceting.maxValuesPerFacet` property | `100` | `Settings Updated`, `Faceting Updated` | | `per_task_uid` | `true` if an uid is used to fetch a particular task resource, otherwise `false` | true | `Tasks Seen` | -| `filteted_by_uid` | `true` if tasks are filtered by the `uid` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | +| `filtered_by_uid` | `true` if tasks are filtered by the `uid` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | | `filtered_by_index_uid` | `true` if tasks are filtered by the `indexUid` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | | `filtered_by_type` | `true` if tasks are filtered by the `type` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | | `filtered_by_status` | `true` if tasks are filtered by the `status` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | @@ -396,7 +396,7 @@ This property allows us to gather essential information to better understand on |---------------|-------------|---------| | user_agent | Represents the user-agent encountered on this call. | `["Meilisearch Ruby (v2.1)", "Ruby (3.0)"]` | | per_task_uid | `true` if an uid is used to fetch a particular task resource, otherwise `false` | `true` | -| filteted_by_uid | `true` if tasks are filtered by the `uid` query parameter, otherwise `false` | false | +| filtered_by_uid | `true` if tasks are filtered by the `uid` query parameter, otherwise `false` | false | | filtered_by_index_uid | `true` if tasks are filtered by the `indexUid` query parameter, otherwise `false` | false | | filtered_by_type | `true` if tasks are filtered by the `type` query parameter, otherwise `false` | false | | filtered_by_status | `true` if tasks are filtered by the `status` query parameter, otherwise `false` | false | @@ -413,7 +413,7 @@ This property allows us to gather essential information to better understand on | Property name | Description | Example | |---------------|-------------|---------| | user_agent | Represents the user-agent encountered on this call. | `["Meilisearch Ruby (v2.1)", "Ruby (3.0)"]` | -| filteted_by_uid | `true` if tasks are filtered by the `uid` query parameter, otherwise `false` | false | +| filtered_by_uid | `true` if tasks are filtered by the `uid` query parameter, otherwise `false` | false | | filtered_by_index_uid | `true` if tasks are filtered by the `indexUid` query parameter, otherwise `false` | false | | filtered_by_type | `true` if tasks are filtered by the `type` query parameter, otherwise `false` | false | | filtered_by_status | `true` if tasks are filtered by the `status` query parameter, otherwise `false` | false | From 3403292a4514db61c56eaf96561291bd43f79187 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Thu, 3 Nov 2022 17:59:59 +0100 Subject: [PATCH 66/76] Update query paramters name and related error codes when invalid --- open-api.yaml | 42 +++++++------- text/0034-telemetry-policies.md | 24 ++++---- text/0060-tasks-api.md | 70 ++++++++++++----------- text/0061-error-format-and-definitions.md | 32 +++++------ 4 files changed, 85 insertions(+), 83 deletions(-) diff --git a/open-api.yaml b/open-api.yaml index 65f3e167..50cf93f4 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -732,31 +732,31 @@ components: required: true schema: type: integer - taskFilterUid: - name: uid + taskFilterUids: + name: uids in: query - description: Permits to filter tasks by their uid. By default, when the `uid` query parameter is not set, all task uids are returned. It's possible to specify several uids by separathing them with the `,` character. + description: Permits to filter tasks by their uid. By default, when the `uids` query parameter is not set, all task uids are returned. It's possible to specify several uids by separathing them with the `,` character. required: false schema: type: number - taskFilterIndexUid: - name: indexUid + taskFilterIndexUids: + name: indexUids in: query - description: Permits to filter tasks by their related index. By default, when `indexUid` query parameter is not set, the tasks of all the indexes are returned. It is possible to specify several indexes by separating them with the `,` character. + description: Permits to filter tasks by their related index. By default, when `indexUids` query parameter is not set, the tasks of all the indexes are returned. It is possible to specify several indexes by separating them with the `,` character. required: false schema: type: string - taskFilterType: - name: type + taskFilterTypes: + name: types in: query - description: Permits to filter tasks by their related type. By default, when `type` query parameter is not set, all task types are returned. It's possible to specify several types by separating them with the `,` character. + description: Permits to filter tasks by their related type. By default, when `types` query parameter is not set, all task types are returned. It's possible to specify several types by separating them with the `,` character. required: false schema: type: string - taskFilterStatus: - name: status + taskFilterStatuses: + name: statuses in: query - description: Permits to filter tasks by their status. By default, when `status` query parameter is not set, all task statuses are returned. It's possible to specify several types by separating them with the `,` character. + description: Permits to filter tasks by their status. By default, when `statuses` query parameter is not set, all task statuses are returned. It's possible to specify several statuses by separating them with the `,` character. required: false schema: type: string @@ -805,7 +805,7 @@ components: taskFilterCanceledBy: name: canceledBy in: query - description: Permits to filter tasks using the uid of the task that canceled them. + description: Permits to filter tasks using the uid of the task that canceled them. It's possible to specify several task uids by separating them with the `,` character. required: false schema: type: string @@ -3443,10 +3443,10 @@ paths: parameters: - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/from' - - $ref: '#/components/parameters/taskFilterUid' - - $ref: '#/components/parameters/taskFilterIndexUid' - - $ref: '#/components/parameters/taskFilterStatus' - - $ref: '#/components/parameters/taskFilterType' + - $ref: '#/components/parameters/taskFilterUids' + - $ref: '#/components/parameters/taskFilterIndexUids' + - $ref: '#/components/parameters/taskFilterStatuses' + - $ref: '#/components/parameters/taskFilterTypes' - $ref: '#/components/parameters/taskFilterCanceledBy' - $ref: '#/components/parameters/taskFilterBeforeEnqueuedAt' - $ref: '#/components/parameters/taskFilterAfterEnqueuedAt' @@ -3531,10 +3531,10 @@ paths: $ref: '#/components/responses/401' operationId: tasks.cancel parameters: - - $ref: '#/components/parameters/taskFilterUid' - - $ref: '#/components/parameters/taskFilterIndexUid' - - $ref: '#/components/parameters/taskFilterStatus' - - $ref: '#/components/parameters/taskFilterType' + - $ref: '#/components/parameters/taskFilterUids' + - $ref: '#/components/parameters/taskFilterIndexUids' + - $ref: '#/components/parameters/taskFilterStatuses' + - $ref: '#/components/parameters/taskFilterTypes' - $ref: '#/components/parameters/taskFilterCanceledBy' - $ref: '#/components/parameters/taskFilterBeforeEnqueuedAt' - $ref: '#/components/parameters/taskFilterAfterEnqueuedAt' diff --git a/text/0034-telemetry-policies.md b/text/0034-telemetry-policies.md index eea50b65..7fce6fdf 100644 --- a/text/0034-telemetry-policies.md +++ b/text/0034-telemetry-policies.md @@ -132,10 +132,10 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat | `pagination.max_total_hits` | The defined value for `pagination.maxTotalHits` property | `1000` | `Settings Updated`, `Pagination Updated` | | `faceting.max_values_per_facet` | The defined value for `faceting.maxValuesPerFacet` property | `100` | `Settings Updated`, `Faceting Updated` | | `per_task_uid` | `true` if an uid is used to fetch a particular task resource, otherwise `false` | true | `Tasks Seen` | -| `filtered_by_uid` | `true` if tasks are filtered by the `uid` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | -| `filtered_by_index_uid` | `true` if tasks are filtered by the `indexUid` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | -| `filtered_by_type` | `true` if tasks are filtered by the `type` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | -| `filtered_by_status` | `true` if tasks are filtered by the `status` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | +| `filtered_by_uid` | `true` if tasks are filtered by the `uids` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | +| `filtered_by_index_uid` | `true` if tasks are filtered by the `indexUids` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | +| `filtered_by_type` | `true` if tasks are filtered by the `types` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | +| `filtered_by_status` | `true` if tasks are filtered by the `statuses` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | | `filtered_by_canceled_by` | `true` if tasks are filtered by the `canceledBy` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | | `filtered_by_before_enqueued_at` | `true` if tasks are filtered by the `beforeEnqueuedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | | `filtered_by_after_enqueued_at ` | `true` if tasks are filtered by the `afterEnqueuedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | @@ -396,10 +396,10 @@ This property allows us to gather essential information to better understand on |---------------|-------------|---------| | user_agent | Represents the user-agent encountered on this call. | `["Meilisearch Ruby (v2.1)", "Ruby (3.0)"]` | | per_task_uid | `true` if an uid is used to fetch a particular task resource, otherwise `false` | `true` | -| filtered_by_uid | `true` if tasks are filtered by the `uid` query parameter, otherwise `false` | false | -| filtered_by_index_uid | `true` if tasks are filtered by the `indexUid` query parameter, otherwise `false` | false | -| filtered_by_type | `true` if tasks are filtered by the `type` query parameter, otherwise `false` | false | -| filtered_by_status | `true` if tasks are filtered by the `status` query parameter, otherwise `false` | false | +| filtered_by_uid | `true` if tasks are filtered by the `uids` query parameter, otherwise `false` | false | +| filtered_by_index_uid | `true` if tasks are filtered by the `indexUids` query parameter, otherwise `false` | false | +| filtered_by_type | `true` if tasks are filtered by the `types` query parameter, otherwise `false` | false | +| filtered_by_status | `true` if tasks are filtered by the `statuses` query parameter, otherwise `false` | false | | filtered_by_canceled_by | `true` if tasks are filtered by the `canceledBy` query parameter, otherwise `false` | false | | filtered_by_before_enqueued_at | `true` if tasks are filtered by the `beforeEnqueuedAt` query parameter, otherwise `false` | false | | filtered_by_after_enqueued_at | `true` if tasks are filtered by the `afterEnqueuedAt` query parameter, otherwise `false` | false | @@ -413,10 +413,10 @@ This property allows us to gather essential information to better understand on | Property name | Description | Example | |---------------|-------------|---------| | user_agent | Represents the user-agent encountered on this call. | `["Meilisearch Ruby (v2.1)", "Ruby (3.0)"]` | -| filtered_by_uid | `true` if tasks are filtered by the `uid` query parameter, otherwise `false` | false | -| filtered_by_index_uid | `true` if tasks are filtered by the `indexUid` query parameter, otherwise `false` | false | -| filtered_by_type | `true` if tasks are filtered by the `type` query parameter, otherwise `false` | false | -| filtered_by_status | `true` if tasks are filtered by the `status` query parameter, otherwise `false` | false | +| filtered_by_uid | `true` if tasks are filtered by the `uids` query parameter, otherwise `false` | false | +| filtered_by_index_uid | `true` if tasks are filtered by the `indexUids` query parameter, otherwise `false` | false | +| filtered_by_type | `true` if tasks are filtered by the `types` query parameter, otherwise `false` | false | +| filtered_by_status | `true` if tasks are filtered by the `statuses` query parameter, otherwise `false` | false | | filtered_by_canceled_by | `true` if tasks are filtered by the `canceledBy` query parameter, otherwise `false` | false | | filtered_by_before_enqueued_at | `true` if tasks are filtered by the `beforeEnqueuedAt` query parameter, otherwise `false` | false | | filtered_by_after_enqueued_at | `true` if tasks are filtered by the `afterEnqueuedAt` query parameter, otherwise `false` | false | diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index d7d98e6b..2a4f2011 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -146,7 +146,7 @@ List of global tasks by `type`: | Name | Description | | ------------- | ----------- | -| matchedTasks | The number of tasks that can be canceled based on the request. If the API key doesn’t have access to any of the indexes specified in the request via the `indexUid` query parameter, those tasks will not be included in `matchedTasks`. | +| matchedTasks | The number of tasks that can be canceled based on the request. If the API key doesn’t have access to any of the indexes specified in the request via the `indexUids` query parameter, those tasks will not be included in `matchedTasks`. | | canceledTasks | The number of tasks successfully canceled. If the task fails, `0` is displayed. `null` when the task status is enqueud or processing. | | originalFilters | The extracted URL query parameters used in the originating task cancelation request. | @@ -625,17 +625,17 @@ This part demonstrates keyset paging in action on `/tasks`. The items `uid` rema #### 11. Filtering task resources -The tasks API endpoints are filterable by `uid`, `indexUid`, `type`, `status`, `beforeEnqueuedAt`, `afterEnqueuedAt`, `beforeStartedAt`, `afterStartedAt`, `beforeFinishedAt`, `afterFinishedAt` query parameters. +The tasks API endpoints are filterable by `uids`, `indexUids`, `types`, `statuses`, `canceledBy`, `beforeEnqueuedAt`, `afterEnqueuedAt`, `beforeStartedAt`, `afterStartedAt`, `beforeFinishedAt`, `afterFinishedAt` query parameters. ##### 11.1 Query parameters definition | parameter | type | required | description | |-----------|--------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| uid | integer | No | Permits to filter tasks by their related unique identifier. By default, when `uid` query parameter is not set, all the tasks are concerned. It is possible to specify several uid by separating them with the `,` character. | -| indexUid | string | No | Permits to filter tasks by their related index. By default, when `indexUid` query parameter is not set, the tasks of all the indexes are concerned. It is possible to specify several indexUids by separating them with the `,` character. | -| status | string | No | Permits to filter tasks by their status. By default, when `status` query parameter is not set, all task statuses are concerned. It's possible to specify several statuses by separating them with the `,` character. | -| type | string | No | Permits to filter tasks by their related type. By default, when `type` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | -| canceledBy | integer | No | Permits to filter tasks by the `taskCancelation` uid that canceled them. | +| uids | integer | No | Permits to filter tasks by their related unique identifier. By default, when `uids` query parameter is not set, all the tasks are concerned. It is possible to specify several uid by separating them with the `,` character. | +| indexUids | string | No | Permits to filter tasks by their related index. By default, when `indexUids` query parameter is not set, the tasks of all the indexes are concerned. It is possible to specify several indexUids by separating them with the `,` character. | +| statuses | string | No | Permits to filter tasks by their status. By default, when `statuses` query parameter is not set, all task statuses are concerned. It's possible to specify several statuses by separating them with the `,` character. | +| types | string | No | Permits to filter tasks by their related type. By default, when `types` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. | +| canceledBy | integer | No | Permits to filter tasks by the `taskCancelation` uid that canceled them. It's possible to specify several task uids by separating them with the `,` character. | | beforeEnqueuedAt | string | No | Filter tasks based on their enqueuedAt time. Retrieve tasks enqueued before the given filter value. | | afterEnqueuedAt | string | No | Filter tasks based on their enqueuedAt time. Retrieve tasks enqueued after the given filter value. | | beforeStartedAt | string | No | Filter tasks based on their startedAt time. Retrieve tasks started before the given value. | @@ -645,53 +645,55 @@ The tasks API endpoints are filterable by `uid`, `indexUid`, `type`, `status`, ##### 11.2. Query Parameters Behaviors -###### 11.2.1. `uid` +###### 11.2.1. `uids` - Filter tasks by their related unique identifier. By default, when `uid` query parameter is not set, all the tasks are concerned. It is possible to specify several uid by separating them with the `,` character. + Filter tasks by their related unique identifier. By default, when `uids` query parameter is not set, all the tasks are concerned. It is possible to specify several uid by separating them with the `,` character. - Type: Integer - Required: False - Default: `*` -`uid` is **case-unsensitive**. +`uids` is **case-unsensitive**. -- 🔴 Sending values with a different type than `Integer` being separated by `,` for the `uid` parameter returns an [`invalid_task_uid`](0061-error-format-and-definitions.md#invalid_task_uid) error. +- 🔴 Sending values with a different type than `Integer` being separated by `,` for the `uid` parameter returns an [`invalid_task_uids_filter`](0061-error-format-and-definitions.md#invalid_task_uids_filter) error. -###### 11.2.2. `indexUid` +###### 11.2.2. `indexUids` -Filter tasks by their related index. By default, when `indexUid` query parameter is not set, the tasks of all the indexes are concerned. It is possible to specify several indexUids by separating them with the `,` character. +Filter tasks by their related index. By default, when `indexUids` query parameter is not set, the tasks of all the indexes are concerned. It is possible to specify several indexUids by separating them with the `,` character. - Type: String - Required: False - Default: `*` -`indexUid` is **case-sensitive**. +`indexUids` is **case-sensitive**. -###### 11.2.3. `status` +###### 11.2.3. `statuses` -Filter tasks by their status. By default, when `status` query parameter is not set, all task statuses are concerned. It's possible to specify several statuses by separating them with the `,` character. +Filter tasks by their status. By default, when `statuses` query parameter is not set, all task statuses are concerned. It's possible to specify several statuses by separating them with the `,` character. - Type: String - Required: False - Default: `*` -- 🔴 If the `status` parameter value is not consistent with one of the task statuses, an [`invalid_task_status`](0061-error-format-and-definitions.md#invalid_task_status) error is returned. +`statuses` is **case-insensitive**. -###### 11.2.4. `type` +- 🔴 If the `statuses` parameter value is not consistent with one of the task statuses, an [`invalid_task_statuses_filter`](0061-error-format-and-definitions.md#invalid_task_statuses_filter) error is returned. -Filter tasks by their related type. By default, when `type` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. +###### 11.2.4. `types` + +Filter tasks by their related type. By default, when `types` query parameter is not set, all task types are concerned. It's possible to specify several types by separating them with the `,` character. - Type: String - Required: False - Default: `*` -`type` is **case-insensitive**. +`types` is **case-insensitive**. -- 🔴 If the `type` parameter value is not consistent with one of the task types, an [`invalid_task_type`](0061-error-format-and-definitions.md#invalid_task_type) error is returned. +- 🔴 If the `types` parameter value is not consistent with one of the task types, an [`invalid_task_types_filter`](0061-error-format-and-definitions.md#invalid_task_types_filter) error is returned. ###### 11.2.5. `canceledBy` -Filter tasks by the `taskCancelation` uid that canceled them. +Filter tasks by the `taskCancelation` uid that canceled them. It's possible to specify several task uids by separating them with the `,` character. - Type: Integer - Required: False @@ -699,7 +701,7 @@ Filter tasks by the `taskCancelation` uid that canceled them. `canceledBy` is **case-insensitive**. -- 🔴Sending a value with a different type than `Integer` for the `canceledBy` parameter returns an [`invalid_task_canceled_by`](0061-error-format-and-definitions.md#invalid_task_canceled_by) error. +- 🔴Sending a value with a different type than `Integer` for the `canceledBy` parameter returns an [`invalid_task_canceled_by_filter`](0061-error-format-and-definitions.md#invalid_task_canceled_by_filter) error. ###### 11.2.6. Date Parameters @@ -718,7 +720,7 @@ Filter tasks based on their enqueuedAt time. Retrieve tasks enqueued before/afte - Default: `*` - 🔴 The date filters are exclusive. It means the given value will not be included. -- 🔴 Sending an invalid value for the date parameter returns an [`invalid_task_date`](0061-error-format-and-definitions.md#invalid_task_date) error. +- 🔴 Sending an invalid value for the date parameter returns an [`invalid_task_date_filter`](0061-error-format-and-definitions.md#invalid_task_date_filter) error. ###### 11.2.6.2. `beforeStartedAt` and `afterStartedAt` @@ -729,7 +731,7 @@ Filter tasks based on their startedAt time. Retrieve tasks started before/after - Default: `*` - 🔴 The date filters are exclusive. It means the given value will not be included. -- 🔴 Sending an invalid value for the date parameter returns an [`invalid_task_date`](0061-error-format-and-definitions.md#invalid_task_date) error. +- 🔴 Sending an invalid value for the date parameter returns an [`invalid_task_date_filter`](0061-error-format-and-definitions.md#invalid_task_date_filter) error. ###### 11.2.6.3. `beforeFinishedAt` and `afterFinishedAt` @@ -740,14 +742,14 @@ Filter tasks based on their finishedAt time. Retrieve tasks finished before/afte - Default: `*` - 🔴 The date filters are exclusive. It means the given value will not be included. -- 🔴 Sending an invalid value for the date parameter returns an [`invalid_task_date`](0061-error-format-and-definitions.md#invalid_task_date) error.###### 11.2.6.4. Date Format +- 🔴 Sending an invalid value for the date parameter returns an [`invalid_task_date_filter`](0061-error-format-and-definitions.md#invalid_task_date_filter) error. ###### 11.2.7. Select multiple values for the same filter It is possible to specify multiple values for a filter using the `,` character. -For example, to select the `enqueued` and `processing` tasks of the `movies` and `movie_reviews` indexes, it is possible to express it like this: `/tasks?indexUid=movies,movie_reviews&status=enqueued,processing` +For example, to select the `enqueued` and `processing` tasks of the `movies` and `movie_reviews` indexes, it is possible to express it like this: `/tasks?indexUids=movies,movie_reviews&statuses=enqueued,processing` --- @@ -786,7 +788,7 @@ This part demonstrates filtering on `/tasks`. **Filter `tasks` that have a `failed` `status`** -`GET` - `/tasks?status=failed` +`GET` - `/tasks?statuses=failed` ```json { @@ -813,7 +815,7 @@ This part demonstrates filtering on `/tasks`. **Filter `tasks` that are of `documentAdditionOrUpdate` type** -`GET` - `/tasks?type=documentAdditionOrUpdate` +`GET` - `/tasks?types=documentAdditionOrUpdate` ```json { @@ -869,7 +871,7 @@ This part demonstrates filtering on `/tasks`. **Filter `tasks` that are of `documentAdditionOrUpdate` type and have a `failed` status** -`GET` - `/tasks?type=documentAdditionOrUpdate&status=failed` +`GET` - `/tasks?types=documentAdditionOrUpdate&statuses=failed` ```json { @@ -895,11 +897,11 @@ This part demonstrates filtering on `/tasks`. ``` - 💡 Filters can be used together. The two parameters are cumulated and a `AND` operation is performed between the two filters. An OR operation between filters is not supported. -- `type` and `status` query parameters can be read as is `type=documentsAdditionOrUpdate AND status=failed`. +- `types` and `statuses` query parameters can be read as is `types=documentsAdditionOrUpdate AND statuses=failed`. **Filter `tasks` by an non-existent `indexUid`** -`GET` - `/tasks?indexUid=aaaaa` +`GET` - `/tasks?indexUids=aaaaa` ```json { @@ -908,11 +910,11 @@ This part demonstrates filtering on `/tasks`. } ``` -- If the `indexUid` parameter value contains an inexistent index, it returns an empty `results` array. +- If the `indexUids` query parameter value contains an inexistent index, it returns an empty `results` array. **Cancel all the tasks with filter** -`POST` - `/taskscancel?status=processing,enqueued` +`POST` - `/tasks/cancel?statuses=processing,enqueued` ```json { diff --git a/text/0061-error-format-and-definitions.md b/text/0061-error-format-and-definitions.md index 21dc0fae..4a64e4e5 100644 --- a/text/0061-error-format-and-definitions.md +++ b/text/0061-error-format-and-definitions.md @@ -912,13 +912,13 @@ HTTP Code: `404 Not Found` --- -## invalid_task_uid +## invalid_task_uids_filter `Synchronous` ### Context -This error occurs when the `uid` query parameter contains invalid values. +This error occurs when the `uids` query parameter contains invalid values. ### Error Definition @@ -927,9 +927,9 @@ HTTP Code: `400 Bad Request` ```json { "message": "Task uid `:uid` is invalid. It should only contains numeric characters separated by `,` character.", - "code": "invalid_task_uid", + "code": "invalid_task_uids_filter", "type": "invalid_request", - "link": "https://docs.meilisearch.com/errors#invalid_task_uid" + "link": "https://docs.meilisearch.com/errors#invalid_task_uids_filter" } ``` @@ -937,7 +937,7 @@ HTTP Code: `400 Bad Request` --- -## invalid_task_date +## invalid_task_date_filter `Synchronous` @@ -952,9 +952,9 @@ HTTP Code: `400 Bad Request` ```json { "message": "Task `:dateFilterName` `:value` is invalid. It should follow the RFC 3339 format. e.g. 'YYYY-MM-DD' or 'YYYY-MM-DD HH:MM:SS'.", - "code": "invalid_task_date", + "code": "invalid_task_date_filter", "type": "invalid_request", - "link": "https://docs.meilisearch.com/errors#invalid_task_date" + "link": "https://docs.meilisearch.com/errors#invalid_task_date_filter" } ``` @@ -963,7 +963,7 @@ HTTP Code: `400 Bad Request` --- -## invalid_task_status +## invalid_task_statuses_filter `Synchronous` @@ -978,9 +978,9 @@ HTTP Code: `400 Bad Request` ```json { "message": "Task status `:status` is invalid. Available task statuses are: `:taskStatuses`.", - "code": "invalid_task_status", + "code": "invalid_task_statuses_filter", "type": "invalid_request", - "link":"https://docs.meilisearch.com/errors#invalid_task_status" + "link":"https://docs.meilisearch.com/errors#invalid_task_statuses_filter" } ``` @@ -989,7 +989,7 @@ HTTP Code: `400 Bad Request` --- -## invalid_task_type +## invalid_task_types_filter `Synchronous` @@ -1004,9 +1004,9 @@ HTTP Code: `400 Bad Request` ```json { "message": "Task type `:type` is invalid. Available task types are: `:taskTypes`.", - "code": "invalid_task_type", + "code": "invalid_task_types_filter", "type": "invalid_request", - "link":"https://docs.meilisearch.com/errors#invalid_task_type" + "link":"https://docs.meilisearch.com/errors#invalid_task_types_filter" } ``` @@ -1015,7 +1015,7 @@ HTTP Code: `400 Bad Request` --- -## invalid_task_canceled_by +## invalid_task_canceled_by_filter `Synchronous` @@ -1030,9 +1030,9 @@ HTTP Code: `400 Bad Request` ```json { "message": "Task canceledBy `:canceledBy` is invalid. It should only contains numeric characters.", - "code": "invalid_task_type", + "code": "invalid_task_canceled_by_filter", "type": "invalid_request", - "link":"https://docs.meilisearch.com/errors#invalid_task_canceled_by" + "link":"https://docs.meilisearch.com/errors#invalid_task_canceled_by_filter" } ``` From e9099f51c6105ac0952674b4401bc603b15e86d0 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Thu, 3 Nov 2022 18:19:39 +0100 Subject: [PATCH 67/76] Fix missing part of error msg --- text/0061-error-format-and-definitions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0061-error-format-and-definitions.md b/text/0061-error-format-and-definitions.md index 4a64e4e5..c9c2ae54 100644 --- a/text/0061-error-format-and-definitions.md +++ b/text/0061-error-format-and-definitions.md @@ -1029,7 +1029,7 @@ HTTP Code: `400 Bad Request` ```json { - "message": "Task canceledBy `:canceledBy` is invalid. It should only contains numeric characters.", + "message": "Task canceledBy `:canceledBy` is invalid. It should only contains numeric characters separated by `,` character.", "code": "invalid_task_canceled_by_filter", "type": "invalid_request", "link":"https://docs.meilisearch.com/errors#invalid_task_canceled_by_filter" From 58dbc764132ee461558e0734fdfe5bb241f849ea Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Thu, 3 Nov 2022 22:22:58 +0100 Subject: [PATCH 68/76] Precise valid date formats --- text/0060-tasks-api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 2a4f2011..18df2b09 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -707,9 +707,9 @@ Filter tasks by the `taskCancelation` uid that canceled them. It's possible to s Date filters accepts the RFC 3339 format. The following syntaxes are valid: -- `Y-M-D` -- `Y-M-DTH:M:SZ` -- `Y-M-DTH:M:S+01:00` +- `YYYY-MM-DD` +- `YYYY-MM-DDTHH:MM:SSZ` +- `YYYY-MM-DDTHH:MM:SS+01:00` ###### 11.2.6.1. `beforeEnqueuedAt` and `afterEnqueuedAt` From 904361467ef9cc04ec50a0712ff64f55c547433a Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Tue, 15 Nov 2022 15:37:09 +0100 Subject: [PATCH 69/76] Add supported format for date filters in open-api.yml --- open-api.yaml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/open-api.yaml b/open-api.yaml index 50cf93f4..890d5ce0 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -763,42 +763,42 @@ components: taskFilterBeforeEnqueuedAt: name: beforeEnqueuedAt in: query - description: Permits to filter tasks based on their enqueuedAt time. Matches tasks enqueued before the given date. + description: Permits to filter tasks based on their enqueuedAt time. Matches tasks enqueued before the given date. Supports RFC 3339 date format. required: false schema: type: string taskFilterAfterEnqueuedAt: name: afterEnqueuedAt in: query - description: Permits to filter tasks based on their enqueuedAt time. Matches tasks enqueued after the given date. + description: Permits to filter tasks based on their enqueuedAt time. Matches tasks enqueued after the given date. Supports RFC 3339 date format. required: false schema: type: string taskFilterBeforeStartedAt: name: beforeStartedAt in: query - description: Permits to filter tasks based on their startedAt time. Matches tasks started before the given date. + description: Permits to filter tasks based on their startedAt time. Matches tasks started before the given date. Supports RFC 3339 date format. required: false schema: type: string taskFilterAfterStartedAt: name: afterStartedAt in: query - description: Permits to filter tasks based on their startedAt time. Matches tasks started after the given date. + description: Permits to filter tasks based on their startedAt time. Matches tasks started after the given date. Supports RFC 3339 date format. required: false schema: type: string taskFilterBeforeFinishedAt: name: beforeFinishedAt in: query - description: Permits to filter tasks based on their finishedAt time. Matches tasks finished before the given date. + description: Permits to filter tasks based on their finishedAt time. Matches tasks finished before the given date. Supports RFC 3339 date format. required: false schema: type: string taskFilterAfterFinishedAt: name: afterFinishedAt in: query - description: Permits to filter tasks based on their finishedAt time. Matches tasks finished after the given date. + description: Permits to filter tasks based on their finishedAt time. Matches tasks finished after the given date. Supports RFC 3339 date format. required: false schema: type: string From 680d847e89ce4f0addbd324500dbf56965b25e53 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Tue, 15 Nov 2022 15:40:51 +0100 Subject: [PATCH 70/76] Update open-api.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Clément Renault --- open-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/open-api.yaml b/open-api.yaml index 890d5ce0..6f63d64a 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -735,7 +735,7 @@ components: taskFilterUids: name: uids in: query - description: Permits to filter tasks by their uid. By default, when the `uids` query parameter is not set, all task uids are returned. It's possible to specify several uids by separathing them with the `,` character. + description: Permits to filter tasks by their uid. By default, when the `uids` query parameter is not set, all task uids are returned. It's possible to specify several uids by separating them with the `,` character. required: false schema: type: number From 80593b072160a797c1e528862fe156b444b0695f Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Tue, 15 Nov 2022 15:41:04 +0100 Subject: [PATCH 71/76] Update text/0060-tasks-api.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Clément Renault --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 18df2b09..c5638edc 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -444,7 +444,7 @@ This means: ##### 6.3.4. Errors -If a user tries canceling a `succeeded`, `failed`, or `canceled` task, it won’t throw an error. Task cancelation is an atomic transaction; all tasks are successfully canceled, or none aren't. +If a user tries canceling a `succeeded`, `failed`, or `canceled` task, it won’t throw an error. Task cancelation is an atomic transaction; all tasks are successfully canceled, or none are. - 🔴 Sending a task cancelation without filtering query parameters returns a [missing_task_filters](0061-error-format-and-definitions.md#missing_task_filters) error. From 198d6a41eb2bcd2defb17f8e3520892cdfef113f Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Tue, 15 Nov 2022 15:42:15 +0100 Subject: [PATCH 72/76] fix typo --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index c5638edc..a13e7aad 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -147,7 +147,7 @@ List of global tasks by `type`: | Name | Description | | ------------- | ----------- | | matchedTasks | The number of tasks that can be canceled based on the request. If the API key doesn’t have access to any of the indexes specified in the request via the `indexUids` query parameter, those tasks will not be included in `matchedTasks`. | -| canceledTasks | The number of tasks successfully canceled. If the task fails, `0` is displayed. `null` when the task status is enqueud or processing. | +| canceledTasks | The number of tasks successfully canceled. If the task fails, `0` is displayed. `null` when the task status is enqueued or processing. | | originalFilters | The extracted URL query parameters used in the originating task cancelation request. | #### 5. Examples From 04ffeaf1b7226561689fb432ad9ee93734ae4a0c Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Mon, 21 Nov 2022 14:29:09 +0100 Subject: [PATCH 73/76] Update open-api.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Clément Renault --- open-api.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/open-api.yaml b/open-api.yaml index 6f63d64a..7769d7b9 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -348,9 +348,9 @@ components: canceledTasks: type: integer description: Number of tasks canceled. - originalFilters: + originalFilter: type: string - description: Filters used for the cancelation task. + description: Filter used for the cancelation task. error: description: Error object containing error details and context when a task has a failed status. $ref: '#/components/schemas/error' From f6a063d36b05e9a36cbe2afbadd7ba60cfbff9d0 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Mon, 21 Nov 2022 14:29:25 +0100 Subject: [PATCH 74/76] Update text/0060-tasks-api.md --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index a13e7aad..ccf6b852 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -148,7 +148,7 @@ List of global tasks by `type`: | ------------- | ----------- | | matchedTasks | The number of tasks that can be canceled based on the request. If the API key doesn’t have access to any of the indexes specified in the request via the `indexUids` query parameter, those tasks will not be included in `matchedTasks`. | | canceledTasks | The number of tasks successfully canceled. If the task fails, `0` is displayed. `null` when the task status is enqueued or processing. | -| originalFilters | The extracted URL query parameters used in the originating task cancelation request. | +| originalFilter | The extracted URL query parameters used in the originating task cancelation request. | #### 5. Examples From 12539223a2121570fd4c0a31350b7a9a92f0ec73 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Wed, 23 Nov 2022 15:02:07 +0100 Subject: [PATCH 75/76] Update text/0060-tasks-api.md --- text/0060-tasks-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index ccf6b852..6b51f0d3 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -140,7 +140,7 @@ List of global tasks by `type`: | name | description | | ----- | ------------ | -| dumpUid | The generated uid of the dump. `null` when the task status is enqueued or processing. | +| dumpUid | The generated uid of the dump. `null` when the task status is enqueued, processing, canceled, or failed. | ##### taskCancelation From 15ac726b2ed4b943f9c5a60697c21d8e05ee01f6 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Tue, 29 Nov 2022 16:05:07 +0100 Subject: [PATCH 76/76] Tasks API - Add task deletion capability (#198) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Describes task deletion feature additions * Update open-api.yml * Update telemetry-policies * Update originalQuery to originalFilters * Follow title structure * Introduce review feedback * Branch the right components * Update text/0060-tasks-api.md Co-authored-by: Clément Renault Co-authored-by: Clément Renault --- open-api.yaml | 56 +++++++++++++++++++++-- text/0034-telemetry-policies.md | 40 +++++++++++----- text/0060-tasks-api.md | 51 +++++++++++++++++++-- text/0061-error-format-and-definitions.md | 2 +- text/0085-api-keys.md | 3 +- 5 files changed, 133 insertions(+), 19 deletions(-) diff --git a/open-api.yaml b/open-api.yaml index 7e9b2e5a..fd456eb2 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -315,6 +315,7 @@ components: - settingsUpdate - dumpCreation - taskCancelation + - taskDeletion - snapshotCreation canceledBy: type: integer @@ -345,13 +346,16 @@ components: description: Identifier generated for the dump for dumpCreation task. matchedTasks: type: integer - description: Number of tasks that match the task cancelation request. + description: Number of tasks that match the request for taskCancelation or taskDeletion tasks. canceledTasks: type: integer - description: Number of tasks canceled. + description: Number of tasks canceled for taskCancelation. + deletedTasks: + type: integer + description: Number of tasks deleted for taskDeletion. originalFilter: type: string - description: Filter used for the cancelation task. + description: Original filter query for taskCancelation or taskDeletion tasks. error: description: Error object containing error details and context when a task has a failed status. $ref: '#/components/schemas/error' @@ -412,6 +416,7 @@ components: - settingsUpdate - dumpCreation - taskCancelation + - taskDeletion enqueuedAt: description: Represent the date and time as a `RFC 3339` format when the task has been enqueued $ref: '#/components/schemas/timestamp' @@ -661,6 +666,7 @@ components: - indexes.delete - tasks.get - tasks.cancel + - tasks.delete - settings.get - settings.update - stats.get @@ -1111,6 +1117,14 @@ components: status: enqueued type: taskCancelation enqueuedAt: '2021-01-01T09:39:00.000000Z' + 202_taskDeletion: + summary: 202 Accepted taskDeletion response example + value: + taskUid: 0 + indexUid: null + status: enqueued + type: taskDeletion + enqueuedAt: '2021-01-01T09:39:00.000000Z' 202_indexSwap: summary: 202 Accepted indexSwap response example value: @@ -3479,6 +3493,42 @@ paths: - $ref: '#/components/parameters/taskFilterAfterFinishedAt' security: - apiKey: [] + delete: + summary: Delete tasks + description: 'Delete finished [tasks](https://docs.meilisearch.com/lean/advanced/asynchronous_operations.html)' + tags: + - tasks + responses: + '202': + description: Accepted + content: + application/json: + schema: + $ref: '#/components/schema/summarizedTask' + examples: + '202': + $ref: '#/components/examples/202_taskDeletion' + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/error' + operationId: tasks.delete + parameters: + - $ref: '#/components/parameters/taskFilterUids' + - $ref: '#/components/parameters/taskFilterIndexUids' + - $ref: '#/components/parameters/taskFilterStatuses' + - $ref: '#/components/parameters/taskFilterTypes' + - $ref: '#/components/parameters/taskFilterCanceledBy' + - $ref: '#/components/parameters/taskFilterBeforeEnqueuedAt' + - $ref: '#/components/parameters/taskFilterAfterEnqueuedAt' + - $ref: '#/components/parameters/taskFilterBeforeStartedAt' + - $ref: '#/components/parameters/taskFilterAfterStartedAt' + - $ref: '#/components/parameters/taskFilterBeforeFinishedAt' + - $ref: '#/components/parameters/taskFilterAfterFinishedAt' + security: + - apiKey: [] '/tasks/:taskUid': get: summary: Get a task diff --git a/text/0034-telemetry-policies.md b/text/0034-telemetry-policies.md index cb6cc919..73b573f2 100644 --- a/text/0034-telemetry-policies.md +++ b/text/0034-telemetry-policies.md @@ -60,6 +60,7 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat | Synonyms Updated | Occurs when synonyms are updated via `PUT` — `/indexes/:indexUid/settings/synonyms`. | | Dump Created | Occurs when a dump is created via `POST` - `/dumps`. | | Tasks Canceled | Occurs when tasks are requested to be canceled via `POST` - `/tasks/cancel`. | +| Tasks Deleted | Occurs when tasks are requested to be deleted via `DELETE`- `/tasks`. | | Tasks Seen | Aggregated event on all received requests via the `GET` - `/tasks` route during one hour or until a batch size reaches `500Kb`. | | Stats Seen | Occurs when stats are fetched via `GET` - `/stats` or `/indexes/:indexUid/stats`. | | Health Seen | Aggregated event on all received requests via the `GET - /health` route during one hour or until a batch size reaches `500Kb`. | @@ -159,17 +160,17 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat | `stop_words.total` | Number of stop words. | `3` | `Settings Updated`, `StopWords Updated` | | `synonyms.total` | Number of synonyms. | `3` | `Settings Updated`, `Synonyms Updated` | | `per_task_uid` | `true` if an uid is used to fetch a particular task resource, otherwise `false` | true | `Tasks Seen` | -| `filtered_by_uid` | `true` if tasks are filtered by the `uids` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | -| `filtered_by_index_uid` | `true` if tasks are filtered by the `indexUids` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | -| `filtered_by_type` | `true` if tasks are filtered by the `types` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | -| `filtered_by_status` | `true` if tasks are filtered by the `statuses` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | -| `filtered_by_canceled_by` | `true` if tasks are filtered by the `canceledBy` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | -| `filtered_by_before_enqueued_at` | `true` if tasks are filtered by the `beforeEnqueuedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | -| `filtered_by_after_enqueued_at ` | `true` if tasks are filtered by the `afterEnqueuedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | -| `filtered_by_before_started_at` | `true` if tasks are filtered by the `beforeStartedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | -| `filtered_by_after_started_at` | `true` if tasks are filtered by the `afterStartedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | -| `filtered_by_before_finished_at` | `true` if tasks are filtered by the `beforeFinishedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | -| `filtered_by_after_finished_at` | `true` if tasks are filtered by the `afterFinishedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` | +| `filtered_by_uid` | `true` if tasks are filtered by the `uids` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled`, `Tasks Deleted` | +| `filtered_by_index_uid` | `true` if tasks are filtered by the `indexUids` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled`, `Tasks Deleted` | +| `filtered_by_type` | `true` if tasks are filtered by the `types` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled`, `Tasks Deleted` | +| `filtered_by_status` | `true` if tasks are filtered by the `statuses` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled`, `Tasks Deleted` | +| `filtered_by_canceled_by` | `true` if tasks are filtered by the `canceledBy` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled`, `Tasks Deleted` | +| `filtered_by_before_enqueued_at` | `true` if tasks are filtered by the `beforeEnqueuedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled`, `Tasks Deleted` | +| `filtered_by_after_enqueued_at ` | `true` if tasks are filtered by the `afterEnqueuedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled`, `Tasks Deleted` | +| `filtered_by_before_started_at` | `true` if tasks are filtered by the `beforeStartedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled`, `Tasks Deleted` | +| `filtered_by_after_started_at` | `true` if tasks are filtered by the `afterStartedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled`, `Tasks Deleted` | +| `filtered_by_before_finished_at` | `true` if tasks are filtered by the `beforeFinishedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled`, `Tasks Deleted` | +| `filtered_by_after_finished_at` | `true` if tasks are filtered by the `afterFinishedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled`, `Tasks Deleted` | | `per_index_uid` | `true` if an uid is used to fetch an index stat resource, otherwise `false` | false | `Stats Seen` | | `swap_operation_number` | The number of swap operation given in `POST /swap-indexes` API call | 2 | `Indexes Swapped` | | `matching_strategy.most_used_strategy` | Most used word matching strategy among all search requests in this batch | `last` | `Documents Searched POST`, `Documents Searched GET` | @@ -544,6 +545,23 @@ This property allows us to gather essential information to better understand on | filtered_by_before_finished_at | `true` if tasks are filtered by the `beforeFinishedAt` query parameter, otherwise `false` | false | | filtered_by_after_finished_at | `true` if tasks are filtered by the `afterFinishedAt` query parameter, otherwise `false` | false | +## `Tasks Deleted` + +| Property name | Description | Example | +|---------------|-------------|---------| +| user_agent | Represents the user-agent encountered on this call. | `["Meilisearch Ruby (v2.1)", "Ruby (3.0)"]` | +| filtered_by_uid | `true` if tasks are filtered by the `uids` query parameter, otherwise `false` | false | +| filtered_by_index_uid | `true` if tasks are filtered by the `indexUids` query parameter, otherwise `false` | false | +| filtered_by_type | `true` if tasks are filtered by the `types` query parameter, otherwise `false` | false | +| filtered_by_status | `true` if tasks are filtered by the `statuses` query parameter, otherwise `false` | false | +| filtered_by_canceled_by | `true` if tasks are filtered by the `canceledBy` query parameter, otherwise `false` | false | +| filtered_by_before_enqueued_at | `true` if tasks are filtered by the `beforeEnqueuedAt` query parameter, otherwise `false` | false | +| filtered_by_after_enqueued_at | `true` if tasks are filtered by the `afterEnqueuedAt` query parameter, otherwise `false` | false | +| filtered_by_before_started_at | `true` if tasks are filtered by the `beforeStartedAt` query parameter, otherwise `false` | false | +| filtered_by_after_started_at | `true` if tasks are filtered by the `afterStartedAt` query parameter, otherwise `false` | false | +| filtered_by_before_finished_at | `true` if tasks are filtered by the `beforeFinishedAt` query parameter, otherwise `false` | false | +| filtered_by_after_finished_at | `true` if tasks are filtered by the `afterFinishedAt` query parameter, otherwise `false` | false | + ## `Stats Seen` | Property name | Description | Example | diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index dd89b369..ffabdebb 100644 --- a/text/0060-tasks-api.md +++ b/text/0060-tasks-api.md @@ -8,7 +8,7 @@ This specification describes the API endpoints for handling asynchronous tasks. ### II. Motivation -As writing is asynchronous for most of Meilisearch's operations, this API allows users to track the progress of asynchronous tasks, know and understand why a task has failed, and cancel specific tasks being enqueued or processing. +As writing is asynchronous for most of Meilisearch's operations, this API allows users to track the progress of asynchronous tasks, know and understand why a task has failed, and cancel specific tasks being enqueued or processing. It's also possible to delete tasks being in a finished state. ### III. Explanation @@ -44,6 +44,7 @@ List of global tasks by `type`: - `dumpCreation` - `taskCancelation` +- `taskDeletion` ##### Summarized `task` Object for `202 Accepted` @@ -83,6 +84,7 @@ List of global tasks by `type`: | settingsUpdate | | dumpCreation | | taskCancelation | +| taskDeletion | | snapshotCreation | > 👍 Type values follow a `camelCase` naming convention. @@ -158,6 +160,14 @@ List of global tasks by `type`: | canceledTasks | The number of tasks successfully canceled. If the task fails, `0` is displayed. `null` when the task status is enqueued or processing. | | originalFilter | The extracted URL query parameters used in the originating task cancelation request. | +##### taskDeletion + +| Name | Description | +|---------------|-------------| +| matchedTasks | The number of tasks that can be deleted based on the request. If the API key doesn’t have access to any of the indexes specified in the request via the `indexUid` query parameter, those tasks will not be included in `matchedTasks`. | +| deletedTasks | The number of tasks successfully deleted. If the task fails, `0` is displayed. `null` when the task status is enqueud or processing. | +| originalFilter | The extracted URL query parameters used in the originating task deletion request. | + ##### snapshotCreation N/A @@ -459,7 +469,42 @@ This means: If a user tries canceling a `succeeded`, `failed`, or `canceled` task, it won’t throw an error. Task cancelation is an atomic transaction; all tasks are successfully canceled, or none are. -- 🔴 Sending a task cancelation without filtering query parameters returns a [missing_task_filters](0061-error-format-and-definitions.md#missing_task_filters) error. +- 🔴 Sending a task cancelation without filtering query parameters returns a [missing_task_filters](0061-error-format-and-definitions.md#missing_task_filters) error. + +The auth layer can return the following errors if Meilisearch is secured (a master-key is defined). + +- 🔴 Accessing this route without the `Authorization` header returns a [missing_authorization_header](0061-error-format-and-definitions.md#missing_authorization_header) error. +- 🔴 Accessing this route with a key that does not have the required permissions (i.e. other than the master-key) returns an [invalid_api_key](0061-error-format-and-definitions.md#invalid_api_key) error. + +--- + +##### 6.4 Delete tasks | `DELETE` - `/tasks` + +##### 6.4.1 Goals + +Allows users to delete a finished (`succeeded`, `processing` or `canceled`) tasks. + +`202` - Response body - `/tasks` + +```json +{ + "taskUid": 0, + "indexUid": null, + "status": "enqueued", + "type": "taskDeletion", + "enqueuedAt": "2021-08-12T10:00:00.000000Z" +} +``` + +##### 6.4.2. Response Definition + +When the request is successful, Meilisearch returns the HTTP code 202 Accepted. The response's content is the summarized representation of the received asynchronous task. + +##### 6.4.3. Errors + +If a user tries deleting an `enqueued`, or `processing` task, it won’t throw an error. Task deletion is an atomic transaction; all tasks are successfully deleted, or none aren't. + +- 🔴 Sending a task deletion without filtering query parameters returns a [missing_task_filters](0061-error-format-and-definitions.md#missing_task_filters) error. The auth layer can return the following errors if Meilisearch is secured (a master-key is defined). @@ -472,7 +517,7 @@ The auth layer can return the following errors if Meilisearch is secured (a mast ##### Context -This error happens when a requested task can't be found. +This error happens when a requested task can't be found. Fetching a deleted task returns a `task_not_found` error. ##### Error Definition diff --git a/text/0061-error-format-and-definitions.md b/text/0061-error-format-and-definitions.md index fa560d21..3ac62b74 100644 --- a/text/0061-error-format-and-definitions.md +++ b/text/0061-error-format-and-definitions.md @@ -1113,7 +1113,7 @@ HTTP Code: `400 Bad Request` ### Context -This error happens when no query parameters are given when a task cancelation request is send. +This error happens when no query parameters are given when a task cancelation or a task deletion request is sent. ### Error Definition diff --git a/text/0085-api-keys.md b/text/0085-api-keys.md index 389e791f..c064b48a 100644 --- a/text/0085-api-keys.md +++ b/text/0085-api-keys.md @@ -316,6 +316,7 @@ Create an API key. | indexes.swap | Provides access to `POST` `/swap-indexes`. See [Swap Indexes API](0191-swap-indexes-api.md) specification. | | tasks.get | Provides access to `GET` `/tasks`. **⚠️Non-authorized `indexes` are omitted from the response on `/tasks`**. Also add access to `GET` `/indexes/:authorizedIndexes/tasks` routes. | | tasks.cancel | Provides access to `POST` `/tasks/cancel`. route. | +| tasks.delete | Provides access to `DELETE` `/tasks` route. | | settings.get | Provides access to `GET` `/indexes/:authorizedIndexes/settings` and `/indexes/:authorizedIndexes/settings/*` routes. | | settings.update | Provides access to `POST / DELETE` `/indexes/:authorizedIndexes/settings` and `/indexes/:authorizedIndexes/settings/*` routes. | | stats.get | Provides access to `GET` `/stats/`. **⚠️Non-authorized `indexes` are omitted from the response on `/stats`**. Also add access to `GET` `/indexes/:authorizedIndexes/stats`. | @@ -464,4 +465,4 @@ The maximum size of the API key storage layer is `100GB`. - A restriction on the maximum offset/limit. - Add search parameters restrictions for an API Key. - Add rfc2822 format expression for `expiredAt` field. e.g. `Wed, 18 Feb 2022 23:16:09 GMT` -- Add an alias that can only be associated to one API Key to retrieve it easily on client side. e.g. `GET /keys/:uid_or_alias` \ No newline at end of file +- Add an alias that can only be associated to one API Key to retrieve it easily on client side. e.g. `GET /keys/:uid_or_alias`