v1.3 (#2471)

* v1.3 * add content * fix table * more content * update search parameter tables * fix stuff * test table * test table * make `showRankingScoreDetails` experimental * add note * update core concepts * update based on spec * Update learn/experimental/ranking_rule_score_details.mdx Co-authored-by: Louis Dureuil <[email protected]> * Apply suggestions from code review Co-authored-by: gui machiavelli <[email protected]> * update based on review * Update reference/api/search.mdx Co-authored-by: gui machiavelli <[email protected]> * v1.3 telemetry updates (#2508) * v1.3: add `total` field (#2510) * v1.3: Update Docker image versions (#2497) * bump docker image version * bump docker image version * v1.3: `attributesToSearchOn` (#2480) * attributesToSearchOn: add new search parameter and error code * attributesToSearchOn: add note to searchable attributes guide, improve heading wording * attributesToSearchOn: improve example, add relevancy info * Update reference/errors/error_codes.mdx Co-authored-by: Many the fish <[email protected]> * attributesToSearchOn: improve wording * `attributesToSearchOn`: default now `["*"]` * Apply suggestions from code review Co-authored-by: Many the fish <[email protected]> --------- Co-authored-by: Many the fish <[email protected]> * v1.3: search for facet values+sort facet values (#2472) * create page * add content * add links+warnings * update content * update guide * update api reference * update to add sorting facet values * update facet_search.mdx * update code samples+error * Update .code-samples.meilisearch.yaml * update filter type * Update .code-samples.meilisearch.yaml Co-authored-by: cvermand <[email protected]> * update based on spec * update based on review * update code sample id names * Apply suggestions from code review Co-authored-by: gui machiavelli <[email protected]> * update based on review * fix container titles --------- Co-authored-by: cvermand <[email protected]> Co-authored-by: gui machiavelli <[email protected]> * v1.3: Vector search (#2479) * vector search: add experimental feature page * vector search: improve wording * vector search: use consistent slug * Update learn/experimental/vector_search.mdx Co-authored-by: Tommy <[email protected]> --------- Co-authored-by: Tommy <[email protected]> * v1.3 postman (#2486) * v1.3: Update Postman for sort and search facets+showRankingScore (#2487) * v1.3: Add `/experimental-features` route to Postman collection (#2501) --------- Co-authored-by: gui machiavelli <[email protected]> Co-authored-by: gui machiavelli <[email protected]> * v1.3: Experimental features API route (#2496) * experimental: add new API route --------- Co-authored-by: Louis Dureuil <[email protected]> Co-authored-by: Tommy <[email protected]> * ranking score details: improve title --------- Co-authored-by: Louis Dureuil <[email protected]> Co-authored-by: gui machiavelli <[email protected]> Co-authored-by: Many the fish <[email protected]> Co-authored-by: cvermand <[email protected]> Co-authored-by: Tommy <[email protected]> Co-authored-by: gui machiavelli <[email protected]>
meilisearch · Jul 31, 2023 · 9627cc2 · 9627cc2
1 parent ee16744
commit 9627cc2
Show file tree

Hide file tree

Showing 24 changed files with 738 additions and 111 deletions.
diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml
@@ -868,7 +868,11 @@ update_faceting_settings_1: |-
     -X PATCH 'http://localhost:7700/indexes/books/settings/faceting' \
     -H 'Content-Type: application/json' \
     --data-binary '{
-      "maxValuesPerFacet": 2
+      "maxValuesPerFacet": 2,
+      "sortFacetValuesBy": {
+        "*": "alpha",
+        "genres": "count"
+      }
     }'
 reset_faceting_settings_1: |-
   curl \
@@ -885,7 +889,10 @@ getting_started_faceting: |-
     -X PATCH 'http://localhost:7700/indexes/movies/settings/faceting' \
     -H 'Content-Type: application/json' \
     --data-binary '{
-      "maxValuesPerFacet": 2
+      "maxValuesPerFacet": 2,
+       "sortFacetValuesBy": {
+         "*": "count"
+       }
     }'
 getting_started_pagination: |-
   curl \
@@ -1061,3 +1068,55 @@ delete_documents_by_filter_1: |-
     --data-binary '{
       "filter": "genres = action OR genres = adventure"
     }'
