From aeaf54c1d6954fcfd4e85cd760fb229fb4e463da Mon Sep 17 00:00:00 2001
From: gui machiavelli <hey@guimachiavelli.com>
Date: Thu, 3 Oct 2024 16:25:13 +0200
Subject: [PATCH] fix inaccuracies

---
 reference/api/multi_search.mdx | 72 ++++++++++++++++++++++++----------
 1 file changed, 51 insertions(+), 21 deletions(-)

diff --git a/reference/api/multi_search.mdx b/reference/api/multi_search.mdx
index 4f37f5189..6978a5ab0 100644
--- a/reference/api/multi_search.mdx
+++ b/reference/api/multi_search.mdx
@@ -34,13 +34,14 @@ Use `federation` to receive a single list with all search results from all speci
 | :--------------------------------------------------------------------------- | :--------------- | :------------ | :-------------------------------------------------- |
 | **[`offset`](/reference/api/search#offset)**                                 | Integer          | `0`           | Number of documents to skip                         |
 | **[`limit`](/reference/api/search#limit)**                                   | Integer          | `20`          | Maximum number of documents returned                |
-| **[`facetsByIndex`](/#facetsbyindex)**                                   | Object of arrays          | `null`          | Display facet information for the specified facets                |
+| **[`facetsByIndex`](/#facetsbyindex)**                                   | Object of arrays          | `null`          | Display facet information for the specified indexes                |
+| **[`mergeFacets`](/#mergefacets)**                                   | Object          | `null`          | Display facet information for the specified indexes                |
 
 If `federation` is missing or `null`, Meilisearch returns a list of multiple search result objects, with each item from the list corresponding to a search query in the request.
 
 ##### `facetsByIndex`
 
-`facetsByIndex` must be an object. Its keys must correspond to indexes in your in Meilisearch project. Each key must be associated with an array of attributes in the filterable attributes list:
+`facetsByIndex` must be an object. Its keys must correspond to indexes in your Meilisearch project. Each key must be associated with an array of attributes in the filterable attributes list:
 
 ```json
 "facetsByIndex": {
@@ -52,28 +53,59 @@ If `federation` is missing or `null`, Meilisearch returns a list of multiple sea
 When you specify `facetsByIndex`, multi-search responses include an extra `facetsByIndex` field. The response's `facetsByIndex` is an object with one field for each queried index:
 
 ```json
-"facetsByIndex": {
-  "INDEX_A": {
-    "distribution": {
-      "ATTRIBUTE_X": {
-        "KEY": 10,
-        "KEY": 5,
-        …
+{
+  "hits" [ … ],
+  …
+  "facetsByIndex": {
+    "INDEX_A": {
+      "distribution": {
+        "ATTRIBUTE_X": {
+          "KEY": <Integer>,
+          "KEY": <Integer>,
+          …
+        },
+        "ATTRIBUTE_Y": {
+          "KEY": <Integer>,
+          …
+        }
       },
-      "ATTRIBUTE_Y": {
-        "KEY": 1,
-        …
+      "stats": {
+        "KEY": {
+          "min": <Integer>,
+          "max": <Integer>
+        }
       }
     },
-    "stats": {
-      "KEY": {
-        "min": 0,
-        "max": 1
-      }
+    "INDEX_B": {
+      …
+    }
+  }
+}
+```
+
+##### `mergeFacets`
+
+`mergeFacets` must be an object and may contain the following fields:
+
+- `maxValuesPerFacet`: must be an integer. When specified, indicates the maximum number of returned values for a single facet. Defaults to the value assigned to [the `maxValuesPerFacet` index setting](/reference/api/settings#faceting)
+
+When both `facetsByIndex` and `mergeFacets` are present and not null, facet information included in multi-search responses is merged across all queried indexes. Instead of `facetsByIndex`, the response includes two extra fields: `facetDistribution` and `facetStats`:
+
+```json
+{
+  "hits": [ … ],
+  …
+  "facetFederation": {
+    "ATTRIBUTE": {
+      "VALUE": <Integer>,
+      "VALUE": <Integer>
     }
   },
-  "INDEX_B": {
-    …
+  "facetStats": {
+    "ATTRIBUTE": {
+      "min": <Integer>,
+      "max": <Integer>
+    }
   }
 }
 ```
@@ -140,8 +172,6 @@ These options are not compatible with federated searches.
 `federationOptions` must be an object. It accepts the following parameters:
 
 - `weight`: serves as a multiplicative factor to ranking scores of search results in this specific query. If < `1.0`, the hits from this query are less likely to appear in the final results list. If > `1.0`, the hits from this query are more likely to appear in the final results list. Must be a positive floating-point number. Defaults to `1.0`
-- `mergeFacets`: when `mergeFacets` is present and not null, facet information included in multi-search responses is merged across all queried indexes. Instead of `facetsByIndex`, the response includes two extra fields: `facetDistribution` and `facetStats`. `mergeFacets` must be an object, which may optionally contain the following fields:
-  - `maxValuesPerFacet`: must be an integer. When specified, indicates the maximum number of returned values for a single facet. If not specified, Meilisearch uses the value assigned to the `maxValuesPerFacet` index setting
 
 ### Response