From a1efc63b949d6dc8631fe0b90981771a06212225 Mon Sep 17 00:00:00 2001 From: Maria Craig Date: Mon, 11 Mar 2024 16:52:52 -0300 Subject: [PATCH] Release v1.7.0 (#263) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Bump version to v1.7 * Stabilize scoreDetails feature (#264) * Stabilize scoreDetails feature * Remove from telemetry and experimental features --------- Co-authored-by: María Co-authored-by: Louis Dureuil --- open-api.yaml | 62 +++++++++++++++++++-------- text/0034-telemetry-policies.md | 9 +++- text/0118-search-api.md | 5 +-- text/0119-instance-options.md | 12 ++++++ text/0193-experimental-features.md | 27 ++---------- text/0194-experimental-feature-api.md | 1 - text/0195-ranking-score.md | 13 +++--- 7 files changed, 73 insertions(+), 56 deletions(-) diff --git a/open-api.yaml b/open-api.yaml index 26bea94e..97ab4ed8 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -2,7 +2,7 @@ openapi: 3.1.0 info: title: Meilisearch Core API description: 'Search documents, configure and manage the Meilisearch engine.' - version: 1.6.0 + version: 1.7.0 contact: name: Meilisearch email: bonjour@Meilisearch.com @@ -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..70932045 100644 --- a/text/0034-telemetry-policies.md +++ b/text/0034-telemetry-policies.md @@ -110,7 +110,10 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat | `infos.with_configuration_file` | `true` if the instance is launched with a configuration file, otherwise `false` | false | Every Hour | | `infos.task_queue_webhook` | `true` if the instance is launched with a task queue webhook, otherwise `false` | false | Every Hour | | `infos.experimental_enable_metrics` | `true` if `--experimental-enable-metrics`/`MEILI_EXPERIMENTAL_ENABLE_METRICS` is specified at launch, otherwise `false` | `false` | Every Hour | +| `infos.experimental_logs_mode` | `human` or `json` depending on the value specified. | `human` | Every Hour | +| `infos.experimental_enable_logs_route` | `true` if `--experimental-enable-logs-route`/`MEILI_EXPERIMENTAL_ENABLE_LOGS_ROUTE` is specified at launch, otherwise `false` | `false` | Every Hour | | `infos.experimental_reduce_indexing_memory_usage` | `true` if `--experimental-reduce-indexing-memory-usage`/`MEILI_EXPERIMENTAL_REDUCE_INDEXING_MEMORY_USAGE` is specified at launch, otherwise `false` | `false` | Every Hour | +| `infos.gpu_enabled` | `true` if Meilisearch was compiled with CUDA support, otherwise `false` | `false` | Every Hour | | `system.distribution` | Distribution on which MeiliSearch is launched | Arch Linux | Every hour | | `system.kernel_version` | Kernel version on which MeiliSearch is launched | 5.14.10 | Every hour | | `system.cores` | Number of cores | 24 | Every hour | @@ -205,7 +208,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` | @@ -260,6 +262,10 @@ This property allows us to gather essential information to better understand on | infos.with_configuration_file | `true` if the instance is launched with a configuration file, otherwise `false` | `false` | | infos.task_queue_webhook | `true` if the instance is launched with a task queue webhook, otherwise `false` | `false` | | infos.experimental_enable_metrics | `true` if `--experimental-enable-metrics`/`MEILI_EXPERIMENTAL_ENABLE_METRICS` is specified at launch, otherwise `false` | `false` | +| infos.experimental_logs_mode | `human` or `json` depending on the value specified. | `human` | +| infos.experimental_enable_logs_route | `true` if `--experimental-enable-logs-route`/`MEILI_EXPERIMENTAL_ENABLE_LOGS_ROUTE` is specified at launch, otherwise `false` | `false` | +| `infos.experimental_reduce_indexing_memory_usage` | `true` if `--experimental-reduce-indexing-memory-usage`/`MEILI_EXPERIMENTAL_REDUCE_INDEXING_MEMORY_USAGE` is specified at launch, otherwise `false` | `false` | +| `infos.gpu_enabled` | `true` if Meilisearch was compiled with CUDA support, otherwise `false` | `false` | ##### MeiliSearch Statistics `stats` @@ -740,7 +746,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/0119-instance-options.md b/text/0119-instance-options.md index f85baf13..46dadbdb 100644 --- a/text/0119-instance-options.md +++ b/text/0119-instance-options.md @@ -500,6 +500,18 @@ Activate the `/metrics` endpoint to collect Meilisearch metrics for monitoring p Enables the `MDB_WRITEMAP` option of LMDB, making the internal key-value store use much less RAM than usual. +#### 3.3.28. Experimental Logs Mode + +**Environment variable**: `MEILI_EXPERIMENTAL_LOGS_MODE` +**CLI option**: `--experimental-logs-mode` +**Default**: `human` + +Lets you customize the mode in which meilisearch should output its logs. +Only two values are possible: +- `human` => The default one; it's easy to read for a human +- `json` => It's better if you're going to send your logs to a log storage software + + #### 3.3.29. Task webhook url **Environment variable**: `MEILI_TASK_WEBHOOK_URL` diff --git a/text/0193-experimental-features.md b/text/0193-experimental-features.md index f3eb915e..98e1d552 100644 --- a/text/0193-experimental-features.md +++ b/text/0193-experimental-features.md @@ -22,6 +22,8 @@ To enable instance experimental features, pass their associated command line fla |------------|-----------------|-----------|-------------------------|-----------------------------------|------------------| |Prometheus Metrics|`--experimental-enable-metrics`|The `/metrics` endpoint exposes metrics to be scraped by a Prometheus collector at regular intervals and stored for analysis.|We have yet to determine which metrics we want to expose and how|TBC|| |Reduce Indexing Memory Usage|`--experimental-reduce-indexing-memory-usage`|Trades-off indexing speed with a lower RAM footprint.|We have yet to determine if a lot impacts performance and whether the RAM usage reduction is significant enough.|TBC|| +|Enable logs route|`--experimental-enable-logs-route`|The `/logs/*` endpoints exposes ways to retrieves and customizes logs.|TBC|| +|Change logs mode|`--experimental-logs-mode json`|The CLI flags takes a parameter, either `json` or `human` that will change the way we output the logs to the console. `human` is used by default.|TBC|| ## 3.2. Runtime experimental features @@ -59,29 +61,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 - - - - @@ -95,4 +74,4 @@ N/A ## 5. Future Possibilities -N/A \ No newline at end of file +N/A 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` |
  • `matchingWords`: Number of words in the query that match in the document. The higher the better
  • `maxMatchingWords`: Maximum number of words in the query that can match in the document for this iteration of the `words` ranking rule. Usually, the query length, but if one of the query terms is set as a stop word, it won’t be counted here.
| | `typo` |
  • `typoCount`: Number of typos to correct in the query so that the document matches for this iteration of the `typo` ranking rule.
  • `maxTypoCount`: Maximum number of typos possible in a document for this iteration of the `typo` ranking rule.
| | `proximity` | No rule-specific field | -| `attribute` |
  • `attribute_ranking_order_score`: Results sorted based on the attribute ranking order
  • `query_word_distance_score`: Documents with attributes containing the query words close to their position in the query will be considered more relevant than documents containing the query words far from their position in the query
| +| `attribute` |
  • `attributeRankingOrderScore`: Results sorted based on the attribute ranking order
  • `queryWordDistanceScore`: Documents with attributes containing the query words close to their position in the query will be considered more relevant than documents containing the query words far from their position in the query
| | `exactness` |
  • `matchType`: It has one of the following values:
    • `exactMatch`: The query exactly matches the entire value of an attribute
    • `matchesStart`: The query matches exactly the start of the value of an attribute
    • `noExactMatch`: The query doesn't exactly match a document
  • `matchingWords`: for `matchesStart`, the number of exact words contained in an attribute. The higher the better
  • `maxMatchingWords`: for `noExactMatch`, the maximum number of exact words contained in an attribute
| #### 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