diff --git a/open-api.yaml b/open-api.yaml index ec9392e0..97ab4ed8 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -134,10 +134,16 @@ components: distance: type: number description: The distance between the target point and the geoPoint in the document + similarity: + type: number + description: | + the similarity score between the target vector and the value vector. + + 1.0 means a perfect similarity, 0.0 a perfect dissimilarity. required: - order - value - description: Custom rule in the form of either `attribute:direction` or `_geoPoint(lat, lng):direction`. + description: Custom rule in the form of either `attribute:direction`, `vectorSort(vector)` or `_geoPoint(lat, lng):direction`. score: type: number description: | @@ -154,9 +160,10 @@ components: $ref: '#/components/schemas/order' matchingWords: type: integer - description: the number of words from the query found + description: number of words in the query that match in the document. The higher the better. maxMatchingWords: type: integer + description: max number of words in the query that can match in the document for this iteration of the words ranking rule. score: $ref: '#/components/schemas/score' required: @@ -197,13 +204,13 @@ components: properties: order: $ref: '#/components/schemas/order' - attribute_ranking_order_score: + attributeRankingOrderScore: type: number description: | Score computed depending on the first attribute each word of the query appears in. The first attribute in the `searchableAttributes` list yields the highest score, the last attribute the lowest. - query_word_distance_score: + queryWordDistanceScore: type: number description: | Score computed depending on the position the attributes where each word of the query appears in. @@ -214,8 +221,8 @@ components: $ref: '#/components/schemas/score' required: - order - - attribute_ranking_order_score - - query_word_distance_score + - attributeRankingOrderScore + - queryWordDistanceScore - score exactness: type: object @@ -229,6 +236,14 @@ components: - `exactMatch`: the document contains an attribute that exactly matches the query. - `matchesStart`: the document contains an attribute that exactly starts with the query. - `noExactMatch`: any other document. + matchingWords: + type: integer + description: | + for `noExactMatch`, the number of exact words contained in an attribute. The higher the better. + maxMatchingWords: + type: integer + description: | + for `noExactMatch`, the maximum number of exact words contained in an attribute score: $ref: '#/components/schemas/score' required: @@ -237,7 +252,7 @@ components: - score additionalProperties: $ref: '#/components/schemas/customRankingRuleDetails' - description: (EXPERIMENTAL) The ranking score per ranking rule. + description: The ranking score per ranking rule. examples: With sort: words: @@ -324,7 +339,7 @@ components: description: Only present if showRankingScore = `true`. The ranking score of that document. _rankingScoreDetails: type: object - description: (EXPERIMENTAL) Only present if showRankingScoreDetails = `true`. The ranking score of each ranking rule for that document. + description: Only present if showRankingScoreDetails = `true`. The ranking score of each ranking rule for that document. properties: '': $ref: '#/components/schemas/rankingScoreDetails' @@ -952,7 +967,7 @@ components: default: false showRankingScoreDetails: type: boolean - description: (EXPERIMENTAL) Defines whether a `_rankingScoreDetails` object containing information about the score of that document for each ranking rule should be returned or not. + description: Defines whether a `_rankingScoreDetails` object containing information about the score of that document for each ranking rule should be returned or not. default: false matchingStrategy: type: string @@ -4402,16 +4417,20 @@ paths: properties: vectorStore: type: boolean - scoreDetails: + metrics: + type: boolean + exportPuffinReports: type: boolean required: - vectorStore - - scoreDetails + - metrics + - exportPuffinReports examples: Default status of the features: value: vectorStore: false - scoreDetails: false + metrics: true + exportPuffinReports: false '401': $ref: '#/components/responses/401' patch: @@ -4431,14 +4450,17 @@ paths: properties: vectorStore: type: boolean - scoreDetails: + metrics: + type: boolean + exportPuffinReports: type: boolean additionalProperties: false examples: Example: value: vectorStore: true - scoreDetails: false + metrics: false + exportPuffinReports: false responses: '200': description: Ok @@ -4450,16 +4472,20 @@ paths: properties: vectorStore: type: boolean - scoreDetails: + metrics: + type: boolean + exportPuffinReports: type: boolean required: - vectorStore - - scoreDetails + - metrics + - exportPuffinReports examples: Updated status of the feature: value: vectorStore: true - scoreDetails: false + metrics: false + exportPuffinReports: false '401': $ref: '#/components/responses/401' /metrics: diff --git a/text/0034-telemetry-policies.md b/text/0034-telemetry-policies.md index d117e02d..f9c2b8ce 100644 --- a/text/0034-telemetry-policies.md +++ b/text/0034-telemetry-policies.md @@ -205,7 +205,6 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat | `per_filter`| `true` if `POST /indexes/:indexUid/documents/delete` endpoint was used in this batch, otherwise `false` | false | `Documents Fetched GET`, `Documents Fetched POST`, `Documents Deleted` | | `clear_all` | `true` if `DELETE /indexes/:indexUid/documents` endpoint was used in this batch, otherwise `false` | false | `Documents Deleted` | | vector_store | Whether the [vector store](./0193-experimental-features.md#vector-store) feature is enabled. | `true` | `Experimental features Updated` | -| score_details | Whether the [score details](./0193-experimental-features.md#score-details) feature is enabled. | `true` | `Experimental features Updated` | | scoring.show_ranking_score | Was `showRankingScore` used in the aggregated event? If yes, `true`, otherwise `false` | `false` | `Documents Searched POST`, `Documents Searched GET`, `Documents Searched by Multi-Search POST` | | scoring.show_ranking_score_details | Was `showRankingScoreDetails` used in the aggregated event? If yes, `true`, otherwise `false` | `false` | `Documents Searched POST`, `Documents Searched GET`, `Documents Searched GET` | | `facets.total_distinct_facet_count` | The total number of distinct facets queried for the aggregated event | `3` | `Facet Searched POST` | @@ -740,7 +739,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)"]` | | vector_store | Whether the [vector store](./0193-experimental-features.md#vector-store) feature is enabled. | `true` | -| score_details | Whether the [score details](./0193-experimental-features.md#score-details) feature is enabled. | `true` | --- diff --git a/text/0118-search-api.md b/text/0118-search-api.md index d95cae6b..d3395b5b 100644 --- a/text/0118-search-api.md +++ b/text/0118-search-api.md @@ -910,8 +910,6 @@ Adds a [`_rankingScore`](#32114-rankingscore) number to each document in the sea #### 3.1.18. `showRankingScoreDetails` -(EXPERIMENTAL) - - Type: Object - Required: False - Default: `false` @@ -919,7 +917,6 @@ Adds a [`_rankingScore`](#32114-rankingscore) number to each document in the sea Adds a [`_rankingScoreDetails`](#32115-rankingscoredetails) object to each document in the search response, containing information about the score of that document for each applied ranking rule. - 🔴 Sending a value with a different type than `Boolean` or `null` for `showRankingScoreDetails` returns an [invalid_search_ranking_score_details](0061-error-format-and-definitions.md#invalid_search_show_ranking_score_details) error. -- 🔴 Using that field while the [`score details`](./0193-experimental-features.md#score-details) experimental feature has not been enabled returns a [feature_not_enabled](0061-error-format-and-definitions.md#feature_not_enabled) error. #### 3.1.19. `matchingStrategy` @@ -1228,7 +1225,7 @@ The relevancy score of a document relative to the search query. Higher is better - Type: Object - Required: False -(EXPERIMENTAL) The ranking score of a document per each ranking rule and relative to the search query. +The ranking score of a document per each ranking rule and relative to the search query. This object features one field for each applied ranking rule, whose values are an object with at least the field `order` indicating in which order this ranking rule has been applied. diff --git a/text/0193-experimental-features.md b/text/0193-experimental-features.md index f3eb915e..6005c594 100644 --- a/text/0193-experimental-features.md +++ b/text/0193-experimental-features.md @@ -59,29 +59,6 @@ curl \ - - - - - - -``` -curl \ - -X PATCH 'http://localhost:7700/experimental-features/' \ - -H 'Content-Type: application/json' \ ---data-binary '{ - "scoreDetails": true - }' -``` - - - Enables computing detailed scores - Confidence on the computed details names - v1.4 - - - - diff --git a/text/0194-experimental-feature-api.md b/text/0194-experimental-feature-api.md index a7d75524..c2498438 100644 --- a/text/0194-experimental-feature-api.md +++ b/text/0194-experimental-feature-api.md @@ -34,7 +34,6 @@ This response is a JSON object containing the following fields: |Field name|Type|Experimental feature| |----------|----|-----| -|`scoreDetails`|Boolean| [Score details](./0193-experimental-features.md#score-details) | |`vectorStore`|Boolean| [Vector store](./0193-experimental-features.md#vector-store) | The PATCH routes accept as payload a JSON object containing the same fields as in the response, with the following effects on the corresponding feature: diff --git a/text/0195-ranking-score.md b/text/0195-ranking-score.md index b734c4e4..07971892 100644 --- a/text/0195-ranking-score.md +++ b/text/0195-ranking-score.md @@ -64,9 +64,7 @@ If you need to factor sort ranking rules into your score, then use the [ranking ### 3.2. Ranking score details -(EXPERIMENTAL) The ranking score details are represented as an object attached to each document returned by a search when the [`showRankingScoreDetails`](./0118-search-api.md#3118-showrankingscoredetails) flag is set to true in the search query. - -The ranking score details are experimental and require enabling the corresponding [experimental feature](./0193-experimental-features.md#score-details). +The ranking score details are represented as an object attached to each document returned by a search when the [`showRankingScoreDetails`](./0118-search-api.md#3118-showrankingscoredetails) flag is set to true in the search query. #### 3.2.1. General shape @@ -90,16 +88,17 @@ The table below details these rule-specific fields. | `words` | | | `typo` | | | `proximity` | No rule-specific field | -| `attribute` | | +| `attribute` | | | `exactness` | | #### 3.2.3. Sort ranking rules -`Sort` and `geosort` ranking rules appear as fields in the score details, but with the following difference: +`Sort`, `_geosort` and (EXPERIMENTAL) `vectorSort` ranking rules appear as fields in the score details, but with the following difference: -- Their key follows the following format: `{:attribute-sorted-on}:{:sort-direction}`, with the `:attribute-sorted-on` the name of the attribute that is being sorted on, and the `:sort-direction` either `asc` if the sort is in ascending order, or `desc` if the sort is in descending order. For the `geosort` ranking rule, it is similarly `_geoPoint({:lat}, {:lng}):{:sort-direction}`, with the `:lat` and `:lng` being the latitude and respective longitude of the point that serves as base to sort by distance. +- Their key follows the following format: `{:attribute-sorted-on}:{:sort-direction}`, with the `:attribute-sorted-on` the name of the attribute that is being sorted on, and the `:sort-direction` either `asc` if the sort is in ascending order, or `desc` if the sort is in descending order. For the `geosort` ranking rule, it is similarly `_geoPoint({:lat}, {:lng}):{:sort-direction}`, with the `:lat` and `:lng` being the latitude and respective longitude of the point that serves as base to sort by distance. (EXPERIMENTAL) For the `vectorSort` ranking rule, it is similarly `vectorSort(:targetVector)` with the `:targetVector` being the searched for vector. - They don't have a `score` field, but instead they have a `value` field, representing the value used to sort the document. It is typically the value of the sorted attribute for the document, but can sometimes be a subvalue (case where the value is an array of values). -- For the `geosort`, there is an additional `distance` field representing the distance between the target point and the point used in the document to sort the document. +- For the `_geosort`, there is an additional `distance` field representing the distance between the target point and the point used in the document to sort the document. +- (EXPERIMENTAL) for the `vectorSort`, there is an additional `similarity` field representing the similarity between the target vector and the value vector. #### 3.2.4 Example