Settings API - Customize the hard limits for pagination and faceting (#157)

* Introduces specification files

* Update files name

* branch telemetry

* Update open-api.yml

* Update text/0034-telemetry-policies.md

Co-authored-by: Clément Renault <[email protected]>

* update open-api.yml

* Update text/157-faceting-setting-api.md

Co-authored-by: Clément Renault <[email protected]>

* Rename limitedTo to maxTotalHits

* Specify order of returned facet

Co-authored-by: Clément Renault <[email protected]>

Author: gmourier

open-api.yaml

@@ -450,10 +450,28 @@ components:
               type: integer
               default: 9
               nullable: false
+    pagination:
+      type: object
+      description: Customize pagination settings
+      properties:
+        maxTotalHits:
+          description: Define the maximum number of documents reachable for a search request. It means that with the default value of `1000`, it is not possible to see the `1001`st result for a **search query**.
+          type: integer
+          default: 1000
+          nullable: false
+    faceting:
+      type: object
+      description: Customize faceting settings
+      properties:
+        maxValuesPerFacet:
+          description: Define maximum number of value returned for a facet for a **search query**. It means that with the default value of `100`, it is not possible to have `101` different colors if the `color`` field is defined as a facet at search time.
+          type: integer
+          default: 100
+          nullable: false
     filterableAttributes:
       type: array
       description: |
-        Attributes to use for facetting and filtering. See [Filtering and Faceted Search](https://docs.meilisearch.com/reference/features/filtering_and_faceted_search.html).
+        Attributes to use for faceting and filtering. See [Filtering and Faceted Search](https://docs.meilisearch.com/reference/features/filtering_and_faceted_search.html).
       items:
         type: string
       example:
@@ -1723,6 +1741,10 @@ paths:
                     $ref: '#/components/schemas/sortableAttributes'
                   typoTolerance:
                     $ref: '#/components/schemas/typoTolerance'
+                  pagination:
+                    $ref: '#/components/schemas/pagination'
+                  faceting:
+                    $ref: '#/components/schemas/faceting'
                 required:
                   - rankingRules
                   - distinctAttribute
@@ -1733,6 +1755,8 @@ paths:
                   - filterableAttributes
                   - sortableAttributes
                   - typoTolerance
+                  - pagination
+                  - faceting
               examples:
                 Example:
                   value:
@@ -1784,6 +1808,10 @@ paths:
                       minWordSizeForTypos:
                         oneTypo: 4
                         twoTypos: 8
+                    pagination:
+                      maxTotalHits: 1000
+                    faceting:
+                      maxValuesPerFacet: 100
         '401':
           $ref: '#/components/responses/401'
         '404':
@@ -1829,6 +1857,10 @@ paths:
                   $ref: '#/components/schemas/sortableAttributes'
                 typoTolerance:
                   $ref: '#/components/schemas/typoTolerance'
+                pagination:
+                  $ref: '#/components/schemas/pagination'
+                faceting:
+                  $ref: '#/components/schemas/faceting'
             examples:
               Example:
                 value:
@@ -1875,6 +1907,10 @@ paths:
                     minWordSizeForTypos:
                       oneTypo: 4
                       twoTypos: 8
+                  pagination:
+                    maxTotalHits: 1000
+                  faceting:
+                    maxValuesPerFacet: 100
       responses:
         '202':
           $ref: '#/components/responses/202'
@@ -2261,6 +2297,142 @@ paths:
           description: Not Found
     parameters:
       - $ref: '#/components/parameters/indexUid'
+  '/indexes/{indexUid}/settings/pagination':
+    get:
+      operationId: indexes.settings.pagination.get
+      summary: Get pagination configuration
+      description: |
+        Get the pagination configuration of an index.
+      tags:
+        - Settings
+      security:
+        - apiKey: []
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/pagination'
+        '401':
+          $ref: '#/components/responses/401'
+        '404':
+          description: Not Found
+    patch:
+      operationId: indexes.settings.pagination.update
+      summary: Update pagination settings
+      description: |
+        Update the pagination configuration of an index.
+
+        > info
+        > If the provided index does not exist, it will be created.
+      tags:
+        - Settings
+      security:
+        - apiKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/pagination'
+            examples: {}
+        description: ''
+      responses:
+        '202':
+          $ref: '#/components/responses/202'
+        '401':
+          $ref: '#/components/responses/401'
+        '404':
+          description: Not Found
+      parameters:
+        - $ref: '#/components/parameters/Content-Type'
+    delete:
+      operationId: indexes.settings.pagination.reset
+      summary: Reset pagination settings to the default configuration
+      description: |
+        Reset the pagination settings of an index to its default configuration.
+      tags:
+        - Settings
+      security:
+        - apiKey: []
+      responses:
+        '202':
+          $ref: '#/components/responses/202'
+        '401':
+          $ref: '#/components/responses/401'
+        '404':
+          description: Not Found
+    parameters:
+      - $ref: '#/components/parameters/indexUid'
+  '/indexes/{indexUid}/settings/faceting':
+    get:
+      operationId: indexes.settings.faceting.get
+      summary: Get faceting configuration
+      description: |
+        Get the faceting configuration of an index.
+      tags:
+        - Settings
+      security:
+        - apiKey: []
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/faceting'
+        '401':
+          $ref: '#/components/responses/401'
+        '404':
+          description: Not Found
+    patch:
+      operationId: indexes.settings.faceting.update
+      summary: Update faceting settings
+      description: |
+        Update the typo tolerance faceting of an index.
+
+        > info
+        > If the provided index does not exist, it will be created.
+      tags:
+        - Settings
+      security:
+        - apiKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/faceting'
+            examples: {}
+        description: ''
+      responses:
+        '202':
+          $ref: '#/components/responses/202'
+        '401':
+          $ref: '#/components/responses/401'
+        '404':
+          description: Not Found
+      parameters:
+        - $ref: '#/components/parameters/Content-Type'
+    delete:
+      operationId: indexes.settings.faceting.reset
+      summary: Reset faceting settings to the default configuration
+      description: |
+        Reset the faceting settings of an index to its default configuration.
+      tags:
+        - Settings
+      security:
+        - apiKey: []
+      responses:
+        '202':
+          $ref: '#/components/responses/202'
+        '401':
+          $ref: '#/components/responses/401'
+        '404':
+          description: Not Found
+    parameters:
+      - $ref: '#/components/parameters/indexUid'
   '/indexes/{indexUid}/settings/filterable-attributes':
     get:
       operationId: indexes.settings.filterableAttributes.get

text/0034-telemetry-policies.md

@@ -54,6 +54,8 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat
 | FilterableAttributes Updated | Occurs when filterable attributes are updated via `POST` - `/indexes/:indexUid/settings/filterable-attributes`. |
 | SortableAttributes Updated | Occurs when sortable attributes are updated via `POST` - `/indexes/:indexUid/settings/sortable-attributes`. |
 | TypoTolerance Updated | Occurs when typo tolerance settings are updated via `POST` - `/indexes/:indexUid/settings/typo-tolerance`. |
+| Pagination Updated | Occurs when pagination settings are updated via `PATCH` — `/indexes/:indexUid/settings/pagination`. |
+| Faceting Updated | Occurs when faceting settings are updated via `PATCH` — `/indexes/:indexUid/settings/faceting`. |
 | Dump Created | Occurs when a dump is created via `POST` - `/dumps`. |
 | Tasks Seen | Occurs when tasks are fetched globally via `GET` - `/tasks`. |
 
@@ -128,6 +130,8 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat
 | `typo_tolerance.disable_on_words`                   | `true` if at least one value is defined | `false` | `Settings Updated`,  `TypoTolerance Updated` |
 | `typo_tolerance.min_word_size_for_typos.one_typo` | The defined value for `minWordSizeForTypos.oneTypo` property | `5` | `Settings Updated`, `TypoTolerance Updated` |
 | `typo_tolerance.min_word_size_for_typos.two_typos`| The defined value for `minWordSizeForTypos.twoTypos` property | `9` | `Settings Updated`, `TypoTolerance Updated` |
+| `pagination.max_total_hits`                 | The defined value for `pagination.maxTotalHits` property | `1000` | `Settings Updated`, `Pagination Updated` |
+| `faceting.max_values_per_facet`         | The defined value for `faceting.maxValuesPerFacet` property | `100` | `Settings Updated`, `Faceting Updated` |
 | `per_task_uid`                          | `true` if an uid is used to fetch a particular task resource, otherwise `false` | true | `Tasks Seen` |
 | `filtered_by_index_uid`                 | `true` if `GET /tasks` endpoint is filered by `indexUid`, otherwise `false` | false | `Tasks Seen` |
 | `filtered_by_type`                      | `true` if `GET /tasks` endpoint is filered by `type`, otherwise `false` | false | `Tasks Seen` |
@@ -311,6 +315,8 @@ This property allows us to gather essential information to better understand on
 | typo_tolerance.disable_on_words    | `true` if at least one value is defined for `disableOnWords` property. | `false` |
 | typo_tolerance.min_word_size_for_typos.one_typo | The defined value for `minWordSizeForTypos.oneTypo` property. | `5` |
 | typo_tolerance.min_word_size_for_typos.two_typos | The defined value for `minWordSizeForTypos.twoTypos` property. | `9` |
+| pagination.max_total_hits                 | The defined value for `pagination.maxTotalHits` property | `1000` |
+| faceting.max_values_per_facet         | The defined value for `faceting.maxValuesPerFacet` property | `100` |
 
 ---
 
@@ -352,12 +358,24 @@ This property allows us to gather essential information to better understand on
 
 | Property name | Description | Example |
 |---------------|-------------|---------|
-| typo_tolerance.enabled        | Whether the typo tolerance is enable.d | `true` |
+| typo_tolerance.enabled        | Whether the typo tolerance is enabled | `true` |
 | typo_tolerance.disable_on_attributes | `true` if at least one value is defined for `disableOnAttributes` property. | `false` |
 | typo_tolerance.disable_on_words    | `true` if at least one value is defined for `disableOnWords` property. | `false` |
 | typo_tolerance.min_word_size_for_typos.one_typo | The defined value for `minWordSizeForTypos.oneTypo` property. | `5` |
 | typo_tolerance.min_word_size_for_typos.two_typos | The defined value for `minWordSizeForTypos.twoTypos` property. | `9` |
 
+## `Pagination Updated`
+
+| Property name | Description | Example |
+|---------------|-------------|---------|
+| pagination.max_total_hits | The defined value for `maxTotalHits` property | `1000` |
+
+## `Faceting Updated`
+
+| Property name | Description | Example |
+|---------------|-------------|---------|
+| faceting.max_values_per_facet | The defined value for `maxValuesPerFacet` property | `100` |
+
 ## `Dump Created`
 
 | Property name | Description | Example |

text/0123-settings-api.md

@@ -22,6 +22,8 @@ N/A
 | [synonyms](0123-synonyms-setting-api.md)                           | `synonyms` sub-resource API endpoints definition             |
 | [distinct-attribute](0123-distinct-attribute-setting-api.md)       | `distinctAttribute` sub-resource API endpoints definition    |
 | [typo-tolerance](0117-typo-tolerance-setting-api.md)               | `typoTolerance` sub-resource API endpoints definition        |
+| [pagination](157-pagination-setting-api.md)                        | `pagination` sub-resource API endpoints definition           |
+| [faceting](157-faceting-setting-api.md)                            | `faceting` sub-resource API endpoints definition             |
 
 Each setting is exposed as a sub-resource of the `indexes/:index_uid/settings` endpoints. e.g. The ranking rules setting of a Meilisearch index is exposed at `indexes/:index_uid/settings/ranking-rules`.
 
@@ -47,7 +49,9 @@ Fetch the settings of a Meilisearch index.
 | `stopWords`              | Array of String         | true     |
 | `synonyms`               | Object                  | true     |
 | `distinctAttribute`      | String / `null`         | true     |
-| `typo`                   | Object                  | true     |
+| `typoTolerance`          | Object                  | true     |
+| `pagination`             | Object                  | true     |
+| `faceting`               | Object                  | true     |
 
 The attributes ordering in the response payload is equivalent to the order described in the table above.
 
@@ -71,7 +75,9 @@ Modify the settings of a Meilisearch index.
 | `stopWords`              | Array of String / `null` | false    |
 | `synonyms`               | Object / `null`          | false    |
 | `distinctAttribute`      | String / `null`          | false    |
-| `typo`                   | Object                   | false    |
+| `typoTolerance`          | Object                   | false    |
+| `pagination`             | Object                   | false    |
+| `faceting`               | Object                   | false    |
 
 The request payload accepts partial definitions.