diff --git a/open-api.yaml b/open-api.yaml index 47dea996..fd456eb2 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 @@ -313,7 +314,12 @@ components: - indexDeletion - settingsUpdate - dumpCreation + - taskCancelation + - taskDeletion - snapshotCreation + canceledBy: + type: integer + 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. @@ -329,7 +335,7 @@ components: description: Number of provided document ids for the 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. @@ -338,6 +344,18 @@ components: dumpUid: type: string description: Identifier generated for the dump for dumpCreation task. + matchedTasks: + type: integer + description: Number of tasks that match the request for taskCancelation or taskDeletion tasks. + canceledTasks: + type: integer + description: Number of tasks canceled for taskCancelation. + deletedTasks: + type: integer + description: Number of tasks deleted for taskDeletion. + originalFilter: + type: string + 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' @@ -361,6 +379,9 @@ components: - indexUid - status - type + - canceledBy + - details + - error - enqueuedAt - startedAt - finishedAt @@ -394,6 +415,8 @@ components: - indexDeletion - 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' @@ -642,6 +665,8 @@ components: - indexes.update - indexes.delete - tasks.get + - tasks.cancel + - tasks.delete - settings.get - settings.update - stats.get @@ -724,28 +749,84 @@ components: taskUid: name: taskUid in: path - description: The task unique identifier + description: The task identifier required: true + schema: + type: integer + 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 separating them with the `,` character. + required: false schema: type: number - taskIndexUid: - name: indexUid + taskFilterIndexUids: + name: indexUids + in: query + 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 + taskFilterTypes: + name: types + in: query + 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 + taskFilterStatuses: + name: statuses + in: query + 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 + taskFilterBeforeEnqueuedAt: + name: beforeEnqueuedAt + in: query + 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. 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. Supports RFC 3339 date format. + required: false + schema: + type: string + taskFilterAfterStartedAt: + name: afterStartedAt 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 based on their startedAt time. Matches tasks started after the given date. Supports RFC 3339 date format. required: false schema: type: string - taskType: - name: type + taskFilterBeforeFinishedAt: + name: beforeFinishedAt 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 based on their finishedAt time. Matches tasks finished before the given date. Supports RFC 3339 date format. required: false schema: type: string - taskStatus: - name: status + taskFilterAfterFinishedAt: + name: afterFinishedAt 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 based on their finishedAt time. Matches tasks finished after the given date. Supports RFC 3339 date format. + required: false + schema: + type: string + taskFilterCanceledBy: + name: canceledBy + in: query + 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 @@ -1028,6 +1109,22 @@ 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' + 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: @@ -3350,9 +3447,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' @@ -3361,6 +3460,7 @@ paths: indexUid: movies_Review status: failed type: documentAdditionOrUpdate + canceledBy: null details: receivedDocuments: 67493 indexedDocuments: 0 @@ -3380,9 +3480,53 @@ paths: parameters: - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/from' - - $ref: '#/components/parameters/taskIndexUid' - - $ref: '#/components/parameters/taskStatus' - - $ref: '#/components/parameters/taskType' + - $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: [] + 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': @@ -3405,9 +3549,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' @@ -3428,11 +3574,49 @@ paths: type: invalid_request link: 'https://docs.meilisearch.com/errors/#task_not_found' operationId: tasks.get - parameters: [] + parameters: + - $ref: '#/components/parameters/taskUid' + security: + - apiKey: [] + '/tasks/cancel': + post: + summary: Cancel tasks + description: 'Cancel enqueued and/or processing [tasks](https://docs.meilisearch.com/learn/advanced/asynchronous_operations.html) ' + tags: + - tasks + responses: + '202': + description: Accepted + content: + application/json: + schema: + $ref: '#/components/schemas/summarizedTask' + examples: + '202': + $ref: '#/components/examples/202_taskCancelation' + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/error' + '401': + $ref: '#/components/responses/401' + operationId: tasks.cancel + 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: [] - parameters: - - $ref: '#/components/parameters/taskUid' '/swap-indexes': post: operationId: indexes.swap diff --git a/text/0034-telemetry-policies.md b/text/0034-telemetry-policies.md index abbb8563..73b573f2 100644 --- a/text/0034-telemetry-policies.md +++ b/text/0034-telemetry-policies.md @@ -59,10 +59,13 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat | StopWords Updated | Occurs when stop words are updated via `PUT` — `/indexes/:indexUid/settings/stop-words`. | | 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`. | | Version Seen | Occurs when `GET - /version` is fetched. | + ---- #### Summarized Metrics/Events table @@ -157,9 +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_index_uid` | `true` if `GET /tasks` endpoint is filtered by `indexUid`, otherwise `false` | false | `Tasks Seen` | -| `filtered_by_type` | `true` if `GET /tasks` endpoint is filtered by `type`, otherwise `false` | false | `Tasks Seen` | -| `filtered_by_status` | `true` if `GET /tasks` endpoint is filtered by `status`, otherwise `false` | false | `Tasks Seen` | +| `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` | @@ -505,9 +516,51 @@ This property allows us to gather essential information to better understand on | user_agent | Represents the user-agent encountered on this endpoint in the aggregated event. | `["Meilisearch Ruby (v2.1)", "Ruby (3.0)"]` | | requests.total_received | The total number of received requests in the aggregated event. | `3480` | | 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` | +| 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 | + +## `Tasks Canceled` + +| 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 | + +## `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` diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md index 72b580e6..ffabdebb 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 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 @@ -20,27 +20,40 @@ As writing is asynchronous for most of Meilisearch's operations, this API makes | field | type | description | |------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| 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`, `indexSwap`, `documentAdditionOrUpdate`, `documentDeletion`, `settingsUpdate`, `dumpCreation`, `snapshopCreation` | +| 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`, `indexSwap`, `documentAdditionOrUpdate`, `documentDeletion`, `settingsUpdate`, `dumpCreation`, `taskCancelation`, `snapshotCreation` | | +| 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) | +| 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. +###### Global task + +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. + +List of global tasks by `type`: + +- `dumpCreation` +- `taskCancelation` +- `taskDeletion` + ##### 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](#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 | @@ -56,6 +69,7 @@ As writing is asynchronous for most of Meilisearch's operations, this API makes | processing | | succeeded | | failed | +| canceled | #### 3. `type` field enum @@ -69,6 +83,8 @@ As writing is asynchronous for most of Meilisearch's operations, this API makes | documentDeletion | | settingsUpdate | | dumpCreation | +| taskCancelation | +| taskDeletion | | snapshotCreation | > 👍 Type values follow a `camelCase` naming convention. @@ -80,13 +96,13 @@ As writing is asynchronous for most of Meilisearch's operations, this API makes | 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 | |---------------------|--------------------------------------| -| providedIds | Number of provided document ids. | +| providedIds | Number of provided document ids. | | deletedDocuments | Number of documents finally deleted. | ##### indexCreation @@ -106,7 +122,7 @@ As writing is asynchronous for most of Meilisearch's operations, this API makes | 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. | ##### indexSwap @@ -134,11 +150,23 @@ As writing is asynchronous for most of Meilisearch's operations, this API makes | name | description | | ----- | ------------ | -| dumpUid | The generated uid of the dump | +| dumpUid | The generated uid of the dump. `null` when the task status is enqueued, processing, canceled, or failed. | + +##### 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 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. | +| originalFilter | The extracted URL query parameters used in the originating task cancelation request. | -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. +##### taskDeletion -Fully qualified and summarized task objects related to a dump creation display a `null` `indexUid` field. +| 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 @@ -155,6 +183,7 @@ e.g. A fully qualified `task` object in an `enqueued` state. "indexUid": "movies", "status": "enqueued", "type": "settingsUpdate", + "canceledBy": null, "details": { "rankingRules": [ "typo", @@ -165,6 +194,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, @@ -180,6 +210,7 @@ e.g. A fully qualified `task` object in a `processing` state. "indexUid": "movies", "status": "processing", "type": "settingsUpdate", + "canceledBy": null, "details": { "rankingRules": [ "typo", @@ -190,6 +221,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", @@ -205,6 +237,7 @@ e.g. A fully qualified `task` object in a `succeeded` state. "indexUid": "movies", "status": "succeeded", "type": "settingsUpdate", + "canceledBy": null, "details": { "rankingRules": [ "typo", @@ -215,6 +248,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", @@ -230,6 +264,7 @@ e.g. A fully qualified `task` object in a `failed` state. "indexUid": "movies", "status": "failed", "type": "settingsUpdate", + "canceledBy": null, "details": { "rankingRules": [ "typo", @@ -254,6 +289,33 @@ 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", + "canceledBy": 1, + "details": { + "rankingRules": [ + "typo", + "ranking:desc", + "words", + "proximity", + "attribute", + "exactness" + ] + }, + "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" +} +``` + e.g. A summarized `task` object in a `202 Accepted` HTTP response returned at index creation. ```json @@ -270,9 +332,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. @@ -286,6 +348,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, @@ -295,11 +363,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", @@ -309,7 +379,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. > @@ -319,7 +389,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). @@ -328,9 +398,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. @@ -342,6 +412,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, @@ -349,7 +424,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. @@ -360,11 +435,89 @@ 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/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/cancel` + +```json +{ + "taskUid": 0, + "indexUid": null, + "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. Auto-batching + +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. +- 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 are. + +- 🔴 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). + +- 🔴 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 -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 @@ -381,23 +534,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. +The API endpoint `GET /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`. @@ -405,11 +558,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 | |-------|------|--------------------------------------| @@ -417,14 +570,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. @@ -513,34 +666,152 @@ 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 -The `/tasks` endpoint is filterable by `indexUid`, `type` and `status` query parameters. +The tasks API endpoints are filterable by `uids`, `indexUids`, `types`, `statuses`, `canceledBy`, `beforeEnqueuedAt`, `afterEnqueuedAt`, `beforeStartedAt`, `afterStartedAt`, `beforeFinishedAt`, `afterFinishedAt` query parameters. -##### 10.1. Query parameters definition +##### 11.1 Query parameters definition | 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. | +| 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. | +| 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. | + +##### 11.2. Query Parameters Behaviors + +###### 11.2.1. `uids` + + 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: `*` -##### 10.2. Usages examples +`uids` is **case-unsensitive**. + +- 🔴 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. `indexUids` + +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: `*` + +`indexUids` is **case-sensitive**. + +###### 11.2.3. `statuses` + +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: `*` + +`statuses` is **case-insensitive**. + +- 🔴 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. + +###### 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: `*` + +`types` is **case-insensitive**. + +- 🔴 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. It's possible to specify several task uids by separating them with the `,` character. + +- Type: Integer +- Required: False +- Default: `null` + +`canceledBy` is **case-insensitive**. + +- 🔴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 + +Date filters accepts the RFC 3339 format. The following syntaxes are valid: + +- `YYYY-MM-DD` +- `YYYY-MM-DDTHH:MM:SSZ` +- `YYYY-MM-DDTHH:MM:SS+01:00` + +###### 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: `*` + +- 🔴 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_filter`](0061-error-format-and-definitions.md#invalid_task_date_filter) error. + +###### 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: `*` + +- 🔴 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_filter`](0061-error-format-and-definitions.md#invalid_task_date_filter) error. + +###### 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: `*` + +- 🔴 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_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?indexUids=movies,movie_reviews&statuses=enqueued,processing` + +--- + +##### 11.3. Usages examples This part demonstrates filtering on `/tasks`. @@ -575,7 +846,7 @@ This part demonstrates filtering on `/tasks`. **Filter `tasks` that have a `failed` `status`** -`GET` - `/tasks?status=failed` +`GET` - `/tasks?statuses=failed` ```json { @@ -602,7 +873,7 @@ This part demonstrates filtering on `/tasks`. **Filter `tasks` that are of `documentAdditionOrUpdate` type** -`GET` - `/tasks?type=documentAdditionOrUpdate` +`GET` - `/tasks?types=documentAdditionOrUpdate` ```json { @@ -627,9 +898,38 @@ This part demonstrates filtering on `/tasks`. } ``` +**Filter `canceled` tasks by `canceledBy` parameter** + +`GET` `tasks?canceledBy=1` + +```json +{ + "results": [ + { + "uid": 1350, + "indexUid": "movies", + "status": "canceled", + "type": "documentAdditionOrUpdate", + "canceledBy": 1, + ..., + }, + ..., + { + "uid": 1343, + "indexUid": "movies", + "status": "canceled", + "type": "documentAdditionOrUpdate", + "canceledBy": 1, + ..., + } + ], + ... +} +``` + **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 { @@ -655,11 +955,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 { @@ -668,50 +968,30 @@ 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. ---- - -##### 10.3. Behaviors for `indexUid`, `status` and `type` query parameters. - -###### 10.3.1. `indexUid` +**Cancel all the tasks with filter** -- Type: String -- Required: False -- Default: `*` +`POST` - `/tasks/cancel?statuses=processing,enqueued` -`indexUid` is **case-sensitive**. - -###### 10.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` - -- 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. - -###### 10.3.4. Select multiple values for the same filter - -It is possible to specify multiple values for a filter using the `,` character. +```json +{ + "taskUid": 1, + "indexUid": null, + "status": "enqueued", + "type": "taskCancelation", + "enqueuedAt": "2021-08-12T10:00:00.000000Z" +} +``` -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.4. Empty `results` If no results match the filters. A response is returned with an empty `results` array. +--- + ## 2. Technical details ### 2.1. Tasks Priority diff --git a/text/0061-error-format-and-definitions.md b/text/0061-error-format-and-definitions.md index 265d79d6..3ac62b74 100644 --- a/text/0061-error-format-and-definitions.md +++ b/text/0061-error-format-and-definitions.md @@ -979,7 +979,60 @@ HTTP Code: `404 Not Found` --- -## invalid_task_status +## invalid_task_uids_filter + +`Synchronous` + +### Context + +This error occurs when the `uids` query parameter contains invalid values. + +### Error Definition + +HTTP Code: `400 Bad Request` + +```json +{ + "message": "Task uid `:uid` is invalid. It should only contains numeric characters separated by `,` character.", + "code": "invalid_task_uids_filter", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#invalid_task_uids_filter" +} +``` + +- `:uid` is inferred when the message is generated. + +--- + +## invalid_task_date_filter + +`Synchronous` + +### Context + +This error occurs when a task date filter contains an invalid value. + +### Error Definition + +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_filter", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#invalid_task_date_filter" +} +``` + +- `:dateFilterName` is inferred when the message is generated. +- `:value` is inferred when the message is generated. + +--- + +## invalid_task_statuses_filter + +`Synchronous` ### Context @@ -992,9 +1045,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" } ``` @@ -1003,7 +1056,9 @@ HTTP Code: `400 Bad Request` --- -## invalid_task_type +## invalid_task_types_filter + +`Synchronous` ### Context @@ -1016,9 +1071,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" } ``` @@ -1027,6 +1082,57 @@ HTTP Code: `400 Bad Request` --- +## invalid_task_canceled_by_filter + +`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 separated by `,` character.", + "code": "invalid_task_canceled_by_filter", + "type": "invalid_request", + "link":"https://docs.meilisearch.com/errors#invalid_task_canceled_by_filter" +} +``` + +- `: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 or a task deletion request is sent. + +### 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` diff --git a/text/0085-api-keys.md b/text/0085-api-keys.md index b7d092b9..c064b48a 100644 --- a/text/0085-api-keys.md +++ b/text/0085-api-keys.md @@ -315,6 +315,8 @@ Create an API key. | indexes.delete | Provides access to `DELETE` `/indexes/:authorizedIndexes`. | | 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`. | @@ -463,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`