Score details

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` |
 
 ---