+get_experimental_features_1: |-
+  curl \
+    -X GET 'http://localhost:7700/experimental-features/'
+update_experimental_features_1: |-
+  curl \
+    -X PATCH 'http://localhost:7700/experimental-features/' \
+    -H 'Content-Type: application/json'  \
+    --data-binary '{
+      "scoreDetails": true
+    }'
+facet_search_1: |-
+  curl \
+    -X POST 'http://localhost:7700/indexes/books/facet-search' \
+    -H 'Content-Type: application/json' \
+    --data-binary '{ 
+      "facetQuery": "fiction",
+      "facetName": "genres",
+      "filter": "rating > 3"
+    }'
+facet_search_2: |-
+  curl \
+    -X PATCH 'http://localhost:7700/indexes/books/settings/faceting' \
+    -H 'Content-Type: application/json' \
+    --data-binary '{
+      "sortFacetValuesBy": {
+        "genres": "count"
+    }
+  }'
+facet_search_3: |-
+  curl \
+    -X POST 'http://localhost:7700/indexes/books/facet-search' \
+    -H 'Content-Type: application/json' \
+    --data-binary '{ 
+      "facetQuery": "c",
+      "facetName": "genres"
+  }'
+search_parameter_guide_show_ranking_score_1: |-
+  curl \
+    -X POST 'http://localhost:7700/indexes/movies/search' \
+    -H 'Content-Type: application/json' \
+    --data-binary '{
+      "q": "dragon",
+      "showRankingScore": true
+    }'
+search_parameter_guide_attributes_to_search_on_1: |-
+  curl \
+    -X POST 'http://localhost:7700/indexes/movies/search' \
+    -H 'Content-Type: application/json' \
+    --data-binary '{
+      "q": "adventure",
+      "attributesToSearchOn": ["overview"]
+    }'
diff --git a/assets/misc/meilisearch-collection-postman.json b/assets/misc/meilisearch-collection-postman.json
@@ -1,7 +1,7 @@
 {
 	"info": {
-		"_postman_id": "01fa1db8-f183-4b88-adaa-d139f7d945e3",
-		"name": "Meilisearch v1.2",
+		"_postman_id": "af5f1b99-255f-4eb3-9756-6636be3a0f16",
+		"name": "Meilisearch v1.3",
 		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
 	},
 	"item": [
@@ -121,7 +121,7 @@
 							}
 						},
 						"url": {
-							"raw": "{{url}}/indexes/{{indexUID}}/documents?csvDelimiter=;",
+							"raw": "{{url}}/indexes/{{indexUID}}/documents",
 							"host": [
 								"{{url}}"
 							],
@@ -161,7 +161,7 @@
 							}
 						},
 						"url": {
-							"raw": "{{url}}/indexes/{{indexUID}}/documents?csvDelimiter=;",
+							"raw": "{{url}}/indexes/{{indexUID}}/documents",
 							"host": [
 								"{{url}}"
 							],
@@ -398,6 +398,16 @@
 									"key": "hitsPerPage",
 									"value": "50",
 									"disabled": true
+								},
+								{
+									"key": "showRankingScore",
+									"value": "true",
+									"disabled": true
+								},
+								{
+									"key": "attributesToSearchOn",
+									"value": "title",
+									"disabled": true
 								}
 							]
 						}
@@ -1767,7 +1777,7 @@
 								],
 								"body": {
 									"mode": "raw",
-									"raw": "{\n    \"maxValuesPerFacet\": 3000\n}"
+									"raw": "{\n    \"maxValuesPerFacet\": 3000,\n    \"sortFacetValuesBy\": {\n        \"*\": \"alpha\",\n        \"genre\": \"count\"\n      }\n}"
 								},
 								"url": {
 									"raw": "{{url}}/indexes/{{indexUID}}/settings/faceting",
@@ -2136,6 +2146,86 @@
 					}
 				}
 			]
