diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 60c51a7ff..e73686f8c 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -1201,6 +1201,28 @@ update_proximity_precision_settings_1: |- reset_proximity_precision_settings_1: |- curl \ -X DELETE 'http://localhost:7700/indexes/books/settings/proximity-precision' +get_facet_search_settings_1: |- + curl \ + -X GET 'http://localhost:7700/indexes/INDEX_UID/settings/facet-search' +update_facet_search_settings_1: |- + curl \ + -X PUT 'http://localhost:7700/indexes/INDEX_UID/settings/facet-search' \ + -H 'Content-Type: application/json' \ + --data-binary 'false' +reset_facet_search_settings_1: |- + curl \ + -X DELETE 'http://localhost:7700/indexes/INDEX_UID/settings/facet-search' +get_prefix_search_settings_1: |- + curl \ + -X GET 'http://localhost:7700/indexes/INDEX_UID/settings/prefix-search' +update_prefix_search_settings_1: |- + curl \ + -X PUT 'http://localhost:7700/indexes/INDEX_UID/settings/prefix-search' \ + -H 'Content-Type: application/json' \ + --data-binary '"disabled"' +reset_prefix_search_settings_1: |- + curl \ + -X DELETE 'http://localhost:7700/indexes/INDEX_UID/settings/prefix-search' index_settings_tutorial_api_get_setting_1: |- curl \ -X GET 'http://localhost:7700/indexes/INDEX_NAME/settings/searchable-attributes' @@ -1348,6 +1370,12 @@ update_localized_attribute_settings_1: |- reset_localized_attribute_settings_1: |- curl \ -X DELETE 'http://localhost:7700/indexes/INDEX_NAME/settings/localized-attributes' +get_all_batches_1: |- + curl \ + -X GET 'http://localhost:7700/batches' +get_batch_1: |- + curl \ + -X GET 'http://localhost:7700/batches/BATCH_UID' ### Code samples for experimental features get_embedders_1: |- diff --git a/assets/misc/meilisearch-collection-postman.json b/assets/misc/meilisearch-collection-postman.json index ac16f5d1f..babcfa407 100644 --- a/assets/misc/meilisearch-collection-postman.json +++ b/assets/misc/meilisearch-collection-postman.json @@ -1,7 +1,7 @@ { "info": { "_postman_id": "cc6bb097-033d-4f65-8704-f10e4e4b10d0", - "name": "Meilisearch v1.11", + "name": "Meilisearch v1.12", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "_exporter_id": "25294324" }, @@ -652,6 +652,11 @@ "value": "3", "disabled": true }, + { + "key": "batchUids", + "value": "0", + "disabled": true + }, { "key": "indexUids", "value": "books", @@ -669,37 +674,37 @@ }, { "key": "beforeEnqueuedAt", - "value": null, + "value": "", "disabled": true }, { "key": "afterEnqueuedAt", - "value": null, + "value": "", "disabled": true }, { "key": "beforeStartedAt", - "value": null, + "value": "", "disabled": true }, { "key": "afterStartedAt", - "value": null, + "value": "", "disabled": true }, { "key": "beforeFinishedAt", - "value": null, + "value": "", "disabled": true }, { "key": "afterFinishedAt", - "value": null, + "value": "", "disabled": true }, { "key": "canceledBy", - "value": null, + "value": "", "disabled": true }, { @@ -711,6 +716,11 @@ "key": "from", "value": "10", "disabled": true + }, + { + "key": "reverse", + "value": "true", + "disabled": true } ] } @@ -888,6 +898,118 @@ } ] }, + { + "name": "Batches", + "item": [ + { + "name": "Get one batch", + "request": { + "method": "GET", + "header": [], + "url": { + "raw": "{{url}}/batches/0", + "host": [ + "{{url}}" + ], + "path": [ + "batches", + "0" + ] + } + }, + "response": [] + }, + { + "name": "Get all batches", + "request": { + "method": "GET", + "header": [], + "url": { + "raw": "{{url}}/batches", + "host": [ + "{{url}}" + ], + "path": [ + "batches" + ], + "query": [ + { + "key": "uids", + "value": "3", + "disabled": true + }, + { + "key": "batchUids", + "value": "0,1", + "disabled": true + }, + { + "key": "indexUids", + "value": "books", + "disabled": true + }, + { + "key": "types", + "value": "documentAdditionOrUpdate", + "disabled": true + }, + { + "key": "statuses", + "value": "failed", + "disabled": true + }, + { + "key": "beforeEnqueuedAt", + "value": "", + "disabled": true + }, + { + "key": "afterEnqueuedAt", + "value": "", + "disabled": true + }, + { + "key": "beforeStartedAt", + "value": "", + "disabled": true + }, + { + "key": "afterStartedAt", + "value": "", + "disabled": true + }, + { + "key": "beforeFinishedAt", + "value": "", + "disabled": true + }, + { + "key": "afterFinishedAt", + "value": "", + "disabled": true + }, + { + "key": "limit", + "value": "2", + "disabled": true + }, + { + "key": "from", + "value": "10", + "disabled": true + }, + { + "key": "reverse", + "value": "true", + "disabled": true + } + ] + } + }, + "response": [] + } + ] + }, { "name": "Indexes", "item": [ @@ -2384,6 +2506,156 @@ }, "response": [] }, + { + "name": "Get facet search", + "request": { + "method": "GET", + "header": [], + "url": { + "raw": "{{url}}/indexes/{{indexUID}}/settings/facet-search", + "host": [ + "{{url}}" + ], + "path": [ + "indexes", + "{{indexUID}}", + "settings", + "facet-search" + ] + } + }, + "response": [] + }, + { + "name": "Update facet search", + "protocolProfileBehavior": { + "disabledSystemHeaders": { + "content-type": true + } + }, + "request": { + "method": "PUT", + "header": [ + { + "key": "Content-Type", + "value": "application/json", + "type": "text" + } + ], + "body": { + "mode": "raw", + "raw": "false" + }, + "url": { + "raw": "{{url}}/indexes/{{indexUID}}/settings/facet-search", + "host": [ + "{{url}}" + ], + "path": [ + "indexes", + "{{indexUID}}", + "settings", + "facet-search" + ] + } + }, + "response": [] + }, + { + "name": "Reset facet search", + "request": { + "method": "DELETE", + "header": [], + "url": { + "raw": "{{url}}/indexes/{{indexUID}}/settings/facet-search", + "host": [ + "{{url}}" + ], + "path": [ + "indexes", + "{{indexUID}}", + "settings", + "facet-search" + ] + } + }, + "response": [] + }, + { + "name": "Get prefix search", + "request": { + "method": "GET", + "header": [], + "url": { + "raw": "{{url}}/indexes/{{indexUID}}/settings/prefix-search", + "host": [ + "{{url}}" + ], + "path": [ + "indexes", + "{{indexUID}}", + "settings", + "prefix-search" + ] + } + }, + "response": [] + }, + { + "name": "Update prefix search", + "protocolProfileBehavior": { + "disabledSystemHeaders": { + "content-type": true + } + }, + "request": { + "method": "PUT", + "header": [ + { + "key": "Content-Type", + "value": "application/json", + "type": "text" + } + ], + "body": { + "mode": "raw", + "raw": "\"disabled\"" + }, + "url": { + "raw": "{{url}}/indexes/{{indexUID}}/settings/prefix-search", + "host": [ + "{{url}}" + ], + "path": [ + "indexes", + "{{indexUID}}", + "settings", + "prefix-search" + ] + } + }, + "response": [] + }, + { + "name": "Reset prefix search", + "request": { + "method": "DELETE", + "header": [], + "url": { + "raw": "{{url}}/indexes/{{indexUID}}/settings/prefix-search", + "host": [ + "{{url}}" + ], + "path": [ + "indexes", + "{{indexUID}}", + "settings", + "prefix-search" + ] + } + }, + "response": [] + }, { "name": "Get search cutoff", "request": { diff --git a/config/sidebar-reference.json b/config/sidebar-reference.json index 34fcff178..26c07e118 100644 --- a/config/sidebar-reference.json +++ b/config/sidebar-reference.json @@ -43,6 +43,11 @@ "label": "Tasks", "slug": "tasks" }, + { + "source": "reference/api/batches.mdx", + "label": "Batches", + "slug": "batches" + }, { "source": "reference/api/keys.mdx", "label": "Keys", diff --git a/guides/docker.mdx b/guides/docker.mdx index c03eed619..ab4770466 100644 --- a/guides/docker.mdx +++ b/guides/docker.mdx @@ -14,7 +14,7 @@ Docker is a tool that bundles applications into containers. Docker containers en Docker containers are distributed in images. To use Meilisearch, use the `docker pull` command to download a Meilisearch image: ```sh -docker pull getmeili/meilisearch:v1.11 +docker pull getmeili/meilisearch:v1.12 ``` Meilisearch deploys a new Docker image with every release of the engine. Each image is tagged with the corresponding Meilisearch version, indicated in the above example by the text following the `:` symbol. You can see [the full list of available Meilisearch Docker images](https://hub.docker.com/r/getmeili/meilisearch/tags#!) on Docker Hub. @@ -31,7 +31,7 @@ After completing the previous step, use `docker run` to launch the Meilisearch i docker run -it --rm \ -p 7700:7700 \ -v $(pwd)/meili_data:/meili_data \ - getmeili/meilisearch:v1.11 + getmeili/meilisearch:v1.12 ``` ### Configure Meilisearch @@ -47,7 +47,7 @@ docker run -it --rm \ -p 7700:7700 \ -e MEILI_MASTER_KEY='MASTER_KEY'\ -v $(pwd)/meili_data:/meili_data \ - getmeili/meilisearch:v1.11 + getmeili/meilisearch:v1.12 ``` #### Passing instance options with CLI arguments @@ -58,7 +58,7 @@ If you want to pass command-line arguments to Meilisearch with Docker, you must docker run -it --rm \ -p 7700:7700 \ -v $(pwd)/meili_data:/meili_data \ - getmeili/meilisearch:v1.11 \ + getmeili/meilisearch:v1.12 \ meilisearch --master-key="MASTER_KEY" ``` @@ -76,7 +76,7 @@ To keep your data intact between reboots, specify a dedicated volume by running docker run -it --rm \ -p 7700:7700 \ -v $(pwd)/meili_data:/meili_data \ - getmeili/meilisearch:v1.11 + getmeili/meilisearch:v1.12 ``` The example above uses `$(pwd)/meili_data`, which is a directory in the host machine. Depending on your OS, mounting volumes from the host to the container might result in performance loss and is only recommended when developing your application. @@ -91,7 +91,7 @@ To import a dump, use Meilisearch's `--import-dump` command-line option and spec docker run -it --rm \ -p 7700:7700 \ -v $(pwd)/meili_data:/meili_data \ - getmeili/meilisearch:v1.11 \ + getmeili/meilisearch:v1.12 \ meilisearch --import-dump /meili_data/dumps/20200813-042312213.dump ``` @@ -111,7 +111,7 @@ To generate a Meilisearch snapshot with Docker, launch Meilisearch with `--sched docker run -it --rm \ -p 7700:7700 \ -v $(pwd)/meili_data:/meili_data \ - getmeili/meilisearch:v1.11 \ + getmeili/meilisearch:v1.12 \ meilisearch --schedule-snapshot --snapshot-dir /meili_data/snapshots ``` @@ -123,7 +123,7 @@ To import a snapshot, launch Meilisearch with the `--import-snapshot` option: docker run -it --rm \ -p 7700:7700 \ -v $(pwd)/meili_data:/meili_data \ - getmeili/meilisearch:v1.11 \ + getmeili/meilisearch:v1.12 \ meilisearch --import-snapshot /meili_data/snapshots/data.ms.snapshot ``` diff --git a/learn/async/asynchronous_operations.mdx b/learn/async/asynchronous_operations.mdx index 4da456044..9f3d68568 100644 --- a/learn/async/asynchronous_operations.mdx +++ b/learn/async/asynchronous_operations.mdx @@ -137,6 +137,10 @@ When you make a [request for an asynchronous operation](#which-operations-are-as **Terminating a Meilisearch instance in the middle of an asynchronous operation is completely safe** and will never adversely affect the database. +### Task batches + +Meilisearch processes tasks in batches, grouping tasks for the best possible performance. In most cases, batching should be transparent and have no impact on the overall task workflow. Use [the `/batches` route](/reference/api/batches) to obtain more information on batches and how they are processing your tasks. + ### Canceling tasks You can cancel a task while it is `enqueued` or `processing` by using [the cancel tasks endpoint](/reference/api/tasks#cancel-tasks). Doing so changes a task's `status` to `canceled`. diff --git a/learn/async/filtering_tasks.mdx b/learn/async/filtering_tasks.mdx index 911b896ca..1985ac573 100644 --- a/learn/async/filtering_tasks.mdx +++ b/learn/async/filtering_tasks.mdx @@ -9,6 +9,10 @@ Querying the [get tasks endpoint](/reference/api/tasks#get-tasks) returns all ta This guide shows you how to use query parameters to filter tasks and obtain a more readable list of asynchronous operations. + +Filtering batches with [the `/batches` route](/reference/api/batches) follows the same rules as filtering tasks. Keep in mind that many `/batches` parameters such as `uids` target the tasks included in batches, instead of the batches themselves. + + ## Requirements - a command-line terminal diff --git a/learn/async/paginating_tasks.mdx b/learn/async/paginating_tasks.mdx index 6806976cf..b1c326c36 100644 --- a/learn/async/paginating_tasks.mdx +++ b/learn/async/paginating_tasks.mdx @@ -7,6 +7,10 @@ description: Meilisearch uses a task queue to handle asynchronous operations. Th By default, Meilisearch returns a list of 20 tasks for each request when you query the [get tasks endpoint](/reference/api/tasks#get-tasks). This guide shows you how to navigate the task list using query parameters. + +Paginating batches with [the `/batches` route](/reference/api/batches) follows the same rules as paginating tasks. + + ## Configuring the number of returned tasks Use the `limit` parameter to change the number of returned tasks: diff --git a/learn/resources/telemetry.mdx b/learn/resources/telemetry.mdx index c0ef6115c..c29996cc5 100644 --- a/learn/resources/telemetry.mdx +++ b/learn/resources/telemetry.mdx @@ -198,9 +198,13 @@ This list is liable to change with every new version of Meilisearch. It's not be | `pagination.max_total_hits` | The defined value for the `pagination.maxTotalHits` property | 1000 | `faceting.max_values_per_facet` | The defined value for the `faceting.maxValuesPerFacet` property | 100 | `distinct_attribute.set` | `true` if a field name is specified, otherwise `false` | false -| `distinct` | Boolean indicating whether a distinct was specified in an aggregated list of requests. | true | -| `proximity_precision.set` | `true` if the setting has been manually set, otherwise `false`. | `false` -| `proximity_precision.value` | `byWord` or `byAttribute`. | `byWord` +| `distinct` | Boolean indicating whether a distinct was specified in an aggregated list of requests. | true +| `proximity_precision.set` | `true` if the setting has been manually set, otherwise `false`. | fals` +| `proximity_precision.value` | `byWord` or `byAttribute`. | "byWord" +| `facet_search.set` | `facetSearch` has been changed by the user | true +| `facet_search.value` | `facetSearch` value set by the user | true +| `prefix_search.set` | `prefixSearch` has been changed by the user | true +| `prefix_search.value` | `prefixSearch` value set by the user | "indexingTime" | `displayed_attributes.total` | Number of displayed attributes | 3 | `displayed_attributes.with_wildcard` | `true` if `*` is specified as a displayed attribute, otherwise `false` | false | `stop_words.total` | Number of stop words | 3 diff --git a/learn/self_hosted/install_meilisearch_locally.mdx b/learn/self_hosted/install_meilisearch_locally.mdx index fb0125f03..96d2445c3 100644 --- a/learn/self_hosted/install_meilisearch_locally.mdx +++ b/learn/self_hosted/install_meilisearch_locally.mdx @@ -54,14 +54,14 @@ These commands launch the **latest stable release** of Meilisearch. ```bash # Fetch the latest version of Meilisearch image from DockerHub -docker pull getmeili/meilisearch:v1.11 +docker pull getmeili/meilisearch:v1.12 # Launch Meilisearch in development mode with a master key docker run -it --rm \ -p 7700:7700 \ -e MEILI_ENV='development' \ -v $(pwd)/meili_data:/meili_data \ - getmeili/meilisearch:v1.11 + getmeili/meilisearch:v1.12 # Use ${pwd} instead of $(pwd) in PowerShell ``` diff --git a/package.json b/package.json index c051dd6c0..946069f2d 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "documentation", - "version": "1.11.0", + "version": "1.12.0", "description": "", "main": "index.js", "dependencies": {}, diff --git a/reference/api/batches.mdx b/reference/api/batches.mdx new file mode 100644 index 000000000..a1fd1ff89 --- /dev/null +++ b/reference/api/batches.mdx @@ -0,0 +1,250 @@ +--- +title: Batches — Meilisearch API reference +description: The /batches route allows you to monitor how Meilisearch is grouping and processing asynchronous operations. +--- + +# Batches + +The `/batches` route gives information about the progress of batches of [asynchronous operations](/learn/async/asynchronous_operations). + +## Batch object + +```json +{ + "uid": 0, + "details": { + "receivedDocuments": 6, + "indexedDocuments": 6 + }, + "stats": { + "totalNbTasks": 1, + "status": { + "succeeded": 1 + }, + "types": { + "documentAdditionOrUpdate": 1 + }, + "indexUids": { + "INDEX_NAME": 1 + } + }, + "duration": "PT0.250518S", + "startedAt": "2024-12-10T15:20:30.18182Z", + "finishedAt": "2024-12-10T15:20:30.432338Z", + "progress": { + "steps": [ + { + "currentStep": "extracting words", + "finished": 2, + "total": 9, + }, + { + "currentStep": "document", + "finished": 30546, + "total": 31944, + } + ], + "percentage": 32.8471 + } +} +``` + +### `uid` + +**Type**: Integer
+**Description**: Unique sequential identifier of the batch. Starts at `0` and increases by one for every new patch. + +### `details` + +**Type**: Object
+**Description**: Basic information on the types tasks in a batch. Consult the [task object reference](/reference/api/tasks#details) for an exhaustive list of possible values. + +### `progress` + +**Type**: Object
+**Description**: Object containing two fields: `steps` and `percentage`. Once Meilisearch has fully processed a batch, its `progress` is set to `null`. + +#### `steps` + +Information about the current operations Meilisearch is performing in this batch. A step may consist of multiple substeps. + +| Name | Description | +| :-----------------| :------------------------------------------------- | +| **`currentStep`** | A string describing the operation | +| **`total`** | The total number of operations in the step | +| **`finished`** | The number of operations Meilisearch has completed | + + +If Meilisearch is taking longer than expected to process a batch, monitor the `steps` array. If the `finished` field of the last item in the `steps` array does not update, Meilisearch may be stuck. + + +#### `percentage` + +The percentage of completed operations, calculated from all current steps and substeps. This value is a rough estimate and may not always reflect the current state of the batch due to how different steps are processed more quickly than others. + +### `stats` + +**Type**: Object
+**Description**: Detailed information on the payload of all tasks in a batch. + +#### `totalNbTasks` + +Number of tasks in the batch. + +#### `status` + +Object listing the [status of each task](/reference/api/tasks#status) in the batch. Contains five keys whose values correspond to the number of tasks with that status. + +#### `types` + +List with the `types` of tasks contained in the batch. + +#### `indexUids` + +List of the number of tasks in the batch separated by the indexes they affect. + +### `duration` + +**Type**: String
+**Description**: The total elapsed time the batch spent in the `processing` state, in [ISO 8601](https://www.ionos.com/digitalguide/websites/web-development/iso-8601/) format. Set to `null` while the batch is processing tasks + +### `startedAt` + +**Type**: String
+**Description**: The date and time when the batch began `processing`, in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format + +### `finishedAt` + +**Type**: String
+**Description**: The date and time when the tasks finished `processing`, whether `failed`, `succeeded`, or `canceled`, in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format + +## Get batches + + + +List all batches, regardless of index. The batch objects are contained in the `results` array. + +Batches are always returned in descending order of `uid`. This means that by default, **the most recently created batch objects appear first**. + +Batch results are [paginated](/learn/async/paginating_tasks) and can be [filtered](/learn/async/filtering_tasks) with query parameters. + + +Some query parameters for `/batches`, such as `uids` and `statuses`, target tasks instead of batches. + +For example, `?uids=0` returns a batch containing the task with a `taskUid` equal to `0`, instead of a batch with a `batchUid` equal to `0`. + + +### Query parameters + +| Query Parameter | Default Value | Description | +| ---------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------- | +| **`uids`** | `*` (all task uids) | Select batches containing the tasks with the specified `uid`s. Separate multiple task `uids` with a comma (`,`) | +| **`batchUids`** | `*` (all batch uids) | Filter batches by their `uid`. Separate multiple batch `uids` with a comma (`,`) | +| **`indexUids`** | `*` (all indexes) | Select batches containing tasks affecting the specified indexes. Separate multiple `indexUids` with a comma (`,`) | +| **`statuses`** | `*` (all statuses) | Select batches containing tasks with the specified `status`. Separate multiple task `statuses` with a comma (`,`) | +| **`types`** | `*` (all types) | Select batches containing tasks with the specified `type`. Separate multiple task `types` with a comma (`,`) | +| **`limit`** | `20` | Number of batches to return | +| **`from`** | `uid` of the last created batch | `uid` of the first batch returned | +| **`reverse`** | `false` | If `true`, returns results in the reverse order, from oldest to most recent | +| **`beforeEnqueuedAt`** | `*` (all tasks) | Select batches containing tasks with the specified `enqueuedAt` field | +| **`beforeStartedAt`** | `*` (all tasks) | Select batches containing tasks with the specified `startedAt` field | +| **`beforeFinishedAt`** | `*` (all tasks) | Select batches containing tasks with the specified `finishedAt` field | +| **`afterEnqueuedAt`** | `*` (all tasks) | Select batches containing tasks with the specified `enqueuedAt` field | +| **`afterStartedAt`** | `*` (all tasks) | Select batches containing tasks with the specified `startedAt` field | +| **`afterFinishedAt`** | `*` (all tasks) | Select batches containing tasks with the specified `finishedAt` field | + +### Response + +| Name | Type | Description | +| :------------ | :------ | :----------------------------------------------------------------------------------------------------------------------------- | +| **`results`** | Array | An array of [batch objects](#batch-object) | +| **`total`** | Integer | Total number of batches matching the filter or query | +| **`limit`** | Integer | Number of batches returned | +| **`from`** | Integer | `uid` of the first batch returned | +| **`next`** | Integer | Value passed to `from` to view the next "page" of results. When the value of `next` is `null`, there are no more tasks to view | + +### Example + + + +#### Response: `200 Ok` + +```json +{ + "results": [ + { + "uid": 2, + "details": { + "stopWords": [ + "of", + "the" + ] + }, + "progress": null, + "stats": { + "totalNbTasks": 1, + "status": { + "succeeded": 1 + }, + "types": { + "settingsUpdate": 1 + }, + "indexUids": { + "INDEX_NAME": 1 + } + }, + "duration": "PT0.110083S", + "startedAt": "2024-12-10T15:49:04.995321Z", + "finishedAt": "2024-12-10T15:49:05.105404Z" + } + ], + "total": 3, + "limit": 1, + "from": 2, + "next": 1 +} +``` + +## Get one batch + + + +Get a single batch. + +### Path parameters + +| Name | Type | Description | +| :---------------- | :----- | :----------------------------------- | +| **`batch_uid`** * | String | [`uid`](#uid) of the requested batch | + +### Example + + + +#### Response: `200 Ok` + +```json +{ + "uid": 1, + "details": { + "receivedDocuments": 1, + "indexedDocuments": 1 + }, + "progress": null, + "stats": { + "totalNbTasks": 1, + "status": { + "succeeded": 1 + }, + "types": { + "documentAdditionOrUpdate": 1 + }, + "indexUids": { + "INDEX_NAME": 1 + } + }, + "duration": "PT0.364788S", + "startedAt": "2024-12-10T15:48:49.672141Z", + "finishedAt": "2024-12-10T15:48:50.036929Z" +} +``` diff --git a/reference/api/settings.mdx b/reference/api/settings.mdx index 1582f3d3f..f470e807a 100644 --- a/reference/api/settings.mdx +++ b/reference/api/settings.mdx @@ -59,6 +59,8 @@ By default, the settings object looks like this. All fields are modifiable. "maxTotalHits": 1000 }, "proximityPrecision": "byWord", + "facetSearch": true, + "prefixSearch": "indexingTime", "searchCutoffMs": null } ``` @@ -126,6 +128,8 @@ Get the settings of an index. "maxTotalHits": 1000 }, "proximityPrecision": "byWord", + "facetSearch": true, + "prefixSearch": "indexingTime", "searchCutoffMs": null } ``` @@ -159,6 +163,8 @@ If the provided index does not exist, it will be created. | **[`filterableAttributes`](#filterable-attributes)** | Array of strings | Empty | Attributes to use as filters and facets | | **[`pagination`](#pagination)** | Object | [Default object](#pagination-object) | Pagination settings | | **[`proximityPrecision`](#proximity-precision)** | String | `"byWord"` | Precision level when calculating the proximity ranking rule | +| **[`facetSearch`](#facet-search)** | Boolean | `true` | Enable or disable [facet search](/reference/api/facet_search) functionality | +| **[`prefixSearch`](#prefix-search)** | String | `"indexingTime"` | When Meilisearch should return results only matching the beginning of query | | **[`rankingRules`](#ranking-rules)** | Array of strings | `["words",`
`"typo",`
`"proximity",`
`"attribute",`
`"sort",`
`"exactness"]` | List of ranking rules in order of importance | | **[`searchableAttributes`](#searchable-attributes)** | Array of strings | All attributes: `["*"]` | Fields in which to search for matching query words sorted by order of importance | | **[`searchCutoffMs`](#search-cutoff)** | Integer | `null`, or 1500ms | Maximum duration of a search query | @@ -1113,6 +1119,8 @@ You can use the returned `taskUid` to get more details on [the status of the tas ### Reset proximity precision settings + + Reset an index's proximity precision setting to its default value. #### Path parameters @@ -1139,6 +1147,201 @@ Reset an index's proximity precision setting to its default value. You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task). +## Facet search + +Processing filterable attributes for facet search is a resource-intensive operation. This feature is enabled by default, but disabling it may speed up indexing. + +`facetSearch` accepts a single Boolean value. If set to `false`, it disables facet search for the whole index. Meilisearch returns an error if you try to access the `/facet-search` endpoint when facet search is disabled. + +### Get facet search settings + + + +Get the facet search settings of an index. + +#### Path parameters + +| Name | Type | Description | +| :---------------- | :----- | :--------------------------------------------------------------------- | +| **`index_uid`** * | String | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index | + +#### Example + + + +##### Response: `200 OK` + +```json +{ + "facetSearch": true +} +``` + +### Update facet search settings + + + +Update the facet search settings for an index. + +#### Path parameters + +| Name | Type | Description | +| :---------------- | :----- | :--------------------------------------------------------------------- | +| **`index_uid`** * | String | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index | + +#### Body + +``` + +``` + +#### Example + + + +##### Response: `202 Accepted` + +```json +{ + "taskUid": 1, + "indexUid": "INDEX_UID", + "status": "enqueued", + "type": "settingsUpdate", + "enqueuedAt": "2024-07-19T22:33:18.523881Z" +} +``` + +Use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task). + +### Reset facet search settings + + + +Reset an index's facet search to its default settings. + +#### Path parameters + +| Name | Type | Description | +| :---------------- | :----- | :--------------------------------------------------------------------- | +| **`index_uid`** * | String | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index | + +#### Example + + + +##### Response: `202 Accepted` + +```json +{ + "taskUid": 1, + "indexUid": "INDEX_UID", + "status": "enqueued", + "type": "settingsUpdate", + "enqueuedAt": "2024-07-19T22:35:33.723983Z" +} +``` + +Use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task). + +## Prefix search + +Prefix search is the process through which Meilisearch matches documents that begin with a specific query term, instead of only exact matches. This is a resource-intensive operation that happens during indexing by default. + +Use `prefixSearch` to change how prefix search works. It accepts one of the following strings: + +- `"indexingTime"`: calculate prefix search during indexing. This is the default behavior +- `"disabled"`: do not calculate prefix search. May speed up indexing, but will severely impact search result relevancy + +### Get prefix search settings + + + +Get the prefix search settings of an index. + +#### Path parameters + +| Name | Type | Description | +| :---------------- | :----- | :--------------------------------------------------------------------- | +| **`index_uid`** * | String | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index | + +#### Example + + + +##### Response: `200 OK` + +```json +{ + "prefixSearch": "indexingTime" +} +``` + +### Update prefix search settings + + + +Update the prefix search settings for an index. + +#### Path parameters + +| Name | Type | Description | +| :---------------- | :----- | :--------------------------------------------------------------------- | +| **`index_uid`** * | String | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index | + +#### Body + +``` +"indexingTime" | "disabled" +``` + +#### Example + + + +##### Response: `202 Accepted` + +```json +{ + "taskUid": 1, + "indexUid": "INDEX_UID", + "status": "enqueued", + "type": "settingsUpdate", + "enqueuedAt": "2024-07-19T22:33:18.523881Z" +} +``` + +Use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task). + +### Reset prefix search settings + + + +Reset an index's prefix search to its default settings. + +#### Path parameters + +| Name | Type | Description | +| :---------------- | :----- | :--------------------------------------------------------------------- | +| **`index_uid`** * | String | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index | + +#### Example + + + +##### Response: `202 Accepted` + +```json +{ + "taskUid": 1, + "indexUid": "INDEX_UID", + "status": "enqueued", + "type": "settingsUpdate", + "enqueuedAt": "2024-07-19T22:35:33.723983Z" +} +``` + +Use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task). + ## Ranking rules Ranking rules are built-in rules that rank search results according to certain criteria. They are applied in the same order in which they appear in the `rankingRules` array. diff --git a/reference/api/tasks.mdx b/reference/api/tasks.mdx index 210b9976a..e280f80ed 100644 --- a/reference/api/tasks.mdx +++ b/reference/api/tasks.mdx @@ -12,7 +12,8 @@ The `/tasks` route gives information about the progress of [asynchronous operati ```json { "uid": 4, - "indexUid" :"movie", + "batchUids": 0, + "indexUid":"movie", "status": "failed", "type": "indexDeletion", "canceledBy": null, @@ -35,10 +36,19 @@ The `/tasks` route gives information about the progress of [asynchronous operati ### `uid` **Type**: Integer
-**Description**: Unique sequential identifier of the task +**Description**: Unique sequential identifier of the task. -The task `uid` is incremented **globally.** +The task `uid` is incremented across all indexes in an instance. + + +### `batchUid` + +**Type**: Integer
+**Description**: Unique sequential identifier of the batch this task belongs to. + + +The batch `uid` is incremented across all indexes in an instance. ### `indexUid` @@ -219,12 +229,14 @@ Task results are [paginated](/learn/async/paginating_tasks) and can be [filtered | Query Parameter | Default Value | Description | | :--------------------- | :----------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **`limit`** | `20` | Number of tasks to return | -| **`from`** | `uid` of the last created task | `uid` of the first task returned | | **`uids`** | `*` (all uids) | [Filter tasks](/learn/async/filtering_tasks) by their `uid`. Separate multiple task `uids` with a comma (`,`) | +| **`batchUids`** | `*` (all batch uids) | [Filter tasks](/learn/async/filtering_tasks) by their `batchUid`. Separate multiple `batchUids` with a comma (`,`) | | **`statuses`** | `*` (all statuses) | [Filter tasks](/learn/async/filtering_tasks) by their `status`. Separate multiple task `statuses` with a comma (`,`) | | **`types`** | `*` (all types) | [Filter tasks](/learn/async/filtering_tasks) by their `type`. Separate multiple task `types` with a comma (`,`) | | **`indexUids`** | `*` (all indexes) | [Filter tasks](/learn/async/filtering_tasks) by their `indexUid`. Separate multiple task `indexUids` with a comma (`,`). Case-sensitive | +| **`limit`** | `20` | Number of tasks to return | +| **`from`** | `uid` of the last created task | `uid` of the first task returned | +| **`reverse`** | `false` | If `true`, returns results in the reverse order, from oldest to most recent | | **`canceledBy`** | N/A | [Filter tasks](/learn/async/filtering_tasks) by their `canceledBy` field. Separate multiple task `uids` with a comma (`,`) | | **`beforeEnqueuedAt`** | `*` (all tasks) | [Filter tasks](/learn/async/filtering_tasks) by their `enqueuedAt` field | | **`beforeStartedAt`** | `*` (all tasks) | [Filter tasks](/learn/async/filtering_tasks) by their `startedAt` field | diff --git a/reference/errors/error_codes.mdx b/reference/errors/error_codes.mdx index 4b96cfb2d..4fe977280 100644 --- a/reference/errors/error_codes.mdx +++ b/reference/errors/error_codes.mdx @@ -35,6 +35,10 @@ The requested document can't be retrieved. Either it doesn't exist, or the datab An error occurred during the dump creation process. The task was aborted. +## `facet_search_disabled` + +The [`/facet-search`](/reference/api/facet_search) route has been queried while [the `facetSearch` index setting](/reference/api/settings#facet-search) is set to `false`. + ## `immutable_api_key_actions` The [`actions`](/reference/api/keys#actions) field of an API key cannot be modified. @@ -93,7 +97,7 @@ The requested index already has a primary key that [cannot be changed](/learn/ge ## `internal` - Meilisearch experienced an internal error. Check the error message, and [open an issue](https://github.com/meilisearch/meilisearch/issues/new?assignees=&labels=&template=bug_report&title=) if necessary. +Meilisearch experienced an internal error. Check the error message, and [open an issue](https://github.com/meilisearch/meilisearch/issues/new?assignees=&labels=&template=bug_report&title=) if necessary. ## `invalid_api_key` @@ -296,6 +300,10 @@ The [`limit`](/reference/api/search#limit) parameter is invalid. It should be an The [`locales`](/reference/api/search#query-locales) parameter is invalid. +## `invalid_settings_facet_search` + +The [`facetSearch`](/reference/api/settings#facet-search) index setting value is invalid. + ## `invalid_settings_localized_attributes` The [`localizedAttributes`](/reference/api/settings#localized-attributes) index setting value is invalid. @@ -308,6 +316,10 @@ The [`matchingStrategy`](/reference/api/search#matching-strategy) parameter is i The [`offset`](/reference/api/search#offset) parameter is invalid. It should be an integer. +## `invalid_settings_prefix_search` + +The [`prefixSearch`](/reference/api/settings#prefix-search) index setting value is invalid. + ## `invalid_search_page` The [`page`](/reference/api/search#page) parameter is invalid. It should be an integer.