diff --git a/open-api.yaml b/open-api.yaml index 30d4c3e6..28dad7d6 100644 --- a/open-api.yaml +++ b/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 diff --git a/text/0124-documents-api.md b/text/0124-documents-api.md index 3dc03f73..e4b3e1f2 100644 --- a/text/0124-documents-api.md +++ b/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 \ No newline at end of file + +- Introduce a way to reject fields from a document in the response. e.g. `?fields=-createdAt` \ No newline at end of file