Score details (#252)

* ranking score spec

* search API changes

* telemetry policies score

* open api

* Fix typos in spec

Co-authored-by: Maria Craig <marycraig90@gmail.com>

* Add multi search telemetry

---------

Co-authored-by: Maria Craig <marycraig90@gmail.com>

Author: dureuill

open-api.yaml

@@ -117,6 +117,157 @@ components:
         - start
         - length
       description: Starting position and length in bytes of the matched term in the returned value
+    order:
+      type: integer
+      description: The order that this ranking rule was applied
+    customRankingRuleDetails:
+      type: object
+      properties:
+        order:
+          $ref: '#/components/schemas/order'
+        value:
+          type:
+            - string
+            - number
+            - point
+          description: The value that was used for sorting this document
+        distance:
+          type: number
+          description: The distance between the target point and the geoPoint in the document
+      required:
+        - order
+        - value
+      description: Custom rule in the form of either `attribute:direction` or `_geoPoint(lat, lng):direction`.
+    score:
+      type: number
+      description: |
+        The relevancy score of a document according to a ranking rule and relative to a search query. Higher is better.
+
+        `1.0` indicates a perfect match, `0.0` no match at all (Meilisearch should not return documents that don't match the query).
+    rankingScoreDetails:
+      type: object
+      properties:
+        words:
+          type: object
+          properties:
+            order:
+              $ref: '#/components/schemas/order'
+            matchingWords:
+              type: integer
+              description: the number of words from the query found
+            maxMatchingWords:
+              type: integer
+            score:
+              $ref: '#/components/schemas/score'
+          required:
+            - order
+            - matchingWords
+            - maxMatchingWords
+            - score
+        typo:
+          type: object
+          properties:
+            order:
+              $ref: '#/components/schemas/order'
+            typoCount:
+              type: integer
+              description: The number of typos to correct in the query to match that document.
+            maxTypoCount:
+              type: integer
+              description: The maximum number of typos that can be corrected in the query to match a document.
+            score:
+              $ref: '#/components/schemas/score'
+          required:
+            - order
+            - typoCount
+            - maxTypoCount
+            - score
+        proximity:
+          type: object
+          properties:
+            order:
+              $ref: '#/components/schemas/order'
+            score:
+              $ref: '#/components/schemas/score'
+          required:
+            - order
+            - score
+        attribute:
+          type: object
+          properties:
+            order:
+              $ref: '#/components/schemas/order'
+            attribute_ranking_order_score:
+              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:
+              type: number
+              description: |
+               Score computed depending on the position the attributes where each word of the query appears in.
+
+               Words appearing in an attribute at the same position as in the query yield the highest score. The greater the distance to the position
+               in the query, the lower the score.
+            score:
+              $ref: '#/components/schemas/score'
+          required:
+            - order
+            - attribute_ranking_order_score
+            - query_word_distance_score
+            - score
+        exactness:
+          type: object
+          properties:
+            order:
+              $ref: '#/components/schemas/order'
+            matchType:
+              type: string
+              description: |
+               One of `exactMatch`, `matchesStart` or `noExactMatch`.
+               - `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.
+            score:
+              $ref: '#/components/schemas/score'
+          required:
+            - order
+            - matchType
+            - score
+      additionalProperties:
+        $ref: '#/components/schemas/customRankingRuleDetails'
+      description: (EXPERIMENTAL) The ranking score per ranking rule.
+      examples:
+        With sort:
+          words:
+            order: 0
+            matchingWords: 7
+            maxMatchingWords: 7
+            score: 1.0
+          "typo":
+            "order": 1
+            "typoCount": 0
+            "maxTypoCount": 0
+            "score": 1.0
+          "proximity":
+            "order": 2,
+            "score": 1.0
+          "attribute":
+            "order": 3
+            "attribute_ranking_order_score": 1.0
+            "query_word_distance_score": 1.0
+            "score": 1.0
+          "title:asc":
+            "order": 4
+            "value": "batman: the dark knight returns, part 1"
+          "release_date:desc":
+            "order": 5
+            "value": 1345507200.0
+          "exactness":
+            "order": 6
+            "matchType": "exactMatch"
+            "score": 1.0
     hit:
       type: object
       additionalProperties: true
@@ -168,6 +319,15 @@ components:
           properties:
             '':
               $ref: '#/components/schemas/matchesPosition'
+        _rankingScore:
+          type: number
+          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.
+          properties:
+            '':
+              $ref: '#/components/schemas/rankingScoreDetails'
         attribute:
           type:
             - string
@@ -712,6 +872,14 @@ components:
           type: boolean
           description: Defines whether an `_matchesPosition` object that contains information about the matches should be returned or not.
           default: false
+        showRankingScore:
+          type: boolean
+          description: Defines whether a `_rankingScore` number representing the relevancy score of that document should be returned or not.
+          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.
+          default: false
         matchingStrategy:
           type: string
           description: Defines which strategy to use to match the query terms within the documents as search results. Two different strategies are available, `last` and `all`. By default, the `last` strategy is chosen.
@@ -762,6 +930,7 @@ components:
             attributesToHighlight:
               - overview
             showMatchesPosition: true
+            showRankingScore: true
             wordsMatchingStrategy: all
     error:
       title: error

text/0034-telemetry-policies.md

@@ -191,6 +191,8 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat
 | `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` |
 
 ----
 
@@ -283,9 +285,11 @@ This property allows us to gather essential information to better understand on
 | formatting.max_attributes_to_crop | The maximum number of attributes to crop encountered among all requests in the aggregated event. | `100` |
 | 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.show_matches_position | Does `showMatchesPosition` has been used in the aggregated event? If yes, `true` otherwise `false` | `false` |
+| formatting.show_matches_position | Was `showMatchesPosition` used in the aggregated event? If yes, `true` otherwise `false` | `false` |
 | facets.avg_facets_number | The average number of facets among all the requests containing the `facets` parameter in the aggregated event. `"facets": []` equals to `0` while not sending `facets` does not influence the average in the aggregated event. | `10` |
 | matching_strategy.most_used_strategy | Most used word matching strategy among all search requests in the aggregated event. `last` / `all` | `last` |
+| scoring.show_ranking_score | Was `showRankingScore` used in the aggregated event? If yes, `true`, otherwise `false` | `false` |
+| scoring.show_ranking_score_details | Was `showRankingScoreDetails` used in the aggregated event? If yes, `true`, otherwise `false` | `false` |
 
 ---
 
@@ -320,6 +324,8 @@ This property allows us to gather essential information to better understand on
 | formatting.show_matches_position | Does `showMatchesPosition` has been used in the aggregated event? If yes, `true` otherwise `false` | `false` |
 | facets.avg_facets_number | The average number of facets among all the requests containing the `facets` parameter in the aggregated event. `"facets": []` equals to `0` while not sending `facets` does not influence the average in the aggregated event. | `10` |
 | matching_strategy.most_used_strategy | Most used word matching strategy among all search requests in the aggregated event. `last` / `all` | `last` |
+| scoring.show_ranking_score | Was `showRankingScore` used in the aggregated event? If yes, `true`, otherwise `false` | `false` |
+| scoring.show_ranking_score_details | Was `showRankingScoreDetails` used in the aggregated event? If yes, `true`, otherwise `false` | `false` |
 
 ---