diff --git a/open-api.yaml b/open-api.yaml index e44bfa35..9b7dd0c3 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -86,7 +86,7 @@ components: overview: 'When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.' release_date: '1993-01-01' description: 'A document made of attribute. The maximum number of attribute for a document is 65,535.' - matchesInfo: + matchesPosition: type: object properties: start: @@ -113,7 +113,7 @@ components: poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg' overview: 'When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.' release_date: '1993-01-01' - _matchesInfo: + _matchesPosition: overview: - start: 49 length: 5 @@ -131,7 +131,7 @@ components: poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg' overview: 'When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.' release_date: '1993-01-01' - _matchesInfo: + _matchesPosition: overview: - start: 49 length: 5 @@ -143,12 +143,12 @@ components: type: object description: Only present if `attributesToHighlight`/`attributesToCrop` is not empty. Return highlighted and cropped fields. additionalProperties: true - _matchesInfo: + _matchesPosition: type: object - description: Only present if matches = `true`. Array of all search query occurrences in all fields. + description: Only present if showMatchesPosition = `true`. Array of all search query occurrences in all fields. properties: '': - $ref: '#/components/schemas/matchesInfo' + $ref: '#/components/schemas/matchesPosition' attribute: type: - string @@ -228,20 +228,17 @@ components: limit: type: integer description: Number of returned documents. - nbHits: + estimatedTotalHits: type: integer - description: Total number of candidates for this search in the database. - exhaustiveNbHits: - type: boolean - description: Whether `nbHits` is exhaustive. - facetsDistribution: + description: Estimated number of candidates for the search query. + facetDistribution: type: object additionalProperties: type: object additionalProperties: type: integer description: | - [Distribution of the given facets](https://docs.meilisearch.com/reference/features/search_parameters.html#facets-distribution). + [Distribution of the given facets](https://docs.meilisearch.com/reference/features/search_parameters.html#facet-distribution). example: genres: action: 273 @@ -251,9 +248,6 @@ components: comedy: 475 mystery: 70 thriller: 217 - exhaustiveFacetsCount: - type: boolean - description: Whether `facetsDistribution` is exhaustive. processingTimeMs: type: integer description: Processing time of the query. @@ -265,8 +259,7 @@ components: - hits - offset - limit - - nbHits - - exhaustiveNbHits + - estimatedTotalHits - processingTimeMs - query task: @@ -769,21 +762,21 @@ components: example: 5 default: 10 description: Sets the total number of words to keep around the matched part of an attribute specified in the `attributesToCrop` parameter. - facetsDistribution: - name: facetsDistribution + facets: + name: facets in: query schema: type: string example: 'genres,author' - description: 'Comma-separated list of attributes whose fields will be distributed as a facet. If you have [set up filterableAttributes](https://docs.meilisearch.com/reference/features/settings.html#filterable-attributes), you can retrieve the count of matching terms for each facets.[Learn more about facet distribution in the dedicated guide](https://docs.meilisearch.com/reference/features/search_parameters.html#facets-distribution)' - matches: - name: matches + description: 'Comma-separated list of attributes whose fields will be distributed as a facet. If you have [set up filterableAttributes](https://docs.meilisearch.com/reference/features/settings.html#filterable-attributes), you can retrieve the count of matching terms for each facets.[Learn more about facet distribution in the dedicated guide](https://docs.meilisearch.com/reference/features/search_parameters.html#facet-distribution)' + showMatchesPosition: + name: showMatchesPosition in: query required: false schema: type: boolean default: 'false' - description: Defines whether an `_matchesInfo` object that contains information about the matches should be returned or not. + description: Defines whether an `_matchesPosition` object that contains information about the matches should be returned or not. sort: name: sort in: query @@ -1432,12 +1425,12 @@ paths: - $ref: '#/components/parameters/attributesToCrop' - $ref: '#/components/parameters/cropMarker' - $ref: '#/components/parameters/cropLength' - - $ref: '#/components/parameters/facetsDistribution' + - $ref: '#/components/parameters/facets' - $ref: '#/components/parameters/filter' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/limit' - - $ref: '#/components/parameters/matches' + - $ref: '#/components/parameters/showMatchesPosition' responses: '200': description: Ok @@ -1460,7 +1453,7 @@ paths: poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg' overview: 'When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.' release_date: '1993-01-01' - _matchesInfo: + _matchesPosition: overview: - start: 49 length: 5 @@ -1468,9 +1461,8 @@ paths: length: 5 limit: 0 offset: 0 - nbHits: 0 + estimatedTotalHits: 0 query: string - exhaustiveNbHits: true processingTimeMs: 0 '401': $ref: '#/components/responses/401' @@ -1539,15 +1531,15 @@ paths: type: number description: Sets the total number of **words** to keep for the cropped part of an attribute specified in the `attributesToCrop` parameter. default: 10 - matches: + showMatchesPosition: type: boolean - description: Defines whether an `_matchesInfo` object that contains information about the matches should be returned or not. + description: Defines whether an `_matchesPosition` object that contains information about the matches should be returned or not. default: false filter: $ref: '#/components/schemas/filter' - facetsDistribution: + facets: type: array - description: 'Array of attributes whose fields will be distributed as a facet. If you have [set up filterableAttributes](https://docs.meilisearch.com/reference/features/settings.html#filterable-attributes), you can retrieve the count of matching terms for each [facets](https://docs.meilisearch.com/reference/features/filtering_and_faceted_search.html#faceted-search).[Learn more about facet distribution in the dedicated guide](https://docs.meilisearch.com/reference/features/search_parameters.html#facets-distribution)' + description: 'Array of attributes whose fields will be distributed as a facet. If you have [set up filterableAttributes](https://docs.meilisearch.com/reference/features/settings.html#filterable-attributes), you can retrieve the count of matching terms for each [facets](https://docs.meilisearch.com/reference/features/filtering_and_faceted_search.html#faceted-search).[Learn more about facet distribution in the dedicated guide](https://docs.meilisearch.com/reference/features/search_parameters.html#facet-distribution)' items: type: string example: '["genres", "author"]' @@ -1569,7 +1561,7 @@ paths: offset: 0 limit: 20 filter: (genres = Horror AND genres = Mystery) OR release_date > 523242000 - facetsDistribution: + facets: - genres - author attributesToRetrieve: @@ -1580,7 +1572,7 @@ paths: cropLength: 20 attributesToHighlight: - overview - matches: true + showMatchesPosition: true responses: '200': description: Ok @@ -1603,7 +1595,7 @@ paths: poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg' overview: 'When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.' release_date: '1993-01-01' - _matchesInfo: + _matchesPosition: overview: - start: 49 length: 5 @@ -1611,9 +1603,8 @@ paths: length: 5 limit: 0 offset: 0 - nbHits: 0 + estimatedTotalHits: 0 query: string - exhaustiveNbHits: true processingTimeMs: 0 '401': $ref: '#/components/responses/401' diff --git a/text/0034-telemetry-policies.md b/text/0034-telemetry-policies.md index d2bd3a44..910720ae 100644 --- a/text/0034-telemetry-policies.md +++ b/text/0034-telemetry-policies.md @@ -35,7 +35,6 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat [Amplitude](https://amplitude.com/) is a tool for graphing and highlighting collected data. Segment feeds Amplitude so that we can build visualizations according to our needs. - ---- #### Events table @@ -113,7 +112,8 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat | `formatting.highlight_post_tag` | `true` if `highlightPostTag` was used in this batch, otherwise `false` | false | `Documents Searched POST`, `Documents Searched GET` | | `formatting.crop_length` | `true` if `cropLength` was used in this batch, otherwise `false` | false | `Documents Searched POST`, `Documents Searched GET` | | `formatting.crop_marker` | `true` if `cropMarker` was used in this batch, otherwise `false` | false | `Documents Searched POST`, `Documents Searched GET` | -| `formatting.matches` | `true` if `matches` was used in this batch, otherwise `false` | false | `Documents Searched POST`, `Documents Searched GET` | +| `formatting.show_matches_position` | `true` if `showMatchesPosition` was used in this batch, otherwise `false` | false | `Documents Searched POST`, `Documents Searched GET` | +| `facets` | `true` if `facets` was used in this batch, otherwise `false` | false | `Documents Searched POST`, `Documents Searched GET` | | `primary_key` | Value given for the `primaryKey` parameter if used, otherwise `null` | id | `Index Created`, `Index Updated`, `Documents Added`, `Documents Updated`| | `payload_type` | All `payload_type` encountered in this batch | ["application/json", "text/plain", "application/x-ndjson"] | `Documents Added`, `Documents Updated` | | `index_creation` | `true` if a document addition or update request triggered index creation in this batch, otherwise `false` | true | `Documents Added`, `Documents Updated` | @@ -133,7 +133,6 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat | `filtered_by_type` | `true` if `GET /tasks` endpoint is filered by `type`, otherwise `false` | false | `Tasks Seen` | | `filtered_by_status` | `true` if `GET /tasks` endpoint is filered by `status`, otherwise `false` | false | `Tasks Seen` | - ---- #### Detailed list of Instance metrics and, events with their metrics @@ -218,7 +217,8 @@ This property allows us to gather essential information to better understand on | formatting.highlight_post_tag | Does `highlightPostTag` has been used in the aggregated event? If yes, `true` otherwise `false` | `false` | | formatting.crop_length | Does `cropLength` has been used in the aggregated event? If yes, `true` otherwise `false` | `false` | | formatting.crop_marker | Does `cropMarker` has been used in the aggregated event? If yes, `true` otherwise `false` | `false` | -| formatting.matches | Does `matches` has been used in the aggregated event? If yes, `true` otherwise `false` | `false` | +| formatting.show_matches_position | Does `showMatchesPosition` has been used in the aggregated event? If yes, `true` otherwise `false` | `false` | +| facets | Does `facets` has been used in the aggregated event? If yes, `true` otherwise `false` | `false` | --- @@ -245,7 +245,8 @@ This property allows us to gather essential information to better understand on | formatting.highlight_post_tag | Does `highlightPostTag` has been used in the aggregated event? If yes, `true` otherwise `false` | `false` | | formatting.crop_length | Does `cropLength` has been used in the aggregated event? If yes, `true` otherwise `false` | `false` | | formatting.crop_marker | Does `cropMarker` has been used in the aggregated event? If yes, `true` otherwise `false` | `false` | -| formatting.matches | Does `matches` has been used in the aggregated event? If yes, `true` otherwise `false` | `false` | +| formatting.show_matches_position | Does `showMatchesPosition` has been used in the aggregated event? If yes, `true` otherwise `false` | `false` | +| facets | Does `facets` has been used in the aggregated event? If yes, `true` otherwise `false` | `false` | --- @@ -347,7 +348,6 @@ This property allows us to gather essential information to better understand on | user_agent | Represents the user-agent encountered on this call. | `["Meilisearch Ruby (v2.1)", "Ruby (3.0)"]` | | searchable_attributes.total | Number of searchable attributes. | `3` | - ## `TypoTolerance Updated` | Property name | Description | Example | diff --git a/text/0118-search-api.md b/text/0118-search-api.md index 3a255138..670f6ce9 100644 --- a/text/0118-search-api.md +++ b/text/0118-search-api.md @@ -36,7 +36,7 @@ If a master key is used to secure a Meilisearch instance, the auth layer returns | [`q`](#311-q) | String | False | | [`filter`](#312-filter) | Array of String - String | False | | [`sort`](#313-sort) | Array of String - String | False | -| [`facetsDistribution`](#314-facetsdistribution) | Array of String - String | False | +| [`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 | @@ -44,9 +44,9 @@ If a master key is used to secure a Meilisearch instance, the auth layer returns | [`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 | -| [`matches`](#3114-matches) | Boolean | False | +| [`cropLength`](#3112-croplength) | Integer | False | +| [`cropMarker`](#3113-cropmarker) | String | False | +| [`showMatchesPosition`](#3114-showmatchesposition) | Boolean | False | #### 3.1.1. `q` @@ -153,25 +153,27 @@ Attributes used as sort criteria must be added to the `sortableAttributes list o > See [Sort](0055-sort.md) -#### 3.1.4. `facetsDistribution` +#### 3.1.4. `facets` - Type: Array of String (POST) | String (GET) - Required: False - Default: `[]|null` -`facetsDistribution` permits to specify facets to be computed for the current search query. +`facets` permits to specify facets to be computed for the current search query. It returns the number of documents matching the current search query for each specified facet. This parameter can take two values: -- An array of attributes: `facetsDistribution=["attributeA", "attributeB", …]` +- An array of attributes: `facets=["attributeA", "attributeB", …]` - A wildcard `"*"` β€” this returns a count for all facets present in `filterableAttributes` -Attributes used in `facetsDistribution` must be added to the `filterableAttributes` list of an index settings. See [Filterable Attributes Setting API](0123-filterable-attributes-setting-api.md). +Attributes used in `facets` must be added to the `filterableAttributes` list of an index settings. See [Filterable Attributes Setting API](0123-filterable-attributes-setting-api.md). -- πŸ”΄ Sending a value with a different type than `Array of String`(POST), `String`(GET) or `null` for `facetsDistribution` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. -- πŸ”΄ Sending a field not defined as a `filterableAttributes` for `facetsDistribution` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. +- πŸ”΄ Sending a value with a different type than `Array of String`(POST), `String`(GET) or `null` for `facets` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. +- πŸ”΄ Sending a field not defined as a `filterableAttributes` for `facets` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. + +The distribution of the different facets is returned in the `facetDistribution` response parameter. #### 3.1.5. `limit` @@ -401,17 +403,18 @@ If the cropped part has been matched against query terms and contains the beginn 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. `matches` +#### 3.1.14. `showMatchesPosition` - Type: Boolean - Required: False - Default: `false` -Adds a `_matchesInfo` object to the search response that contains the location of each occurrence of queried terms across all fields. The given positions are in bytes. +Adds a `_matchesPosition` object to the search response that contains the location of each occurrence of queried terms across all fields. The given positions are in bytes. It's useful when more control is needed than offered by the built-in highlighting/cropping features. -- πŸ”΄ Sending a value with a different type than `Boolean` or `null` for `matches` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. +- πŸ”΄ 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.2. Search Response Properties @@ -420,12 +423,10 @@ It's useful when more control is needed than offered by the built-in highlightin | [`hits`](#321-hits) | Array[Hit] | True | | [`limit`](#322-limit) | Integer | True | | [`offset`](#323-offset) | Integer | True | -| [`nbHits`](#324-nbhits) | Integer | True | -| [`exhaustiveNbHits`](#325-exhaustivenbhits) | Boolean | True | -| [`facetsDistribution`](#326-facetsdistribution) | Object | False | -| [`exhaustiveFacetsCount`](#327-exhaustivefacetscount) | Boolean | False | -| [`processingTimeMs`](#328-processingtimems) | Integer | True | -| [`query`](#329-query) | String | True | +| [`estimatedTotalHits`](#324-estimatedTotalHits) | Integer | True | +| [`facetDistribution`](#325-facetdistribution) | Object | False | +| [`processingTimeMs`](#326-processingtimems) | Integer | True | +| [`query`](#327-query) | String | True | #### 3.2.1. `hits` @@ -446,7 +447,7 @@ A search result can contain special properties. See [3.2.1.1. `hit` Special Prop |--------------------------------------|-------------|----------| | [`_geoDistance`](#32111-geodistance) | Integer | False | | [`_formatted`](#32112-formatted) | Object | False | -| [`_matchesInfo`](#32113-matchesinfo) | Object | False | +| [`_matchesPosition`](#32113-matchesposition) | Object | False | ###### 3.2.1.1.1. `_geoDistance` @@ -640,18 +641,18 @@ Example 4: -> All the attributes are highlighted because `attributesToHighlight` is set to `["*"]`. -###### 3.2.1.1.3. `_matchesInfo` +###### 3.2.1.1.3. `_matchesPosition` - Type: Object - Required: False -Contains the location of each occurrence of queried terms across all fields. The `_matchesInfo` object is added to a search result when the `matches` search parameter is specified to true. +Contains the location of each occurrence of queried terms across all fields. The `_matchesPosition` object is added to a search result when the `showMatchesPosition` search parameter is specified to true. The beginning of a matching term within a field is indicated by `start`, and its `length` by length. `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. `matches`](#3114-matches) section. +> See [3.1.14. `showMatchesPosition`](#3114-showmatchesposition) section. #### 3.2.2. `limit` @@ -671,50 +672,32 @@ Returns the `offset` search parameter used for the query. > See [3.1.6. `offset` section](#316-offset) section. -#### 3.2.4. `nbHits` +#### 3.2.4. `estimatedTotalHits` - Type: Integer - Required: True -Returns the total number of candidates for the search query. - -#### 3.2.5. `exhaustiveNbHits` - -- Type: Boolean -- Required: True - -Whether `nbHits` is exhaustive. +Returns the estimated number of candidates for the search query. -> Always return `false`. - -#### 3.2.6. `facetsDistribution` +#### 3.2.5. `facetDistribution` - Type: Object - Required: False -Added to the search response when `facetsDistribution` is set for a search query. It contains the number of remaining candidates for each specified facet in the `facetsDistribution` search parameter. +Added to the search response when `facets` is set for a search query. It contains the number of remaining candidates for each specified facet in the `facets` search parameter. If a field distributed as a facet contains no value, it is returned as a `facetDistribution` field with an empty object as value. -> See [3.1.4. `facetsDistribution`](#314-facetsdistribution) section. - -#### 3.2.7. `exhaustiveFacetsCount` - -- Type: Boolean -- Required: False - -Whether `facetsDistribution` count is exhaustive. The field `exhaustiveFacetsCount` is added when `facetsDistribution` is set as a search parameter. - -> Always returns `false`. +> See [3.1.4. `facet`](#314-facets) section. -#### 3.2.8. `processingTimeMs` +#### 3.2.6. `processingTimeMs` - Type: Integer - Required: True Processing time of the search query in **milliseconds**. -#### 3.2.9. `query` +#### 3.2.7. `query` - Type: String - Required: True @@ -733,7 +716,7 @@ n/a ### 3.1. Formatting Search Results -- Replaces `_matchesInfo` with chars position instead of bytes. It could also be a `mode` to choose `byte` or `char`. +- Replaces `_matchesPosition` with chars position instead of bytes. It could also be a `mode` to choose `byte` or `char`. - Move `attributesToHighlight`, `highlightPreTag`, `highlightPostTag`, `attributesToCrop`, `cropLength` and `cropMarker` into a `formatter` objet. - Add an option to only highlight complete query term. - Expose the `formatter` resource as an index setting. diff --git a/text/0123-filterable-attributes-setting-api.md b/text/0123-filterable-attributes-setting-api.md index 84776a5e..f5ecba80 100644 --- a/text/0123-filterable-attributes-setting-api.md +++ b/text/0123-filterable-attributes-setting-api.md @@ -15,7 +15,7 @@ N/A Filters have several use-cases, such as restricting the results a specific user has access to or creating faceted search interfaces. Faceted search interfaces are particularly efficient in helping users navigate a great number of results across many broad categories. -`filterableAttributes` need to be properly processed and prepared by Meilisearch before they can be used at search time. Fields defined as `filterableAttributes` are usable in the [`filter`](0118-search-api.md#1212-filter) and [facetsDistribution](0118-search-api.md#1214-facetsdistribution) search API parameters. +`filterableAttributes` need to be properly processed and prepared by Meilisearch before they can be used at search time. Fields defined as `filterableAttributes` are usable in the [`filter`](0118-search-api.md#312-filter) and [facets](0118-search-api.md#314-facets) search API parameters. By default, Meilisearch has no filterable attributes defined.