add code samples, errors, update multi_search ref

guimachiavelli · guimachiavelli · commit c211cda4529b · 2025-02-04T19:12:02.000+01:00
diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml
@@ -1444,3 +1444,42 @@ experimental_post_logs_stream_1: |-
 experimental_delete_logs_stream_1: |-
   curl \
     -X DELETE MEILISEARCH_URL/logs/stream
+multi_search_remote_federated_1: |-
+  curl \
+    -X POST 'MEILISEARCH_URL/multi-search' \
+    -H 'Content-Type: application/json' \
+    --data-binary '{
+      "federation": {},
+      "queries": [
+        {
+          "indexUid": "movies",
+          "q": "batman",
+          "remote": "ms-00"
+        },
+        {
+          "indexUid": "movies",
+          "q": "batman",
+          "remote": "ms-01"
+        }
+      ]
+    }'
+get_network_1: |-
+  curl \
+    -X GET 'MEILISEARCH_URL/network'
+update_network_1: |-
+  curl \
+    -X PATCH 'MEILISEARCH_URL/network' \
+    -H 'Content-Type: application/json' \
+    --data-binary '{
+      "self": "ms-00",
+      "remotes": {
+        "ms-00": {
+          "url": "http://INSTANCE_URL",
+          "searchApiKey": "INSTANCE_API_KEY"
+        },
+        "ms-01": {
+          "url": "http://ANOTHER_INSTANCE_URL",
+          "searchApiKey": "ANOTHER_INSTANCE_API_KEY"
+        }
+      }
+    }'
diff --git a/reference/api/multi_search.mdx b/reference/api/multi_search.mdx
@@ -139,14 +139,14 @@ There is no way to specify that two documents should be treated as the same acro
 
 | Search parameter                                                             | Type             | Default value | Description                                         |
 | :--------------------------------------------------------------------------- | :--------------- | :------------ | :-------------------------------------------------- |
