diff --git a/open-api.yaml b/open-api.yaml index 47dea996..1273d9ee 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -33,6 +33,22 @@ components: type: integer description: Offset given for the query. If offset is not provided as a query parameter, this parameter displays the default offset value. example: 0 + page: + type: integer + description: Sets the specific results page to fetch. If page is not provided as a query parameter, this parameter is ignored. + example: 1 + hitsPerPage: + type: integer + description: Sets the number of results returned per page. If hitsPerPage is not provided as a query parameter, this parameter is ignored. + example: 20 + totalHits: + type: integer + description: Returns the total number of search results. Computed if either `page` or `hitsPerPage` is provided as a query parameter. + example: 20 + totalPages: + type: integer + description: Returns the total number of navigatable results pages for the search query. Computed if either `page` or `hitsPerPage` is provided as a query parameter. + example: 20 total: type: integer description: Total number of browsable results using offset/limit parameters for the given resource. @@ -234,6 +250,18 @@ components: estimatedTotalHits: type: integer description: Estimated number of candidates for the search query. + page: + type: integer + description: The specific search results page to fetch. + hitsPerPage: + type: integer + description: Number of returned results per page. + totalHits: + type: integer + description: Exhaustive total number of search results for the search query. + totalPages: + type: integer + description: Number of navigatable results pages for the search query. facetDistribution: type: object additionalProperties: @@ -260,9 +288,6 @@ components: example: ninja required: - hits - - offset - - limit - - estimatedTotalHits - processingTimeMs - query task: @@ -771,6 +796,20 @@ components: schema: type: number default: 0 + page: + name: page + in: query + description: Sets the specific results page. + schema: + type: number + default: 1 + hitsPerPage: + name: hitsPerPage + in: query + description: Sets the number of results returned for a query. If hitsPerPage is not provided as a query parameter, this parameter is ignored. + schema: + type: number + default: 20 from: name: from in: query @@ -1653,6 +1692,8 @@ paths: - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/limit' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/hitsPerPage' - $ref: '#/components/parameters/showMatchesPosition' - $ref: '#/components/parameters/matchingStrategy' responses: @@ -1780,6 +1821,14 @@ paths: type: number description: Maximum number of documents returned. default: 20 + page: + type: number + description: The specific search results page to fetch. + example: 1 + hitsPerPage: + type: number + description: Number of returned results per page. + example: 20 sort: $ref: '#/components/schemas/sort' examples: diff --git a/text/0034-telemetry-policies.md b/text/0034-telemetry-policies.md index abbb8563..bb1c2591 100644 --- a/text/0034-telemetry-policies.md +++ b/text/0034-telemetry-policies.md @@ -119,6 +119,7 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat | `q.max_terms_number` | Highest number of terms given for the `q` parameter in this batch | 5 | `Documents Searched POST`, `Documents Searched GET` | | `pagination.max_limit` | Highest value given for the `limit` parameter in this batch | 60 | `Documents Searched POST`, `Documents Searched GET` | | `pagination.max_offset` | Highest value given for the `offset` parameter in this batch | 1000 | `Documents Searched POST`, `Documents Searched GET` | +| `pagination.most_used_navigation` | Most used search results navigation among all search requests in this batch. `estimated` / `exhaustive` | `estimated` | `Documents Searched POST`, `Documents Searched GET` | | `formatting.max_attributes_to_retrieve` | The maximum number of attributes to retrieve encountered among all requests in this batch. | 100 | `Documents Searched POST`, `Documents Searched GET` | | `formatting.max_attributes_to_highlight` | The maximum number of attributes to highlight encountered among all requests in this batch. | 100 | `Documents Searched POST`, `Documents Searched GET` | | `formatting.highlight_pre_tag` | `true` if `highlightPreTag` was used in this batch, otherwise `false` | false | `Documents Searched POST`, `Documents Searched GET` | @@ -252,6 +253,7 @@ This property allows us to gather essential information to better understand on | q.max_terms_number | The maximum number of terms for the `q` parameter among all requests in the aggregated event. | `5` | | pagination.max_limit | The maximum limit encountered among all requests in the aggregated event. | `20` | | pagination.max_offset | The maximum offset encountered among all requests in the aggregated event. | `1000` | +| pagination.most_used_navigation | Most used search results navigation among all requests in the aggregated event. `estimated` / `exhaustive` | `estimated` || | formatting.max_attributes_to_retrieve | The maximum number of attributes to retrieve encountered among all requests in the aggregated event. | `100` | | formatting.max_attributes_to_highlight | The maximum number of attributes to highlight encountered among all requests in the aggregated event. | `100` | | formatting.highlight_pre_tag | Does `highlightPreTag` has been used in the aggregated event? If yes, `true` otherwise `false` | `false` | @@ -284,6 +286,7 @@ This property allows us to gather essential information to better understand on | q.max_terms_number | The maximum number of terms for the `q` parameter among all requests in the aggregated event. | `5` | | pagination.max_limit | The maximum limit encountered among all requests in the aggregated event. | `20` | | pagination.max_offset | The maximum offset encountered among all requests in the aggregated event. | `1000` | +| pagination.most_used_navigation | Most used search results navigation among all requests in the aggregated event. `estimated` / `exhaustive` | `estimated` | | formatting.max_attributes_to_retrieve | The maximum number of attributes to retrieve encountered among all requests in the aggregated event. | `100` | | formatting.max_attributes_to_highlight | The maximum number of attributes to highlight encountered among all requests in the aggregated event. | `100` | | formatting.highlight_pre_tag | Does `highlightPreTag` has been used in the aggregated event? If yes, `true` otherwise `false` | `false` | diff --git a/text/0118-search-api.md b/text/0118-search-api.md index 668d4d2b..b30e8410 100644 --- a/text/0118-search-api.md +++ b/text/0118-search-api.md @@ -39,15 +39,18 @@ If a master key is used to secure a Meilisearch instance, the auth layer returns | [`facets`](#314-facets) | Array of String - String | False | | [`limit`](#315-limit) | Integer | False | | [`offset`](#316-offset) | Integer | False | -| [`attributesToRetrieve`](#317-attributestoretrieve) | Array of String - String | False | -| [`attributesToHighlight`](#318-attributestohighlight) | Array of String - String | False | -| [`highlightPreTag`](#319-highlightpretag) | String | False | -| [`highlightPostTag`](#3110-highlightposttag) | String | False | -| [`attributesToCrop`](#3111-attributestocrop) | Array of String - String | False | -| [`cropLength`](#3112-croplength) | Integer | False | -| [`cropMarker`](#3113-cropmarker) | String | False | -| [`showMatchesPosition`](#3114-showmatchesposition) | Boolean | False | -| [`matchingStrategy`](#3115-matchingStrategy) | String | False | +| [`page`](#317-page) | Integer | False | +| [`hitsPerPage`](#318-hitsperpage) | Integer | False | +| [`attributesToRetrieve`](#319-attributestoretrieve) | Array of String - String | False | +| [`attributesToHighlight`](#3110-attributestohighlight)| Array of String - String | False | +| [`highlightPreTag`](#3111-highlightpretag) | String | False | +| [`highlightPostTag`](#3112-highlightposttag) | String | False | +| [`attributesToCrop`](#3113-attributestocrop) | Array of String - String | False | +| [`cropLength`](#3114-croplength) | Integer | False | +| [`cropMarker`](#3115-cropmarker) | String | False | +| [`showMatchesPosition`](#3116-showmatchesposition) | Boolean | False | +| [`matchingStrategy`](#3117-matchingStrategy) | String | False | + #### 3.1.1. `q` @@ -416,6 +419,8 @@ The distribution of the different facets is returned in the `facetDistribution` Sets the maximum number of documents to be returned for the search query. +If in addition to either `page` and/or `hitsPerPage`, `limit` and/or `offset` are provided as well, `limit` and `offset` are ignored. See [explaination](#3181-navigating-search-results-by-page-selection). + - πŸ”΄ Sending a value with a different type than `Integer` for `limit` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. #### 3.1.6. `offset` @@ -426,9 +431,163 @@ Sets the maximum number of documents to be returned for the search query. Sets the starting point in the search results, effectively skipping over a given number of documents. +If in addition to either `page` and/or `hitsPerPage`, `limit` and/or `offset` are provided as well, `limit` and `offset` are ignored. See [details](#3181-navigating-search-results-by-page-selection). + - πŸ”΄ Sending a value with a different type than `Integer` for `offset` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. -#### 3.1.7. `attributesToRetrieve` +#### 3.1.7. `page` + +- Type: Integer +- Required: False +- Default: `null` + +Sets the specific results page to fetch. + +By default, page is `null`, or `1` if `hitsPerPage` is provided. +The first page has a value of `1`, the second `2`, etc... When `0` is provided as a value, no hits are returned. + +When providing `page` or `hitsPerPage` in the query parameters, the `page selection` system is enabled, which makes it possible to navigate through the search results pages. See explanation on the [`page selection`](#3181-navigating-search-results-by-page-selection). + +If in addition to either `page` and/or `hitsPerPage`, `limit` and/or `offset` are provided as well, `limit` and `offset` are ignored. See [explaination](#3181-navigating-search-results-by-page-selection). + +- πŸ”΄ Sending a value with a different type than `Integer` for `page` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. + +#### 3.1.8. `hitsPerPage` + +- Type: Integer +- Required: False +- Default: `null` + +Sets the number of results returned for a query. + +By default, `hitsPerPage` is `null`, or `20` if `page` is provided. When `0` is provided as a value, no hits are returned. + +When providing `page` or `hitsPerPage` in the query parameters, the `page selection` system is enabled, which makes it possible to navigate through the search results pages. See explanation on the [`page selection`](#3181-navigating-search-results-by-page-selection). + +If in addition to either `page` and/or `hitsPerPage`, `limit` and/or `offset` are provided as well, `limit` and `offset` are ignored. See [explaination](#3181-navigating-search-results-by-page-selection). + +- πŸ”΄ Sending a value with a different type than `Integer` for `hitsPerPage` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. + +#### 3.1.8.1. Navigating search results by page selection + +By default, `limit` and `offset` are used to navigate search results. While being performant, it lacks exhaustiveness to create a seamless page selection navigation. Upon using `limit`/`offset`, `estimatedTotalHits` is returned, which provides a rough estimation of how many hits may be candidates for a given request. See [`limit`/`offset` usage](#31811-limitoffset-usage) for further explanation. + +The `page selection` system provides an alternative that tackles the above-mentioned issue when reliable information is needed to navigate results with a page selector. e.g. A page selector component `<< < 1, 2, 3, ...14 > >>`. Nonetheless, it's considered less performant on a larger number of results as the engine needs to compute the `totalHits` exhaustively. +With this page selection system, it is possible to jump from one page to another using the `page` parameter and decide how many results should be returned per page with the `hitsPerPage` parameter. See [`page`/`hitsPerPage` usage](#31812-pagehitsperpage-usage) for further explanation. + +##### 3.1.8.1.1. Limit/offset usage + +When either `limit` or `offset` is specified or when neither `limit`, `offset`, `page` and `hitsPerPage` are specified, the response object contains the related fields: +- [`estimatedTotalHits`](#324-estimatedtotalhits) +- [`limit`](#322-limit) +- [`offset`](#323-offset) + +If in addition to `limit` and/or `offset`, either `page` or `hitsPerPage` is also provided, `limit` and `offset` parameters are ignored. + +For example, given the following query parameters: + +- limit: 10 +- offset: 1 + +The response objects contain these specific fields: +```json +{ + "hits": [ + /// ... 10 hits + ], + /// ... other fields + "limit": 10, + "offset": 1, + "estimatedTotalHits": 1345 +} +``` + +For example, on a query with no query parameters: + +The response objects contain these specific fields: +```json +{ + "hits": [ + /// ... 10 hits + ], + /// ... other fields + "limit": 20, + "offset": 0, + "estimatedTotalHits": 1345 +} +``` + +##### 3.1.8.1.2 page/hitsPerPage usage + +As soon as either `page` or `hitsPerPage` is used as a query parameter, in the response object, `limit`, `offset`, and `estimatedTotalHits` are removed and page selection related fields are returned: + +- [`hitsPerPage`](#326-hitsperpage): number of results per page. +- [`page`](#325-page): current search results page. The counting starts at `1`. +- [`totalPages`](#327-totalpages): total number of results pages. Calculated using `hitsPerPage` value. +- [`totalHits`](#328-totalhits): total number of search results. + +Both `totalPages` and `totalHits` are computed until they reach the [`pagination.maxTotalHits`](#https://github.com/meilisearch/specifications/blob/main/text/157-pagination-setting-api.md#311-maxtotalhits) number from the settings. + +If in addition to either `page` and/or `hitsPerPage`, `limit` and/or `offset` are provided as well, `limit` and `offset` are ignored. + +For example, given the following query parameters: + +- page: 2 +- hitsPerPage: 10 + +The response objects contain these specific fields: +```json +{ + "hits": [ + /// ... 10 hits + ], + /// ... other fields + "page": 2, + "hitsPerPage": 10, + "totalHits": 2100, + "totalPages": 210 +} +``` + +For example, given the following query parameters: + +- page: 2 +- hitsPerPage: 10 +- limit: 1 + +The response objects contain these specific fields: +```json +{ + "hits": [ + /// ... 10 hits + ], + /// ... other fields + "page": 2, + "hitsPerPage": 10, + "totalHits": 2100, + "totalPages": 210 +} +``` + +For example, given the following query parameters: + +- page: 0 +- hitsPerPage: 10 + +The response objects contain these specific fields: +```json +{ + "hits": [], + /// ... other fields + "page": 0, + "hitsPerPage": 10, + "totalHits": 2100, + "totalPages": 210 +} +``` + + +#### 3.1.9. `attributesToRetrieve` - Type: Array of String (POST) | String (GET) - Required: False @@ -442,7 +601,7 @@ If no value is specified, the default value of `attributesToRetrieve` is used (` - πŸ”΄ Sending a value with a different type than `Array of String`(POST), `String`(GET) or `null` for `attributesToRetrieve` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. -#### 3.1.8. `attributesToHighlight` +#### 3.1.10. `attributesToHighlight` - Type: Array of String (POST) | String(GET) - Required: False @@ -454,29 +613,29 @@ If `attributesToHighlight` is present in the search query, the search results wi If `"*"` is provided as a value (`attributesToHighlight=["*"]`), all the attributes present in `displayedAttributes` setting will be highlighted. -Highlighted parts are surrounded by the [`highlightPreTag`](#319-highlightpretag) and [`highlightPostTag`](#3110-highlightposttag) parameters. +Highlighted parts are surrounded by the [`highlightPreTag`](3111-highlightpretag) and [`highlightPostTag`](#3112-highlightposttag) parameters. `attributesToHighlight` only works on values of the following types: `string`, `number`, `array`, `object`. When highlighted, number attributes are transformed to string. - πŸ”΄ Sending a value with a different type than `Array[String]`(POST), `String`(GET) or `null` for `attributesToHighlight` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. -##### 3.1.8.1. searchableAttributes +##### 3.1.10.1. searchableAttributes Attributes not defined in the `searchableAttributes` index setting are also highlighted if assigned to `attributesToHighlight`. -##### 3.1.8.2. stopWords +##### 3.1.10.2. stopWords Attributes defined in the `stopWords` index setting are also highlighted if matched. -##### 3.1.8.3. Tokenizer Separators +##### 3.1.10.3. Tokenizer Separators Tokenizer separators are not highlighted. -##### 3.1.8.4. synonyms +##### 3.1.10.4. synonyms Synonyms are also highlighted. -#### 3.1.9. `highlightPreTag` +#### 3.1.11. `highlightPreTag` - Type: String - Required: False @@ -484,13 +643,13 @@ Synonyms are also highlighted. Specifies the string to put **before** every highlighted query terms. -This parameter is applied to the fields configured in `attributesToHighlight`. If there are none, this parameter has no effect. See [3.1.8. `attributesToHighlight`](#318-attributestohighlight) section. +This parameter is applied to the fields configured in `attributesToHighlight`. If there are none, this parameter has no effect. See [3.1.10. `attributesToHighlight`](3110-attributestohighlight) section. - πŸ”΄ Sending a value with a different type than `String` for `highlightPreTag` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. If `attributesToHighlight` is omitted while `highlightPreTag` is specified, there is no error. -#### 3.1.10. `highlightPostTag` +#### 3.1.12. `highlightPostTag` - Type: String - Required: False @@ -498,13 +657,13 @@ If `attributesToHighlight` is omitted while `highlightPreTag` is specified, ther Specifies the string to put **after** the highlighted query terms. -This parameter is applied to the fields from `attributesToHighlight`. If there are none, this parameter has no effect. See [3.1.8. `attributesToHighlight`](#318-attributestohighlight) section. +This parameter is applied to the fields from `attributesToHighlight`. If there are none, this parameter has no effect. See [3.1.10. `attributesToHighlight`](3110-attributestohighlight) section. - πŸ”΄ Sending a value with a different type than `String` for `highlightPostTag` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. If `attributesToHighlight` is omitted while `highlightPostTag` is specified, there is no error. -#### 3.1.11. `attributesToCrop` +#### 3.1.13. `attributesToCrop` - Type: Array[String]|String - Required: False @@ -516,27 +675,27 @@ If `attributesToCrop` is present in the search query, the search results will in If `"*"` is provided as a value (`attributesToCrop=["*"]`), all the attributes present in `displayedAttributes` setting will be cropped. -The number of words contained in the cropped value is defined by the `cropLength` parameter. See [3.1.1.12. `cropLength`](#3112-croplength) section. +The number of words contained in the cropped value is defined by the `cropLength` parameter. See [3.1.1.14. `cropLength`](#3114-croplength) section. The value of `cropLength` can be customized per attribute. See [3.1.12.1. Custom `cropLength` Defined Per Cropped Attribute](#31121-custom-croplength-defined-per-attribute) section. -The engine adds a marker by default in front of and/or behind the part selected by the cropper. This marker is customizable. See [3.1.13. `cropMarker`](#3113-cropmarker) section. +The engine adds a marker by default in front of and/or behind the part selected by the cropper. This marker is customizable. See [3.1.13. `cropMarker`](#3115-cropmarker) section. - πŸ”΄ Sending a value with a different type than `Array[String]`(POST), `String`(GET) or `null` for `attributesToCrop` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. -##### 3.1.11.2. searchableAttributes +##### 3.1.13.2. searchableAttributes Attributes configured in `attributesToCrop` are cropped even if not present in the `searchableAttributes` index setting. -##### 3.1.11.3. stopWords +##### 3.1.13.3. stopWords Terms defined in the `stopWords` index setting are counted as words regarding `cropLength`. -##### 3.1.11.3. Tokenizer Separators +##### 3.1.13.3. Tokenizer Separators Tokenizer separators aren't counted as words regarding `cropLength`. -#### 3.1.12. `cropLength` +#### 3.1.14. `cropLength` - Type: Integer - Required: False @@ -544,13 +703,13 @@ Tokenizer separators aren't counted as words regarding `cropLength`. Sets the total number of **words** to keep for the cropped part of an attribute specified in the `attributesToCrop` parameter. It means that if `10` is set for `cropLength`, the cropped part returned in `_formatted` will only be 10 words long. -This parameter is applied to the fields from `attributesToCrop`. If there are none, this parameter has no effect. See [3.1.11. `attributesToCrop`](#3111-attributestocrop) section. +This parameter is applied to the fields from `attributesToCrop`. If there are none, this parameter has no effect. See [3.1.13. `attributesToCrop`](#3113-attributestocrop) section. Sending a `0` value deactivates the cropping unless a custom crop length is defined for an attribute inside `attributesToCrop`. - πŸ”΄ Sending a value with a different type than `Integer` for `cropLength` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. -##### 3.1.12.1. Custom `cropLength` Defined Per Attribute. +##### 3.1.14.1. Custom `cropLength` Defined Per Attribute. Optionally, indicating a custom crop length for any of the listed attributes is possible: @@ -558,9 +717,9 @@ Optionally, indicating a custom crop length for any of the listed attributes is A custom crop length set in this way has priority over the `cropLength` parameter. -##### 3.1.12.2 Examples +##### 3.1.14.2 Examples -###### 3.1.12.1.1. Extending around +###### 3.1.14.1.1. Extending around Given an attribute defined in `attributesToCrop` containing: @@ -574,7 +733,7 @@ Cropped query terms are counted as a word regarding `cropLength`. Sending more query terms than the `cropLength` value has no impact. The cropped part will contain the `cropLength` number. -###### 3.1.12.1.2. Keeping a phrase context +###### 3.1.14.1.2. Keeping a phrase context After Meilisearch has chosen the best possible match window (some number of words < `cropLength`), it will add words from before or after the match window until the total number is equal to `cropLength`. In doing so, it will attempt to add context to the match window by choosing words from the same sentence(s) where the match window occurs. @@ -590,25 +749,25 @@ and not like: `Natalie risk her future. Split The World is a book…` -#### 3.1.13. `cropMarker` +#### 3.1.15. `cropMarker` - Type: String - Required: False - Default: `"…"` (U+2026) -Sets which string to add before and/or after the cropped text. See [3.1.11. `attributesToCrop`](#3111-attributestocrop) section. +Sets which string to add before and/or after the cropped text. See [3.1.13. `attributesToCrop`](#3113-attributestocrop) section. -The specified crop marker is applied by following rules outline in section [3.1.13.1. Applying `cropMarker`](#31131-applying-cropmarker). +The specified crop marker is applied by following rules outline in section [3.1.15.1. Applying `cropMarker`](#3115-cropmarker). Specifying `cropMarker` to `""` or `null` implies that no marker will be applied to the cropped part. -This parameter is applied to the fields configured in `attributesToCrop`. If there are none, this parameter has no effect. See [3.1.11. `attributesToCrop`](#3111-attributestocrop) section. +This parameter is applied to the fields configured in `attributesToCrop`. If there are none, this parameter has no effect. See [3.1.13. `attributesToCrop`](#3113-attributestocrop) section. - πŸ”΄ Sending a value with a different type than `String` or `null` for `cropMarker` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. -##### 3.1.13.1. Applying `cropMarker` +##### 3.1.15.1. Applying `cropMarker` -###### 3.1.13.1.1. Matched Part To Be Cropped +###### 3.1.15.1.1. Matched Part To Be Cropped The cropping algorithm tries to match the window with the highest density of query terms within the `cropLength` limit. @@ -630,13 +789,13 @@ Only one cropped part from an attribute is returned. If no part is found when selecting a part to be cropped, the returned value in `_formatted` will start at the beginning of the attribute and include a number of words equal to `cropLength`. -###### 3.1.13.1.2. Positioning Markers +###### 3.1.15.1.2. Positioning Markers If the cropped part has been matched against query terms and contains the beginning of the attribute to be cropped, the `cropMarker` is not placed to the left of the cropped part. If the cropped part has been matched against query terms and contains the end of the attribute to be cropped, the `cropMarker` is not placed to the right of the cropped part. -#### 3.1.14. `showMatchesPosition` +#### 3.1.16. `showMatchesPosition` - Type: Boolean - Required: False @@ -648,7 +807,7 @@ It's useful when more control is needed than offered by the built-in highlightin - πŸ”΄ Sending a value with a different type than `Boolean` or `null` for `showMatchesPosition` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. -#### 3.1.15. `matchingStrategy` +#### 3.1.17. `matchingStrategy` - Type: String - Required: False @@ -660,11 +819,11 @@ Two different strategies are available, `last` and `all`. By default, the `last` - πŸ”΄ Sending a value with a different type than `String` and other than `last` or `all` as a value for `matchingStrategy` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. -##### 3.1.15.1. `last` strategy +##### 3.1.17.1. `last` strategy The documents containing ALL the query words (i.e. in the `q` parameter) are returned first by Meilisearch. If Meilisearch doesn't have enough documents to fit the requested `limit`, it iteratively ignores the query words from the last typed word to the first typed word to match more documents. -##### 3.1.15.2. `all` strategy +##### 3.1.17.2. `all` strategy Only the documents containing ALL the query words (i.e. in the `q` parameter) are returned by Meilisearch. If Meilisearch doesn't have enough documents to fit the requested `limit`, it returns the documents found without trying to match more documents. @@ -673,12 +832,16 @@ Only the documents containing ALL the query words (i.e. in the `q` parameter) ar | Field | Type | Required | |-------------------------------------------------|------------|----------| | [`hits`](#321-hits) | Array[Hit] | True | -| [`limit`](#322-limit) | Integer | True | -| [`offset`](#323-offset) | Integer | True | -| [`estimatedTotalHits`](#324-estimatedTotalHits) | Integer | True | -| [`facetDistribution`](#325-facetdistribution) | Object | False | -| [`processingTimeMs`](#326-processingtimems) | Integer | True | -| [`query`](#327-query) | String | True | +| [`limit`](#322-limit) | Integer | False | +| [`offset`](#323-offset) | Integer | False | +| [`estimatedTotalHits`](#324-estimatedTotalHits) | Integer | False | +| [`page`](#325-page) | Integer | False | +| [`hitsPerPage`](#326-hitsperpage) | Integer | False | +| [`totalPages`](#327-totalpages) | Integer | False | +| [`totalHits`](#328-totalhits) | Integer | False | +| [`facetDistribution`](#329-facetdistribution) | Object | False | +| [`processingTimeMs`](#3210-processingtimems) | Integer | True | +| [`query`](#3211-query) | String | True | #### 3.2.1. `hits` @@ -689,7 +852,7 @@ Results of the search query as an array of documents. > Hit object represents a matched document as a search result. -> The search parameters `attributesToRetrieve` influence the returned payload for a hit. See [3.1.7. `attributesToRetrieve`](#317-attributestoretrieve) section. +> The search parameters `attributesToRetrieve` influence the returned payload for a hit. See [3.1.7. `attributesToRetrieve`](#319-attributestoretrieve) section. A search result can contain special properties. See [3.2.1.1. `hit` Special Properties](#3211-hits-special-properties) section. @@ -904,34 +1067,84 @@ The beginning of a matching term within a field is indicated by `start`, and its `start` and `length` are measured in bytes and not the number of characters. For example, `ΓΌ` represents two bytes but one character. -> See [3.1.14. `showMatchesPosition`](#3114-showmatchesposition) section. +> See [3.1.14. `showMatchesPosition`](#3116-showmatchesposition) section. #### 3.2.2. `limit` - Type: Integer -- Required: True +- Required: False + +Returns the `limit` search parameter used for the query. +This field is returned only when: +- `limit` and/or `offset` are used as query parameters. +- None of `limit`, `offset`, `page`, `hitsPerPage` are used as a query parameter -Returns the `limit` search parameter used for the query. +See [details](#3181-navigating-search-results-by-page-selection) on the different ways of navigating search results. > See [3.1.5. `limit`](#315-limit) section. #### 3.2.3. `offset` - Type: Integer -- Required: True +- Required: False Returns the `offset` search parameter used for the query. +This field is returned only when none of `page` and `hitsPerPage` are used as a query parameter. + +See [explanation](#3181-navigating-search-results-by-page-selection) on the different ways of navigating search results. > See [3.1.6. `offset` section](#316-offset) section. #### 3.2.4. `estimatedTotalHits` - Type: Integer -- Required: True +- Required: False + +Returns the estimated number of candidates for the search query. This field is returned only when `limit` or/and `offset` are used as a query parameter. + +This field is returned only when: +- `limit` and/or `offset` are used as query parameters. +- None of `limit`, `offset`, `page`, `hitsPerPage` are used as a query parameter + +See [details](#3181-navigating-search-results-by-page-selection) on the different ways of navigation search results. + +#### 3.2.5. `page` + +- Type: Integer +- Required: False + +Returns the current search results page. This field is returned only when the `page selection` feature is enabled; see [details](#3181-navigating-search-results-by-page-selection). + +> See [3.1.7. `page` section](#317-page) section. + +#### 3.2.6. `hitsPerPage` + +- Type: Integer +- Required: False + +Returns the number of results per page. This field is returned only when the `page selection` feature is enabled; see [details](#3181-navigating-search-results-by-page-selection). + +> See [3.1.7. `hitsPerPage` section](#318-hitsperpage) section. + +#### 3.2.7. `totalPages` + +- Type: Integer +- Required: False + +Returns the total number of results pages. Calculated using [`hitsPerPage`]. Both `totalPages` and `totalHits` are computed until they reach the [`pagination.maxTotalHits`](#https://github.com/meilisearch/specifications/blob/main/text/157-pagination-setting-api.md#311-maxtotalhits) number from the settings. + +This field is returned only when the `page selection` feature is enabled; see [details](#3181-navigating-search-results-by-page-selection). + +#### 3.2.8. `totalHits` + +- Type: Integer +- Required: False + +Returns the total number of search results. Both `totalPages` and `totalHits` are computed until they reach the [`pagination.maxTotalHits`](#https://github.com/meilisearch/specifications/blob/main/text/157-pagination-setting-api.md#311-maxtotalhits) number from the settings. -Returns the estimated number of candidates for the search query. +This field is returned only when the `page selection` feature is enabled, see [details](#3181-navigating-search-results-by-page-selection). -#### 3.2.5. `facetDistribution` +#### 3.2.9. `facetDistribution` - Type: Object - Required: False @@ -942,14 +1155,14 @@ If a field distributed as a facet contains no value, it is returned as a `facetD > See [3.1.4. `facet`](#314-facets) section. -#### 3.2.6. `processingTimeMs` +#### 3.2.10. `processingTimeMs` - Type: Integer - Required: True Processing time of the search query in **milliseconds**. -#### 3.2.7. `query` +#### 3.2.11. `query` - Type: String - Required: True