+		},
+		{
+			"name": "Facet search",
+			"item": [
+				{
+					"name": "Search for facet values",
+					"request": {
+						"method": "POST",
+						"header": [
+							{
+								"key": "Content-Type",
+								"value": "application/json",
+								"type": "text"
+							}
+						],
+						"body": {
+							"mode": "raw",
+							"raw": "{ \n      \"facetQuery\": \"adventure\",\n      \"facetName\": \"genre\",\n      \"q\": \"prinec\"\n}"
+						},
+						"url": {
+							"raw": "{{url}}/facet-search",
+							"host": [
+								"{{url}}"
+							],
+							"path": [
+								"facet-search"
+							]
+						}
+					},
+					"response": []
+				}
+			]
+		},
+		{
+			"name": "Experimental features",
+			"item": [
+				{
+					"name": "Get all experimental features",
+					"request": {
+						"method": "GET",
+						"header": [],
+						"url": {
+							"raw": "{{url}}/experimental-features",
+							"host": [
+								"{{url}}"
+							],
+							"path": [
+								"experimental-features"
+							]
+						}
+					},
+					"response": []
+				},
+				{
+					"name": "Configure an experimental feature",
+					"request": {
+						"method": "PATCH",
+						"header": [],
+						"body": {
+							"mode": "raw",
+							"raw": "{\n    \"scoreDetails\": true\n}",
+							"options": {
+								"raw": {
+									"language": "json"
+								}
+							}
+						},
+						"url": {
+							"raw": "{{url}}/experimental-features",
+							"host": [
+								"{{url}}"
+							],
+							"path": [
+								"experimental-features"
+							]
+						}
+					},
+					"response": []
+				}
+			]
 		}
 	],
 	"auth": {

diff --git a/config/sidebar-learn.json b/config/sidebar-learn.json
@@ -383,6 +383,11 @@
 			"title": "Experimental",
 			"slug": "experimental",
 			"routes": [
+					{
+							"source": "learn/experimental/overview.mdx",
+							"label": "Overview",
+							"slug": "overview"
+					},
 					{
 							"source": "learn/experimental/metrics.mdx",
 							"label": "Metrics",
@@ -392,6 +397,16 @@
 							"source": "learn/experimental/reduce-indexing-memory-usage.mdx",
 							"label": "Reduce indexing memory usage",
 							"slug": "reduce-indexing-memory-usage"
+					},
+					{
+						  "source": "learn/experimental/ranking_rule_score_details.mdx",
+						  "label": "Detailed ranking scores",
+						  "slug": "ranking_rule_score_details"
+				  },
+					{
+							"source": "learn/experimental/vector_search.mdx",
+							"label": "Vector search",
+							"slug": "vector_search"
 					}
 			]
 	},

diff --git a/config/sidebar-reference.json b/config/sidebar-reference.json
@@ -28,6 +28,11 @@
             "label": "Multi-search",
             "slug": "multi_search"
         },
+        {
+            "source": "reference/api/facet_search.mdx",
+            "label": "Facet search",
+            "slug": "facet_search"
+        },
         {
             "source": "reference/api/tasks.mdx",
             "label": "Tasks",
@@ -62,6 +67,11 @@
             "source": "reference/api/dump.mdx",
             "label": "Dumps",
             "slug": "dump"
+        },
+        {
+            "source": "reference/api/experimental_features.mdx",
+            "label": "Experimental features",
+            "slug": "experimental_features"
         }
       ]
   },

diff --git a/learn/async/managing_tasks.mdx b/learn/async/managing_tasks.mdx
@@ -86,6 +86,7 @@ The following command returns two tasks at a time, starting from task `uid` `10`
   "results": [
     …
   ],
+  "total": 50,
   "limit": 2,
   "from": 10,
   "next": 8

