From 868eb4e0334bca2cb8a911e02bf26cf5f561864b Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Thu, 14 Apr 2022 12:26:02 +0200 Subject: [PATCH 1/5] Specifies that displayedAttributes setting does not impact the GET documents endpoint --- text/0124-documents-api.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/text/0124-documents-api.md b/text/0124-documents-api.md index 3dc03f73..cfaf5eb2 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 @@ -80,12 +82,12 @@ Sets the maximum number of documents to be returned by the current request. 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 an attribute has been removed from `displayedAttributes` index settings, `attributesToRetrieve` will silently ignore it and the field will not appear in the returned documents. +If no value is specified, all attributes from the documents are returned in the response. > Specified fields have to be separated by a comma. e.g. `&attributesToRetrieve=title,description` +> The index setting `displayedAttributes` has no impact on this endpoint. + ##### 3.1.1.3. Response Definition A `results` array representing documents as JSON objects. From fcb0840c6eb591a09149970bb6fa38df8beafe27 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Thu, 21 Apr 2022 12:28:08 +0200 Subject: [PATCH 2/5] Rename attributeToRetrieve to fields on /documents --- open-api.yaml | 16 ++++++++++++++-- text/0124-documents-api.md | 10 +++++----- 2 files changed, 19 insertions(+), 7 deletions(-) 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 cfaf5eb2..855b69f7 100644 --- a/text/0124-documents-api.md +++ b/text/0124-documents-api.md @@ -55,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` @@ -74,7 +74,7 @@ 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 @@ -84,7 +84,7 @@ Configures which attributes will be retrieved in the returned documents. If no value is specified, all attributes from the documents are returned in the response. -> 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. @@ -155,7 +155,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` From fd73aff8e4575f6ff0ec5f7848ac26c21a392048 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Thu, 21 Apr 2022 12:33:00 +0200 Subject: [PATCH 3/5] Add a future possibily to rejectt a field from a document in the given response --- text/0124-documents-api.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/text/0124-documents-api.md b/text/0124-documents-api.md index 855b69f7..43ef6fc7 100644 --- a/text/0124-documents-api.md +++ b/text/0124-documents-api.md @@ -491,4 +491,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 From c8697df91e0cc58da39591a5b96f05b029a91ff7 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Thu, 19 May 2022 16:15:22 +0200 Subject: [PATCH 4/5] Precise behavior details about fields query parameter --- text/0124-documents-api.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/text/0124-documents-api.md b/text/0124-documents-api.md index 43ef6fc7..af03b7be 100644 --- a/text/0124-documents-api.md +++ b/text/0124-documents-api.md @@ -78,11 +78,16 @@ Sets the maximum number of documents to be returned by the current request. - Type: String - Required: False -- Default: `null` +- Default: `*` Configures which attributes will be retrieved in the returned documents. -If no value is specified, all attributes from the documents are returned in the response. +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` From 47d36c935273465e6a8a1c23b4b225d0402b3b22 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Wed, 1 Jun 2022 19:13:39 +0200 Subject: [PATCH 5/5] Add fields query parameter on GET /indexes/{index}/documents/{docId} --- text/0124-documents-api.md | 34 ++++++++++++++++++++++++++++++---- 1 file changed, 30 insertions(+), 4 deletions(-) diff --git a/text/0124-documents-api.md b/text/0124-documents-api.md index af03b7be..e4b3e1f2 100644 --- a/text/0124-documents-api.md +++ b/text/0124-documents-api.md @@ -187,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 { @@ -206,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`