v1.11: Federated search facets

reference/api/multi_search.mdx

@@ -34,9 +34,82 @@ 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 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 Meilisearch project. Each key must be associated with an array of attributes in the filterable attributes list:
+
+```json
+"facetsByIndex": {
+  "INDEX_A": ["ATTRIBUTE_X", "ATTRIBUTE_Y"],
+  "INDEX_B": ["ATTRIBUTE_Z"]
+}
+```
+
+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
+{
+  "hits" [ … ],
+  …
+  "facetsByIndex": {
+    "INDEX_A": {
+      "distribution": {
+        "ATTRIBUTE_X": {
+          "KEY": <Integer>,
+          "KEY": <Integer>,
+          …
+        },
+        "ATTRIBUTE_Y": {
+          "KEY": <Integer>,
+          …
+        }
+      },
+      "stats": {
+        "KEY": {
+          "min": <Integer>,
+          "max": <Integer>
+        }
+      }
+    },
+    "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>
+    }
+  },
+  "facetStats": {
+    "ATTRIBUTE": {
+      "min": <Integer>,
+      "max": <Integer>
+    }
+  }
+}
+```
+
 ##### Merge algorithm for federated searches
 
 Federated search's merged results are returned in decreasing ranking score. To obtain the final list of results, Meilisearch compares with the following procedure:

reference/errors/error_codes.mdx

@@ -213,6 +213,34 @@ A multi-search query contains a negative value for `federated.weight`.
 
 Two or more queries in a multi-search request have incompatible results.
 
+## `invalid_multi_search_facets`
+
+`federation.facetsByIndex.<INDEX_NAME>` contains a value that is not in the filterable attributes list.
+
+## `invalid_multi_search_sort_facet_values_by`
+
+`federation.mergeFacets.sortFacetValuesBy` is not a string or doesn’t have one of the allowed values.
+
+## `invalid_multi_search_query_facets`
+
+A query in the queries array contains `facets` when federation is present and non-`null`.
+
+## `invalid_multi_search_merge_facets`
+
+`federation.mergeFacets`  is not an object or contains unexpected fields.
+
+## `invalid_multi_search_max_values_per_facet`
+
+`federation.mergeFacets.maxValuesPerFacet` is not a positive integer.
+
+## `invalid_multi_search_facet_order`
+
+Two or more indexes have a different `faceting.sortFacetValuesBy` for the same requested facet.
+
+## `invalid_multi_search_facets_by_index`
+
+`facetsByIndex` is not an object or contains unknown fields.
+
 ## `invalid_search_attributes_to_crop`
 
 The [`attributesToCrop`](/reference/api/search#attributes-to-crop) parameter is invalid. It should be an array of strings, a string, or set to `null`.