diff --git a/learn/cookbooks/docker.mdx b/learn/cookbooks/docker.mdx
@@ -9,7 +9,7 @@ Docker is a tool that bundles applications into containers. Docker containers en
 Docker containers are distributed in images. To use Meilisearch, use the `docker pull` command to download a Meilisearch image:
 
 ```sh
-docker pull getmeili/meilisearch:v1.2
+docker pull getmeili/meilisearch:v1.3
 ```
 
 Meilisearch deploys a new Docker image with every release of the engine. Each image is tagged with the corresponding Meilisearch version, indicated in the above example by the text following the `:` symbol. You can see [the full list of available Meilisearch Docker images](https://hub.docker.com/r/getmeili/meilisearch/tags#!) on Docker Hub.
@@ -26,7 +26,7 @@ After completing the previous step, use `docker run` to launch the Meilisearch i
 docker run -it --rm \
   -p 7700:7700 \
   -v $(pwd)/meili_data:/meili_data \
-  getmeili/meilisearch:v1.2
+  getmeili/meilisearch:v1.3
 ```
 
 ### Configure Meilisearch
@@ -42,7 +42,7 @@ docker run -it --rm \
   -p 7700:7700 \
   -e MEILI_MASTER_KEY='MASTER_KEY'\
   -v $(pwd)/meili_data:/meili_data \
-  getmeili/meilisearch:v1.2
+  getmeili/meilisearch:v1.3
 ```
 
 #### Passing instance options with CLI arguments
@@ -53,7 +53,7 @@ If you want to pass command-line arguments to Meilisearch with Docker, you must
 docker run -it --rm \
   -p 7700:7700 \
   -v $(pwd)/meili_data:/meili_data \
-  getmeili/meilisearch:v1.2
+  getmeili/meilisearch:v1.3
   meilisearch --master-key="MASTER_KEY"
 ```
 
@@ -71,7 +71,7 @@ To keep your data intact between reboots, specify a dedicated volume by running
 docker run -it --rm \
   -p 7700:7700 \
   -v $(pwd)/meili_data:/meili_data \
-  getmeili/meilisearch:v1.2
+  getmeili/meilisearch:v1.3
 ```
 
 The example above uses `$(pwd)/meili_data`, which is a directory in the host machine. Depending on your OS, mounting volumes from the host to the container might result in performance loss and is only recommended when developing your application.
@@ -86,7 +86,7 @@ To import a dump, use Meilisearch's `--import-dump` command-line option and spec
 docker run -it --rm \
   -p 7700:7700 \
   -v $(pwd)/meili_data:/meili_data \
-  getmeili/meilisearch:v1.2
+  getmeili/meilisearch:v1.3
   meilisearch --import-dump /meili_data/dumps/20200813-042312213.dump
 ```
 
@@ -106,7 +106,7 @@ To generate a Meilisearch snapshot with Docker, launch Meilisearch with `--sched
 docker run -it --rm \
   -p 7700:7700 \
   -v $(pwd)/meili_data:/meili_data \
-  getmeili/meilisearch:v1.2
+  getmeili/meilisearch:v1.3
   meilisearch --schedule-snapshot --snapshot-dir /meili_data/snapshots
 ```
 
@@ -118,7 +118,7 @@ To import a snapshot, launch Meilisearch with the `--import-snapshot` option:
 docker run -it --rm \
   -p 7700:7700 \
   -v $(pwd)/meili_data:/meili_data \
-  getmeili/meilisearch:v1.2
+  getmeili/meilisearch:v1.3
   meilisearch --import-snapshot /meili_data/snapshots/data.ms.snapshot
 ```
 

diff --git a/learn/core_concepts/relevancy.mdx b/learn/core_concepts/relevancy.mdx
@@ -177,6 +177,28 @@ In general, `sort` will be most useful when you want to allow users to define wh
 
 Custom ranking rules, instead, are always active once configured and will be useful when you want to promote certain types of results. A good use-case for custom ranking rules is ensuring discounted products in a webshop always feature among the top results.
 
+### Ranking score
+
+When using the [`showRankingScore` search parameter](/reference/api/search#show-ranking-score), Meilisearch adds a global ranking score field, `_rankingScore`, to each document. The `_rankingScore` is between `0.0` and `1.0`. The higher the ranking score, the more relevant the document.
+
+Ranking rules sort documents either by relevancy (`words`, `typo`, `proximity`, `exactness`, `attribute`) or by the value of a field (`sort`). Since `sort`  doesn't rank documents by relevancy, it does not influence the `_rankingScore`.
+
+<Capsule intent="note">
+A document's ranking score does not change based on the scores of other documents in the same index.
+
+For example, if a document A has a score of `0.5` for a query term, this value remains constant no matter the score of documents B, C, or D.```
+</Capsule>
+
+The table below details all the index settings that can influence the `_rankingScore`. **Unlisted settings do not influence the ranking score.**
+
+| Index setting          | Influences if                        | Rationale                                                                                                                                                      |
+| :--------------------- | :----------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `searchableAttributes` | The `attribute` ranking rule is used | The `attribute` ranking rule rates the document depending on the attribute in which the query terms show up. The order is determined by `searchableAttributes` |
+| `rankingRules`         | Always                               | The score is computed by computing the subscore of each ranking rule with a weight that depends on their order                                                 |
+| `stopWords`            | Always                               | Stop words influence the `words` ranking rule, which is almost always used                                                                                     |
+| `synonyms`             | Always                               | Synonyms influence the `words` ranking rule, which is almost always used                                                                                       |
+| `typoTolerance`        | The `typo` ranking rule is used      | Used to compute the maximum number of typos for a query                                                                                                        |
+
 ## Attribute ranking order
 
 In a typical dataset, some fields are more relevant to search than others. A `title`, for example, has a value more meaningful to a movie search than its `overview` or its `release_date`.