diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 047cb60b9f..b9389d79d7 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -432,13 +432,13 @@ search_parameter_guide_highlight_tag_1: |- "highlightPreTag": "", "highlightPostTag": "" }' -search_parameter_guide_matches_1: |- +search_parameter_guide_show_matches_position_1: |- curl \ -X POST 'http://localhost:7700/indexes/movies/search' \ -H 'Content-Type: application/json' \ --data-binary '{ "q": "winter feast", - "matches": true + "showMatchesPosition": true }' settings_guide_synonyms_1: |- curl \ @@ -648,13 +648,13 @@ faceted_search_filter_1: |- "director = \"Jordan Peele\"" ] }' -faceted_search_facets_distribution_1: |- +faceted_search_facets_1: |- curl \ -X POST 'http://localhost:7700/indexes/movies/search' \ -H 'Content-Type: application/json' \ --data-binary '{ "q": "Batman", - "facetsDistribution": ["genres"] + "facets": ["genres"] }' faceted_search_walkthrough_filter_1: |- curl \ diff --git a/.vuepress/public/sample-template.yaml b/.vuepress/public/sample-template.yaml index 8b52eec657..68b240e516 100644 --- a/.vuepress/public/sample-template.yaml +++ b/.vuepress/public/sample-template.yaml @@ -65,7 +65,7 @@ search_parameter_guide_limit_1: |- search_parameter_guide_retrieve_1: |- search_parameter_guide_crop_1: |- search_parameter_guide_highlight_1: |- -search_parameter_guide_matches_1: |- +search_parameter_guide_show_matches_position_1: |- settings_guide_synonyms_1: |- settings_guide_stop_words_1: |- settings_guide_ranking_rules_1: |- @@ -90,7 +90,7 @@ getting_started_sorting: |- getting_started_filtering: |- faceted_search_update_settings_1: |- faceted_search_filter_1: |- -faceted_search_facets_distribution_1: |- +faceted_search_facets_1: |- faceted_search_walkthrough_filter_1: |- add_movies_json_1: |- post_dump_1: |- diff --git a/learn/advanced/filtering_and_faceted_search.md b/learn/advanced/filtering_and_faceted_search.md index 5c7e83c362..7a057de53f 100644 --- a/learn/advanced/filtering_and_faceted_search.md +++ b/learn/advanced/filtering_and_faceted_search.md @@ -278,30 +278,29 @@ You can then use this filter to search for `thriller`: ### Facets distribution -When creating a faceted search interface it is often useful to have a count of how many results belong to each facet. This can be done by using the [`facetsDistribution` search parameter](/reference/api/search.md#facets-distribution) in combination with `filter` when searching. +When creating a faceted search interface it is often useful to have a count of how many results belong to each facet. This can be done by using the [`facets` search parameter](/reference/api/search.md#facets) in combination with `filter` when searching. ::: note -Meilisearch does not differentiate between facets and filters. This means that, despite its name, `facetsDistribution` can be used with any attributes added to `filterableAttributes`. +Meilisearch does not differentiate between facets and filters. This means that, despite its name, `facets` can be used with any attributes added to `filterableAttributes`. ::: -Using `facetsDistribution` will add an extra field to the returned search results containing the number of matching documents distributed among all the values of a given facet. +Using `facets` will add an extra field to the returned search results containing the number of matching documents distributed among all the values of a given facet. In the example below, [IMDb](https://www.imdb.com) displays the facet count in parentheses next to each faceted category. This UI gives users a visual clue of the range of results available for each facet. ![IMDb facets](/faceted-search/facets-imdb.png) -#### Using facet distribution +#### Using `facets` -[`facetsDistribution` is a search parameter](/reference/api/search.md#facets-distribution) and as such must be added to a search request. It expects an array of strings. Each string is an attribute present in the `filterableAttributes` list. +[`facets` is a search parameter](/reference/api/search.md#facets) and as such must be added to a search request. It expects an array of strings. Each string is an attribute present in the `filterableAttributes` list. -Using the `facetsDistribution` search parameter adds two new keys to the returned object: `facetsDistribution` and `exhaustiveFacetsCount`. +Using the `facets` search parameter adds `facetDistribution` to the returned object. -`facetsDistribution` contains an object for every given facet. For each of these facets, there is another object containing all the different values and the count of matching documents. Note that zero values will not be returned: if there are no `romance` movies matching the query, `romance` is not displayed. +`facetDistribution` contains an object for every given facet. For each of these facets, there is another object containing all the different values and the count of matching documents. Note that zero values will not be returned: if there are no `romance` movies matching the query, `romance` is not displayed. ```json { - "exhaustiveFacetsCount": false, - "facetsDistribution" : { + "facetDistribution" : { "genres" : { "horror": 50, "comedy": 34 @@ -310,19 +309,13 @@ Using the `facetsDistribution` search parameter adds two new keys to the returne } ``` -`exhaustiveFacetsCount` is a boolean value that informs the user whether the facet count is exact or just an approximation. For performance reasons, Meilisearch chooses to use approximate facet count values when there are too many documents across several different fields. - -::: warning -`exhaustiveFacetsCount` is not currently implemented in and will always return `false`. -::: - ##### Example You can write a search query that gives you the distribution of `batman` movies per genre: - + -This query would return not only the matching movies, but also the `facetsDistribution` key containing all relevant data: +This query would return not only the matching movies, but also the `facetDistribution` key containing all relevant data: ```json { @@ -330,7 +323,7 @@ This query would return not only the matching movies, but also the `facetsDistri … ], … - "facetsDistribution": { + "facetDistribution": { "genres": { "action": 273, "animation": 118, diff --git a/learn/configuration/distinct.md b/learn/configuration/distinct.md index 02274a3248..fe6b446919 100644 --- a/learn/configuration/distinct.md +++ b/learn/configuration/distinct.md @@ -65,8 +65,7 @@ After setting the distinct attribute as shown above, querying for `lee leather j ], "offset": 0, "limit": 20, - "nbHits": 1, - "exhaustiveNbHits": false, + "estimatedTotalHits": 1, "processingTimeMs": 0, "query": "lee leather jacket" } diff --git a/learn/getting_started/algolia_migration.md b/learn/getting_started/algolia_migration.md index e08bcca0d0..96e20a3922 100644 --- a/learn/getting_started/algolia_migration.md +++ b/learn/getting_started/algolia_migration.md @@ -181,7 +181,7 @@ The below table compares Algolia's **API parameters** with the equivalent Meilis | `query` | `q` | | `attributesToRetrieve` | `attributesToRetrieve` | | `filters` | `filter` | -| `facets` | `facetsDistribution` | +| `facets` | `facetDistribution` | | `attributesToHighlight` | `attributesToHighlight` | | `offset` | `offset` | | `length` | `limit` | diff --git a/learn/getting_started/filtering_and_sorting.md b/learn/getting_started/filtering_and_sorting.md index 7e5c05c9ad..0222a597ef 100644 --- a/learn/getting_started/filtering_and_sorting.md +++ b/learn/getting_started/filtering_and_sorting.md @@ -41,8 +41,7 @@ Let's say you only want to view meteorites that weigh less than 200g: }, … ], - "nbHits": 114, - "exhaustiveNbHits": false, + "estimatedTotalHits": 114, "query": "", "limit": 20, "offset": 0, @@ -77,8 +76,7 @@ Let's sort the meteorites in the previous example based on mass: }, … ], - "nbHits": 114, - "exhaustiveNbHits": false, + "estimatedTotalHits": 114, "query": "", "limit": 20, "offset": 0, @@ -132,8 +130,7 @@ Let's say you want to find out which meteorites crashed within a 210km radius of }, … ], - "nbHits": 7, - "exhaustiveNbHits": false, + "estimatedTotalHits": 7, "query": "", "limit": 20, "offset": 0, @@ -180,8 +177,7 @@ The following command sorts meteorites by how close they were to the Taj Mahal: }, … ] - "nbHits": 1000, - "exhaustiveNbHits": false, + "estimatedTotalHits": 1000, "query": "", "limit": 20, "offset": 0, diff --git a/learn/getting_started/quick_start.md b/learn/getting_started/quick_start.md index 5d5d0ced71..029ee10342 100644 --- a/learn/getting_started/quick_start.md +++ b/learn/getting_started/quick_start.md @@ -252,8 +252,7 @@ In the above code sample, the parameter `q` represents the search query. The doc }, … ], - "nbHits": 66, - "exhaustiveNbHits": false, + "estimatedTotalHits": 66, "query": "botman", "limit": 20, "offset": 0, diff --git a/reference/api/search.md b/reference/api/search.md index 491fc9aa8b..3ace364f00 100644 --- a/reference/api/search.md +++ b/reference/api/search.md @@ -33,7 +33,7 @@ This is the preferred route to perform search when an API key is required, as it | **[offset](#offset)** | Number of documents to skip | `0` | | **[limit](#limit)** | Maximum number of documents returned | `20` | | **[filter](#filter)** | Filter queries by an attribute's value | `null` | -| **[facetsDistribution](#facets-distribution)** | Display the count of matches per facet | `null` | +| **[facets](#facets)** | Display the count of matches per facet | `null` | | **[attributesToRetrieve](#attributes-to-retrieve)** | Attributes to display in the returned documents | `["*"]` | | **[attributesToCrop](#attributes-to-crop)** | Attributes whose values have to be cropped | `null` | | **[cropLength](#crop-length)** | Maximum length of cropped value in words | `10` | @@ -41,7 +41,7 @@ This is the preferred route to perform search when an API key is required, as it | **[attributesToHighlight](#attributes-to-highlight)** | Highlight matching terms contained in an attribute | `null` | | **[highlightPreTag](#highlight-tags)** | String inserted at the start of a highlighted term | `""` | | **[highlightPostTag](#highlight-tags)** | String inserted at the end of a highlighted term | `""` | -| **[matches](#matches)** | Return matching terms location | `false` | +| **[showMatchesPosition](#show-matches-position)** | Return matching terms location | `false` | | **[sort](#sort)** | Sort search results by an attribute's value | `null` | [Learn more about how to use each search parameter](#search-parameters). @@ -58,17 +58,15 @@ Query terms enclosed in double quotes are treated as [phrase searches](#query-q) ### Response -| field | Description | type | -| -------------------- | ------------------------------ | :--------: | -| **hits** | Results of the query | `array of objects` | -| **offset** | Number of documents skipped | `number` | -| **limit** | Number of documents to take | `number` | -| **nbHits** | Total number of matches | `number` | -| **exhaustiveNbHits** | Whether `nbHits` is exhaustive | `boolean` | -| **facetsDistribution** | **[Distribution of the given facets](#facets-distribution)** | `object` -| **exhaustiveFacetsCount** | Whether `facetsDistribution` is exhaustive | `boolean` -| **processingTimeMs** | Processing time of the query | `number` | -| **query** | Query originating the response | `string` | +| field | Description | type | +| ------------------------| ----------------------------------------------- | :----------------: | +| **hits** | Results of the query | `array of objects` | +| **offset** | Number of documents skipped | `number` | +| **limit** | Number of documents to take | `number` | +| **estimatedTotalHits** | Total number of matches | `number` | +| **facets** | **[Distribution of the given facets](#facets)** | `object` | +| **processingTimeMs** | Processing time of the query | `number` | +| **query** | Query originating the response | `string` | ### Example @@ -97,8 +95,7 @@ Query terms enclosed in double quotes are treated as [phrase searches](#query-q) ], "offset": 0, "limit": 20, - "nbHits": 976, - "exhaustiveNbHits": false, + "estimatedTotalHits": 976, "processingTimeMs": 35, "query": "american " } @@ -124,7 +121,7 @@ This route should only be used when no API key is required. If an API key is req | **[offset](#offset)** | Number of documents to skip | `0` | | **[limit](#limit)** | Maximum number of documents returned | `20` | | **[filter](#filter)** | Filter queries by an attribute's value | `null` | -| **[facetsDistribution](#facets-distribution)** | Display the count of matches per facet | `null` | +| **[facets](#facets)** | Display the count of matches per facet | `null` | | **[attributesToRetrieve](#attributes-to-retrieve)** | Attributes to display in the returned documents | `["*"]` | | **[attributesToCrop](#attributes-to-crop)** | Attributes whose values have to be cropped | `null` | | **[cropLength](#crop-length)** | Maximum length of cropped value in words | `10` | @@ -132,7 +129,7 @@ This route should only be used when no API key is required. If an API key is req | **[attributesToHighlight](#attributes-to-highlight)** | Highlight matching terms contained in an attribute | `null` | | **[highlightPreTag](#highlight-tags)** | String inserted at the start of a highlighted term | `""` | | **[highlightPostTag](#highlight-tags)** | String inserted at the end of a highlighted term | `""` | -| **[matches](#matches)** | Return matching terms location | `false` | +| **[showMatchesPosition](#show-matches-position)** | Return matching terms location | `false` | | **[sort](#sort)** | Sort search results by an attribute's value | `null` | [Learn more about how to use each search parameter](#search-parameters). @@ -147,17 +144,15 @@ Query terms enclosed in double quotes are treated as [phrase searches](#query-q) ### Response -| field | Description | type | -| -------------------- | ------------------------------ | :--------: | -| **hits** | Results of the query | `array of objects` | -| **offset** | Number of documents skipped | `number` | -| **limit** | Number of documents to take | `number` | -| **nbHits** | Total number of matches | `number` | -| **exhaustiveNbHits** | Whether `nbHits` is exhaustive | `boolean` | -| **facetsDistribution** | **[Distribution of the given facets](#facets-distribution)** | `object` -| **exhaustiveFacetsCount** | Whether `facetsDistribution` is exhaustive | `boolean` -| **processingTimeMs** | Processing time of the query | `number` | -| **query** | Query originating the response | `string` | +| field | Description | type | +| ----------------------- | ----------------------------------------------- | :----------------: | +| **hits** | Results of the query | `array of objects` | +| **offset** | Number of documents skipped | `number` | +| **limit** | Number of documents to take | `number` | +| **estimatedTotalHits** | Total number of matches | `number` | +| **facets** | **[Distribution of the given facets](#facets)** | `object` | +| **processingTimeMs** | Processing time of the query | `number` | +| **query** | Query originating the response | `string` | ### Example @@ -186,8 +181,7 @@ Query terms enclosed in double quotes are treated as [phrase searches](#query-q) ], "offset": 0, "limit": 20, - "nbHits": 976, - "exhaustiveNbHits": false, + "estimatedTotalHits": 976, "processingTimeMs": 35, "query": "american " } @@ -211,7 +205,7 @@ This is not necessary when using the `POST` route or one of our [SDKs](/learn/wh | **[offset](#offset)** | Number of documents to skip | `0` | | **[limit](#limit)** | Maximum number of documents returned | `20` | | **[filter](#filter)** | Filter queries by an attribute's value | `null` | -| **[facetsDistribution](#facets-distribution)** | Display the count of matches per facet | `null` | +| **[facets](#facets)** | Display the count of matches per facet | `null` | | **[attributesToRetrieve](#attributes-to-retrieve)** | Attributes to display in the returned documents | `["*"]` | | **[attributesToCrop](#attributes-to-crop)** | Attributes whose values have to be cropped | `null` | | **[cropLength](#crop-length)** | Maximum length of cropped value in words | `10` | @@ -219,7 +213,7 @@ This is not necessary when using the `POST` route or one of our [SDKs](/learn/wh | **[attributesToHighlight](#attributes-to-highlight)** | Highlight matching terms contained in an attribute | `null` | | **[highlightPreTag](#highlight-tags)** | String inserted at the start of a highlighted term | `""` | | **[highlightPostTag](#highlight-tags)** | String inserted at the end of a highlighted term | `""` | -| **[matches](#matches)** | Return matching terms location | `false` | +| **[showMatchesPosition](#show-matches-position)** | Return matching terms location | `false` | | **[sort](#sort)** | Sort search results by an attribute's value | `null` | ### Query (q) @@ -366,53 +360,39 @@ _geoRadius(lat, lng, distance_in_meters) -### Facets distribution +### Facets -**Parameter**: `facetsDistribution` +**Parameter**: `facets` **Expected value**: an array of `attribute`s or `["*"]` **Default value**: `null` -Returns the number of documents matching the current search query for each given facet. +Returns the number of documents matching the current search query for each given facet. When `facets` is set, the search results object contains the `facetDistribution` field that shows the number of remaining candidates for each specified facet. This parameter can take two values: -- An array of attributes: `facetsDistribution=["attributeA", "attributeB", …]` +- An array of attributes: `facets=["attributeA", "attributeB", …]` - An asterisk—this will return a count for all facets present in `filterableAttributes` ::: note -If an attribute used on `facetsDistribution` has not been added to the `filterableAttributes` list, it will be ignored. +If an attribute used on `facets` has not been added to the `filterableAttributes` list, it will be ignored. ::: -#### Returned fields - -When `facetsDistribution` is set, the search results object contains **two additional fields**: - -- `facetsDistribution`: The number of remaining candidates for each specified facet -- `exhaustiveFacetsCount`: A `true` or `false` value indicating whether the count is exact (`true`) or approximate (`false`) - -`exhaustiveFacetsCount` is `false` when the search matches contain too many different values for the given `facetName`s. In this case, Meilisearch stops the distribution count to prevent slowing down the request. - -::: warning -`exhaustiveFacetsCount` is not currently implemented and will always return `false`. -::: - -[Learn more about facet distribution in the filtering and faceted search guide.](/learn/advanced/filtering_and_faceted_search.md#facets-distribution) +[Learn more about facet distribution in the filtering and faceted search guide.](/learn/advanced/filtering_and_faceted_search.md#using-facets) #### Example Given a movie database, suppose that you want to know the number of `Batman` movies per genre: - + You would get the following response: ```json { … - "nbHits": 1684, + "estimatedTotalHits": 1684, "query": "Batman", - "exhaustiveFacetsCount": false, - "facetsDistribution": { + "facetDistribution": { "genres": { "action": 273, "animation": 118, @@ -620,13 +600,13 @@ You can find the highlighted query terms inside the `_formatted` property: Though it is not necessary to use `highlightPreTag` and `highlightPostTag` in conjunction, be careful to ensure tags are correctly matched. In the above example, not setting `highlightPostTag` would result in malformed HTML: `Winter Feast`. ::: -### Matches +### Show matches position -**Parameter**: `matches` +**Parameter**: `showMatchesPosition` **Expected value**: `true` or `false` **Default value**: `false` -Adds a `_matchesInfo` object to the search response that contains the location of each occurrence of queried terms across all fields. This is useful when you need more control than offered by our [built-in highlighting](#attributes-to-highlight). `matches` only works for strings, numbers, and arrays of strings and numbers. +Adds a `_matchesPosition` object to the search response that contains the location of each occurrence of queried terms across all fields. This is useful when you need more control than offered by our [built-in highlighting](#attributes-to-highlight). `showMatchesPosition` only works for strings, numbers, and arrays of strings and numbers. The beginning of a matching term within a field is indicated by `start`, and its length by `length`. @@ -636,11 +616,11 @@ The beginning of a matching term within a field is indicated by `start`, and its #### Example -If you set `matches` to `true` and search for `winter feast`: +If you set `showMatchesPosition` to `true` and search for `winter feast`: - + -You would get the following response with **information about the matches in the `_matchesInfo` object**. Note how Meilisearch searches for `winter` and `feast` separately because of the whitespace: +You would get the following response with **information about the matches in the `_matchesPosition` object**. Note how Meilisearch searches for `winter` and `feast` separately because of the whitespace: ```json { @@ -649,7 +629,7 @@ You would get the following response with **information about the matches in the "poster": "https://image.tmdb.org/t/p/w500/rV77WxY35LuYLOuQvBeD1nyWMuI.jpg", "overview": "The Winter Feast is Po's favorite holiday. Every year he and his father hang decorations, cook together, and serve noodle soup to the villagers. But this year Shifu informs Po that as Dragon Warrior, it is his duty to host the formal Winter Feast at the Jade Palace. Po is caught between his obligations as the Dragon Warrior and his family traditions: between Shifu and Mr. Ping.", "release_date": 1290729600, - "_matchesInfo": { + "_matchesPosition": { "overview": [ { "start": 4,