Define fields to search on at runtime

open-api.yaml

@@ -716,6 +716,10 @@ components:
           type: string
           description: Defines which strategy to use to match the query terms within the documents as search results. Two different strategies are available, `last` and `all`. By default, the `last` strategy is chosen.
           default: 'last'
+        attributesToSearchOn:
+          type: array
+          description: Defines which `searchableAttributes` the query will search on.
+          default: '["*"]'
         filter:
           $ref: '#/components/schemas/filter'
         facets:

text/0034-telemetry-policies.md

@@ -121,6 +121,7 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat
 | `filter.with_geoRadius`                 | `true` if the filter rule `_geoRadius` was used in this batch, otherwise `false` | false | `Documents Searched POST`, `Documents Searched GET` |
 | `filter.with_geoBoundingBox`            | `true` if the filter rule `_geoBoundingBox` was used in this batch, otherwise `false`| false | `Documents Searched POST`, `Documents Searched GET` |
 | `filter.most_used_syntax`               | Most used filter syntax among all requests containing the `filter` parameter in this batch | string | `Documents Searched POST`, `Documents Searched GET` |
+| `attributes_to_search_on.total_number_of_uses`| Total number of queries where `attributesToSearchOn` is set | 5 | `Documents Searched POST`, `Documents Searched GET` |
 | `q.max_terms_number`                    | Highest number of terms given for the `q` parameter in this batch | 5 | `Documents Searched POST`, `Documents Searched GET` |
 | `pagination.max_limit`                  | Highest value given for the `limit` parameter in this batch | 60 | `Documents Searched POST`, `Documents Searched GET`, `Documents Fetched GET`, `Documents Fetched POST` |
 | `pagination.max_offset`                 | Highest value given for the `offset` parameter in this batch | 1000 | `Documents Searched POST`, `Documents Searched GET`, `Documents Fetched GET`, `Documents Fetched POST` |
@@ -267,6 +268,7 @@ This property allows us to gather essential information to better understand on
 | filter.with_geoBoundingBox | Does the built-in filter rule _geoBoundingBox has been used in the aggregated event?| `false` |
 | filter.avg_criteria_number | The average number of filter criteria among all the requests containing the `filter` parameter in the aggregated event. `"filter": []` equals to `0` while not sending `filter` does not influence the average in the aggregated event. | `4` |
 | filter.most_used_syntax | The most used filter syntax among all the requests containing the requests containing the `filter` parameter in the aggregated event. `string` / `array` / `mixed` | `mixed` |
+| attributes_to_search_on.total_number_of_uses| Total number of queries where `attributesToSearchOn` is set | `5` |
 | q.max_terms_number | The maximum number of terms for the `q` parameter among all requests in the aggregated event. | `5` |
 | pagination.max_limit | The maximum limit encountered among all requests in the aggregated event. | `20` |
 | pagination.max_offset | The maximum offset encountered among all requests in the aggregated event. | `1000` |
@@ -301,6 +303,7 @@ This property allows us to gather essential information to better understand on
 | filter.with_geoBoundingBox | Does the built-in filter rule _geoBoundingBox has been used in the aggregated event?| `false` |
 | filter.avg_criteria_number | The average number of filter criteria among all the requests containing the `filter` parameter in the aggregated event. `"filter": []` equals to `0` while not sending `filter` does not influence the average in the aggregated event. | `4` |
 | filter.most_used_syntax | The most used filter syntax among all the requests containing the requests containing the `filter` parameter in the aggregated event. `string` / `array` / `mixed` | `mixed` |
+| attributes_to_search_on.total_number_of_uses | Total number of queries where `attributesToSearchOn` is set | 5 |
 | q.max_terms_number | The maximum number of terms for the `q` parameter among all requests in the aggregated event. | `5` |
 | pagination.max_limit | The maximum limit encountered among all requests in the aggregated event. | `20` |
 | pagination.max_offset | The maximum offset encountered among all requests in the aggregated event. | `1000` |

text/0061-error-format-and-definitions.md

@@ -1808,6 +1808,49 @@ HTTP Code: `400 Bad Request`
 }
 ```
 
+## invalid_search_attributes_to_search_on
+
+`Synchronous`
+
+### Context
+
+This error occurs if a value with a different type than `Array of String`(POST), `String`(GET) or `null` and other than attributes names contained in the settings `searchableAttributes` as a value for `attributesToSearchOn` is specified.
+
+### Error Definition
+
+HTTP Code: `400 Bad Request`
+
+```json
+{
+    "message": "`:deserr_helper`",
+    "code": "invalid_search_attributes_to_search_on",
+    "type": "invalid_request",
+    "link": "https://docs.meilisearch.com/errors#invalid_search_attributes_to_search_on"
+}
+```
+
+#### Variant: one of the values is not part of the settings `searchableAttributes` list
+
+```json
+{
+    "message": "Attribute `:value` is not searchable. Available searchable attributes are: `:searchableAttributes`.",
+    "code": "invalid_search_attributes_to_search_on",
+    "type": "invalid_request",
+    "link": "https://docs.meilisearch.com/errors#invalid_search_attributes_to_search_on"
+}
+```
+
+#### Variant: one of the values is not part of the settings `searchableAttributes` list and not all of the `searchableAttributes` are displayable
+
+```json
+{
+    "message": "Attribute `:value` is not searchable. Available searchable attributes are: `:DisplayableSearchableAttributes, <..hidden-attributes>`.",
+    "code": "invalid_search_attributes_to_search_on",
+    "type": "invalid_request",
+    "link": "https://docs.meilisearch.com/errors#invalid_search_attributes_to_search_on"
+}
+```
+
 ---
 
 ## invalid_document_geo_field

text/0118-search-api.md

@@ -51,6 +51,7 @@ If a master key is used to secure a Meilisearch instance, the auth layer returns
 | [`cropMarker`](#3115-cropmarker)                      | String                   | False    |
 | [`showMatchesPosition`](#3116-showmatchesposition)    | Boolean                  | False    |
 | [`matchingStrategy`](#3117-matchingStrategy)          | String                   | False    |
+| [`attributesToSearchOn`](#3118-attributesToSearchOn)  | Array of String - String | False    |
 
 
 #### 3.1.1. `q`
@@ -912,6 +913,20 @@ The documents containing ALL the query words (i.e. in the `q` parameter) are ret
 
 Only the documents containing ALL the query words (i.e. in the `q` parameter) are returned by Meilisearch. If Meilisearch doesn't have enough documents to fit the requested `limit`, it returns the documents found without trying to match more documents.
 
+#### 3.1.17. `attributesToSearchOn`
+
+- Type: Array of String (POST) | String (GET)
+- Required: False
+- Default: `["*"]`
+
+Defines which `searchableAttributes` the query will search on.
+
+- If `attributesToSearchOn` is not set, set to `["*"]` or set to `null`, then the query will search on all `searchableAttributes`.
+- Sending the attributes in a different order than the order set in the settings `searchableAttributes` doesn't reorder the fields' rank for the `Attributes` ranking rule
+- 🔴 Sending a value with a different type than `Array of String`(POST), `String`(GET) or `null` for `attributesToSearchOn` returns an [invalid_attributes_to_search_on](0061-error-format-and-definitions.md#invalid_search_attributes_to_search_on) error.
+- 🔴 Sending an attribute that is not part of the settings `searchableAttributes` list returns an [invalid_attributes_to_search_on](0061-error-format-and-definitions.md#invalid_search_attributes_to_search_on) error.
+
+
 ### 3.2. Search Response Properties
 
 | Field                                           | Type       | Required |