Documents API - displayedAttributes should not impact the documents API / Rename attributesToRetrieve to fields

open-api.yaml

@@ -156,7 +156,7 @@ components:
           type:
             - string
             - number
-          description: Retrieve attributes of the document. `attributesToRetrieve` controls these fields.
+          description: Retrieve attributes of a search result. `attributesToRetrieve` controls these fields.
         _geoDistance:
           type: number
           description: 'Using _geoPoint({lat}, {lng}) built-in sort rule at search leads the engine to return a _geoDistance within the search results. This field represents the distance in meters of the document from the specified _geoPoint.'
@@ -815,6 +815,16 @@ components:
 
         > warn
         > Attribute(s) used in `filter` should be declared as filterable attributes. See [Filtering and Faceted Search](https://docs.meilisearch.com/reference/features/filtering_and_faceted_search.html).
+    fields:
+      name: fields
+      in: query
+      description: 'Comma-separated list of fields to display for an API resource. By default it contains all fields of an API resource.'
+      schema:
+        type: string
+        items:
+          type: string
+        example: 'uid,createdAt'
+        default: '*'
     Content-Type:
       name: Content-Type
       in: header
@@ -1255,7 +1265,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/limit'
         - $ref: '#/components/parameters/offset'
-        - $ref: '#/components/parameters/attributesToRetrieve'
+        - $ref: '#/components/parameters/fields'
     post:
       operationId: indexes.documents.create
       summary: Add or replace documents
@@ -1431,6 +1441,8 @@ paths:
           $ref: '#/components/responses/401'
         '404':
           description: Not Found
+      parameters:
+        - $ref: '#/components/parameters/fields'
     delete:
       operationId: indexes.documents.remove
       summary: Delete one document

text/0124-documents-api.md

@@ -4,6 +4,8 @@
 
 This specification describes the documents API endpoints permitting to list, fetch, add/replace, and delete index documents.
 
+It is an API dedicated to document management within the Meilisearch index.
+
 ## 2. Motivation
 N/A
 
@@ -53,8 +55,8 @@ Unique identifier of an index.
 | Field                    | Type                     | Required |
 |--------------------------|--------------------------|----------|
 | `offset`                 | Integer / `null`         | false    |
-| `limit`                  | Integer / `null`         | false    |
-| `attributesToRetrieve`   | String / `null`          | false    |
+| `limit`                  | String / `null`          | false    |
+| `fields`                 | String / `null`          | false    |
 
 ###### 3.1.1.2.1. `offset`
 
@@ -72,19 +74,24 @@ Sets the starting point in the results, effectively skipping over a given number
 
 Sets the maximum number of documents to be returned by the current request.
 
-###### 3.1.1.2.3. `attributesToRetrieve`
+###### 3.1.1.2.3. `fields`
 
 - Type: String
 - Required: False
-- Default: `null`
+- Default: `*`
 
 Configures which attributes will be retrieved in the returned documents.
 
-If no value is specified, `attributesToRetrieve` uses the `displayedAttributes` list, which by default contains all attributes found in the documents.
+If `fields` is not specified, all attributes from the documents are returned in the response. It's equivalent to `fields=*`.
+
+- Sending `fields` without specifying a value, returns empty documents ressources. `fields=`.
+- Sending `fields` with a non-existent field as part of the value will not return an error, the non-existent field will not be displayed.
 
-> If an attribute has been removed from `displayedAttributes` index settings, `attributesToRetrieve` will silently ignore it and the field will not appear in the returned documents.
+> `fields` values are case-sensitive.
 
-> Specified fields have to be separated by a comma. e.g. `&attributesToRetrieve=title,description`
+> Specified fields have to be separated by a comma. e.g. `&fields=title,description`
+
+> The index setting `displayedAttributes` has no impact on this endpoint.
 
 ##### 3.1.1.3. Response Definition
 
@@ -153,7 +160,7 @@ Gives the total number of documents that can be browsed in the related index.
 
 - 🔴 Sending a value with a different type than `Integer` or `null` for `offset` will return a [bad_request](0061-error-format-and-definitions.md#bad_request) error.
 - 🔴 Sending a value with a different type than `Integer` or `null` for `limit` will return a [bad_request](0061-error-format-and-definitions.md#bad_request) error.
-- 🔴 Sending a value with a different type than `String` or `null` for `attributesToRetrieve` will return a [bad_request](0061-error-format-and-definitions.md#bad_request) error.
+- 🔴 Sending a value with a different type than `String` or `null` for `fields` will return a [bad_request](0061-error-format-and-definitions.md#bad_request) error.
 
 #### 3.1.2. `GET` - `indexes/:index_uid/documents/:document_id`
 
@@ -180,14 +187,39 @@ Unique identifier of an index.
 
 Unique identifier of a document.
 
-##### 3.1.2.1. Request Payload Definition
+##### 3.1.2.2. Query Parameters
+
+| Field                    | Type                     | Required |
+|--------------------------|--------------------------|----------|
+| `fields`                 | String / `null`          | false    |
+
+###### 3.1.2.2.1. `fields`
+
+- Type: String
+- Required: False
+- Default: `*`
+
+Configures which attributes will be retrieved in the returned documents.
+
+If `fields` is not specified, all attributes from the documents are returned in the response. It's equivalent to `fields=*`.
+
+- Sending `fields` without specifying a value, returns empty documents ressources. `fields=`.
+- Sending `fields` with a non-existent field as part of the value will not return an error, the non-existent field will not be displayed.
+
+> `fields` values are case-sensitive.
+
+> Specified fields have to be separated by a comma. e.g. `&fields=title,description`
+
+> The index setting `displayedAttributes` has no impact on this endpoint.
+
+##### 3.1.2.3. Request Payload Definition
 N/A
 
-##### 3.1.2.2. Response Definition
+##### 3.1.2.4. Response Definition
 
 A document represented as a JSON object.
 
-##### 3.1.2.2.1. Example
+##### 3.1.2.4.1. Example
 
 ```json
 {
@@ -199,10 +231,11 @@ A document represented as a JSON object.
 }
 ```
 
-##### 3.1.2.3. Errors
+##### 3.1.2.5. Errors
 
 - 🔴 If the requested `index_uid` does not exist, the API returns an [index_not_found](0061-error-format-and-definitions.md#index_not_found) error.
 - 🔴 If the requested `document_id` does not exist, the API returns an [document_not_found](0061-error-format-and-definitions.md#document_not_found) error.
+- 🔴 Sending a value with a different type than `String` or `null` for `fields` will return a [bad_request](0061-error-format-and-definitions.md#bad_request) error.
 
 #### 3.1.3. `POST` - `indexes/:index_uid/documents`
 
@@ -489,4 +522,5 @@ The auth layer can return the following errors if Meilisearch is secured (a mast
 N/A
 
 ## 5. Future Possibilities
-N/A
+
+- Introduce a way to reject fields from a document in the response. e.g. `?fields=-createdAt`