Skip to content
This repository was archived by the owner on Mar 21, 2024. It is now read-only.

Score details #252

Merged
macraig merged 6 commits into from
Jul 31, 2023
Merged

Score details #252

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
204f8ac
ranking score spec
dureuill Jul 3, 2023
bd1feb3
search API changes
dureuill Jul 3, 2023
aa6a1ba
telemetry policies score
dureuill Jul 3, 2023
cd90e09
open api
dureuill Jun 29, 2023
c25d758
Fix typos in spec
dureuill Jul 4, 2023
9ed3609
Add multi search telemetry
dureuill Jul 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
169 changes: 169 additions & 0 deletions open-api.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

@ahmednfwela ahmednfwela Aug 31, 2023

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dureuill @brunoocasali this attribute should be attributeRankingOrderScore ?
also query_word_distance_score => queryWordDistanceScore

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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -762,6 +930,7 @@ components:
attributesToHighlight:
- overview
showMatchesPosition: true
showRankingScore: true
wordsMatchingStrategy: all
error:
title: error
Expand Down
8 changes: 7 additions & 1 deletion text/0034-telemetry-policies.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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` |
Comment thread
dureuill marked this conversation as resolved.
Outdated
| scoring.show_ranking_score_details | Was `showRankingScoreDetails` used in the aggregated event? If yes, `true`, otherwise `false` | `false` | `Documents Searched POST`, `Documents Searched GET` |
Comment thread
dureuill marked this conversation as resolved.
Outdated

----

Expand Down Expand Up @@ -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` |

---

Expand Down Expand Up @@ -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` |

---

Expand Down
105 changes: 78 additions & 27 deletions text/0118-search-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,25 +32,27 @@ If a master key is used to secure a Meilisearch instance, the auth layer returns

### 3.1. Search Payload Parameters

| Field | Type | Required |
|-------------------------------------------------------|--------------------------|----------|
| [`q`](#311-q) | String | False |
| [`filter`](#312-filter) | Array of String - String | False |
| [`sort`](#313-sort) | Array of String - String | False |
| [`facets`](#314-facets) | Array of String - String | False |
| [`limit`](#315-limit) | Integer | False |
| [`offset`](#316-offset) | Integer | 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 |
| Field | Type | Required |
|---------------------------------------------------------------|--------------------------|----------|
| [`q`](#311-q) | String | False |
| [`filter`](#312-filter) | Array of String - String | False |
| [`sort`](#313-sort) | Array of String - String | False |
| [`facets`](#314-facets) | Array of String - String | False |
| [`limit`](#315-limit) | Integer | False |
| [`offset`](#316-offset) | Integer | 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 |
| [`showRankingScore`](#3117-showrankingscore) | Boolean | False |
| [`showRankingScoreDetails`](#3118-showrankingscoredetails) | Boolean | False |
| [`matchingStrategy`](#3119-matchingStrategy) | String | False |


#### 3.1.1. `q`
Expand Down Expand Up @@ -533,7 +535,7 @@ The first page has a value of `1`, the second `2`, etc... When `0` is provided a

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).
If in addition to either `page` and/or `hitsPerPage`, `limit` and/or `offset` are provided as well, `limit` and `offset` are ignored. See [explanation](#3181-navigating-search-results-by-page-selection).

- 🔴 Sending a value with a different type than `Integer` for `page` returns an [invalid_search_page](0061-error-format-and-definitions.md#invalid_search_page) error.

Expand Down Expand Up @@ -892,7 +894,32 @@ 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 an [invalid_search_show_matches_position](0061-error-format-and-definitions.md#invalid_search_show_matches_position) error.

#### 3.1.17. `matchingStrategy`
#### 3.1.17. `showRankingScore`

Comment thread
brunoocasali marked this conversation as resolved.
- Type: Boolean
- Required: False
- Default: `false`

Adds a [`_rankingScore`](#32114-rankingscore) number to each document in the search response, representing the relevancy score of a document according to the applied ranking rules 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).

- 🔴 Sending a value with a different type than `Boolean` or `null` for `showRankingScore` returns an [invalid_search_ranking_score](0061-error-format-and-definitions.md#invalid_search_show_ranking_score) error.

#### 3.1.18. `showRankingScoreDetails`

(EXPERIMENTAL)

- Type: Object
- Required: False
- Default: `false`

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`

- Type: String
- Required: False
Expand Down Expand Up @@ -940,15 +967,17 @@ Results of the search query as an array of documents.

> 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.
A search result can contain special properties. See [3.2.1.1. `hit` Special Properties](#3211-hit-special-properties) section.

##### 3.2.1.1. `hit` Special Properties

| Field | Type | Required |
|----------------------------------------------|---------|----------|
| [`_geoDistance`](#32111-geodistance) | Integer | False |
| [`_formatted`](#32112-formatted) | Object | False |
| [`_matchesPosition`](#32113-matchesposition) | Object | False |
| Field | Type | Required |
|------------------------------------------------------|---------|----------|
| [`_geoDistance`](#32111-geodistance) | Integer | False |
| [`_formatted`](#32112-formatted) | Object | False |
| [`_matchesPosition`](#32113-matchesposition) | Object | False |
| [`_rankingScore`](#32114-rankingscore) | Number | False |
| [`_rankingScoreDetails`](#32115-rankingscoredetails) | Object | False |

###### 3.2.1.1.1. `_geoDistance`

Expand Down Expand Up @@ -1155,6 +1184,28 @@ The beginning of a matching term within a field is indicated by `start`, and its

> See [3.1.14. `showMatchesPosition`](#3116-showmatchesposition) section.

###### 3.2.1.1.4. `_rankingScore`

- Type: Number
- Required: False

The relevancy score of a document relative to the 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).

> See [Ranking Score](./0195-ranking-score.md#31-ranking-score) for details.

###### 3.2.1.1.5. `_rankingScoreDetails`

- Type: Object
- Required: False

(EXPERIMENTAL) 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.

> See [Ranking Score details](./0195-ranking-score.md#32-ranking-score-details) for details.

#### 3.2.2. `limit`

- Type: Integer
Expand Down
Loading