-| **[`federationOptions`](#federationoptions)**            | Object           | `null`        | Configure federation settings for a specific query |
-| **[`indexUid`](/learn/getting_started/indexes#index-uid)**                     | String           | N/A           | `uid` of the requested index                        |
+| **[`federationOptions`](#federationoptions)**                                | Object           | `null`        | Configure federation settings for a specific query  |
+| **[`indexUid`](/learn/getting_started/indexes#index-uid)**                   | String           | N/A           | `uid` of the requested index                        |
 | **[`q`](/reference/api/search#query-q)**                                     | String           | `""`          | Query string                                        |
 | **[`offset`](/reference/api/search#offset)**                                 | Integer          | `0`           | Number of documents to skip                         |
 | **[`limit`](/reference/api/search#limit)**                                   | Integer          | `20`          | Maximum number of documents returned                |
 | **[`hitsPerPage`](/reference/api/search#number-of-results-per-page)**        | Integer          | `1`           | Maximum number of documents returned for a page     |
 | **[`page`](/reference/api/search#page)**                                     | Integer          | `1`           | Request a specific page of results                  |
-| **[`filter`](/reference/api/search#filter)**                                 | [String](/learn/filtering_and_sorting/filter_expression_reference) | `null`        | Filter queries by an attribute's value              |
+| **[`filter`](/reference/api/search#filter)**                                 | String           | `null`        | Filter queries by an attribute's value              |
 | **[`facets`](/reference/api/search#facets)**                                 | Array of strings | `null`        | Display the count of matches per facet              |
 | **[`attributesToRetrieve`](/reference/api/search#attributes-to-retrieve)**   | Array of strings | `["*"]`       | Attributes to display in the returned documents     |
 | **[`attributesToCrop`](/reference/api/search#attributes-to-crop)**           | Array of strings | `null`        | Attributes whose values have to be cropped          |
@@ -172,10 +172,11 @@ 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`
+- `remote` <NoticeTag type="experimental" label="experimental" />: indicates the remote instance where Meilisearch will perform the query. Must be a string corresponding to a [remote object](/reference/api/network). Defaults to `null`
 
 ### Response
 
-The response to `/multi-search` queries may take two shapes: federated and non-federated.
+The response to `/multi-search` queries may take different shapes depending on the type of query you're making.
 
 #### Non-federated multi-search requests
 
@@ -187,7 +188,7 @@ Each search result object is composed of the following fields:
 
 | Name                     | Type             | Description                                                                      |
 | :----------------------- | :--------------- | :------------------------------------------------------------------------------- |
-| **`indexUid`**           | String           | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index           |
+| **`indexUid`**           | String           | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index         |
 | **`hits`**               | Array of objects | Results of the query                                                             |
 | **`offset`**             | Number           | Number of documents skipped                                                      |
 | **`limit`**              | Number           | Number of documents to take                                                      |
@@ -212,24 +213,27 @@ Federated search requests return a single object and the following fields:
 | **`limit`**              | Number           | Number of documents to take                                                      |
 | **`estimatedTotalHits`** | Number           | Estimated total number of matches                                                |
 | **`processingTimeMs`**   | Number           | Processing time of the query                                                     |
-| **`facetsByIndex`**      | Object           | [Data for facets present in the search results](#facetsbyindex)                                                     |
-| **`facetDistribution`**  | Object           | [Distribution of the given facets](#mergefacets)                                                       |
-| **`facetStats`**         | Object           | [The numeric `min` and `max` values per facet](#mergefacets)                                                     |
+| **`facetsByIndex`**      | Object           | [Data for facets present in the search results](#facetsbyindex)                  |
+| **`facetDistribution`**  | Object           | [Distribution of the given facets](#mergefacets)                                 |
+| **`facetStats`**         | Object           | [The numeric `min` and `max` values per facet](#mergefacets)                     |
+| **`remoteErrors`**       | Object           | Indicates which remote requests failed and why                                   |
 
 Each result in the `hits` array contains an additional `_federation` field with the following fields:
 
-| Name                     | Type             | Description                                                                      |
-| :----------------------- | :--------------- | :------------------------------------------------------------------------------- |
-| **`indexUid`**           | String           | Index of origin for this document           |
-| **`queriesPosition`**    | Number           | Array index number of the query in the request's `queries` array |
+| Name                        | Type             | Description                                                                        |
+| :-------------------------- | :--------------- | :--------------------------------------------------------------------------------- |
+| **`indexUid`**              | String           | Index of origin for this document                                                  |
+| **`queriesPosition`**       | Number           | Array index number of the query in the request's `queries` array                   |
+| **`remote`**                | String           | String indicating the queried remote instance                                      |
+| **`weightedRankingScore`**  | Number           | The product of the _rankingScore of the hit and the weight of the query of origin. |
 
 ### Example
 
 #### Non-federated multi-search
 
 <CodeSamples id="multi_search_1" />
 
-#### Response: `200 Ok`
+##### Response: `200 Ok`
 
 ```json
 {
@@ -289,7 +293,7 @@ Each result in the `hits` array contains an additional `_federation` field with
 
 <CodeSamples id="multi_search_federated_1" />
 
-#### Response: `200 Ok`
+##### Response: `200 Ok`
 
 ```json
 {
@@ -321,3 +325,51 @@ Each result in the `hits` array contains an additional `_federation` field with
   "semanticHitCount": 0
 }
 ```
+
+#### Remote federated multi-search <NoticeTag type="experimental" label="experimental" />
+
+<CodeSamples id="multi_search_remote_federated_1" />
+
+##### Response: `200 Ok`
+
+```json
+{
+  "hits": [
+    {
+      "id": 42,
+      "title": "Batman returns",
+      "overview": …, 
+      "_federation": {
+        "indexUid": "movies",
+        "queriesPosition": 0,
+        "weightedRankingScore": 1.0,
+        "remote": "ms-01"
+    }
+    },
+    {
+      "id": 87,
+      "description": …,
+      "title": "Batman: the killing joke",
+      "_federation": {
+        "indexUid": "movies",
+        "queriesPosition": 1,
+        "weightedRankingScore": 0.9848484848484849,
+        "remote": "ms-00"
+      }
+    },
+    …
+  ],
+  "processingTimeMs": 35,
+  "limit": 5,
+  "offset": 0,
+  "estimatedTotalHits": 111,
+  "remoteErrors": {
+    "ms-02": {
+      "message": "error sending request",
+      "code": "proxy_could_not_send_request",
+      "type": "system",
+      "link": "https://docs.meilisearch.com/errors#proxy_could_not_make_request"
+    }
+  }
+}
+```
diff --git a/reference/api/network.mdx b/reference/api/network.mdx
@@ -52,7 +52,7 @@ This feature is not available for Meilisearch Cloud users.
 **Default value**: `{}`<br />
 **Description**: An object containing `remote` objects. The key of each remote object indicates the name of the remote instance
 
-### The remote object
+#### The remote object
 
 ```json
 "ms-00": {
@@ -61,15 +61,15 @@ This feature is not available for Meilisearch Cloud users.
 }
 ```
 
-### `url`
+##### `url`
 
 **Type**: String<br />
 **Default value**: `null`<br />
 **Description**: URL indicating the address of a Meilisearch instance. This URL does not need to be public, but must be accessible to all instances in the network. Required.
 
-### `searchApiKey`
+##### `searchApiKey`
 
-**Type**: Stringf<br />
+**Type**: String<br />
 **Default value**: `null`<br />
 **Description**: An API key with search permissions
 
@@ -109,7 +109,7 @@ Update the `self` and `remotes` fields of the network object.
 
 Updates to the network object are **partial**. Only provide the fields you intend to update. Fields not present in the payload will remain unchanged.
 
-To reset `self` and `remotes` to their original value, set them to `null`. To remov a single `remote` from your network, set the value of its name to `null`.
+To reset `self` and `remotes` to their original value, set them to `null`. To remove a single `remote` from your network, set the value of its name to `null`.
 
 ### Body
 
@@ -125,6 +125,17 @@ To reset `self` and `remotes` to their original value, set them to `null`. To re
 #### Response: `200 Ok`
 
 ```json
-
+{
+  "self": "ms-00",
+  "remotes": {
+    "ms-00": {
+      "url": "http://INSTANCE_URL",
+      "searchApiKey": "INSTANCE_API_KEY"
+    },
+    "ms-01": {
+      "url": "http://ANOTHER_INSTANCE_URL",
+      "searchApiKey": "ANOTHER_INSTANCE_API_KEY"
+    }
+  }
+}
 ```
-
diff --git a/reference/errors/error_codes.mdx b/reference/errors/error_codes.mdx
@@ -43,6 +43,10 @@ An error occurred during the dump creation process. The task was aborted.
 
 The [`/facet-search`](/reference/api/facet_search) route has been queried while [the `facetSearch` index setting](/reference/api/settings#facet-search) is set to `false`.
 
+## `feature_not_enabled`
+
+Trying to perform one of the actions guarded by `proxy_search` without enabling that feature first. Find the list above: [New experimental feature `proxySearch`](https://www.notion.so/New-experimental-feature-proxySearch-1894b06b651f809997abd5d66440cfc6?pvs=21)  
+
 ## `immutable_api_key_actions`
 
 The [`actions`](/reference/api/keys#actions) field of an API key cannot be modified.
@@ -213,6 +217,10 @@ A multi-search query includes `federationOptions` but the top-level `federation`
 
 A multi-search query contains `page`, `hitsPerPage`, `limit` or `offset`, but the top-level federation object is not `null`.
 
+## `invalid_multi_search_query_position`
+
+`federationOptions.queryPosition` is not a positive integer.
+
 ## `invalid_multi_search_weight`
 
 A multi-search query contains a negative value for `federated.weight`.
@@ -249,6 +257,26 @@ Two or more indexes have a different `faceting.sortFacetValuesBy` for the same r
 
 `facetsByIndex` is not an object or contains unknown fields.
 
+## `invalid_multi_search_remote`
+
+`federationOptions.remote` is not `network.self` and is not a key in `network.remotes`.
+
+## `invalid_network_self`
+
+The [network object](/reference/api/network#the-network-object) contains a `self` that is not a string or `null`.
+
+## `invalid_network_remotes`
+
+The [network object](/reference/api/network#the-network-object) contains a `remotes` that is not an object or `null`.
+
+## `invalid_network_url`
+
+One of the remotes in the [network object](/reference/api/network#the-network-object) contains a `url` that is not a string.
+
+## `invalid_network_search_api_key`
+
+One of the remotes in the [network object](/reference/api/network#the-network-object) contains a `searchApiKey` that is not a string or `null`.
+
 ## `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`.
@@ -411,41 +439,41 @@ This error occurs if:
 - The [`minWordSizeForTypos`](/reference/api/settings#typo-tolerance-object) field is invalid. It should either be an integer or set to `null`
 - The value of either [`oneTypo`](/reference/api/settings#typo-tolerance-object) or [`twoTypos`](/reference/api/settings#typo-tolerance-object) is invalid. It should either be an integer or set to `null`
 
-### `invalid_similar_id`
+## `invalid_similar_id`
 
 The provided target document identifier is invalid. A document identifier can be of type integer or string, only composed of alphanumeric characters (a-z A-Z 0-9), hyphens (-) and underscores (_).
 
-### `not_found_similar_id`
+## `not_found_similar_id`
 
 Meilisearch could not find the target document. Make sure your target document identifier corresponds to a document in your index.
 
-### `invalid_similar_attributes_to_retrieve`
+## `invalid_similar_attributes_to_retrieve`
 
 [`attributesToRetrieve`](/reference/api/search#attributes-to-retrieve) is invalid. It should be an array of strings, a string, or set to null.
 
-### `invalid_similar_filter`
+## `invalid_similar_filter`
 
 [`filter`](/reference/api/search#filter) is invalid or contains a filter expression with a missing or invalid operator. Filter expressions must be a string, array of strings, or array of array of strings for the POST endpoint. It must be a string for the GET endpoint.
 
 Meilisearch also throws this error if the attribute used for filtering is not defined in the `filterableAttributes` list.
 
-### `invalid_similar_limit`
+## `invalid_similar_limit`
 
 [`limit`](/reference/api/search#limit) is invalid. It should be an integer.
 
-### `invalid_similar_offset`
+## `invalid_similar_offset`
 
 [`offset`](/reference/api/search#offset) is invalid. It should be an integer.
 
-### `invalid_similar_show_ranking_score`
+## `invalid_similar_show_ranking_score`
 
 [`ranking_score`](/reference/api/search#ranking-score) is invalid. It should be a boolean.
 
-### `invalid_similar_show_ranking_score_details`
+## `invalid_similar_show_ranking_score_details`
 
 [`ranking_score_details`](/reference/api/search#ranking-score-details) is invalid. It should be a boolean.
 
-### `invalid_embedder`
+## `invalid_embedder`
 
 [`embedder`](/reference/api/search#hybrid-search-experimental) is invalid. It should be a string corresponding to the name of a configured embedder.
 
@@ -575,6 +603,10 @@ The [`facetName`](/reference/api/facet_search#body) parameter is required.
 
 You need to set a master key before you can access the `/keys` route. Read more about setting a master key at launch in our [security tutorial](/learn/security/basic_security).
 
+## `missing_network_url`
+
+One of the remotes in the [network object](/reference/api/network#the-network-object) does not contain the `url` field.
+
 ## `missing_payload`
 
 The Content-Type header was specified, but no request body was sent to the server or the request body is empty.
@@ -618,6 +650,32 @@ You have reached the limit of concurrent search requests. You may configure it b
 
 The document exists in store, but there was an error retrieving it. This probably comes from an inconsistent state in the database.
 
-### `vector_embedding_error`
+## `vector_embedding_error`
 
 Error while generating embeddings.
+
+## Remote federated search errors
+
+### `remote_bad_response`
+
+The remote instance answered with a response that this instance could not use as a federated search response.
+
+### `remote_bad_request`
+
+The remote instance answered with `400 BAD REQUEST`.
+
+### `remote_could_not_send_request`
+
+There was an error while sending the remote federated search request.
+
+### `remote_invalid_api_key`
+
+The remote instance answered with `403 FORBIDDEN` or `401 UNAUTHORIZED` to this instance’s request. The configured search API key is either missing, invalid, or lacks the required search permission.
+
+### `remote_remote_error`
+
+The remote instance answered with `500 INTERNAL ERROR`.
+
+### `remote_timeout`
+
+The proxy did not answer in the allocated time.
