Merge branch 'v0.28-pagination-settings' into update-indexes.md-to-add-pagination

Author: guimachiavelli

.code-samples.meilisearch.yaml

@@ -183,6 +183,9 @@ update_settings_1: |-
           "twoTypos": 10
         },
         "disableOnAttributes": ["title"]
+      },
+      "pagination": {
+        "maxTotalHits": 5000
       }
     }'
 reset_settings_1: |-
@@ -964,4 +967,17 @@ settings_guide_pagination_1: |-
     -H 'Content-Type: application/json' \
     --data-binary '{
       "maxTotalHits": 50
-  }'
+    }'
+get_pagination_settings_1: |-
+  curl \
+    -X GET 'http://localhost:7700/indexes/books/settings/pagination'
+update_pagination_settings_1: |-
+  curl \
+    -X PATCH 'http://localhost:7700/indexes/books/settings/pagination' \
+    -H 'Content-Type: application/json' \
+    --data-binary '{
+      "maxTotalHits": 100
+    }'
+reset_pagination_settings_1: |-
+  curl \
+    -X DELETE 'http://localhost:7700/indexes/books/settings/pagination'

.vuepress/config.js

@@ -324,6 +324,7 @@ module.exports = {
                 '/reference/api/displayed_attributes',
                 '/reference/api/distinct_attribute',
                 '/reference/api/filterable_attributes',
+                '/reference/api/pagination',
                 '/reference/api/ranking_rules',
                 '/reference/api/searchable_attributes',
                 '/reference/api/sortable_attributes',

.vuepress/public/sample-template.yaml

@@ -147,3 +147,6 @@ updating_guide_update_settings_old: |-
 updating_guide_add_documents_old: |-
 getting_started_typo_tolerance: |-
 settings_guide_pagination_1: |-
+get_pagination_settings_1: |-
+update_pagination_settings_1: |-
+reset_pagination_settings_1: |-

learn/advanced/known_limitations.md

@@ -97,6 +97,6 @@ user = 1 OR user = 2 […] OR user = 1500 OR user = 1501 […] OR user = 2000 OR
 
 ## Maximum number of results per search
 
-**Limitation:** Meilisearch returns up to 1000 documents per search.
+**Limitation:** By default, Meilisearch returns up to 1000 documents per search.
 
-**Explanation:** This non-customizable limit ensures the database is protected from malicious scraping. This limit only applies to the [search route](/reference/api/search.md). If you want to get all documents in your database, you can use the [get documents endpoint](/reference/api/documents.md#get-documents) instead.
+**Explanation:** Meilisearch limits the maximum amount of returned search results to protect your database from malicious scraping. You may change this by using the `maxTotalHits` property of the [pagination index settings](/reference/api/pagination.md#maxtotalhits). `maxTotalHits` only applies to the [search route](/reference/api/search.md) and has no effect on the [get documents endpoint](/reference/api/documents.md#get-documents).

reference/api/pagination.md

@@ -0,0 +1,98 @@
+# Pagination
+
+_Child route of the [settings route](/reference/api/settings.md)._
+
+This route allows you to configure the pagination settings for an index.
+
+Pagination settings can also be updated directly through the [global settings route](/reference/api/settings.md#update-settings) along with the other settings.
+
+To learn more about paginating search results with Meilisearch, refer to our [dedicated guide](/learn/advanced/pagination.md).
+
+::: warning
+Updating the settings means overwriting the default settings of Meilisearch. You can reset to default values using the `DELETE` routes.
+:::
+
+## Get pagination settings
+
+<RouteHighlighter method="GET" route="/indexes/{index_uid}/settings/pagination"/>
+
+Get the pagination settings of an index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required.
+
+### Example
+
+<CodeSamples id="get_pagination_settings_1" />
+
+#### Response: `200 OK`
+
+```json
+{
+  "maxTotalHits": 1000
+}
+```
+
+### Returned fields
+
+#### `maxTotalHits`
+
+The maximum number of results Meilisearch can return.
+
+## Update pagination settings
+
+<RouteHighlighter method="PATCH" route="/indexes/{index_uid}/settings/pagination"/>
+
+Partially update the pagination settings for an index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required.
+
+### Body
+
+#### `maxTotalHits`
+
+**Type:** integer
+**Default value:** `1000`
+
+An integer indicating the maximum number of search results Meilisearch can return. `maxTotalHits` takes priority over search parameters such as `limit` and `offset`.
+
+For example, if you set `maxTotalHits` to 100, you will not be able to access search results beyond 100 no matter the value configured for `offset`.
+
+::: note
+Setting `maxTotalHits` to a high value might negatively impact performance and expose instance data to malicious scraping.
+:::
+
+#### Example
+
+<CodeSamples id="update_pagination_settings_1" />
+
+#### Response: `200 OK`
+
+```json
+{
+    "taskUid": 1,
+    "indexUid": "books",
+    "status": "enqueued",
+    "type": "settingsUpdate",
+    "enqueuedAt": "2022-04-14T20:56:44.991039Z"
+}
+```
+
+You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task).
+
+## Reset pagination settings
+
+Reset an index's pagination settings to their default value. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required.
+
+#### Example
+
+<CodeSamples id="reset_pagination_settings_1" />
+
+#### Response: `200 OK`
+
+```json
+{
+    "taskUid": 1,
+    "indexUid": "books",
+    "status": "enqueued",
+    "type": "settingsUpdate",
+    "enqueuedAt": "2022-04-14T20:53:32.863107Z"
+}
+```
+
+You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task).

reference/api/search.md

@@ -20,7 +20,7 @@ Other than the differences mentioned above, the two routes are strictly equivale
 Search for documents matching a specific query in the given index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required.
 
 ::: note
-This endpoint has a [non-customizable limit of 1000 results](/learn/advanced/known_limitations.md#maximum-number-of-results-per-search). If you want to scrape your database, use the [get documents endpoint](/reference/api/documents.md#get-documents) instead.
+By default, [this endpoint returns a maximum of 1000 results](/learn/advanced/known_limitations.md#maximum-number-of-results-per-search). If you want to scrape your database, use the [get documents endpoint](/reference/api/documents.md#get-documents) instead.
 :::
 
 This is the preferred route to perform search when an API key is required, as it allows for [preflight requests](https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request) to be cached. Caching preflight requests **considerably improves search speed**.
@@ -111,7 +111,7 @@ Query terms enclosed in double quotes are treated as [phrase searches](#query-q)
 Search for documents matching a specific query in the given index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required.
 
 :::note
-This endpoint has a [non-customizable limit of 1000 results](/learn/advanced/known_limitations.md#maximum-number-of-results-per-search). If you want to scrape your database, you can use the [get documents endpoint](/reference/api/documents.md#get-documents) instead.
+By default, [this endpoint returns a maximum of 1000 results](/learn/advanced/known_limitations.md#maximum-number-of-results-per-search). If you want to scrape your database, use the [get documents endpoint](/reference/api/documents.md#get-documents) instead.
 :::
 
 This route should only be used when no API key is required. If an API key is required, use the POST route instead.