From 8aa9b7aa8f82e6c210d56eae3d98d7666cff336a Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 8 Jun 2022 15:18:23 +0200 Subject: [PATCH 001/150] v0.28: bump version number --- .vuepress/config.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.vuepress/config.js b/.vuepress/config.js index a9992b9b14..395bd548d8 100644 --- a/.vuepress/config.js +++ b/.vuepress/config.js @@ -1,6 +1,6 @@ const ogprefix = 'og: http://ogp.me/ns#' module.exports = { - title: 'Meilisearch Documentation v0.27', + title: 'Meilisearch Documentation v0.28', description: 'Open source Instant Search Engine', theme: 'default-prefers-color-scheme', themeConfig: { From d6312cfbec8c2352d4b69bd759d04af7f3e497f0 Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Tue, 14 Jun 2022 18:56:44 +0200 Subject: [PATCH 002/150] Rewrite language.md for hebrew --- learn/what_is_meilisearch/language.md | 32 +++++++++++++-------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/learn/what_is_meilisearch/language.md b/learn/what_is_meilisearch/language.md index 38c9bf3e56..125b559555 100644 --- a/learn/what_is_meilisearch/language.md +++ b/learn/what_is_meilisearch/language.md @@ -1,42 +1,42 @@ # Language -**Meilisearch is multilingual**, featuring optimized support for: +Meilisearch is multilingual, featuring optimized support for: - **Any language that uses whitespace to separate words** - **Chinese** (through [Jieba](https://github.com/messense/jieba-rs)) - **Japanese** (through [Lindera](https://github.com/lindera-morphology/lindera)) +- **Hebrew** (with normalization through [Niqqud](https://docs.rs/niqqud/latest/niqqud/)) -We aim to provide global language support, and your feedback helps us [move closer to that goal](#improving-our-language-support). If you notice inconsistencies in your search results or the way your documents are processed, please open an issue on our [GitHub repository](https://github.com/meilisearch/meilisearch/issues/new/choose). +We aim to provide global language support, and your feedback helps us move closer to that goal. If you notice inconsistencies in your search results or the way your documents are processed, please [open an issue in our tokenizer repo](https://github.com/meilisearch/charabia/issues/new). -If you'd like to learn more about how different languages are processed in Meilisearch, see our [tokenizer documentation](/learn/advanced/tokenization.md). +[Read more about our tokenizer](/learn/advanced/tokenization.md) ## Improving our language support -While we have employees from all over the world at Meilisearch, we don't speak every language. In fact, we rely almost entirely on feedback from external contributors to know how our engine is performing across different languages. +While we have employees from all over the world at Meilisearch, we don't speak every language. We rely almost entirely on feedback from external contributors to understand how our engine is performing across different languages. -If you'd like to help us create a more global Meilisearch, please consider sharing your tests, results, and general feedback with us through [GitHub issues](https://github.com/meilisearch/Meilisearch/issues). Here are some of the languages that have been requested by users and their corresponding issue: - -- [Arabic](https://github.com/meilisearch/meilisearch/issues/554) -- [Lao](https://github.com/meilisearch/meilisearch/issues/563) -- [Persian/Farsi](https://github.com/meilisearch/meilisearch/issues/553) -- [Thai](https://github.com/meilisearch/meilisearch/issues/864) - -If you'd like us to add or improve support for a language that isn't in the above list, please create an [issue](https://github.com/meilisearch/meilisearch/issues/new?assignees=&labels=&template=feature_request.md&title=) saying so, and then make a [pull request on the documentation](https://github.com/meilisearch/documentation/edit/master/reference/features/language.md) to add it to the above list. +- If you'd like to request dedicated support for a language but aren't able to work on a tokenization pipeline yourself, please [open a discussion in our product repo](https://github.com/meilisearch/product/discussions). +- If you are interested in contributing to the Meilisearch tokenizer directly, please have a look at the [contribution guide](https://github.com/meilisearch/charabia/blob/main/CONTRIBUTING.md) before doing so. ## FAQ ### What do you mean when you say Meilisearch offers _optimized_ support for a language? -Under the hood, Meilisearch relies on tokenizers that identify the most important parts of each document in a given dataset. We currently use two tokenization pipelines: one for languages that separate words with spaces and one specifically tailored for Chinese. Languages that delimit their words in other ways will still work, but the quality and relevancy of search results may vary significantly. +Under the hood, Meilisearch relies on tokenizers that identify the most important parts of each document in a given dataset. We currently use four tokenization pipelines: + +- A default one designed for languages that separate words with spaces +- One specifically tailored for Chinese +- One specifically tailored for Japanese +- One specifically tailored for Hebrew ### My language does not use whitespace to separate words. Can I still use Meilisearch? -Yes, but your experience might not be optimized and results might be less relevant than in whitespace-separated languages and Chinese. +Yes, but search results might be less relevant than in one of the fully optimized languages. ### My language does not use the Roman alphabet. Can I still use Meilisearch? -Yes—our users work with many different alphabets and writing systems such as Cyrillic, Thai, and Japanese. +Yes—our users work with many different alphabets and writing systems, such as Cyrillic, Thai, and Japanese. ### Does Meilisearch plan to support additional languages in the future? -Yes, we definitely do. The more feedback we get from native speakers, the easier it is for us to understand how to improve performance for those languages—and the more requests to improve support for a specific language, the more likely we are to devote resources to that project. +Yes, we definitely do. The more feedback we get from native speakers, the easier it is for us to understand how to improve performance for those languages. Similarly, the more requests we get to improve support for a specific language, the more likely we are to devote resources to that project. From 85227a7a934961b6448184772b4773b1232e5971 Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Wed, 15 Jun 2022 16:31:34 +0200 Subject: [PATCH 003/150] Update tokenization page (four total pipelines Also reduce technical complexity of language page (no need to mention specific normalizers + segmenters) --- learn/advanced/tokenization.md | 8 +++++--- learn/what_is_meilisearch/language.md | 11 ++++++----- 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/learn/advanced/tokenization.md b/learn/advanced/tokenization.md index acf63d63be..3a17cdcba2 100644 --- a/learn/advanced/tokenization.md +++ b/learn/advanced/tokenization.md @@ -17,9 +17,11 @@ We can break down the tokenization process like so: 1. Crawl the document(s) and determine the primary language for each field 2. Go back over the documents field-by-field, running the corresponding tokenization pipeline, if it exists -Pipelines include many language-specific operations. Currently, we have two pipelines: +Pipelines include many language-specific operations. Currently, we have four pipelines: -1. A specialized Chinese pipeline using [Jieba](https://github.com/messense/jieba-rs) -2. A default Meilisearch pipeline that separates words based on categories. Works with a variety of languages +1. A default Meilisearch pipeline for languages that use whitespace to separate words. Uses [unicode segmenter](https://github.com/unicode-rs/unicode-segmentation) +2. A specialized Chinese pipeline using [Jieba](https://github.com/messense/jieba-rs) +3. A specialized Japanese pipeline using [Lindera](https://github.com/lindera-morphology/lindera) +4. A specialized Hebrew pipeline based off the default Meilisearch pipeline. Uses [Niqqud](https://docs.rs/niqqud/latest/niqqud/) for normalization For more details, check out the [feature specification](https://github.com/meilisearch/specifications/blob/master/text/0001-script-based-tokenizer.md). diff --git a/learn/what_is_meilisearch/language.md b/learn/what_is_meilisearch/language.md index 125b559555..5e7521d818 100644 --- a/learn/what_is_meilisearch/language.md +++ b/learn/what_is_meilisearch/language.md @@ -3,9 +3,9 @@ Meilisearch is multilingual, featuring optimized support for: - **Any language that uses whitespace to separate words** -- **Chinese** (through [Jieba](https://github.com/messense/jieba-rs)) -- **Japanese** (through [Lindera](https://github.com/lindera-morphology/lindera)) -- **Hebrew** (with normalization through [Niqqud](https://docs.rs/niqqud/latest/niqqud/)) +- **Chinese** +- **Japanese** +- **Hebrew** We aim to provide global language support, and your feedback helps us move closer to that goal. If you notice inconsistencies in your search results or the way your documents are processed, please [open an issue in our tokenizer repo](https://github.com/meilisearch/charabia/issues/new). @@ -15,8 +15,9 @@ We aim to provide global language support, and your feedback helps us move close While we have employees from all over the world at Meilisearch, we don't speak every language. We rely almost entirely on feedback from external contributors to understand how our engine is performing across different languages. -- If you'd like to request dedicated support for a language but aren't able to work on a tokenization pipeline yourself, please [open a discussion in our product repo](https://github.com/meilisearch/product/discussions). -- If you are interested in contributing to the Meilisearch tokenizer directly, please have a look at the [contribution guide](https://github.com/meilisearch/charabia/blob/main/CONTRIBUTING.md) before doing so. +If you'd like to request optimized support for a language that we don't currently support, please [open a discussion in our product repository](https://github.com/meilisearch/product/discussions). + +If you'd like to help by developing a tokenizer pipeline yourself: first of all, thank you! We recommend that you take a look at the [tokenizer contribution guide](https://github.com/meilisearch/charabia/blob/main/CONTRIBUTING.md) before making a PR. ## FAQ From 556a908fd6cbf130f003ca81d5f87c9ea46d4215 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 15 Jun 2022 18:47:01 +0200 Subject: [PATCH 004/150] update cropping behaviour --- reference/api/search.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/reference/api/search.md b/reference/api/search.md index 491fc9aa8b..6a8c1773e4 100644 --- a/reference/api/search.md +++ b/reference/api/search.md @@ -460,7 +460,17 @@ Optionally, you can indicate a custom crop length for any attributes given to `a Instead of supplying individual attributes, you can provide `["*"]` as a wildcard: `attributesToCrop=["*"]`. This causes `_formatted` to include the cropped values of all attributes present in [`attributesToRetrieve`](#attributes-to-retrieve). -**Meilisearch crops around the first occurrence of any one of the terms present in the search query.** If Meilisearch does not find any query terms in a field, cropping begins at the first word in that field. +#### Cropping rules + +Suppose you have a field containing the following string: `Donatello is a skilled and smart turtle. Leonardo is the most skilled turtle. Raphael is the strongest turtle.` + +Meilisearch takes sentence context in consideration when cropping. For example, if your search term is `Leonardo` and your `cropLength` is 6, Meilisearch will prioritize keeping the sentence together and return: `Leonardo is the most skilled turtle.` + +If a query contains only a single search term, Meilisearch crops around the first occurrence of that term. If you search for `turtle` and your `cropLength` is 7, Meilisearch will return the first instance of that word: `Donatello is a skilled and smart turtle.` + +If a query contains multiple search terms, Meilisearch centers the crop around the largest number of unique matches, giving priority to terms that are closer to each other and follow the original query order. If you search for `skilled turtle` with a `cropLength` of 6, Meilisearch will return `Leonardo is the most skilled turtle`. + +If Meilisearch does not find any query terms in a field, cropping begins at the first word in that field. If you search for `Michelangelo` with a `cropLength` of 4, Meilisearch will return `Donatello is a skilled …`. #### Example @@ -530,7 +540,7 @@ When searching for `shifu`, you can use `cropMarker` to change the default `…` "id": 50393, "title": "Kung Fu Panda Holiday", "poster": "https://image.tmdb.org/t/p/w1280/gp18R42TbSUlw9VnXFqyecm52lq.jpg", - "overview": "[…]villager. But this year Shifu informs Po that as Dragon[…]", + "overview": "[…]But this year Shifu informs Po that as Dragon Warrior,[…]", "release_date": 1290729600 } } From fda72a558e73c70a550fa960510ce7cef1a9c386 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Thu, 16 Jun 2022 11:16:06 +0400 Subject: [PATCH 005/150] v0.28: API endpoint verbs update --- .code-samples.meilisearch.yaml | 72 +++++++++++++------------- reference/api/displayed_attributes.md | 2 +- reference/api/distinct_attribute.md | 2 +- reference/api/filterable_attributes.md | 2 +- reference/api/ranking_rules.md | 2 +- reference/api/searchable_attributes.md | 2 +- reference/api/settings.md | 2 +- reference/api/sortable_attributes.md | 2 +- reference/api/stop_words.md | 2 +- reference/api/synonyms.md | 2 +- reference/api/typo_tolerance.md | 2 +- 11 files changed, 46 insertions(+), 46 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 047cb60b9f..fcb90e2b9e 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -136,7 +136,7 @@ get_settings_1: |- -X GET 'http://localhost:7700/indexes/movies/settings' update_settings_1: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings' \ + -X PATCH 'http://localhost:7700/indexes/movies/settings' \ -H 'Content-Type: application/json' \ --data-binary '{ "rankingRules": [ @@ -193,7 +193,7 @@ get_synonyms_1: |- -X GET 'http://localhost:7700/indexes/movies/settings/synonyms' update_synonyms_1: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings/synonyms' \ + -X PUT 'http://localhost:7700/indexes/movies/settings/synonyms' \ -H 'Content-Type: application/json' \ --data-binary '{ "wolverine": [ @@ -214,7 +214,7 @@ get_stop_words_1: |- -X GET 'http://localhost:7700/indexes/movies/settings/stop-words' update_stop_words_1: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings/stop-words' \ + -X PUT 'http://localhost:7700/indexes/movies/settings/stop-words' \ -H 'Content-Type: application/json' \ --data-binary '[ "the", @@ -229,7 +229,7 @@ get_ranking_rules_1: |- -X GET 'http://localhost:7700/indexes/movies/settings/ranking-rules' update_ranking_rules_1: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings/ranking-rules' \ + -X PUT 'http://localhost:7700/indexes/movies/settings/ranking-rules' \ -H 'Content-Type: application/json' \ --data-binary '[ "words", @@ -249,7 +249,7 @@ get_distinct_attribute_1: |- -X GET 'http://localhost:7700/indexes/shoes/settings/distinct-attribute' update_distinct_attribute_1: |- curl \ - -X POST 'http://localhost:7700/indexes/shoes/settings/distinct-attribute' \ + -X PUT 'http://localhost:7700/indexes/shoes/settings/distinct-attribute' \ -H 'Content-Type: application/json' \ --data-binary '"skuid"' reset_distinct_attribute_1: |- @@ -260,7 +260,7 @@ get_filterable_attributes_1: |- -X GET 'http://localhost:7700/indexes/movies/settings/filterable-attributes' update_filterable_attributes_1: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings/filterable-attributes' \ + -X PUT 'http://localhost:7700/indexes/movies/settings/filterable-attributes' \ -H 'Content-Type: application/json' \ --data-binary '[ "genres", @@ -274,7 +274,7 @@ get_searchable_attributes_1: |- -X GET 'http://localhost:7700/indexes/movies/settings/searchable-attributes' update_searchable_attributes_1: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings/searchable-attributes' \ + -X PUT 'http://localhost:7700/indexes/movies/settings/searchable-attributes' \ -H 'Content-Type: application/json' \ --data-binary '[ "title", @@ -289,7 +289,7 @@ get_displayed_attributes_1: |- -X GET 'http://localhost:7700/indexes/movies/settings/displayed-attributes' update_displayed_attributes_1: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings/displayed-attributes' \ + -X PUT 'http://localhost:7700/indexes/movies/settings/displayed-attributes' \ -H 'Content-Type: application/json' \ --data-binary '[ "title", @@ -314,12 +314,12 @@ get_version_1: |- -X GET 'http://localhost:7700/version' distinct_attribute_guide_1: |- curl \ - -X POST 'http://localhost:7700/indexes/jackets/settings' \ + -X PUT 'http://localhost:7700/indexes/jackets/settings' \ -H 'Content-Type: application/json' \ --data-binary '{ "distinctAttribute": "product_id" }' field_properties_guide_searchable_1: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings' \ + -X PUT 'http://localhost:7700/indexes/movies/settings' \ -H 'Content-Type: application/json' \ --data-binary '{ "searchableAttributes": [ @@ -330,7 +330,7 @@ field_properties_guide_searchable_1: |- }' field_properties_guide_displayed_1: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings' \ + -X PUT 'http://localhost:7700/indexes/movies/settings' \ -H 'Content-Type: application/json' \ --data-binary '{ "displayedAttributes": [ @@ -442,7 +442,7 @@ search_parameter_guide_matches_1: |- }' settings_guide_synonyms_1: |- curl \ - -X POST 'http://localhost:7700/indexes/tops/settings' \ + -X PUT 'http://localhost:7700/indexes/tops/settings' \ -H 'Content-Type: application/json' \ --data-binary '{ "synonyms": { @@ -452,7 +452,7 @@ settings_guide_synonyms_1: |- }' settings_guide_stop_words_1: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings' \ + -X PUT 'http://localhost:7700/indexes/movies/settings' \ -H 'Content-Type: application/json' \ --data-binary '{ "stopWords": [ @@ -463,7 +463,7 @@ settings_guide_stop_words_1: |- }' settings_guide_ranking_rules_1: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings' \ + -X PUT 'http://localhost:7700/indexes/movies/settings' \ -H 'Content-Type: application/json' \ --data-binary '{ "rankingRules": [ @@ -479,12 +479,12 @@ settings_guide_ranking_rules_1: |- }' settings_guide_distinct_1: |- curl \ - -X POST 'http://localhost:7700/indexes/jackets/settings' \ + -X PUT 'http://localhost:7700/indexes/jackets/settings' \ -H 'Content-Type: application/json' \ --data-binary '{ "distinctAttribute": "product_id" } settings_guide_searchable_1: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings' \ + -X PUT 'http://localhost:7700/indexes/movies/settings' \ -H 'Content-Type: application/json' \ --data-binary '{ "searchableAttributes": [ @@ -495,7 +495,7 @@ settings_guide_searchable_1: |- }' settings_guide_displayed_1: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings' \ + -X PUT 'http://localhost:7700/indexes/movies/settings' \ -H 'Content-Type: application/json' \ --data-binary '{ "displayedAttributes": [ @@ -507,7 +507,7 @@ settings_guide_displayed_1: |- }' settings_guide_sortable_1: |- curl \ - -X POST 'http://localhost:7700/indexes/books/settings' \ + -X PUT 'http://localhost:7700/indexes/books/settings' \ -H 'Content-Type: application/json' \ --data-binary '{ "sortableAttributes": [ @@ -544,7 +544,7 @@ getting_started_add_meteorites: |- --data-binary @meteorites.json getting_started_update_ranking_rules: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings/ranking-rules' \ + -X PUT 'http://localhost:7700/indexes/movies/settings/ranking-rules' \ -H 'Content-Type: application/json' \ --data-binary '[ "exactness", @@ -558,7 +558,7 @@ getting_started_update_ranking_rules: |- ]' getting_started_update_displayed_attributes: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings/displayed-attributes' \ + -X PUT 'http://localhost:7700/indexes/movies/settings/displayed-attributes' \ -H 'Content-Type: application/json' \ --data-binary '[ "title", @@ -567,17 +567,17 @@ getting_started_update_displayed_attributes: |- ]' getting_started_update_searchable_attributes: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings/searchable-attributes' \ + -X PUT 'http://localhost:7700/indexes/movies/settings/searchable-attributes' \ -H 'Content-Type: application/json' \ --data-binary '["title"]' getting_started_update_stop_words: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings/stop-words' \ + -X PUT 'http://localhost:7700/indexes/movies/settings/stop-words' \ -H 'Content-Type: application/json' \ --data-binary '["the"]' getting_started_synonyms: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings/synonyms' \ + -X PUT 'http://localhost:7700/indexes/movies/settings/synonyms' \ -H 'Content-Type: application/json' \ --data-binary '{ "winnie": ["piglet"], @@ -608,7 +608,7 @@ getting_started_sorting: |- }' getting_started_configure_settings: |- curl \ - -X POST 'http://localhost:7700/indexes/meteorites/settings' \ + -X PUT 'http://localhost:7700/indexes/meteorites/settings' \ -H 'Content-Type: application/json' \ --data-binary '{ "filterableAttributes": [ @@ -626,7 +626,7 @@ getting_started_communicating_with_a_protected_instance: |- -H 'Authorization: Bearer API_KEY' faceted_search_update_settings_1: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings' \ + -X PUT 'http://localhost:7700/indexes/movies/settings' \ -H 'Content-Type: application/json' \ --data-binary '{ "filterableAttributes": [ @@ -686,7 +686,7 @@ authorization_header_1: |- -H 'Authorization: Bearer MASTER_KEY' sorting_guide_update_sortable_attributes_1: |- curl \ - -X POST 'http://localhost:7700/indexes/books/settings/sortable-attributes' \ + -X PUT 'http://localhost:7700/indexes/books/settings/sortable-attributes' \ -H 'Content-Type: application/json' \ --data-binary '[ "author", @@ -694,7 +694,7 @@ sorting_guide_update_sortable_attributes_1: |- ]' sorting_guide_update_ranking_rules_1: |- curl \ - -X POST 'http://localhost:7700/indexes/books/settings/ranking-rules' \ + -X PUT 'http://localhost:7700/indexes/books/settings/ranking-rules' \ -H 'Content-Type: application/json' \ --data-binary '[ "words", @@ -725,7 +725,7 @@ get_sortable_attributes_1: |- -X GET 'http://localhost:7700/indexes/books/settings/sortable-attributes' update_sortable_attributes_1: |- curl \ - -X POST 'http://localhost:7700/indexes/books/settings/sortable-attributes' \ + -X PUT 'http://localhost:7700/indexes/books/settings/sortable-attributes' \ -H 'Content-Type: application/json' \ --data-binary '[ "price", @@ -759,7 +759,7 @@ geosearch_guide_filter_usage_2: |- --data-binary '{ "filter": "_geoRadius(45.472735, 9.184019, 2000) AND type = pizza" }' geosearch_guide_sort_settings_1: |- curl \ - -X POST 'http://localhost:7700/indexes/restaurants/settings/sortable-attributes' \ + -X PUT 'http://localhost:7700/indexes/restaurants/settings/sortable-attributes' \ -H 'Content-type:application/json' \ --data-binary '["_geo"]' geosearch_guide_sort_usage_1: |- @@ -844,7 +844,7 @@ get_typo_tolerance_1: |- -X GET 'http://localhost:7700/indexes/books/settings/typo-tolerance' update_typo_tolerance_1: |- curl \ - -X POST 'http://localhost:7700/indexes/books/settings/typo-tolerance' \ + -X PATCH 'http://localhost:7700/indexes/books/settings/typo-tolerance' \ -H 'Content-Type: application/json' \ --data-binary '{ "minWordSizeForTypos": { @@ -858,17 +858,17 @@ reset_typo_tolerance_1: |- -X DELETE 'http://localhost:7700/indexes/books/settings/typo-tolerance' typo_tolerance_guide_1: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings/typo-tolerance' \ + -X PATCH 'http://localhost:7700/indexes/movies/settings/typo-tolerance' \ -H 'Content-Type: application/json' \ --data-binary '{ "enabled": false }' typo_tolerance_guide_2: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings/typo-tolerance' \ + -X PATCH 'http://localhost:7700/indexes/movies/settings/typo-tolerance' \ -H 'Content-Type: application/json' \ --data-binary '{ "disableOnAttributes": ["title"] }' typo_tolerance_guide_3: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings/typo-tolerance' \ + -X PATCH 'http://localhost:7700/indexes/movies/settings/typo-tolerance' \ -H 'Content-Type: application/json' \ --data-binary '{ "disableOnWords": [ @@ -877,7 +877,7 @@ typo_tolerance_guide_3: |- }' typo_tolerance_guide_4: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings/typo-tolerance' \ + -X PATCH 'http://localhost:7700/indexes/movies/settings/typo-tolerance' \ -H 'Content-Type: application/json' \ --data-binary '{ "minWordSizeForTypos": { @@ -887,7 +887,7 @@ typo_tolerance_guide_4: |- }' settings_guide_typo_tolerance_1: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings/typo-tolerance' \ + -X PATCH 'http://localhost:7700/indexes/movies/settings/typo-tolerance' \ -H 'Content-Type: application/json' \ --data-binary '{ "minWordSizeForTypos": { @@ -953,7 +953,7 @@ updating_guide_add_documents_old: |- -H 'X-Meili-API-Key: API_KEY' getting_started_typo_tolerance: |- curl \ - -X POST 'http://localhost:7700/indexes/movies/settings/typo-tolerance' \ + -X PATCH 'http://localhost:7700/indexes/movies/settings/typo-tolerance' \ -H 'Content-Type: application/json' \ --data-binary '{ "minWordSizeForTypos": { "oneTypo": 4 } diff --git a/reference/api/displayed_attributes.md b/reference/api/displayed_attributes.md index 99f1448be2..c6593acb27 100644 --- a/reference/api/displayed_attributes.md +++ b/reference/api/displayed_attributes.md @@ -38,7 +38,7 @@ List the settings. ## Update displayed attributes - + Update the [displayed attributes](/learn/configuration/settings.md#displayed-attributes) of an index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required. diff --git a/reference/api/distinct_attribute.md b/reference/api/distinct_attribute.md index f321ff31e2..354ca3f7e5 100644 --- a/reference/api/distinct_attribute.md +++ b/reference/api/distinct_attribute.md @@ -30,7 +30,7 @@ Get the [distinct attribute](/learn/configuration/settings.md#distinct-attribute ## Update distinct attribute - + Update the [distinct attribute](/learn/configuration/settings.md#distinct-attribute) field of an index. This will re-index all documents in the index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required. diff --git a/reference/api/filterable_attributes.md b/reference/api/filterable_attributes.md index d91d4ba5bb..de1286dda6 100644 --- a/reference/api/filterable_attributes.md +++ b/reference/api/filterable_attributes.md @@ -34,7 +34,7 @@ List the settings. ## Update filterable attributes - + Update an index's [filterable attributes list](/learn/advanced/filtering_and_faceted_search.md). This will re-index all documents in the index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required. diff --git a/reference/api/ranking_rules.md b/reference/api/ranking_rules.md index ae25f32d4d..681e36e456 100644 --- a/reference/api/ranking_rules.md +++ b/reference/api/ranking_rules.md @@ -44,7 +44,7 @@ List the settings. ## Update ranking rules - + Update the [ranking rules](/learn/core_concepts/relevancy.md#ranking-rules) of an index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required. diff --git a/reference/api/searchable_attributes.md b/reference/api/searchable_attributes.md index 47e82d0d02..710fa0eff2 100644 --- a/reference/api/searchable_attributes.md +++ b/reference/api/searchable_attributes.md @@ -37,7 +37,7 @@ List the settings. ## Update searchable attributes - + Update the [searchable attributes](/learn/configuration/displayed_searchable_attributes.md#searchable-fields) of an index. This will re-index all documents in the index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required. diff --git a/reference/api/settings.md b/reference/api/settings.md index 2d22e9b45b..e687279fb1 100644 --- a/reference/api/settings.md +++ b/reference/api/settings.md @@ -103,7 +103,7 @@ List the settings. ## Update settings - + Update the settings of an index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required. diff --git a/reference/api/sortable_attributes.md b/reference/api/sortable_attributes.md index 3c36dc3ddc..65325ffcf4 100644 --- a/reference/api/sortable_attributes.md +++ b/reference/api/sortable_attributes.md @@ -33,7 +33,7 @@ List the settings. ## Update sortable attributes - + Update an index's sortable attributes list. This will re-index all documents in the index. This will re-index all documents in the index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required. diff --git a/reference/api/stop_words.md b/reference/api/stop_words.md index d5bcd1b5f2..2d3cc0f6b6 100644 --- a/reference/api/stop_words.md +++ b/reference/api/stop_words.md @@ -38,7 +38,7 @@ Get the stop-words list of an index. The index [`uid`](/learn/core_concepts/inde ## Update stop-words - + Update the list of stop-words of an index. This will re-index all documents in the index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required. diff --git a/reference/api/synonyms.md b/reference/api/synonyms.md index f5cfb91136..e1d555a0e7 100644 --- a/reference/api/synonyms.md +++ b/reference/api/synonyms.md @@ -42,7 +42,7 @@ Get the list of [synonyms](/learn/configuration/synonyms.md) of an index. The in ## Update synonyms - + Update the list of [synonyms](/learn/configuration/synonyms.md) of an index. Synonyms are [normalized](/learn/configuration/synonyms.md#normalization). The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required. diff --git a/reference/api/typo_tolerance.md b/reference/api/typo_tolerance.md index 4c686f6f84..79043b5188 100644 --- a/reference/api/typo_tolerance.md +++ b/reference/api/typo_tolerance.md @@ -61,7 +61,7 @@ An array of attributes for which the typo tolerance feature is disabled. ## Update typo tolerance - + Partially update the typo tolerance settings for an index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required. From 066999129fc871f5fbf4b3bff8aaaa5f33ed04ac Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Thu, 16 Jun 2022 11:23:10 +0400 Subject: [PATCH 006/150] v0.28: Update Docker and Source tags --- learn/getting_started/quick_start.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/learn/getting_started/quick_start.md b/learn/getting_started/quick_start.md index 5d5d0ced71..782b4dfc64 100644 --- a/learn/getting_started/quick_start.md +++ b/learn/getting_started/quick_start.md @@ -51,14 +51,14 @@ These commands launch the **latest stable release** of Meilisearch. ```bash # Fetch the latest version of Meilisearch image from DockerHub -docker pull getmeili/meilisearch:v0.27.2 +docker pull getmeili/meilisearch:v0.28 # Launch Meilisearch in development mode with a master key docker run -it --rm \ -p 7700:7700 \ -e MEILI_MASTER_KEY='MASTER_KEY'\ -v $(pwd)/meili_data:/meili_data \ - getmeili/meilisearch:v0.27.1 \ + getmeili/meilisearch:v0.28 \ meilisearch --env="development" ``` @@ -104,7 +104,7 @@ Choose the release you want to use. You can find the full list [here](https://gi In the cloned repository, run the following command replacing `vX.Y.Z` with the tag you selected: ```bash -git checkout v0.25.2 +git checkout v0.28 ``` Finally, update the rust toolchain, compile the project, and execute the binary. From eaede9754c87f6acc6731c7ea7c66fe733212e67 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Thu, 16 Jun 2022 12:10:22 +0400 Subject: [PATCH 007/150] v0.28: /search name changes --- .code-samples.meilisearch.yaml | 8 +- .vuepress/public/sample-template.yaml | 4 +- .../advanced/filtering_and_faceted_search.md | 27 +++---- learn/configuration/distinct.md | 3 +- learn/getting_started/algolia_migration.md | 2 +- .../getting_started/filtering_and_sorting.md | 12 +-- learn/getting_started/quick_start.md | 3 +- reference/api/search.md | 76 +++++++------------ 8 files changed, 51 insertions(+), 84 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 047cb60b9f..b9389d79d7 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -432,13 +432,13 @@ search_parameter_guide_highlight_tag_1: |- "highlightPreTag": "", "highlightPostTag": "" }' -search_parameter_guide_matches_1: |- +search_parameter_guide_show_matches_position_1: |- curl \ -X POST 'http://localhost:7700/indexes/movies/search' \ -H 'Content-Type: application/json' \ --data-binary '{ "q": "winter feast", - "matches": true + "showMatchesPosition": true }' settings_guide_synonyms_1: |- curl \ @@ -648,13 +648,13 @@ faceted_search_filter_1: |- "director = \"Jordan Peele\"" ] }' -faceted_search_facets_distribution_1: |- +faceted_search_facets_1: |- curl \ -X POST 'http://localhost:7700/indexes/movies/search' \ -H 'Content-Type: application/json' \ --data-binary '{ "q": "Batman", - "facetsDistribution": ["genres"] + "facets": ["genres"] }' faceted_search_walkthrough_filter_1: |- curl \ diff --git a/.vuepress/public/sample-template.yaml b/.vuepress/public/sample-template.yaml index 8b52eec657..68b240e516 100644 --- a/.vuepress/public/sample-template.yaml +++ b/.vuepress/public/sample-template.yaml @@ -65,7 +65,7 @@ search_parameter_guide_limit_1: |- search_parameter_guide_retrieve_1: |- search_parameter_guide_crop_1: |- search_parameter_guide_highlight_1: |- -search_parameter_guide_matches_1: |- +search_parameter_guide_show_matches_position_1: |- settings_guide_synonyms_1: |- settings_guide_stop_words_1: |- settings_guide_ranking_rules_1: |- @@ -90,7 +90,7 @@ getting_started_sorting: |- getting_started_filtering: |- faceted_search_update_settings_1: |- faceted_search_filter_1: |- -faceted_search_facets_distribution_1: |- +faceted_search_facets_1: |- faceted_search_walkthrough_filter_1: |- add_movies_json_1: |- post_dump_1: |- diff --git a/learn/advanced/filtering_and_faceted_search.md b/learn/advanced/filtering_and_faceted_search.md index 5c7e83c362..cb28212316 100644 --- a/learn/advanced/filtering_and_faceted_search.md +++ b/learn/advanced/filtering_and_faceted_search.md @@ -278,13 +278,13 @@ You can then use this filter to search for `thriller`: ### Facets distribution -When creating a faceted search interface it is often useful to have a count of how many results belong to each facet. This can be done by using the [`facetsDistribution` search parameter](/reference/api/search.md#facets-distribution) in combination with `filter` when searching. +When creating a faceted search interface it is often useful to have a count of how many results belong to each facet. This can be done by using the [`facets` search parameter](/reference/api/search.md#facets) in combination with `filter` when searching. ::: note -Meilisearch does not differentiate between facets and filters. This means that, despite its name, `facetsDistribution` can be used with any attributes added to `filterableAttributes`. +Meilisearch does not differentiate between facets and filters. This means that, despite its name, `facets` can be used with any attributes added to `filterableAttributes`. ::: -Using `facetsDistribution` will add an extra field to the returned search results containing the number of matching documents distributed among all the values of a given facet. +Using `facets` will add an extra field to the returned search results containing the number of matching documents distributed among all the values of a given facet. In the example below, [IMDb](https://www.imdb.com) displays the facet count in parentheses next to each faceted category. This UI gives users a visual clue of the range of results available for each facet. @@ -292,16 +292,15 @@ In the example below, [IMDb](https://www.imdb.com) displays the facet count in p #### Using facet distribution -[`facetsDistribution` is a search parameter](/reference/api/search.md#facets-distribution) and as such must be added to a search request. It expects an array of strings. Each string is an attribute present in the `filterableAttributes` list. +[`facets` is a search parameter](/reference/api/search.md#facets) and as such must be added to a search request. It expects an array of strings. Each string is an attribute present in the `filterableAttributes` list. -Using the `facetsDistribution` search parameter adds two new keys to the returned object: `facetsDistribution` and `exhaustiveFacetsCount`. +Using the `facets` search parameter adds `facetDistribution` to the returned object. -`facetsDistribution` contains an object for every given facet. For each of these facets, there is another object containing all the different values and the count of matching documents. Note that zero values will not be returned: if there are no `romance` movies matching the query, `romance` is not displayed. +`facetDistribution` contains an object for every given facet. For each of these facets, there is another object containing all the different values and the count of matching documents. Note that zero values will not be returned: if there are no `romance` movies matching the query, `romance` is not displayed. ```json { - "exhaustiveFacetsCount": false, - "facetsDistribution" : { + "facetDistribution" : { "genres" : { "horror": 50, "comedy": 34 @@ -310,19 +309,13 @@ Using the `facetsDistribution` search parameter adds two new keys to the returne } ``` -`exhaustiveFacetsCount` is a boolean value that informs the user whether the facet count is exact or just an approximation. For performance reasons, Meilisearch chooses to use approximate facet count values when there are too many documents across several different fields. - -::: warning -`exhaustiveFacetsCount` is not currently implemented in and will always return `false`. -::: - ##### Example You can write a search query that gives you the distribution of `batman` movies per genre: - + -This query would return not only the matching movies, but also the `facetsDistribution` key containing all relevant data: +This query would return not only the matching movies, but also the `facetDistribution` key containing all relevant data: ```json { @@ -330,7 +323,7 @@ This query would return not only the matching movies, but also the `facetsDistri … ], … - "facetsDistribution": { + "facetDistribution": { "genres": { "action": 273, "animation": 118, diff --git a/learn/configuration/distinct.md b/learn/configuration/distinct.md index 02274a3248..fe6b446919 100644 --- a/learn/configuration/distinct.md +++ b/learn/configuration/distinct.md @@ -65,8 +65,7 @@ After setting the distinct attribute as shown above, querying for `lee leather j ], "offset": 0, "limit": 20, - "nbHits": 1, - "exhaustiveNbHits": false, + "estimatedTotalHits": 1, "processingTimeMs": 0, "query": "lee leather jacket" } diff --git a/learn/getting_started/algolia_migration.md b/learn/getting_started/algolia_migration.md index e08bcca0d0..96e20a3922 100644 --- a/learn/getting_started/algolia_migration.md +++ b/learn/getting_started/algolia_migration.md @@ -181,7 +181,7 @@ The below table compares Algolia's **API parameters** with the equivalent Meilis | `query` | `q` | | `attributesToRetrieve` | `attributesToRetrieve` | | `filters` | `filter` | -| `facets` | `facetsDistribution` | +| `facets` | `facetDistribution` | | `attributesToHighlight` | `attributesToHighlight` | | `offset` | `offset` | | `length` | `limit` | diff --git a/learn/getting_started/filtering_and_sorting.md b/learn/getting_started/filtering_and_sorting.md index 7e5c05c9ad..0222a597ef 100644 --- a/learn/getting_started/filtering_and_sorting.md +++ b/learn/getting_started/filtering_and_sorting.md @@ -41,8 +41,7 @@ Let's say you only want to view meteorites that weigh less than 200g: }, … ], - "nbHits": 114, - "exhaustiveNbHits": false, + "estimatedTotalHits": 114, "query": "", "limit": 20, "offset": 0, @@ -77,8 +76,7 @@ Let's sort the meteorites in the previous example based on mass: }, … ], - "nbHits": 114, - "exhaustiveNbHits": false, + "estimatedTotalHits": 114, "query": "", "limit": 20, "offset": 0, @@ -132,8 +130,7 @@ Let's say you want to find out which meteorites crashed within a 210km radius of }, … ], - "nbHits": 7, - "exhaustiveNbHits": false, + "estimatedTotalHits": 7, "query": "", "limit": 20, "offset": 0, @@ -180,8 +177,7 @@ The following command sorts meteorites by how close they were to the Taj Mahal: }, … ] - "nbHits": 1000, - "exhaustiveNbHits": false, + "estimatedTotalHits": 1000, "query": "", "limit": 20, "offset": 0, diff --git a/learn/getting_started/quick_start.md b/learn/getting_started/quick_start.md index 5d5d0ced71..029ee10342 100644 --- a/learn/getting_started/quick_start.md +++ b/learn/getting_started/quick_start.md @@ -252,8 +252,7 @@ In the above code sample, the parameter `q` represents the search query. The doc }, … ], - "nbHits": 66, - "exhaustiveNbHits": false, + "estimatedTotalHits": 66, "query": "botman", "limit": 20, "offset": 0, diff --git a/reference/api/search.md b/reference/api/search.md index 491fc9aa8b..a2b8beaea1 100644 --- a/reference/api/search.md +++ b/reference/api/search.md @@ -33,7 +33,7 @@ This is the preferred route to perform search when an API key is required, as it | **[offset](#offset)** | Number of documents to skip | `0` | | **[limit](#limit)** | Maximum number of documents returned | `20` | | **[filter](#filter)** | Filter queries by an attribute's value | `null` | -| **[facetsDistribution](#facets-distribution)** | Display the count of matches per facet | `null` | +| **[facets](#facets)** | Display the count of matches per facet | `null` | | **[attributesToRetrieve](#attributes-to-retrieve)** | Attributes to display in the returned documents | `["*"]` | | **[attributesToCrop](#attributes-to-crop)** | Attributes whose values have to be cropped | `null` | | **[cropLength](#crop-length)** | Maximum length of cropped value in words | `10` | @@ -41,7 +41,7 @@ This is the preferred route to perform search when an API key is required, as it | **[attributesToHighlight](#attributes-to-highlight)** | Highlight matching terms contained in an attribute | `null` | | **[highlightPreTag](#highlight-tags)** | String inserted at the start of a highlighted term | `""` | | **[highlightPostTag](#highlight-tags)** | String inserted at the end of a highlighted term | `""` | -| **[matches](#matches)** | Return matching terms location | `false` | +| **[showMatchesPosition](#show-matches-position)** | Return matching terms location | `false` | | **[sort](#sort)** | Sort search results by an attribute's value | `null` | [Learn more about how to use each search parameter](#search-parameters). @@ -63,10 +63,8 @@ Query terms enclosed in double quotes are treated as [phrase searches](#query-q) | **hits** | Results of the query | `array of objects` | | **offset** | Number of documents skipped | `number` | | **limit** | Number of documents to take | `number` | -| **nbHits** | Total number of matches | `number` | -| **exhaustiveNbHits** | Whether `nbHits` is exhaustive | `boolean` | -| **facetsDistribution** | **[Distribution of the given facets](#facets-distribution)** | `object` -| **exhaustiveFacetsCount** | Whether `facetsDistribution` is exhaustive | `boolean` +| **estimatedTotalHits** | Total number of matches | `number` | +| **facets** | **[Distribution of the given facets](#facets)** | `object` | **processingTimeMs** | Processing time of the query | `number` | | **query** | Query originating the response | `string` | @@ -97,8 +95,7 @@ Query terms enclosed in double quotes are treated as [phrase searches](#query-q) ], "offset": 0, "limit": 20, - "nbHits": 976, - "exhaustiveNbHits": false, + "estimatedTotalHits": 976, "processingTimeMs": 35, "query": "american " } @@ -124,7 +121,7 @@ This route should only be used when no API key is required. If an API key is req | **[offset](#offset)** | Number of documents to skip | `0` | | **[limit](#limit)** | Maximum number of documents returned | `20` | | **[filter](#filter)** | Filter queries by an attribute's value | `null` | -| **[facetsDistribution](#facets-distribution)** | Display the count of matches per facet | `null` | +| **[facets](#facets)** | Display the count of matches per facet | `null` | | **[attributesToRetrieve](#attributes-to-retrieve)** | Attributes to display in the returned documents | `["*"]` | | **[attributesToCrop](#attributes-to-crop)** | Attributes whose values have to be cropped | `null` | | **[cropLength](#crop-length)** | Maximum length of cropped value in words | `10` | @@ -132,7 +129,7 @@ This route should only be used when no API key is required. If an API key is req | **[attributesToHighlight](#attributes-to-highlight)** | Highlight matching terms contained in an attribute | `null` | | **[highlightPreTag](#highlight-tags)** | String inserted at the start of a highlighted term | `""` | | **[highlightPostTag](#highlight-tags)** | String inserted at the end of a highlighted term | `""` | -| **[matches](#matches)** | Return matching terms location | `false` | +| **[showMatchesPosition](#show-matches-position)** | Return matching terms location | `false` | | **[sort](#sort)** | Sort search results by an attribute's value | `null` | [Learn more about how to use each search parameter](#search-parameters). @@ -152,10 +149,8 @@ Query terms enclosed in double quotes are treated as [phrase searches](#query-q) | **hits** | Results of the query | `array of objects` | | **offset** | Number of documents skipped | `number` | | **limit** | Number of documents to take | `number` | -| **nbHits** | Total number of matches | `number` | -| **exhaustiveNbHits** | Whether `nbHits` is exhaustive | `boolean` | -| **facetsDistribution** | **[Distribution of the given facets](#facets-distribution)** | `object` -| **exhaustiveFacetsCount** | Whether `facetsDistribution` is exhaustive | `boolean` +| **estimatedTotalHits** | Total number of matches | `number` | +| **facets** | **[Distribution of the given facets](#facets)** | `object` | **processingTimeMs** | Processing time of the query | `number` | | **query** | Query originating the response | `string` | @@ -186,8 +181,7 @@ Query terms enclosed in double quotes are treated as [phrase searches](#query-q) ], "offset": 0, "limit": 20, - "nbHits": 976, - "exhaustiveNbHits": false, + "estimatedTotalHits": 976, "processingTimeMs": 35, "query": "american " } @@ -211,7 +205,7 @@ This is not necessary when using the `POST` route or one of our [SDKs](/learn/wh | **[offset](#offset)** | Number of documents to skip | `0` | | **[limit](#limit)** | Maximum number of documents returned | `20` | | **[filter](#filter)** | Filter queries by an attribute's value | `null` | -| **[facetsDistribution](#facets-distribution)** | Display the count of matches per facet | `null` | +| **[facets](#facets)** | Display the count of matches per facet | `null` | | **[attributesToRetrieve](#attributes-to-retrieve)** | Attributes to display in the returned documents | `["*"]` | | **[attributesToCrop](#attributes-to-crop)** | Attributes whose values have to be cropped | `null` | | **[cropLength](#crop-length)** | Maximum length of cropped value in words | `10` | @@ -219,7 +213,7 @@ This is not necessary when using the `POST` route or one of our [SDKs](/learn/wh | **[attributesToHighlight](#attributes-to-highlight)** | Highlight matching terms contained in an attribute | `null` | | **[highlightPreTag](#highlight-tags)** | String inserted at the start of a highlighted term | `""` | | **[highlightPostTag](#highlight-tags)** | String inserted at the end of a highlighted term | `""` | -| **[matches](#matches)** | Return matching terms location | `false` | +| **[showMatchesPosition](#show-matches-position)** | Return matching terms location | `false` | | **[sort](#sort)** | Sort search results by an attribute's value | `null` | ### Query (q) @@ -366,53 +360,39 @@ _geoRadius(lat, lng, distance_in_meters) -### Facets distribution +### Facets -**Parameter**: `facetsDistribution` +**Parameter**: `facets` **Expected value**: an array of `attribute`s or `["*"]` **Default value**: `null` -Returns the number of documents matching the current search query for each given facet. +Returns the number of documents matching the current search query for each given facet. When `facets` is set, the search results object contains the `facetDistribution` field that shows the number of remaining candidates for each specified facet. This parameter can take two values: -- An array of attributes: `facetsDistribution=["attributeA", "attributeB", …]` +- An array of attributes: `facets=["attributeA", "attributeB", …]` - An asterisk—this will return a count for all facets present in `filterableAttributes` ::: note -If an attribute used on `facetsDistribution` has not been added to the `filterableAttributes` list, it will be ignored. +If an attribute used on `facets` has not been added to the `filterableAttributes` list, it will be ignored. ::: -#### Returned fields - -When `facetsDistribution` is set, the search results object contains **two additional fields**: - -- `facetsDistribution`: The number of remaining candidates for each specified facet -- `exhaustiveFacetsCount`: A `true` or `false` value indicating whether the count is exact (`true`) or approximate (`false`) - -`exhaustiveFacetsCount` is `false` when the search matches contain too many different values for the given `facetName`s. In this case, Meilisearch stops the distribution count to prevent slowing down the request. - -::: warning -`exhaustiveFacetsCount` is not currently implemented and will always return `false`. -::: - -[Learn more about facet distribution in the filtering and faceted search guide.](/learn/advanced/filtering_and_faceted_search.md#facets-distribution) +[Learn more about facet distribution in the filtering and faceted search guide.](/learn/advanced/filtering_and_faceted_search.html#using-facets) #### Example Given a movie database, suppose that you want to know the number of `Batman` movies per genre: - + You would get the following response: ```json { … - "nbHits": 1684, + "estimatedTotalHits": 1684, "query": "Batman", - "exhaustiveFacetsCount": false, - "facetsDistribution": { + "facetDistribution": { "genres": { "action": 273, "animation": 118, @@ -620,13 +600,13 @@ You can find the highlighted query terms inside the `_formatted` property: Though it is not necessary to use `highlightPreTag` and `highlightPostTag` in conjunction, be careful to ensure tags are correctly matched. In the above example, not setting `highlightPostTag` would result in malformed HTML: `Winter Feast`. ::: -### Matches +### Show matches position -**Parameter**: `matches` +**Parameter**: `showMatchesPosition` **Expected value**: `true` or `false` **Default value**: `false` -Adds a `_matchesInfo` object to the search response that contains the location of each occurrence of queried terms across all fields. This is useful when you need more control than offered by our [built-in highlighting](#attributes-to-highlight). `matches` only works for strings, numbers, and arrays of strings and numbers. +Adds a `_matchesPosition` object to the search response that contains the location of each occurrence of queried terms across all fields. This is useful when you need more control than offered by our [built-in highlighting](#attributes-to-highlight). `showMatchesPosition` only works for strings, numbers, and arrays of strings and numbers. The beginning of a matching term within a field is indicated by `start`, and its length by `length`. @@ -636,11 +616,11 @@ The beginning of a matching term within a field is indicated by `start`, and its #### Example -If you set `matches` to `true` and search for `winter feast`: +If you set `showMatchesPosition` to `true` and search for `winter feast`: - + -You would get the following response with **information about the matches in the `_matchesInfo` object**. Note how Meilisearch searches for `winter` and `feast` separately because of the whitespace: +You would get the following response with **information about the matches in the `_matchesPosition` object**. Note how Meilisearch searches for `winter` and `feast` separately because of the whitespace: ```json { @@ -649,7 +629,7 @@ You would get the following response with **information about the matches in the "poster": "https://image.tmdb.org/t/p/w500/rV77WxY35LuYLOuQvBeD1nyWMuI.jpg", "overview": "The Winter Feast is Po's favorite holiday. Every year he and his father hang decorations, cook together, and serve noodle soup to the villagers. But this year Shifu informs Po that as Dragon Warrior, it is his duty to host the formal Winter Feast at the Jade Palace. Po is caught between his obligations as the Dragon Warrior and his family traditions: between Shifu and Mr. Ping.", "release_date": 1290729600, - "_matchesInfo": { + "_matchesPosition": { "overview": [ { "start": 4, From 670796461a6715db42c6ea729f06136b39600569 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Thu, 16 Jun 2022 12:12:40 +0400 Subject: [PATCH 008/150] update link --- reference/api/search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/search.md b/reference/api/search.md index a2b8beaea1..24df0491b8 100644 --- a/reference/api/search.md +++ b/reference/api/search.md @@ -377,7 +377,7 @@ This parameter can take two values: If an attribute used on `facets` has not been added to the `filterableAttributes` list, it will be ignored. ::: -[Learn more about facet distribution in the filtering and faceted search guide.](/learn/advanced/filtering_and_faceted_search.html#using-facets) +[Learn more about facet distribution in the filtering and faceted search guide.](/learn/advanced/filtering_and_faceted_search.md#using-facets) #### Example From 709245a85e3a574f57f37880b06b08f72df9d187 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 16 Jun 2022 11:42:46 +0200 Subject: [PATCH 009/150] _geo now accepts both numeric and string values for lat, lng --- learn/advanced/geosearch.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/learn/advanced/geosearch.md b/learn/advanced/geosearch.md index 20c3578331..c43c23a936 100644 --- a/learn/advanced/geosearch.md +++ b/learn/advanced/geosearch.md @@ -8,14 +8,14 @@ In order to start filtering and sorting documents based on their geographic loca `_geo` is a reserved field. If you include it in your documents, Meilisearch expects its value to conform to a specific format. -When using JSON and NDJSON, `_geo` must contain an object with two keys: `lat` and `lng`. Both must contain a floating point number indicating, respectively, latitude and longitude: +When using JSON and NDJSON, `_geo` must contain an object with two keys: `lat` and `lng`. Both fields must contain either a floating point number or a string indicating, respectively, latitude and longitude: ```json { … "_geo": { "lat": 0.0, - "lng": 0.0 + "lng": "0.0" } } ``` From 7e91bcdea3058917e278a7ee53599e3a7a5540fd Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Thu, 16 Jun 2022 14:40:19 +0400 Subject: [PATCH 010/150] update based on review --- learn/getting_started/quick_start.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/learn/getting_started/quick_start.md b/learn/getting_started/quick_start.md index 782b4dfc64..8ecaa1a595 100644 --- a/learn/getting_started/quick_start.md +++ b/learn/getting_started/quick_start.md @@ -51,14 +51,14 @@ These commands launch the **latest stable release** of Meilisearch. ```bash # Fetch the latest version of Meilisearch image from DockerHub -docker pull getmeili/meilisearch:v0.28 +docker pull getmeili/meilisearch:v0.28.0 # Launch Meilisearch in development mode with a master key docker run -it --rm \ -p 7700:7700 \ -e MEILI_MASTER_KEY='MASTER_KEY'\ -v $(pwd)/meili_data:/meili_data \ - getmeili/meilisearch:v0.28 \ + getmeili/meilisearch:v0.28.0 \ meilisearch --env="development" ``` @@ -104,7 +104,7 @@ Choose the release you want to use. You can find the full list [here](https://gi In the cloned repository, run the following command replacing `vX.Y.Z` with the tag you selected: ```bash -git checkout v0.28 +git checkout v0.28.0 ``` Finally, update the rust toolchain, compile the project, and execute the binary. From 09af7e294841a9f9cb16b5bc816d9841b89345a2 Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Thu, 16 Jun 2022 13:29:13 +0200 Subject: [PATCH 011/150] Delete get task by index and get tasks by index --- reference/api/tasks.md | 80 ------------------------------------------ 1 file changed, 80 deletions(-) diff --git a/reference/api/tasks.md b/reference/api/tasks.md index 71a550b649..1aec038a99 100644 --- a/reference/api/tasks.md +++ b/reference/api/tasks.md @@ -89,83 +89,3 @@ Here is an example response representing [a processed task](/learn/advanced/asyn "finishedAt": "2021-08-10T14:29:19.000000Z" } ``` - -## Get all tasks by index - - - -List all [tasks](/learn/advanced/asynchronous_operations.md) for a given [index](/learn/core_concepts/indexes.md). The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required. - -### Example - - - -#### Response: `200 Ok` - -```json -{ - "results": [ - { - "uid": 1, - "indexUid": "movies", - "status": "enqueued", - "type": "documentAddition", - "duration": null, - "enqueuedAt": "2021-08-12T10:00:00.000000Z", - "startedAt": null, - "finishedAt": null - }, - { - "uid": 0, - "indexUid": "movies", - "status": "succeeded", - "type": "documentAddition", - "details": { - "receivedDocuments": 100, - "indexedDocuments": 100 - }, - "duration": "PT16S", - "enqueuedAt": "2021-08-11T09:25:53.000000Z", - "startedAt": "2021-08-11T10:03:00.000000Z", - "finishedAt": "2021-08-11T10:03:16.000000Z" - } - ] -} -``` - -## Get task by index - - - -Get a single [task](/learn/advanced/asynchronous_operations.md) in a given [index](/learn/core_concepts/indexes.md). Both the index [`uid`](/learn/core_concepts/indexes.md#index-uid) and task [`uid`](/learn/advanced/asynchronous_operations.md#response) are required. - -### Example - - - -#### Response: `200 Ok` - -Here is an example response representing [a processed task](/learn/advanced/asynchronous_operations.md#understanding-tasks). - -```json -{ - "uid": 1, - "indexUid": "movies", - "status": "succeeded", - "type": "settingsUpdate", - "details": { - "rankingRules": [ - "typo", - "ranking:desc", - "words", - "proximity", - "attribute", - "exactness" - ] - }, - "duration": "PT1S", - "enqueuedAt": "2021-08-10T14:29:17.000000Z", - "startedAt": "2021-08-10T14:29:18.000000Z", - "finishedAt": "2021-08-10T14:29:19.000000Z" -} -``` From 934dfd61800d4151fcbcaa21981d6e462bdd13a0 Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Thu, 16 Jun 2022 13:30:25 +0200 Subject: [PATCH 012/150] Change name of 'get all tasks' endpoint to 'get tasks' --- reference/api/tasks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/tasks.md b/reference/api/tasks.md index 1aec038a99..e3cc43c9f5 100644 --- a/reference/api/tasks.md +++ b/reference/api/tasks.md @@ -6,7 +6,7 @@ The `/tasks` route gives information about the progress of [asynchronous operati The task `uid` is incremented **globally.** ::: -## Get all tasks +## Get tasks From 936ebb446fdd693937a84cec27d4f6f81d35bc17 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 16 Jun 2022 13:41:24 +0200 Subject: [PATCH 013/150] update GET /documents response object --- reference/api/documents.md | 41 +++++++++++++++++++++++--------------- 1 file changed, 25 insertions(+), 16 deletions(-) diff --git a/reference/api/documents.md b/reference/api/documents.md index a7123d51b5..bd242be39a 100644 --- a/reference/api/documents.md +++ b/reference/api/documents.md @@ -53,24 +53,33 @@ Documents are ordered by Meilisearch depending on the hash of their id. #### Response: `200 Ok` ```json -[ - { - "id": 25684, - "release_date": "1993-01-01", - "poster": "https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg", - "title": "American Ninja 5", - "overview": "When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja." - }, - { - "id": 468219, - "title": "Dead in a Week (Or Your Money Back)", - "release_date": "2018-09-12", - "poster": "https://image.tmdb.org/t/p/w1280/f4ANVEuEaGy2oP5M0Y2P1dwxUNn.jpg", - "overview": "William has failed to kill himself so many times that he outsources his suicide to aging assassin Leslie. But with the contract signed and death assured within a week (or his money back), William suddenly discovers reasons to live... However Leslie is under pressure from his boss to make sure the contract is completed." - } -] +{ + "results": [ + { + "id": 25684, + "release_date": "1993-01-01", + "poster": "https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg", + "title": "American Ninja 5", + "overview": "When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja." + }, + { + "id": 468219, + "title": "Dead in a Week (Or Your Money Back)", + "release_date": "2018-09-12", + "poster": "https://image.tmdb.org/t/p/w1280/f4ANVEuEaGy2oP5M0Y2P1dwxUNn.jpg", + "overview": "William has failed to kill himself so many times that he outsources his suicide to aging assassin Leslie. But with the contract signed and death assured within a week (or his money back), William suddenly discovers reasons to live... However Leslie is under pressure from his boss to make sure the contract is completed." + } + ], + "offset": 0, + "limit": 2, + "total": 2054 +} ``` +::: note +The response's `total` value response indicates the total number of documents in the queried index. +::: + ## Add or replace documents From ed24d0f50b89275dc326d58121656e0d44238574 Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Thu, 16 Jun 2022 13:43:06 +0200 Subject: [PATCH 014/150] Change name of 'get task' endpoint to 'get one task' --- reference/api/tasks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/tasks.md b/reference/api/tasks.md index e3cc43c9f5..b6071ea135 100644 --- a/reference/api/tasks.md +++ b/reference/api/tasks.md @@ -53,7 +53,7 @@ List all tasks globally, regardless of index. The `task` objects are contained i Tasks are displayed in descending order by `uid`. This means that **the most recently created `task` objects appear first**. ::: -## Get task +## Get one task From a22ef1f37718c8cbe95fc71e4623219d6f3cb239 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 16 Jun 2022 13:45:32 +0200 Subject: [PATCH 015/150] rename /documents `attributesToRetrieve` to `fields` --- .vuepress/public/postman/meilisearch-collection.json | 2 +- reference/api/documents.md | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.vuepress/public/postman/meilisearch-collection.json b/.vuepress/public/postman/meilisearch-collection.json index 5af874b190..08ae02eb1e 100644 --- a/.vuepress/public/postman/meilisearch-collection.json +++ b/.vuepress/public/postman/meilisearch-collection.json @@ -55,7 +55,7 @@ "disabled": true }, { - "key": "attributesToRetrieve", + "key": "fields", "value": "*", "disabled": true } diff --git a/reference/api/documents.md b/reference/api/documents.md index bd242be39a..0aae4cdb12 100644 --- a/reference/api/documents.md +++ b/reference/api/documents.md @@ -40,11 +40,11 @@ Documents are ordered by Meilisearch depending on the hash of their id. #### Query parameters -| Query Parameter | Description | Default Value | -| ------------------------ | --------------------------- | :-----------: | -| **offset** | number of documents to skip | 0 | -| **limit** | number of documents to take | 20 | -| **attributesToRetrieve** | document attributes to show | \* | +| Query Parameter | Description | Default Value | +| ------------------------ | ------------------------------ | :-----------: | +| **offset** | number of documents to skip | 0 | +| **limit** | number of documents to display | 20 | +| **fields** | document attributes to show | \* | ### Example @@ -72,7 +72,7 @@ Documents are ordered by Meilisearch depending on the hash of their id. ], "offset": 0, "limit": 2, - "total": 2054 + "total": 50134 } ``` From 578f9f3562e28a2589abd8f77ac2121f46ced2da Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Thu, 16 Jun 2022 16:51:16 +0400 Subject: [PATCH 016/150] v0.28: API key updates --- .code-samples.meilisearch.yaml | 14 +++--------- learn/security/master_api_keys.md | 18 +++++++++------ reference/api/keys.md | 38 +++++++++++++++++++++++-------- 3 files changed, 43 insertions(+), 27 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 047cb60b9f..2372947445 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -116,16 +116,8 @@ update_a_key_1: |- -H 'Authorization: Bearer MASTER_KEY' \ -H 'Content-Type: application/json' \ --data-binary '{ - "description": "Manage documents: Products/Reviews API key", - "actions": [ - "documents.add", - "documents.delete" - ], - "indexes": [ - "products", - "reviews" - ], - "expiresAt": "2042-04-02T00:42:42Z" + "name": "Products/Reviews API key", + "description": "Manage documents: Products/Reviews API key" }' delete_a_key_1: |- curl \ @@ -786,7 +778,7 @@ security_guide_update_key_1: |- -X PATCH 'http://localhost:7700/keys/d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4' \ -H 'Authorization: Bearer MASTER_KEY' \ -H 'Content-Type: application/json' \ - --data-binary '{ "indexes": ["doctors"] }' + --data-binary '{ "name": "Default Search API Key" }' security_guide_create_key_1: |- curl \ -X POST 'http://localhost:7700/keys' \ diff --git a/learn/security/master_api_keys.md b/learn/security/master_api_keys.md index cff165cde6..cec2191fd7 100644 --- a/learn/security/master_api_keys.md +++ b/learn/security/master_api_keys.md @@ -82,15 +82,19 @@ Exposing your master key can give malicious users complete control over your Mei Meilisearch gives you fine-grained control over which users can access which indexes, endpoints, and routes. When protecting your instance with a master key, you can ensure only authorized users can carry out sensitive tasks such as adding documents or altering index settings. -The master key is the only key with access to the [`/keys` route](/reference/api/keys.md). This route allows you to [create](#creating-an-api-key), [update](#updating-an-api-key), [list](#listing-api-keys), and [delete](#deleting-an-api-key) API keys. +You can access to the [`/keys` route](/reference/api/keys.md) with the master key or an API key with containing `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. This route allows you to [create](#creating-an-api-key), [update](#updating-an-api-key), [list](#listing-api-keys), and [delete](#deleting-an-api-key) API keys. + +::: note +If you change your master key, the `key` field is re-generated. +::: Though the default API keys are usually enough to manage the security needs of most applications, this might not be the case when dealing with privacy-sensitive data. In these situations, the fine-grained control offered by the `/keys` endpoint allows you to clearly decide who can access what information and for how long. ### Updating an API key -You can freely update an API key at any time, even after it expires. This includes editing the indexes, endpoints, and routes it can access, as well as its description and expiry date. +You can freely update the `name` and `description` of an API key at any time, even after it expires. -We can update the `Default Search API Key` so regular users cannot perform search operations in our `patient_medical_records` index: +We can update the `Default Search API Key` to add a description: @@ -110,13 +114,13 @@ We can update the `Default Search API Key` so regular users cannot perform searc } ``` -To update an API key, you must use the [update API key endpoint](/reference/api/keys.md#update-a-key) which can only be accessed with the master key. +To update an API key, you must use the [update API key endpoint](/reference/api/keys.md#update-a-key), which can only be accessed with the master key or an API key containing the `keys.update` action. -Meilisearch supports partial updates with the `PATCH` route. This means your payload only needs to contain the data you want to update—in this case, `indexes`. +Meilisearch supports partial updates with the `PATCH` route. This means your payload only needs to contain the data you want to update—in this case, `description`. ### Creating an API key -You can create API keys by using the [create key endpoint](/reference/api/keys.md#create-a-key). This endpoint is always protected and can only be accessed with the master key. +You can create API keys by using the [create key endpoint](/reference/api/keys.md#create-a-key). This endpoint is always protected and can only be accessed with the master key or an API key with the `keys.create` action. Since we have altered the permissions in our default search key, we need to create a new API key so authorized users can search through out `patient_medical_records` index: @@ -146,7 +150,7 @@ It is good practice to always set an expiry date when creating a new API key. If You can use the [list keys endpoint](/reference/api/keys.md) to obtain information on any active key in your Meilisearch instance. This is useful when you need an overview of existing keys and their permissions. -[`GET /keys`](/reference/api/keys.md#get-all-keys) returns a full list of all existing keys. **Expired keys will appear in the response, but deleted keys will not**. As with creating, deleting, and updating API keys, you need the master key to access this endpoint. +[`GET /keys`](/reference/api/keys.md#get-all-keys) returns a full list of all existing keys. **Expired keys will appear in the response, but deleted keys will not**. As with creating, deleting, and updating API keys, you either need the master key or an API key with the `keys.get` action to access this endpoint. [`GET /keys/{key}`](/reference/api/keys.md#get-one-key) returns information on a single key. `{key}` should be replaced with the full `key` value obtained during key creation. diff --git a/reference/api/keys.md b/reference/api/keys.md index a6582e1f69..248fa30d1a 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -1,12 +1,6 @@ # Keys -The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must [set the master key](/learn/configuration/instance_options.md#master-key) and supply it in the header of the request: - -```bash -curl \ - -H 'Authorization: Bearer MASTER_KEY' - … -``` +The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must either [set the master key](/learn/configuration/instance_options.md#master-key) and supply it in the header of the request or your API key must have the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. [Learn more about managing keys and their rights](/learn/security/master_api_keys.md). @@ -74,13 +68,21 @@ List all existing API keys. **Expired keys are included in the response**, but d ### Returned fields +#### `name` + +A human-readable name for the key. Default value is `null`. + #### `description` A description for the key. Default value is `null`. +#### `uid` + +A [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) to identify the API Key. If not specified, it is generated by Meilisearch. + #### `key` -An alphanumeric key value generated by Meilisearch on API key creation. Used for authorization when [making calls to a protected Meilisearch instance](/learn/security/master_api_keys.md#communicating-with-a-protected-instance). +An alphanumeric key value generated by Meilisearch with an HMAC using an SHA-256 hash of the `uid` and the master key on API key creation. Used for authorization when [making calls to a protected Meilisearch instance](/learn/security/master_api_keys.md#communicating-with-a-protected-instance). This value is also used as the `{key}` path variable to [update](#update-a-key), [delete](#delete-a-key), or [get](#get-one-key) a specific key. @@ -146,6 +148,20 @@ Only the `indexes`, `actions`, and `expiresAt` fields are mandatory. ### Body +#### `name` + +**Type:** string +**Default value:** `null` + +A human-readable name for the key. + +#### `uid` + +**Type:** string +**Default value:** none + +A [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) to identify the API Key. If not specified, it is generated by Meilisearch. + #### `description` **Type:** string @@ -177,6 +193,10 @@ A list of API actions permitted for the key. `["*"]` for all actions. | dumps.create | Provides access to the [create dump](/reference/api/dump.md#create-a-dump) endpoint. **Not restricted by `indexes`.** | | dumps.get | Provides access to the [get dump status](/reference/api/dump.md#get-dump-status) endpoint. **Not restricted by `indexes`.** | | version | Provides access to the [get Meilisearch version](/reference/api/version.md#get-version-of-meilisearch) endpoint. | +| keys.get | Provides access to the [get all keys](#get-all-keys) endpoint.| +| keys.create | Provides access to the [create key](#create-a-key) endpoint.| +| keys.update | Provides access to the [update keys](#update-a-key) endpoint.| +| keys.delete | Provides access to the [delete keys](#delete-a-key) endpoint.| #### `indexes` @@ -220,7 +240,7 @@ Date and time when the key will expire, represented in RFC 3339 format. `null` i -Update the description, permissions, or expiration date of an API key. A valid API [key](/reference/api/keys.md#key) is required. +Update the name and description of an API key. A valid API [key](/reference/api/keys.md#key) is required. To learn more about the variables sent in the body of the request, see the [create key](#body) endpoint. From e9d805e39ba1937a70bd95127d95dae41594cd21 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Thu, 16 Jun 2022 17:37:32 +0400 Subject: [PATCH 017/150] update errors+tenant tokens --- learn/security/tenant_tokens.md | 10 +++++----- reference/api/error_codes.md | 16 ++++++++++++++++ 2 files changed, 21 insertions(+), 5 deletions(-) diff --git a/learn/security/tenant_tokens.md b/learn/security/tenant_tokens.md index 21939b7087..a88afbec2e 100644 --- a/learn/security/tenant_tokens.md +++ b/learn/security/tenant_tokens.md @@ -66,18 +66,18 @@ const tokenPayload = { 'filter': `user_id = ${currentUserID}` } }, - apiKeyPrefix: apiKey.substring(0, 8), + apiKeyUid: apiKey.substring(0, 8), exp: parseInt(Date.now() / 1000) + 20 * 60 // 20 minutes }; const token = jwt.sign(tokenPayload, apiKey, {algorithm: 'HS256'}); ``` -`tokenPayload` contains the token payload. It must contain three fields: `searchRules`, `apiKeyPrefix`, and `exp`. +`tokenPayload` contains the token payload. It must contain three fields: `searchRules`, `apiKeyUid`, and `exp`. `searchRules` must be a JSON object containing a set of search rules. These rules specify restrictions applied to every query using this web token. -`apiKeyPrefix` must be the first 8 characters of a valid Meilisearch API key. +`apiKeyUid` must be the `uid` of a valid Meilisearch API key. `exp` is the only optional parameter of a tenant token. It must be a UNIX timestamp specifying the expiration date of the token. @@ -117,7 +117,7 @@ The token payload contains most of the relevant token data. It must be an object ```json { "exp": 1646756934, - "apiKeyPrefix": "12345678", + "apiKeyUid": "12345678", "searchRules": { "patient_medical_records": { "filter": "user_id = 1" @@ -188,7 +188,7 @@ The previous rules can be combined in one tenant token: ```json { - "apiKeyPrefix": "rkDxFUHd", + "apiKeyUid": "rkDxFUHd", "exp": 1641835850, "searchRules": { "*": { diff --git a/reference/api/error_codes.md b/reference/api/error_codes.md index 0dcc2b22e9..3b97e2c630 100644 --- a/reference/api/error_codes.md +++ b/reference/api/error_codes.md @@ -168,3 +168,19 @@ The requested task does not exist. Please ensure that you are using the correct ### `invalid_typo_tolerance_min_word_size_for_typos` The `minWordSizeForTypos` object is invalid. The value for both `oneTypo` and `twoTypos` should be between `0` and `255`, and `twoTypos` should be greater or equal to `oneTypo`. + +### `immutable_field` + +The field you are trying to modify is immutable. + +### `api_key_already_exists` + +A key with this `uid` already exists. + +### `invalid_api_key_uid` + +The given `uid` is invalid. The `uid` must follow the [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) format. + +### `invalid_api_key_name` + +The give `name` is invalid. It should either be a string or `null`. \ No newline at end of file From 44ca0850049e34f56a01e60bf447d719642e5401 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Thu, 16 Jun 2022 17:46:29 +0400 Subject: [PATCH 018/150] update keys.md --- reference/api/error_codes.md | 2 +- reference/api/keys.md | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/reference/api/error_codes.md b/reference/api/error_codes.md index 3b97e2c630..8af92c036a 100644 --- a/reference/api/error_codes.md +++ b/reference/api/error_codes.md @@ -183,4 +183,4 @@ The given `uid` is invalid. The `uid` must follow the [uuid v4](https://www.soha ### `invalid_api_key_name` -The give `name` is invalid. It should either be a string or `null`. \ No newline at end of file +The give `name` is invalid. It should either be a string or `null`. diff --git a/reference/api/keys.md b/reference/api/keys.md index 248fa30d1a..75f0cbd385 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -1,6 +1,6 @@ # Keys -The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must either [set the master key](/learn/configuration/instance_options.md#master-key) and supply it in the header of the request or your API key must have the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. +The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must either [set the master key](/learn/configuration/instance_options.md#master-key) and supply it in the header of the request, or your API key must contain the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. [Learn more about managing keys and their rights](/learn/security/master_api_keys.md). @@ -82,7 +82,7 @@ A [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) to identify the #### `key` -An alphanumeric key value generated by Meilisearch with an HMAC using an SHA-256 hash of the `uid` and the master key on API key creation. Used for authorization when [making calls to a protected Meilisearch instance](/learn/security/master_api_keys.md#communicating-with-a-protected-instance). +An alphanumeric key value generated by Meilisearch using the `uid` and the master key on API key creation. Used for authorization when [making calls to a protected Meilisearch instance](/learn/security/master_api_keys.md#communicating-with-a-protected-instance). This value is also used as the `{key}` path variable to [update](#update-a-key), [delete](#delete-a-key), or [get](#get-one-key) a specific key. @@ -238,9 +238,9 @@ Date and time when the key will expire, represented in RFC 3339 format. `null` i ## Update a key - + -Update the name and description of an API key. A valid API [key](/reference/api/keys.md#key) is required. +Update the name and description of an API key. A valid API [uid](/reference/api/keys.md#key) is required. To learn more about the variables sent in the body of the request, see the [create key](#body) endpoint. @@ -272,9 +272,9 @@ Updates to keys are **partial**. This means you should provide only the fields y ## Delete a key - + -Delete the specified API key. A valid API [key](/reference/api/keys.md#key) is required. +Delete the specified API key. A valid API [uid](/reference/api/keys.md#uid) is required. ### Example From 8b620830bc123c6b55c8813c21c7f480d34e06f7 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Thu, 16 Jun 2022 18:21:30 +0400 Subject: [PATCH 019/150] pagination basics --- learn/security/master_api_keys.md | 4 ++-- reference/api/keys.md | 25 ++++++++++++++++++++++--- 2 files changed, 24 insertions(+), 5 deletions(-) diff --git a/learn/security/master_api_keys.md b/learn/security/master_api_keys.md index cec2191fd7..57a2dc0643 100644 --- a/learn/security/master_api_keys.md +++ b/learn/security/master_api_keys.md @@ -82,7 +82,7 @@ Exposing your master key can give malicious users complete control over your Mei Meilisearch gives you fine-grained control over which users can access which indexes, endpoints, and routes. When protecting your instance with a master key, you can ensure only authorized users can carry out sensitive tasks such as adding documents or altering index settings. -You can access to the [`/keys` route](/reference/api/keys.md) with the master key or an API key with containing `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. This route allows you to [create](#creating-an-api-key), [update](#updating-an-api-key), [list](#listing-api-keys), and [delete](#deleting-an-api-key) API keys. +You can access the [`/keys` route](/reference/api/keys.md) using the master key or an API key containing `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. This route allows you to [create](#creating-an-api-key), [update](#updating-an-api-key), [list](#listing-api-keys), and [delete](#deleting-an-api-key) API keys. ::: note If you change your master key, the `key` field is re-generated. @@ -92,7 +92,7 @@ Though the default API keys are usually enough to manage the security needs of m ### Updating an API key -You can freely update the `name` and `description` of an API key at any time, even after it expires. +You can update the `name` and `description` of an API key at any time, even after it expires. We can update the `Default Search API Key` to add a description: diff --git a/reference/api/keys.md b/reference/api/keys.md index 75f0cbd385..3327bda3ff 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -62,10 +62,17 @@ List all existing API keys. **Expired keys are included in the response**, but d "createdAt": "2021-08-11T10:00:00Z", "updatedAt": "2021-08-11T10:00:00Z" } - ] + ], + "offset":0, + "limit":20, + "total":7 } ``` +::: note +API keys are displayed in descending order based on their `createdAt` date. This means that the most recently created keys appear first. +::: + ### Returned fields #### `name` @@ -108,11 +115,23 @@ Date and time when the key was created, represented in RFC 3339 format. Date and time when the key was last updated, represented in RFC 3339 format. +### `offset` + +Sets the starting point in the results, effectively skipping over a given number of API keys. + +### `limit` + +Sets the maximum number of documents to be returned by the current request. + +### `total` + +Gives the total number of API keys that can be browsed. + ## Get one key - + -Get information on the specified key. Attempting to use this endpoint with a non-existent or deleted key will result in [an error](/reference/api/error_codes.md#api-key-not-found). A valid API [key](/reference/api/keys.md#key) is required. +Get information on the specified key. Attempting to use this endpoint with a non-existent or deleted key will result in [an error](/reference/api/error_codes.md#api-key-not-found). A valid API [key](/reference/api/keys.md#key) or [uid](/reference/api/keys.md#uid) is required. ### Example From ad9b84f545371193faa8cf4394076abdc42a94d7 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 16 Jun 2022 17:49:42 +0200 Subject: [PATCH 020/150] improve wording --- reference/api/documents.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/documents.md b/reference/api/documents.md index 0aae4cdb12..76f75a50bb 100644 --- a/reference/api/documents.md +++ b/reference/api/documents.md @@ -43,7 +43,7 @@ Documents are ordered by Meilisearch depending on the hash of their id. | Query Parameter | Description | Default Value | | ------------------------ | ------------------------------ | :-----------: | | **offset** | number of documents to skip | 0 | -| **limit** | number of documents to display | 20 | +| **limit** | number of documents to return | 20 | | **fields** | document attributes to show | \* | ### Example From d8020709ccb387ebecf4a692241f2f7a5ed3dea0 Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Thu, 16 Jun 2022 17:58:18 +0200 Subject: [PATCH 021/150] Tasks: add new query params --- reference/api/tasks.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/reference/api/tasks.md b/reference/api/tasks.md index b6071ea135..442c4f6bc4 100644 --- a/reference/api/tasks.md +++ b/reference/api/tasks.md @@ -10,7 +10,16 @@ The task `uid` is incremented **globally.** -List all tasks globally, regardless of index. The `task` objects are contained in the `results` array. +List all tasks globally, regardless of index. The `task` objects are contained in the `results` array. Tasks are always returned in descending order of `uid`. + +Task results are paginated and can be filtered. + +#### Query parameters + +| Query Parameter | Description | Default Value | +| ------------------------ | --------------------------- | :-----------: | +| **limit** | number of tasks to return | 20 | +| **from** | the `uid` of the first task returned | the `uid` of the last created task | ### Example From d90113d09ccdc428332f919a01b38db597d46dc3 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 16 Jun 2022 17:59:54 +0200 Subject: [PATCH 022/150] improve wording --- reference/api/search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/search.md b/reference/api/search.md index 6a8c1773e4..ffdd9e281f 100644 --- a/reference/api/search.md +++ b/reference/api/search.md @@ -464,7 +464,7 @@ Instead of supplying individual attributes, you can provide `["*"]` as a wildcar Suppose you have a field containing the following string: `Donatello is a skilled and smart turtle. Leonardo is the most skilled turtle. Raphael is the strongest turtle.` -Meilisearch takes sentence context in consideration when cropping. For example, if your search term is `Leonardo` and your `cropLength` is 6, Meilisearch will prioritize keeping the sentence together and return: `Leonardo is the most skilled turtle.` +Meilisearch respects sentence boundaries when cropping. For example, if your search term is `Leonardo` and your `cropLength` is 6, Meilisearch will prioritize keeping the sentence together and return: `Leonardo is the most skilled turtle.` If a query contains only a single search term, Meilisearch crops around the first occurrence of that term. If you search for `turtle` and your `cropLength` is 7, Meilisearch will return the first instance of that word: `Donatello is a skilled and smart turtle.` From 481e44ced23480779d4d0695d93f6a18ae6d2f5d Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 16 Jun 2022 18:15:20 +0200 Subject: [PATCH 023/150] remove `name` attribute from /indexes responses --- learn/core_concepts/indexes.md | 1 - reference/api/indexes.md | 4 ---- 2 files changed, 5 deletions(-) diff --git a/learn/core_concepts/indexes.md b/learn/core_concepts/indexes.md index 36f069949e..9eb84d248a 100644 --- a/learn/core_concepts/indexes.md +++ b/learn/core_concepts/indexes.md @@ -29,7 +29,6 @@ The `uid` is the **unique identifier** of an index. It is set when creating the ```json { "uid": "movies", - "name": "movies", "createdAt": "2019-11-20T09:40:33.711324Z", "updatedAt": "2019-11-20T10:16:42.761858Z" } diff --git a/reference/api/indexes.md b/reference/api/indexes.md index 4b108640d0..3e8b6ca11b 100644 --- a/reference/api/indexes.md +++ b/reference/api/indexes.md @@ -20,21 +20,18 @@ List all [indexes](/learn/core_concepts/indexes.md). [ { "uid": "books", - "name": "books", "createdAt": "2022-03-08T10:00:27.377346Z", "updatedAt": "2022-03-08T10:00:27.391209Z", "primaryKey": "id" }, { "uid": "meteorites", - "name": "meteorites", "createdAt": "2022-03-08T10:00:44.518768Z", "updatedAt": "2022-03-08T10:00:44.582083Z", "primaryKey": "id" }, { "uid": "movies", - "name": "movies", "createdAt": "2022-02-10T07:45:15.628261Z", "updatedAt": "2022-02-21T15:28:43.496574Z", "primaryKey": "id" @@ -57,7 +54,6 @@ Get information about an [index](/learn/core_concepts/indexes.md). The index [`u ```json { "uid": "movies", - "name": "movies", "createdAt": "2022-02-10T07:45:15.628261Z", "updatedAt": "2022-02-21T15:28:43.496574Z", "primaryKey": "id" From f56caf9aecc2214803306dc5734ebbd77434dae0 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Mon, 20 Jun 2022 10:59:34 +0400 Subject: [PATCH 024/150] update title --- learn/advanced/filtering_and_faceted_search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/advanced/filtering_and_faceted_search.md b/learn/advanced/filtering_and_faceted_search.md index cb28212316..7a057de53f 100644 --- a/learn/advanced/filtering_and_faceted_search.md +++ b/learn/advanced/filtering_and_faceted_search.md @@ -290,7 +290,7 @@ In the example below, [IMDb](https://www.imdb.com) displays the facet count in p ![IMDb facets](/faceted-search/facets-imdb.png) -#### Using facet distribution +#### Using `facets` [`facets` is a search parameter](/reference/api/search.md#facets) and as such must be added to a search request. It expects an array of strings. Each string is an attribute present in the `filterableAttributes` list. From cc798dbf8dfe4f3a025e428a2dd7625a3f051896 Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Mon, 20 Jun 2022 11:02:33 +0400 Subject: [PATCH 025/150] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Clémentine Urquizar - curqui Co-authored-by: Tommy <68053732+dichotommy@users.noreply.github.com> --- learn/getting_started/quick_start.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/learn/getting_started/quick_start.md b/learn/getting_started/quick_start.md index 8ecaa1a595..60067edb38 100644 --- a/learn/getting_started/quick_start.md +++ b/learn/getting_started/quick_start.md @@ -58,7 +58,7 @@ docker run -it --rm \ -p 7700:7700 \ -e MEILI_MASTER_KEY='MASTER_KEY'\ -v $(pwd)/meili_data:/meili_data \ - getmeili/meilisearch:v0.28.0 \ + getmeili/meilisearch:v0.28 \ meilisearch --env="development" ``` @@ -101,7 +101,7 @@ cd meilisearch Choose the release you want to use. You can find the full list [here](https://github.com/meilisearch/meilisearch/releases). -In the cloned repository, run the following command replacing `vX.Y.Z` with the tag you selected: +In the cloned repository, run the following command to access the most recent version of Meilisearch: ```bash git checkout v0.28.0 From 26a70c4ba303f83e3520d37c987405f70807ad0e Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Mon, 20 Jun 2022 11:02:42 +0400 Subject: [PATCH 026/150] Update learn/getting_started/quick_start.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Clémentine Urquizar - curqui --- learn/getting_started/quick_start.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/getting_started/quick_start.md b/learn/getting_started/quick_start.md index 60067edb38..0f7bad107c 100644 --- a/learn/getting_started/quick_start.md +++ b/learn/getting_started/quick_start.md @@ -51,7 +51,7 @@ These commands launch the **latest stable release** of Meilisearch. ```bash # Fetch the latest version of Meilisearch image from DockerHub -docker pull getmeili/meilisearch:v0.28.0 +docker pull getmeili/meilisearch:v0.28 # Launch Meilisearch in development mode with a master key docker run -it --rm \ From 795617be643628be5752668d8b0ecd8f8f6085d3 Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Mon, 20 Jun 2022 13:45:16 +0200 Subject: [PATCH 027/150] Tasks: add filtering section --- reference/api/tasks.md | 32 ++++++++++++++++++++++++++++---- 1 file changed, 28 insertions(+), 4 deletions(-) diff --git a/reference/api/tasks.md b/reference/api/tasks.md index 442c4f6bc4..7ff83c1b8d 100644 --- a/reference/api/tasks.md +++ b/reference/api/tasks.md @@ -16,10 +16,34 @@ Task results are paginated and can be filtered. #### Query parameters -| Query Parameter | Description | Default Value | -| ------------------------ | --------------------------- | :-----------: | -| **limit** | number of tasks to return | 20 | -| **from** | the `uid` of the first task returned | the `uid` of the last created task | +| Query Parameter | Description | Default Value | +|-----------------|--------------------------------------|:----------------------------------:| +| **limit** | number of tasks to return | 20 | +| **from** | the `uid` of the first task returned | the `uid` of the last created task | + +### Filtering tasks + +You can filter the task list by the value of the `status`, `type`, or `indexUid` fields. For example, this command would return only `enqueued` tasks: + +``` +curl -X GET 'https://localhost:7700/tasks?status=enqueued' +``` + +Use the ampersand character `&` to combine filters, equivalent to a logical `AND`. For example, the following command would return all `finished` tasks that also belong to the `movies` index: + +``` +curl -X GET 'https://localhost:7700/tasks?status=finished&indexUid=movies' +``` + +Use the comma character `,` to add multiple filter values for a single field. For example, to get all tasks whose `type` is either `indexUpdate` or `documentAdditionOrUpdate`, you would run the following command: + +``` +curl -X GET 'https://localhost:7700/tasks?type=indexUpdate,documentAdditionOrUpdate' +``` + +[Read more about the possible values of these fields in our asynchronous operations guide.](/learn/advanced/asynchronous_operations.md) + +### Paginating tasks ### Example From 318977f7f36475001abab0cdb6e7fefedc39d197 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Mon, 20 Jun 2022 17:34:22 +0400 Subject: [PATCH 028/150] add pagination+other updates --- .code-samples.meilisearch.yaml | 8 ++--- learn/advanced/updating.md | 4 +++ learn/security/master_api_keys.md | 47 ++++++++++++++----------- reference/api/keys.md | 57 ++++++++++++++++++------------- 4 files changed, 69 insertions(+), 47 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 2372947445..3b3ec8cb32 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -97,7 +97,7 @@ get_one_key_1: |- -H 'Authorization: Bearer MASTER_KEY' get_all_keys_1: |- curl \ - -X GET 'http://localhost:7700/keys' \ + -X GET 'http://localhost:7700/keys?limit=3' \ -H 'Authorization: Bearer MASTER_KEY' create_a_key_1: |- curl \ @@ -775,10 +775,10 @@ security_guide_search_key_1: |- -H 'Authorization: Bearer API_KEY' security_guide_update_key_1: |- curl \ - -X PATCH 'http://localhost:7700/keys/d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4' \ + -X PATCH 'http://localhost:7700/keys/74c9c733-3368-4738-bbe5-1d18a5fecb37 \ -H 'Authorization: Bearer MASTER_KEY' \ -H 'Content-Type: application/json' \ - --data-binary '{ "name": "Default Search API Key" }' + --data-binary '{ "description": "Default Search API Key" }' security_guide_create_key_1: |- curl \ -X POST 'http://localhost:7700/keys' \ @@ -796,7 +796,7 @@ security_guide_list_keys_1: |- -H 'Authorization: Bearer MASTER_KEY' security_guide_delete_key_1: |- curl \ - -X DELETE 'http://localhost:7700/keys/d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4' \ + -X DELETE 'http://localhost:7700/keys/ac5cd97d-5a4b-4226-a868-2d0eb6d197ab' \ -H 'Authorization: Bearer MASTER_KEY' primary_field_guide_create_index_primary_key: |- curl \ diff --git a/learn/advanced/updating.md b/learn/advanced/updating.md index 508f2a2969..6e15ff0d0e 100644 --- a/learn/advanced/updating.md +++ b/learn/advanced/updating.md @@ -102,6 +102,10 @@ docker run -it --rm \ :::: +:::note +If you are updating to v0.28, keys imported from the old version will have their `key` and `uid` fields regenerated. +::: + ### Proceed according to your database version Now that you know which Meilisearch version your database is compatible with, proceed accordingly: diff --git a/learn/security/master_api_keys.md b/learn/security/master_api_keys.md index 57a2dc0643..817727ab60 100644 --- a/learn/security/master_api_keys.md +++ b/learn/security/master_api_keys.md @@ -82,31 +82,29 @@ Exposing your master key can give malicious users complete control over your Mei Meilisearch gives you fine-grained control over which users can access which indexes, endpoints, and routes. When protecting your instance with a master key, you can ensure only authorized users can carry out sensitive tasks such as adding documents or altering index settings. -You can access the [`/keys` route](/reference/api/keys.md) using the master key or an API key containing `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. This route allows you to [create](#creating-an-api-key), [update](#updating-an-api-key), [list](#listing-api-keys), and [delete](#deleting-an-api-key) API keys. - -::: note -If you change your master key, the `key` field is re-generated. -::: +You can access the [`/keys` route](/reference/api/keys.md) using the master key or an API key with access to the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. This `/keys` route allows you to [create](#creating-an-api-key), [update](#updating-an-api-key), [list](#listing-api-keys), and [delete](#deleting-an-api-key) API keys. Though the default API keys are usually enough to manage the security needs of most applications, this might not be the case when dealing with privacy-sensitive data. In these situations, the fine-grained control offered by the `/keys` endpoint allows you to clearly decide who can access what information and for how long. ### Updating an API key -You can update the `name` and `description` of an API key at any time, even after it expires. +You can only update the `name` and `description` of an API key, even after it expires. -We can update the `Default Search API Key` to add a description: +We can update the `Default Search API Key` to change the description: ```json { + "name": "Default Search API Key", "description": "Default Search API Key", "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", + "uid":"74c9c733-3368-4738-bbe5-1d18a5fecb37", "actions": [ "search" ], "indexes": [ - "doctors" + "*" ], "expiresAt": null, "createdAt": "2022-01-01T10:00:00Z", @@ -114,7 +112,7 @@ We can update the `Default Search API Key` to add a description: } ``` -To update an API key, you must use the [update API key endpoint](/reference/api/keys.md#update-a-key), which can only be accessed with the master key or an API key containing the `keys.update` action. +To update an API key, you must use the [update API key endpoint](/reference/api/keys.md#update-a-key), which can only be accessed with the master key or an API key with the `keys.update` action. Meilisearch supports partial updates with the `PATCH` route. This means your payload only needs to contain the data you want to update—in this case, `description`. @@ -122,7 +120,7 @@ Meilisearch supports partial updates with the `PATCH` route. This means your pay You can create API keys by using the [create key endpoint](/reference/api/keys.md#create-a-key). This endpoint is always protected and can only be accessed with the master key or an API key with the `keys.create` action. -Since we have altered the permissions in our default search key, we need to create a new API key so authorized users can search through out `patient_medical_records` index: +Let's create a new API key so authorized users can search through out `patient_medical_records` index: @@ -130,8 +128,10 @@ All [`/keys` endpoints](/reference/api/keys.md) are synchronous, so your key wil ```json { + "name": null, "description": "Search patient records key", "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", + "uid": "ac5cd97d-5a4b-4226-a868-2d0eb6d197ab", "actions": [ "search" ], @@ -152,7 +152,7 @@ You can use the [list keys endpoint](/reference/api/keys.md) to obtain informati [`GET /keys`](/reference/api/keys.md#get-all-keys) returns a full list of all existing keys. **Expired keys will appear in the response, but deleted keys will not**. As with creating, deleting, and updating API keys, you either need the master key or an API key with the `keys.get` action to access this endpoint. -[`GET /keys/{key}`](/reference/api/keys.md#get-one-key) returns information on a single key. `{key}` should be replaced with the full `key` value obtained during key creation. +[`GET /keys/{key_or_uid}`](/reference/api/keys.md#get-one-key) returns information on a single key. `{key_or_uid}` should be replaced with the full `key` or `uid` value obtained during key creation. We can query our instance to confirm which active keys can search our `patient_medical_records` index: @@ -162,21 +162,25 @@ We can query our instance to confirm which active keys can search our `patient_m { "results": [ { - "description": "Default Search API Key (Use it to search from the frontend code)", - "key": "0a6e572506c52ab0bd6195921575d23092b7f0c284ab4ac86d12346c33057f99", + "name": "Default Search API Key", + "description": "Default Search API Key", + "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", + "uid":"74c9c733-3368-4738-bbe5-1d18a5fecb37", "actions": [ - "search" + "search" ], "indexes": [ - "doctors" + "*" ], "expiresAt": null, - "createdAt": "2021-08-11T10:00:00Z", - "updatedAt": "2021-08-11T10:00:00Z" + "createdAt": "2022-01-01T10:00:00Z", + "updatedAt": "2022-01-01T10:00:00Z" }, { + "name": "Default Admin API Key", "description": "Default Admin API Key (Use it for all other operations. Caution! Do not share it on the client side)", "key": "380689dd379232519a54d15935750cc7625620a2ea2fc06907cb40ba5b421b6f", + "uid": "20f7e4c4-612c-4dd1-b783-7934cc038213", "actions": [ "*" ], @@ -188,8 +192,10 @@ We can query our instance to confirm which active keys can search our `patient_m "updatedAt": "2021-08-11T10:00:00Z" }, { + "name": null, "description": "Search patient records key", "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", + "uid": "ac5cd97d-5a4b-4226-a868-2d0eb6d197ab", "actions": [ "search" ], @@ -200,7 +206,10 @@ We can query our instance to confirm which active keys can search our `patient_m "createdAt": "2022-01-01T10:00:00Z", "updatedAt": "2022-01-01T10:00:00Z" } - ] + ], + "offset":0, + "limit":20, + "total":3 } ``` @@ -216,8 +225,6 @@ If we accidentally exposed our `Search patient records key`, we can delete it to Once a key is past its `expiresAt` date, using it for API authorization will return an error. Expired keys will still be returned by the [list keys endpoint](/reference/api/keys.md#get-all-keys). -If you must continue using an expired key, you may use the [update key endpoint](/reference/api/keys.md#update-a-key) to set a new `expiresAt` date and effectively reactivate it. - ## Changing the master key To change the master key, first terminate your Meilisearch instance. Then relaunch it, [supplying a new value for the master key](#protecting-a-meilisearch-instance). diff --git a/reference/api/keys.md b/reference/api/keys.md index 3327bda3ff..12d754d197 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -1,6 +1,6 @@ # Keys -The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must either [set the master key](/learn/configuration/instance_options.md#master-key) and supply it in the header of the request, or your API key must contain the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. +The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must either [set the master key](/learn/configuration/instance_options.md#master-key) and supply it in the header of the request, or your API key must have access to the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. [Learn more about managing keys and their rights](/learn/security/master_api_keys.md). @@ -12,6 +12,13 @@ List all existing API keys. **Expired keys are included in the response**, but d [See below for an explanation of returned fields.](#description) +#### Query parameters + +| Query Parameter | Description | Default Value | +| ------------------------ | --------------------------| ------------- | +| **offset** | number of keys to skip | 0 | +| **limit** | number of keys to return | 20 | + ### Example @@ -64,7 +71,7 @@ List all existing API keys. **Expired keys are included in the response**, but d } ], "offset":0, - "limit":20, + "limit":3, "total":7 } ``` @@ -75,6 +82,24 @@ API keys are displayed in descending order based on their `createdAt` date. This ### Returned fields +Returns API keys in an array called `results`, along with the following fields: + +#### `offset` + +The number of keys skipped over. + +#### `limit` + +The maximum number of keys to be returned by the request. + +#### `total` + +The total number of API keys that can be browsed. + +### The `results` array + +For each key, it returns: + #### `name` A human-readable name for the key. Default value is `null`. @@ -85,7 +110,7 @@ A description for the key. Default value is `null`. #### `uid` -A [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) to identify the API Key. If not specified, it is generated by Meilisearch. +A [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) to identify the API key. If not specified, it is generated by Meilisearch. #### `key` @@ -115,21 +140,9 @@ Date and time when the key was created, represented in RFC 3339 format. Date and time when the key was last updated, represented in RFC 3339 format. -### `offset` - -Sets the starting point in the results, effectively skipping over a given number of API keys. - -### `limit` - -Sets the maximum number of documents to be returned by the current request. - -### `total` - -Gives the total number of API keys that can be browsed. - ## Get one key - + Get information on the specified key. Attempting to use this endpoint with a non-existent or deleted key will result in [an error](/reference/api/error_codes.md#api-key-not-found). A valid API [key](/reference/api/keys.md#key) or [uid](/reference/api/keys.md#uid) is required. @@ -179,7 +192,7 @@ A human-readable name for the key. **Type:** string **Default value:** none -A [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) to identify the API Key. If not specified, it is generated by Meilisearch. +A [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) to identify the API key. If not specified, it is generated by Meilisearch. #### `description` @@ -214,8 +227,8 @@ A list of API actions permitted for the key. `["*"]` for all actions. | version | Provides access to the [get Meilisearch version](/reference/api/version.md#get-version-of-meilisearch) endpoint. | | keys.get | Provides access to the [get all keys](#get-all-keys) endpoint.| | keys.create | Provides access to the [create key](#create-a-key) endpoint.| -| keys.update | Provides access to the [update keys](#update-a-key) endpoint.| -| keys.delete | Provides access to the [delete keys](#delete-a-key) endpoint.| +| keys.update | Provides access to the [update key](#update-a-key) endpoint.| +| keys.delete | Provides access to the [delete key](#delete-a-key) endpoint.| #### `indexes` @@ -276,12 +289,10 @@ Updates to keys are **partial**. This means you should provide only the fields y "description": "Manage documents: Products/Reviews API key", "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", "actions": [ - "documents.add", - "documents.delete" + "documents.add" ], "indexes": [ - "products", - "reviews" + "products" ], "expiresAt": "2021-12-31T23:59:59Z", "createdAt": "2021-11-12T10:00:00Z", From ae2a4418cbf01e890caade7131bfa61d1ad7555b Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Mon, 20 Jun 2022 17:51:35 +0400 Subject: [PATCH 029/150] update code samples --- .code-samples.meilisearch.yaml | 4 ++-- reference/api/keys.md | 18 ++++++++++++++---- 2 files changed, 16 insertions(+), 6 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 3b3ec8cb32..6c53c49064 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -112,7 +112,7 @@ create_a_key_1: |- }' update_a_key_1: |- curl \ - -X PATCH 'http://localhost:7700/keys/d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4' \ + -X PATCH 'http://localhost:7700/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \ -H 'Authorization: Bearer MASTER_KEY' \ -H 'Content-Type: application/json' \ --data-binary '{ @@ -121,7 +121,7 @@ update_a_key_1: |- }' delete_a_key_1: |- curl \ - -X DELETE 'http://localhost:7700/keys/d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4' \ + -X DELETE 'http://localhost:7700/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \ -H 'Authorization: Bearer MASTER_KEY' get_settings_1: |- curl \ diff --git a/reference/api/keys.md b/reference/api/keys.md index 12d754d197..1fbbb0791b 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -29,8 +29,10 @@ List all existing API keys. **Expired keys are included in the response**, but d { "results": [ { + "name": null, "description": "Manage documents: Products/Reviews API key", "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", + "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d", "actions": [ "documents.add", "documents.delete" @@ -44,8 +46,10 @@ List all existing API keys. **Expired keys are included in the response**, but d "updatedAt": "2021-10-13T15:00:00Z" }, { + "name": "Default Search API Key", "description": "Default Search API Key (Use it to search from the frontend code)", "key": "0a6e572506c52ab0bd6195921575d23092b7f0c284ab4ac86d12346c33057f99", + "uid": "74c9c733-3368-4738-bbe5-1d18a5fecb37", "actions": [ "search" ], @@ -57,8 +61,10 @@ List all existing API keys. **Expired keys are included in the response**, but d "updatedAt": "2021-08-11T10:00:00Z" }, { + "name": "Default Admin API Key", "description": "Default Admin API Key (Use it for all other operations. Caution! Do not share it on the client side)", "key": "380689dd379232519a54d15935750cc7625620a2ea2fc06907cb40ba5b421b6f", + "uid": "20f7e4c4-612c-4dd1-b783-7934cc038213", "actions": [ "*" ], @@ -286,17 +292,21 @@ Updates to keys are **partial**. This means you should provide only the fields y ```json { + "name": "Products/Reviews API key", "description": "Manage documents: Products/Reviews API key", "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", + "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d", "actions": [ - "documents.add" + "documents.add", + "documents.delete" ], "indexes": [ - "products" + "products", + "reviews" ], "expiresAt": "2021-12-31T23:59:59Z", - "createdAt": "2021-11-12T10:00:00Z", - "updatedAt": "2021-10-12T15:00:00Z" + "createdAt": "2021-10-12T00:00:00Z", + "updatedAt": "2021-10-13T15:00:00Z" } ``` From 76c7094d827029416938b305596d921045e039d0 Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Mon, 20 Jun 2022 15:51:41 +0200 Subject: [PATCH 030/150] Tasks: add pagination section --- reference/api/tasks.md | 68 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 62 insertions(+), 6 deletions(-) diff --git a/reference/api/tasks.md b/reference/api/tasks.md index 7ff83c1b8d..281acc6318 100644 --- a/reference/api/tasks.md +++ b/reference/api/tasks.md @@ -25,26 +25,82 @@ Task results are paginated and can be filtered. You can filter the task list by the value of the `status`, `type`, or `indexUid` fields. For example, this command would return only `enqueued` tasks: -``` -curl -X GET 'https://localhost:7700/tasks?status=enqueued' +```bash +curl -X GET 'http://localhost:7700/tasks?status=enqueued' ``` Use the ampersand character `&` to combine filters, equivalent to a logical `AND`. For example, the following command would return all `finished` tasks that also belong to the `movies` index: -``` -curl -X GET 'https://localhost:7700/tasks?status=finished&indexUid=movies' +```bash +curl -X GET 'http://localhost:7700/tasks?status=finished&indexUid=movies' ``` Use the comma character `,` to add multiple filter values for a single field. For example, to get all tasks whose `type` is either `indexUpdate` or `documentAdditionOrUpdate`, you would run the following command: -``` -curl -X GET 'https://localhost:7700/tasks?type=indexUpdate,documentAdditionOrUpdate' +```bash +curl -X GET 'http://localhost:7700/tasks?type=indexUpdate,documentAdditionOrUpdate' ``` [Read more about the possible values of these fields in our asynchronous operations guide.](/learn/advanced/asynchronous_operations.md) ### Paginating tasks +The task list is paginated, by default returning 20 tasks at a time. You can adjust the number of documents returned using the `limit` parameter, and control where the list begins using the `from` parameter. + +For each call to this endpoint, the response will include the `next` field: this value should be passed to `from` to view the next "page" of results. When the value of `next` is `null`, there are no more tasks to view. + +This command returns tasks two at a time starting from task `uid` `10`. + +```bash +curl -X GET 'http://localhost:7700/tasks?limit=2&from=10 +``` + +**Response:** + +```json +{ + "results": [ + { + "uid": 10, + "indexUid": "elements", + "status": "succeeded", + "type": "indexCreation", + "details": { + "primaryKey": null + }, + "duration": "PT0.006034S", + "enqueuedAt": "2022-06-20T13:41:42.446908Z", + "startedAt": "2022-06-20T13:41:42.447477Z", + "finishedAt": "2022-06-20T13:41:42.453511Z" + }, + { + "uid": 9, + "indexUid": "particles", + "status": "succeeded", + "type": "indexCreation", + "details": { + "primaryKey": null + }, + "duration": "PT0.007317S", + "enqueuedAt": "2022-06-20T13:41:31.841575Z", + "startedAt": "2022-06-20T13:41:31.842116Z", + "finishedAt": "2022-06-20T13:41:31.849433Z" + } + ], + "limit": 2, + "from": 10, + "next": 8 +} +``` + +To view the next page of results, you would repeat the same query, replacing the value of `from` with the value of `next`: + +```bash +curl -X GET 'http://localhost:7700/tasks?limit=2&from=8 +``` + +You have reached the final page when the returned value of `next` is `null`. + ### Example From 22385e52596b85d17a61c39ed1cfc3586b953d99 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Mon, 20 Jun 2022 18:03:51 +0400 Subject: [PATCH 031/150] update actions+indentation --- learn/security/master_api_keys.md | 6 +++--- reference/api/keys.md | 7 +++---- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/learn/security/master_api_keys.md b/learn/security/master_api_keys.md index 817727ab60..f4760a183c 100644 --- a/learn/security/master_api_keys.md +++ b/learn/security/master_api_keys.md @@ -180,12 +180,12 @@ We can query our instance to confirm which active keys can search our `patient_m "name": "Default Admin API Key", "description": "Default Admin API Key (Use it for all other operations. Caution! Do not share it on the client side)", "key": "380689dd379232519a54d15935750cc7625620a2ea2fc06907cb40ba5b421b6f", - "uid": "20f7e4c4-612c-4dd1-b783-7934cc038213", + "uid": "20f7e4c4-612c-4dd1-b783-7934cc038213", "actions": [ - "*" + "*" ], "indexes": [ - "*" + "*" ], "expiresAt": null, "createdAt": "2021-08-11T10:00:00Z", diff --git a/reference/api/keys.md b/reference/api/keys.md index 1fbbb0791b..109a484e30 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -1,6 +1,6 @@ # Keys -The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must either [set the master key](/learn/configuration/instance_options.md#master-key) and supply it in the header of the request, or your API key must have access to the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. +The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must either [set the master key](/learn/configuration/instance_options.md#master-key) and supply it in the header of the request, or use API keys that have access to the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. [Learn more about managing keys and their rights](/learn/security/master_api_keys.md). @@ -229,7 +229,6 @@ A list of API actions permitted for the key. `["*"]` for all actions. | settings.update | Provides access to the [update settings](/reference/api/settings.md#update-settings) and [reset settings](/reference/api/settings.md#reset-settings) endpoints and equivalents for all subroutes on authorized indexes. | | stats.get | Provides access to the [get stats of an index](/reference/api/stats.md#get-stats-of-an-index) endpoint and the [get stats of all indexes](/reference/api/stats.md#get-stats-of-all-indexes) endpoint. For the latter, **non-authorized `indexes` are omitted from the response**. | | dumps.create | Provides access to the [create dump](/reference/api/dump.md#create-a-dump) endpoint. **Not restricted by `indexes`.** | -| dumps.get | Provides access to the [get dump status](/reference/api/dump.md#get-dump-status) endpoint. **Not restricted by `indexes`.** | | version | Provides access to the [get Meilisearch version](/reference/api/version.md#get-version-of-meilisearch) endpoint. | | keys.get | Provides access to the [get all keys](#get-all-keys) endpoint.| | keys.create | Provides access to the [create key](#create-a-key) endpoint.| @@ -263,10 +262,10 @@ Date and time when the key will expire, represented in RFC 3339 format. `null` i "description": "Add documents: Products API key", "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", "actions": [ - "documents.add" + "documents.add" ], "indexes": [ - "products" + "products" ], "expiresAt": "2021-11-13T00:00:00Z", "createdAt": "2021-11-12T10:00:00Z", From 439a04a3dd1ddf8f17f7ab8762392dcd91dc02fa Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Mon, 20 Jun 2022 16:58:04 +0200 Subject: [PATCH 032/150] Tasks: change to documentAdditionOrUpdate --- learn/advanced/asynchronous_operations.md | 44 +++++++++++------------ learn/core_concepts/primary_key.md | 8 ++--- learn/getting_started/quick_start.md | 4 +-- reference/api/documents.md | 4 +-- reference/api/tasks.md | 16 ++++----- resources/faq.md | 4 +-- 6 files changed, 40 insertions(+), 40 deletions(-) diff --git a/learn/advanced/asynchronous_operations.md b/learn/advanced/asynchronous_operations.md index 1b2b32f056..25805b03df 100644 --- a/learn/advanced/asynchronous_operations.md +++ b/learn/advanced/asynchronous_operations.md @@ -30,18 +30,18 @@ Most of Meilisearch's asynchronous operations belong to a category called "tasks The response from the [task API](/reference/api/tasks.md) will always include the following fields in the stated order: -| Field | Type | Description | -|--------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------| -| `uid` | integer | The unique sequential identifier of the task | -| `indexUid` | string | The unique index identifier | -| `status` | string | The status of the task. Possible values are `enqueued`, `processing`, `succeeded`, `failed` | -| `type` | string | The type of task. Possible values are `indexCreation`, `indexUpdate`, `indexDeletion`, `documentAddition`, `documentPartial`, `documentDeletion`, `settingsUpdate`, `clearAll` | -| `details` | object | Detailed information on the task payload | -| `error` | object | Error details and context. Only present when a task has the `failed` status | -| `duration` | string | The total elapsed time the task spent in the `processing` state, in ISO 8601 format | -| `enqueuedAt` | string | The date and time when the task was first `enqueued`, in RFC 3339 format | -| `startedAt` | string | The date and time when the task began `processing`, in RFC 3339 format | -| `finishedAt` | string | The date and time when the task finished processing, whether `failed` or `succeeded`, in RFC 3339 format. | +| Field | Type | Description | +|--------------|---------|----------------------------------------------------------------------------------------------| +| `uid` | integer | The unique sequential identifier of the task | +| `indexUid` | string | The unique index identifier | +| `status` | string | The status of the task. Possible values are `enqueued`, `processing`, `succeeded`, `failed` | +| `type` | string | The type of task. Possible values are `indexCreation`, `indexUpdate`, `indexDeletion`, `documentAdditionOrUpdate`, `documentDeletion`, `settingsUpdate` | +| `details` | object | Detailed information on the task payload | +| `error` | object | Error details and context. Only present when a task has the `failed` status | +| `duration` | string | The total elapsed time the task spent in the `processing` state, in ISO 8601 format | +| `enqueuedAt` | string | The date and time when the task was first `enqueued`, in RFC 3339 format | +| `startedAt` | string | The date and time when the task began `processing`, in RFC 3339 format | +| `finishedAt` | string | The date and time when the task finished processing, whether `failed` or `succeeded`, in RFC 3339 format. | If a task fails due to an error, all error fields will be appended to the task response in an `error` object. @@ -49,13 +49,13 @@ If a task fails due to an error, all error fields will be appended to the task r All asynchronous operations return a summarized version of the [`task` object](#response). It contains the following fields in the stated order: -| Field | Type | Description | -|------------|---------|--------------------------------- | -| `uid` | integer | Unique sequential identifier | -| `indexUid` | string | Unique index identifier | -| `status` | string | Status of the task. Value is `enqueued` | -| `type` | string | Type of task | -| `enqueuedAt` | string | Represents the date and time in the RFC 3339 format when the task has been `enqueued` | +| Field | Type | Description | +|--------------|---------|---------------------------------------------------------------------------------------| +| `uid` | integer | Unique sequential identifier | +| `indexUid` | string | Unique index identifier | +| `status` | string | Status of the task. Value is `enqueued` | +| `type` | string | Type of task | +| `enqueuedAt` | string | Represents the date and time in the RFC 3339 format when the task has been `enqueued` | You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). @@ -79,7 +79,7 @@ When you query the task endpoint using this `uid`, you see that it has been enqu "uid": 1, "indexUid": "movies", "status": "enqueued", - "type": "documentAddition", + "type": "documentAdditionOrUpdate", "details": { "receivedDocuments": 67493, "indexedDocuments": null @@ -98,7 +98,7 @@ Later, you check the request's status one more time. It was successfully process "uid": 1, "indexUid": "movies", "status": "succeeded", - "type": "documentAddition", + "type": "documentAdditionOrUpdate", "details": { "receivedDocuments": 67493, "indexedDocuments": 67493 @@ -117,7 +117,7 @@ Had the task failed, the response would have included an `error` object: "uid": 1, "indexUid": "movies", "status": "failed", - "type": "documentAddition", + "type": "documentAdditionOrUpdate", "details": { "receivedDocuments": 67493, "indexedDocuments": 0 diff --git a/learn/core_concepts/primary_key.md b/learn/core_concepts/primary_key.md index 08c6d1fd3a..4eab7f9abc 100644 --- a/learn/core_concepts/primary_key.md +++ b/learn/core_concepts/primary_key.md @@ -120,7 +120,7 @@ The code below adds a document to the `books` index and sets `reference_number` "uid": 1, "indexUid": "books", "status": "succeeded", - "type": "documentAddition", + "type": "documentAdditionOrUpdate", "details":{ "receivedDocuments":1, "indexedDocuments":1 @@ -177,7 +177,7 @@ This error occurs when you add documents for the first time and Meilisearch [fai "uid":1, "indexUid": "books", "status": "failed", - "type": "documentAddition", + "type": "documentAdditionOrUpdate", "details":{ "receivedDocuments":5, "indexedDocuments":null @@ -204,7 +204,7 @@ This error occurs when your index already has a primary key, but one of the docu "uid":1, "indexUid": "books", "status": "failed", - "type": "documentAddition", + "type": "documentAdditionOrUpdate", "details":{ "receivedDocuments":1, "indexedDocuments":null @@ -231,7 +231,7 @@ This happens when your document id does not have the correct [format](#formattin "uid":1, "indexUid": "books", "status": "failed", - "type": "documentAddition", + "type": "documentAdditionOrUpdate", "details":{ "receivedDocuments":5, "indexedDocuments":null diff --git a/learn/getting_started/quick_start.md b/learn/getting_started/quick_start.md index 5d5d0ced71..da67fabda2 100644 --- a/learn/getting_started/quick_start.md +++ b/learn/getting_started/quick_start.md @@ -191,7 +191,7 @@ The previous command added documents from `movies.json` to a new index called `m "uid": 0, "indexUid": "movies", "status": "enqueued", - "type": "documentAddition", + "type": "documentAdditionOrUpdate", "enqueuedAt": "2021-08-11T09:25:53.000000Z" } ``` @@ -209,7 +209,7 @@ If the document addition is successful, the response should look like this: "uid": 0, "indexUid": "movies", "status": "succeeded", - "type": "documentAddition", + "type": "documentAdditionOrUpdate", "details":{ "receivedDocuments": 19547, "indexedDocuments": 19547 diff --git a/reference/api/documents.md b/reference/api/documents.md index a7123d51b5..bdc9939fb9 100644 --- a/reference/api/documents.md +++ b/reference/api/documents.md @@ -116,7 +116,7 @@ The body is composed of a **JSON array** of documents. "uid": 1, "indexUid": "movies", "status": "enqueued", - "type": "documentAddition", + "type": "documentAdditionOrUpdate", "enqueuedAt": "2021-08-11T09:25:53.000000Z" } ``` @@ -171,7 +171,7 @@ The documents are matched because they have the same [primary key](/learn/core_c "uid": 1, "indexUid": "movies", "status": "enqueued", - "type": "documentAddition", + "type": "documentAdditionOrUpdate", "enqueuedAt": "2021-08-11T09:25:53.000000Z" } ``` diff --git a/reference/api/tasks.md b/reference/api/tasks.md index 281acc6318..2774d11362 100644 --- a/reference/api/tasks.md +++ b/reference/api/tasks.md @@ -19,7 +19,7 @@ Task results are paginated and can be filtered. | Query Parameter | Description | Default Value | |-----------------|--------------------------------------|:----------------------------------:| | **limit** | number of tasks to return | 20 | -| **from** | the `uid` of the first task returned | the `uid` of the last created task | +| **from** | `uid` of the first task returned | `uid` of the last created task | ### Filtering tasks @@ -29,16 +29,16 @@ You can filter the task list by the value of the `status`, `type`, or `indexUid` curl -X GET 'http://localhost:7700/tasks?status=enqueued' ``` -Use the ampersand character `&` to combine filters, equivalent to a logical `AND`. For example, the following command would return all `finished` tasks that also belong to the `movies` index: +Use the ampersand character `&` to combine filters, equivalent to a logical `AND`. For example, the following command would return all `succeeded` tasks that also belong to the `movies` index: ```bash -curl -X GET 'http://localhost:7700/tasks?status=finished&indexUid=movies' +curl -X GET 'http://localhost:7700/tasks?status=succeeded&indexUid=movies' ``` -Use the comma character `,` to add multiple filter values for a single field. For example, to get all tasks whose `type` is either `indexUpdate` or `documentAdditionOrUpdate`, you would run the following command: +Use the comma character `,` to add multiple filter values for a single field. For example, to get all tasks whose `type` is either `settingsUpdate` or `documentAdditionOrUpdate`, you would run the following command: ```bash -curl -X GET 'http://localhost:7700/tasks?type=indexUpdate,documentAdditionOrUpdate' +curl -X GET 'http://localhost:7700/tasks?type=settingsUpdate,documentAdditionOrUpdate' ``` [Read more about the possible values of these fields in our asynchronous operations guide.](/learn/advanced/asynchronous_operations.md) @@ -99,7 +99,7 @@ To view the next page of results, you would repeat the same query, replacing the curl -X GET 'http://localhost:7700/tasks?limit=2&from=8 ``` -You have reached the final page when the returned value of `next` is `null`. +When the returned value of `next` is `null`, you have reached the final page of results. ### Example @@ -114,7 +114,7 @@ You have reached the final page when the returned value of `next` is `null`. "uid": 1, "indexUid": "movies_reviews", "status": "enqueued", - "type": "documentAddition", + "type": "documentAdditionOrUpdate", "duration": null, "enqueuedAt": "2021-08-12T10:00:00.000000Z", "startedAt": null, @@ -124,7 +124,7 @@ You have reached the final page when the returned value of `next` is `null`. "uid": 0, "indexUid": "movies", "status": "succeeded", - "type": "documentAddition", + "type": "documentAdditionOrUpdate", "details": { "receivedDocuments": 100, "indexedDocuments": 100 diff --git a/resources/faq.md b/resources/faq.md index dd22872afe..6608903dd5 100644 --- a/resources/faq.md +++ b/resources/faq.md @@ -58,7 +58,7 @@ All asynchronous operations return a summarized version of the [`task` object](/ "uid": 1, "indexUid": "movies", "status": "enqueued", - "type": "documentAddition", + "type": "documentAdditionOrUpdate", "enqueuedAt": "2021-08-11T09:25:53.000000Z" } ``` @@ -160,7 +160,7 @@ Here is an example of a failed task: "uid": 1, "indexUid": "movies", "status": "failed", - "type": "documentAddition", + "type": "documentAdditionOrUpdate", "details": { "receivedDocuments": 67493, "indexedDocuments": 0 From 10a7153f9ca27ce642281c3f4611261b9bb8e149 Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Mon, 20 Jun 2022 17:04:33 +0200 Subject: [PATCH 033/150] Tasks: change clearAll to documentDeletion --- reference/api/documents.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/documents.md b/reference/api/documents.md index bdc9939fb9..59b8e1d441 100644 --- a/reference/api/documents.md +++ b/reference/api/documents.md @@ -195,7 +195,7 @@ Delete all documents in the specified index. The index [`uid`](/learn/core_conce "uid": 1, "indexUid": "movies", "status": "enqueued", - "type": "clearAll", + "type": "documentDeletion", "enqueuedAt": "2021-08-11T09:25:53.000000Z" } ``` From 364fedfd9c21a3e03c01dcb0e4dfd684bb9d63d0 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 20 Jun 2022 17:17:02 +0200 Subject: [PATCH 034/150] update /indexes with new pagination parameters/response --- .code-samples.meilisearch.yaml | 2 +- reference/api/indexes.md | 54 +++++++++++++++++++++------------- 2 files changed, 34 insertions(+), 22 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 047cb60b9f..336bf1a25f 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -8,7 +8,7 @@ get_one_index_1: |- -X GET 'http://localhost:7700/indexes/movies' list_all_indexes_1: |- curl \ - -X GET 'http://localhost:7700/indexes' + -X GET 'http://localhost:7700/indexes?limit=3' create_an_index_1: |- curl \ -X POST 'http://localhost:7700/indexes' \ diff --git a/reference/api/indexes.md b/reference/api/indexes.md index 3e8b6ca11b..fb8e913a09 100644 --- a/reference/api/indexes.md +++ b/reference/api/indexes.md @@ -8,7 +8,14 @@ The `/indexes` route allows you to create, manage, and delete your indexes. -List all [indexes](/learn/core_concepts/indexes.md). +List all [indexes](/learn/core_concepts/indexes.md). Results can be paginated by using the `offset` and `limit` query parameters. + +#### Query parameters + +| Query parameter | Description | Default value | +| ------------------------ | --------------------------- | :-----------: | +| **offset** | Number of indexes to skip | 0 | +| **limit** | Number of indexes to return | 20 | ### Example @@ -17,26 +24,31 @@ List all [indexes](/learn/core_concepts/indexes.md). #### Response: `200 Ok` ```json -[ - { - "uid": "books", - "createdAt": "2022-03-08T10:00:27.377346Z", - "updatedAt": "2022-03-08T10:00:27.391209Z", - "primaryKey": "id" - }, - { - "uid": "meteorites", - "createdAt": "2022-03-08T10:00:44.518768Z", - "updatedAt": "2022-03-08T10:00:44.582083Z", - "primaryKey": "id" - }, - { - "uid": "movies", - "createdAt": "2022-02-10T07:45:15.628261Z", - "updatedAt": "2022-02-21T15:28:43.496574Z", - "primaryKey": "id" - } -] +{ + "results": [ + { + "uid": "books", + "createdAt": "2022-03-08T10:00:27.377346Z", + "updatedAt": "2022-03-08T10:00:27.391209Z", + "primaryKey": "id" + }, + { + "uid": "meteorites", + "createdAt": "2022-03-08T10:00:44.518768Z", + "updatedAt": "2022-03-08T10:00:44.582083Z", + "primaryKey": "id" + }, + { + "uid": "movies", + "createdAt": "2022-02-10T07:45:15.628261Z", + "updatedAt": "2022-02-21T15:28:43.496574Z", + "primaryKey": "id" + } + ], + "offset": 0, + "limit": 3, + "total": 5 +} ``` ## Get one index From 2aec18b320587f5c37aedac25b21c27b60b4fc77 Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Mon, 20 Jun 2022 18:28:11 +0200 Subject: [PATCH 035/150] Replace uid with taskUid --- learn/advanced/asynchronous_operations.md | 10 +++++----- learn/advanced/updating.md | 21 +++++++++++++++------ learn/getting_started/quick_start.md | 4 ++-- reference/api/displayed_attributes.md | 8 ++++---- reference/api/distinct_attribute.md | 8 ++++---- reference/api/documents.md | 20 ++++++++++---------- reference/api/filterable_attributes.md | 8 ++++---- reference/api/indexes.md | 12 ++++++------ reference/api/overview.md | 4 ++-- reference/api/ranking_rules.md | 8 ++++---- reference/api/searchable_attributes.md | 8 ++++---- reference/api/settings.md | 8 ++++---- reference/api/sortable_attributes.md | 8 ++++---- reference/api/stop_words.md | 8 ++++---- reference/api/synonyms.md | 8 ++++---- reference/api/typo_tolerance.md | 8 ++++---- resources/faq.md | 6 +++--- 17 files changed, 83 insertions(+), 74 deletions(-) diff --git a/learn/advanced/asynchronous_operations.md b/learn/advanced/asynchronous_operations.md index 25805b03df..4fce55cde8 100644 --- a/learn/advanced/asynchronous_operations.md +++ b/learn/advanced/asynchronous_operations.md @@ -24,7 +24,7 @@ Currently, these are Meilisearch's asynchronous operations: ## Understanding tasks -Most of Meilisearch's asynchronous operations belong to a category called "tasks". After you have requested an asynchronous operation, you can use the [task API](/reference/api/tasks.md) to find the detailed status of your request. To do so, you will need your task's `uid`. +Most of Meilisearch's asynchronous operations belong to a category called "tasks". After you have requested an asynchronous operation, you can use the [task API](/reference/api/tasks.md) to find the detailed status of your request. To do so, you will need the task's unique identifier. ### Response @@ -51,13 +51,13 @@ All asynchronous operations return a summarized version of the [`task` object](# | Field | Type | Description | |--------------|---------|---------------------------------------------------------------------------------------| -| `uid` | integer | Unique sequential identifier | +| `taskUid` | integer | Unique sequential identifier | | `indexUid` | string | Unique index identifier | | `status` | string | Status of the task. Value is `enqueued` | | `type` | string | Type of task | | `enqueuedAt` | string | Represents the date and time in the RFC 3339 format when the task has been `enqueued` | -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). ### Task `status` @@ -70,9 +70,9 @@ Task responses always contain a field indicating the request's current `status`. ### Examples -Suppose you add a new document to your instance using the [add documents endpoint](/reference/api/documents.md#add-or-replace-documents) and receive a `uid` in response. +Suppose you add a new document to your instance using the [add documents endpoint](/reference/api/documents.md#add-or-replace-documents) and receive a `taskUid` in response. -When you query the task endpoint using this `uid`, you see that it has been enqueued: +When you query the [get task endpoint](/reference/api/tasks.md#get-one-task) using this value, you see that it has been enqueued: ```json { diff --git a/learn/advanced/updating.md b/learn/advanced/updating.md index 508f2a2969..123a2dd904 100644 --- a/learn/advanced/updating.md +++ b/learn/advanced/updating.md @@ -138,7 +138,7 @@ If it's something else, then you need to use the [reset displayed attributes end -This command returns a `uid`. You can use this to [track the status of the operation](/reference/api/tasks.md#get-task). Once the status is `succeeded`, you're good to go. +This command returns a `taskUid`. You can use this to [track the status of the operation](/reference/api/tasks.md#get-one-task). Once the status is `succeeded`, you're good to go. Now that all fields are displayed, proceed to the next step. @@ -262,11 +262,20 @@ Since these versions predate the [dumps feature](/learn/advanced/dumps.md), the In this guide, we will: -1. [Save your settings](#step-1-save-your-settings) -2. [Set all fields as displayed attributes](#step-2-set-all-fields-as-displayed-attributes) -3. [Save your documents](#step-3-save-your-documents) -4. [Delete the database folder](#step-4-delete-the-database-folder) -5. [Upload your data to the latest version of Meilisearch](#step-5-upload-your-data-to-the-latest-version-of-meilisearch) +- [Update to the latest Meilisearch version](#update-to-the-latest-meilisearch-version) + - [Verify your database version](#verify-your-database-version) + - [Proceed according to your database version](#proceed-according-to-your-database-version) + - [Updating from v0.15.0 or above](#updating-from-v0150-or-above) + - [Step 1: Set all fields as displayed attributes](#step-1-set-all-fields-as-displayed-attributes) + - [Step 2: Create the dump](#step-2-create-the-dump) + - [Step 3: Delete the database folder](#step-3-delete-the-database-folder) + - [Step 4: Import the dump](#step-4-import-the-dump) + - [Updating from v0.14.0 or below](#updating-from-v0140-or-below) + - [Step 1: Save your settings](#step-1-save-your-settings) + - [Step 2: Set all fields as displayed attributes](#step-2-set-all-fields-as-displayed-attributes) + - [Step 3: Save your documents](#step-3-save-your-documents) + - [Step 4: Delete the database folder](#step-4-delete-the-database-folder) + - [Step 5: Upload your data to the latest version of Meilisearch](#step-5-upload-your-data-to-the-latest-version-of-meilisearch) If you don’t need to preserve index settings, skip directly to [step two](#step-2-set-all-fields-as-displayed-attributes). diff --git a/learn/getting_started/quick_start.md b/learn/getting_started/quick_start.md index da67fabda2..79526e9e12 100644 --- a/learn/getting_started/quick_start.md +++ b/learn/getting_started/quick_start.md @@ -188,7 +188,7 @@ The previous command added documents from `movies.json` to a new index called `m ```json { - "uid": 0, + "taskUid": 0, "indexUid": "movies", "status": "enqueued", "type": "documentAdditionOrUpdate", @@ -198,7 +198,7 @@ The previous command added documents from `movies.json` to a new index called `m Most database operations in Meilisearch are [asynchronous](/learn/advanced/asynchronous_operations.md). This means that rather than being processed instantly, **API requests are added to a queue and processed one at a time**. -Use the returned `uid` to [check the status](/reference/api/tasks.md) of your documents: +Use the returned `taskUid` to [check the status](/reference/api/tasks.md) of your documents: diff --git a/reference/api/displayed_attributes.md b/reference/api/displayed_attributes.md index 99f1448be2..6c9cf113ae 100644 --- a/reference/api/displayed_attributes.md +++ b/reference/api/displayed_attributes.md @@ -62,7 +62,7 @@ An array of strings that contains attributes of an index to display. ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "settingsUpdate", @@ -70,7 +70,7 @@ An array of strings that contains attributes of an index to display. } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). ## Reset displayed attributes @@ -90,7 +90,7 @@ All attributes found in the documents added to the index. ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "settingsUpdate", @@ -98,4 +98,4 @@ All attributes found in the documents added to the index. } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). diff --git a/reference/api/distinct_attribute.md b/reference/api/distinct_attribute.md index f321ff31e2..d8a62e0cbd 100644 --- a/reference/api/distinct_attribute.md +++ b/reference/api/distinct_attribute.md @@ -54,7 +54,7 @@ If the field does not exist, no error will be thrown. ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "settingsUpdate", @@ -62,7 +62,7 @@ If the field does not exist, no error will be thrown. } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). ## Reset distinct attribute @@ -80,7 +80,7 @@ Reset the [distinct attribute](/learn/configuration/settings.md#distinct-attribu ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "settingsUpdate", @@ -88,4 +88,4 @@ Reset the [distinct attribute](/learn/configuration/settings.md#distinct-attribu } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). diff --git a/reference/api/documents.md b/reference/api/documents.md index 59b8e1d441..9b29b89fd5 100644 --- a/reference/api/documents.md +++ b/reference/api/documents.md @@ -113,7 +113,7 @@ The body is composed of a **JSON array** of documents. ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "documentAdditionOrUpdate", @@ -121,7 +121,7 @@ The body is composed of a **JSON array** of documents. } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). ## Add or update documents @@ -168,7 +168,7 @@ The documents are matched because they have the same [primary key](/learn/core_c ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "documentAdditionOrUpdate", @@ -176,7 +176,7 @@ The documents are matched because they have the same [primary key](/learn/core_c } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). ## Delete all documents @@ -192,7 +192,7 @@ Delete all documents in the specified index. The index [`uid`](/learn/core_conce ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "documentDeletion", @@ -200,7 +200,7 @@ Delete all documents in the specified index. The index [`uid`](/learn/core_conce } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). ## Delete one document @@ -216,7 +216,7 @@ Delete one document based on its unique id. Both the index [`uid`](/learn/core_c ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "documentDeletion", @@ -224,7 +224,7 @@ Delete one document based on its unique id. Both the index [`uid`](/learn/core_c } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). ## Delete documents by batch @@ -248,7 +248,7 @@ The body must be a **JSON Array** with the unique id's of the documents to delet ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "documentDeletion", @@ -256,4 +256,4 @@ The body must be a **JSON Array** with the unique id's of the documents to delet } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). diff --git a/reference/api/filterable_attributes.md b/reference/api/filterable_attributes.md index d91d4ba5bb..31178a9fa5 100644 --- a/reference/api/filterable_attributes.md +++ b/reference/api/filterable_attributes.md @@ -54,7 +54,7 @@ An array of strings containing the attributes that can be used as filters at que ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "settingsUpdate", @@ -62,7 +62,7 @@ An array of strings containing the attributes that can be used as filters at que } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). ## Reset filterable attributes @@ -82,7 +82,7 @@ An empty array (`[]`). ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "settingsUpdate", @@ -90,4 +90,4 @@ An empty array (`[]`). } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). diff --git a/reference/api/indexes.md b/reference/api/indexes.md index 4b108640d0..36966d667e 100644 --- a/reference/api/indexes.md +++ b/reference/api/indexes.md @@ -100,7 +100,7 @@ Creating an index is an asynchronous task. [You can read more about asynchronous ```json { - "uid": 0, + "taskUid": 0, "indexUid": "movies", "status": "enqueued", "type": "indexCreation", @@ -108,7 +108,7 @@ Creating an index is an asynchronous task. [You can read more about asynchronous } ``` -You can use the response's `uid` to [track the status of your request](/reference/api/tasks.md#get-task). +You can use the response's `taskUid` to [track the status of your request](/reference/api/tasks.md#get-task). ## Update an index @@ -140,7 +140,7 @@ This is an asynchronous task. [You can read more about asynchronous operations i ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "indexUpdate", @@ -148,7 +148,7 @@ This is an asynchronous task. [You can read more about asynchronous operations i } ``` -You can use the response's `uid` to [track the status of your request](/reference/api/tasks.md#get-task). +You can use the response's `taskUid` to [track the status of your request](/reference/api/tasks.md#get-task). ## Delete an index @@ -166,7 +166,7 @@ This is an asynchronous task. [You can read more about asynchronous operations i ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "indexDeletion", @@ -174,4 +174,4 @@ This is an asynchronous task. [You can read more about asynchronous operations i } ``` -You can use the response's `uid` to [track the status of your request](/reference/api/tasks.md#get-task). +You can use the response's `taskUid` to [track the status of your request](/reference/api/tasks.md#get-task). diff --git a/reference/api/overview.md b/reference/api/overview.md index 656d76a7d5..54a9e18514 100644 --- a/reference/api/overview.md +++ b/reference/api/overview.md @@ -81,7 +81,7 @@ Meilisearch is an **asynchronous API**. This means that in response to most writ ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "indexUpdate", @@ -89,6 +89,6 @@ Meilisearch is an **asynchronous API**. This means that in response to most writ } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). See more information about [asynchronous operations](/learn/advanced/asynchronous_operations.md). diff --git a/reference/api/ranking_rules.md b/reference/api/ranking_rules.md index ae25f32d4d..802475226c 100644 --- a/reference/api/ranking_rules.md +++ b/reference/api/ranking_rules.md @@ -68,7 +68,7 @@ To add your own ranking rule, you have to communicate an attribute followed by a ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "settingsUpdate", @@ -76,7 +76,7 @@ To add your own ranking rule, you have to communicate an attribute followed by a } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). ## Reset ranking rules @@ -112,7 +112,7 @@ An array that contains the [built-in ranking rules](/learn/core_concepts/relevan ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "settingsUpdate", @@ -120,4 +120,4 @@ An array that contains the [built-in ranking rules](/learn/core_concepts/relevan } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). diff --git a/reference/api/searchable_attributes.md b/reference/api/searchable_attributes.md index 47e82d0d02..47c23fb47b 100644 --- a/reference/api/searchable_attributes.md +++ b/reference/api/searchable_attributes.md @@ -65,7 +65,7 @@ A match in title will make a document more relevant than another document with a ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "settingsUpdate", @@ -73,7 +73,7 @@ A match in title will make a document more relevant than another document with a } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). ## Reset searchable attributes @@ -93,7 +93,7 @@ All attributes found in the documents added to the index. ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "settingsUpdate", @@ -101,4 +101,4 @@ All attributes found in the documents added to the index. } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). diff --git a/reference/api/settings.md b/reference/api/settings.md index 2d22e9b45b..0cc23a4240 100644 --- a/reference/api/settings.md +++ b/reference/api/settings.md @@ -137,7 +137,7 @@ If the provided index does not exist, it will be created. ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "settingsUpdate", @@ -145,7 +145,7 @@ If the provided index does not exist, it will be created. } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). ## Reset settings @@ -176,7 +176,7 @@ All settings will be reset to their default value. ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "settingsUpdate", @@ -184,4 +184,4 @@ All settings will be reset to their default value. } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). diff --git a/reference/api/sortable_attributes.md b/reference/api/sortable_attributes.md index 3c36dc3ddc..f288ec10b1 100644 --- a/reference/api/sortable_attributes.md +++ b/reference/api/sortable_attributes.md @@ -55,7 +55,7 @@ An array of strings containing the attributes that can be used to sort search re ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "settingsUpdate", @@ -63,7 +63,7 @@ An array of strings containing the attributes that can be used to sort search re } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). ## Reset sortable attributes @@ -83,7 +83,7 @@ An empty array (`[]`). ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "settingsUpdate", @@ -91,4 +91,4 @@ An empty array (`[]`). } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). diff --git a/reference/api/stop_words.md b/reference/api/stop_words.md index d5bcd1b5f2..c4043139bc 100644 --- a/reference/api/stop_words.md +++ b/reference/api/stop_words.md @@ -58,7 +58,7 @@ If a list of stop-words already exists it will be overwritten (_replaced_). ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "settingsUpdate", @@ -66,7 +66,7 @@ If a list of stop-words already exists it will be overwritten (_replaced_). } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). ## Reset stop-words @@ -86,7 +86,7 @@ Empty array: `[]` ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "settingsUpdate", @@ -94,4 +94,4 @@ Empty array: `[]` } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). diff --git a/reference/api/synonyms.md b/reference/api/synonyms.md index f5cfb91136..3001b83405 100644 --- a/reference/api/synonyms.md +++ b/reference/api/synonyms.md @@ -60,7 +60,7 @@ An object that contains all synonyms and their associated words. ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "settingsUpdate", @@ -68,7 +68,7 @@ An object that contains all synonyms and their associated words. } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). ## Reset synonyms @@ -88,7 +88,7 @@ Empty object : `{}` ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "settingsUpdate", @@ -96,4 +96,4 @@ Empty object : `{}` } ``` -You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). diff --git a/reference/api/typo_tolerance.md b/reference/api/typo_tolerance.md index 4c686f6f84..1c9a224b22 100644 --- a/reference/api/typo_tolerance.md +++ b/reference/api/typo_tolerance.md @@ -107,7 +107,7 @@ An array of attributes for which the typo tolerance feature is disabled. ```json { - "uid": 1, + "taskUid": 1, "indexUid": "books", "status": "enqueued", "type": "settingsUpdate", @@ -115,7 +115,7 @@ An array of attributes for which the typo tolerance feature is disabled. } ``` -You can use the returned `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). ## Reset typo tolerance @@ -129,7 +129,7 @@ Reset an index's typo tolerance settings to their default value. The index [`uid ```json { - "uid": 1, + "taskUid": 1, "indexUid": "books", "status": "enqueued", "type": "settingsUpdate", @@ -137,4 +137,4 @@ Reset an index's typo tolerance settings to their default value. The index [`uid } ``` -You can use the returned `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). diff --git a/resources/faq.md b/resources/faq.md index 6608903dd5..15d42b41f0 100644 --- a/resources/faq.md +++ b/resources/faq.md @@ -55,7 +55,7 @@ All asynchronous operations return a summarized version of the [`task` object](/ ```json { - "uid": 1, + "taskUid": 1, "indexUid": "movies", "status": "enqueued", "type": "documentAdditionOrUpdate", @@ -63,7 +63,7 @@ All asynchronous operations return a summarized version of the [`task` object](/ } ``` -This response indicates that the operation has been taken into account and will be processed once it reaches the front of the queue. You can use this `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +This response indicates that the operation has been taken into account and will be processed once it reaches the front of the queue. You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). ## I am trying to add my documents but I keep receiving a `400 - Bad Request` response. @@ -151,7 +151,7 @@ See more [information about the primary key](/learn/core_concepts/primary_key.md ## I have uploaded my documents, but I get no result when I search in my index. -Your document upload probably failed. To understand why, please check the status of the document addition task using the `uid`. If the task failed, the response should contain an `error` object. +Your document upload probably failed. To understand why, please check the status of the document addition task using the returned `taskUid`. If the task failed, the response should contain an `error` object. Here is an example of a failed task: From 534fddb4334613e346bee0f0885ca6ce18a6830e Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Mon, 20 Jun 2022 18:37:54 +0200 Subject: [PATCH 036/150] Fix links --- learn/advanced/asynchronous_operations.md | 4 ++-- reference/api/displayed_attributes.md | 4 ++-- reference/api/distinct_attribute.md | 4 ++-- reference/api/documents.md | 10 +++++----- reference/api/filterable_attributes.md | 4 ++-- reference/api/indexes.md | 6 +++--- reference/api/keys.md | 2 +- reference/api/overview.md | 2 +- reference/api/ranking_rules.md | 4 ++-- reference/api/searchable_attributes.md | 4 ++-- reference/api/settings.md | 4 ++-- reference/api/sortable_attributes.md | 4 ++-- reference/api/stop_words.md | 4 ++-- reference/api/synonyms.md | 4 ++-- reference/api/typo_tolerance.md | 4 ++-- resources/faq.md | 2 +- 16 files changed, 33 insertions(+), 33 deletions(-) diff --git a/learn/advanced/asynchronous_operations.md b/learn/advanced/asynchronous_operations.md index 4fce55cde8..da66d11ae4 100644 --- a/learn/advanced/asynchronous_operations.md +++ b/learn/advanced/asynchronous_operations.md @@ -57,7 +57,7 @@ All asynchronous operations return a summarized version of the [`task` object](# | `type` | string | Type of task | | `enqueuedAt` | string | Represents the date and time in the RFC 3339 format when the task has been `enqueued` | -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). ### Task `status` @@ -140,7 +140,7 @@ Had the task failed, the response would have included an `error` object: 1. When you make a task request, Meilisearch puts it in the task queue, sets the task's `status` to `enqueued` and returns a [`task` object](/learn/advanced/asynchronous_operations.md#response) 2. When your task reaches the front of the queue, Meilisearch begins working on it and changes the request `status` to `processing` 3. Once the task has completed processing, Meilisearch marks it as `succeeded`, if it was successful, or `failed`, if there was an error. -4. Tasks marked as `succeeded` or `failed` are not deleted and will remain visible in [the task list](/reference/api/tasks.md#get-all-tasks) +4. Tasks marked as `succeeded` or `failed` are not deleted and will remain visible in [the task list](/reference/api/tasks.md#get-tasks) ### Dumps diff --git a/reference/api/displayed_attributes.md b/reference/api/displayed_attributes.md index 6c9cf113ae..97761ae830 100644 --- a/reference/api/displayed_attributes.md +++ b/reference/api/displayed_attributes.md @@ -70,7 +70,7 @@ An array of strings that contains attributes of an index to display. } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). ## Reset displayed attributes @@ -98,4 +98,4 @@ All attributes found in the documents added to the index. } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). diff --git a/reference/api/distinct_attribute.md b/reference/api/distinct_attribute.md index d8a62e0cbd..5fc1983993 100644 --- a/reference/api/distinct_attribute.md +++ b/reference/api/distinct_attribute.md @@ -62,7 +62,7 @@ If the field does not exist, no error will be thrown. } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). ## Reset distinct attribute @@ -88,4 +88,4 @@ Reset the [distinct attribute](/learn/configuration/settings.md#distinct-attribu } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). diff --git a/reference/api/documents.md b/reference/api/documents.md index 9b29b89fd5..67b263af2a 100644 --- a/reference/api/documents.md +++ b/reference/api/documents.md @@ -121,7 +121,7 @@ The body is composed of a **JSON array** of documents. } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). ## Add or update documents @@ -176,7 +176,7 @@ The documents are matched because they have the same [primary key](/learn/core_c } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). ## Delete all documents @@ -200,7 +200,7 @@ Delete all documents in the specified index. The index [`uid`](/learn/core_conce } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). ## Delete one document @@ -224,7 +224,7 @@ Delete one document based on its unique id. Both the index [`uid`](/learn/core_c } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). ## Delete documents by batch @@ -256,4 +256,4 @@ The body must be a **JSON Array** with the unique id's of the documents to delet } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). diff --git a/reference/api/filterable_attributes.md b/reference/api/filterable_attributes.md index 31178a9fa5..8ee65a221f 100644 --- a/reference/api/filterable_attributes.md +++ b/reference/api/filterable_attributes.md @@ -62,7 +62,7 @@ An array of strings containing the attributes that can be used as filters at que } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). ## Reset filterable attributes @@ -90,4 +90,4 @@ An empty array (`[]`). } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). diff --git a/reference/api/indexes.md b/reference/api/indexes.md index 36966d667e..4e6bb3ef6f 100644 --- a/reference/api/indexes.md +++ b/reference/api/indexes.md @@ -108,7 +108,7 @@ Creating an index is an asynchronous task. [You can read more about asynchronous } ``` -You can use the response's `taskUid` to [track the status of your request](/reference/api/tasks.md#get-task). +You can use the response's `taskUid` to [track the status of your request](/reference/api/tasks.md#get-one-task). ## Update an index @@ -148,7 +148,7 @@ This is an asynchronous task. [You can read more about asynchronous operations i } ``` -You can use the response's `taskUid` to [track the status of your request](/reference/api/tasks.md#get-task). +You can use the response's `taskUid` to [track the status of your request](/reference/api/tasks.md#get-one-task). ## Delete an index @@ -174,4 +174,4 @@ This is an asynchronous task. [You can read more about asynchronous operations i } ``` -You can use the response's `taskUid` to [track the status of your request](/reference/api/tasks.md#get-task). +You can use the response's `taskUid` to [track the status of your request](/reference/api/tasks.md#get-one-task). diff --git a/reference/api/keys.md b/reference/api/keys.md index a6582e1f69..8716a20d18 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -170,7 +170,7 @@ A list of API actions permitted for the key. `["*"]` for all actions. | indexes.get | Provides access to the [get one index](/reference/api/indexes.md#get-one-index) and [list all indexes](/reference/api/indexes.md#list-all-indexes) endpoints. **Non-authorized `indexes` will be omitted from the response**. | | indexes.update | Provides access to the [update index](/reference/api/indexes.md#update-an-index) endpoint. | | indexes.delete | Provides access to the [delete index](/reference/api/indexes.md#delete-an-index) endpoint. | -| tasks.get | Provides access to the [get one task](/reference/api/tasks.md#get-task) and [get all tasks](/reference/api/tasks.md#get-all-tasks) endpoints. **Tasks from non-authorized `indexes` will be omitted from the response**. Also provides access to the [get one task by index](/reference/api/tasks.md#get-task-by-index) and [get all tasks by index](/reference/api/tasks.md#get-all-tasks-by-index) endpoints on authorized indexes. | +| tasks.get | Provides access to the [get one task](/reference/api/tasks.md#get-one-task) and [get tasks](/reference/api/tasks.md#get-tasks) endpoints. **Tasks from non-authorized `indexes` will be omitted from the response**. | | settings.get | Provides access to the [get settings](/reference/api/settings.md#get-settings) endpoint and equivalents for all subroutes on authorized indexes. | | settings.update | Provides access to the [update settings](/reference/api/settings.md#update-settings) and [reset settings](/reference/api/settings.md#reset-settings) endpoints and equivalents for all subroutes on authorized indexes. | | stats.get | Provides access to the [get stats of an index](/reference/api/stats.md#get-stats-of-an-index) endpoint and the [get stats of all indexes](/reference/api/stats.md#get-stats-of-all-indexes) endpoint. For the latter, **non-authorized `indexes` are omitted from the response**. | diff --git a/reference/api/overview.md b/reference/api/overview.md index 54a9e18514..5b1d8b8f69 100644 --- a/reference/api/overview.md +++ b/reference/api/overview.md @@ -89,6 +89,6 @@ Meilisearch is an **asynchronous API**. This means that in response to most writ } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). See more information about [asynchronous operations](/learn/advanced/asynchronous_operations.md). diff --git a/reference/api/ranking_rules.md b/reference/api/ranking_rules.md index 802475226c..1b2228ec16 100644 --- a/reference/api/ranking_rules.md +++ b/reference/api/ranking_rules.md @@ -76,7 +76,7 @@ To add your own ranking rule, you have to communicate an attribute followed by a } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). ## Reset ranking rules @@ -120,4 +120,4 @@ An array that contains the [built-in ranking rules](/learn/core_concepts/relevan } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). diff --git a/reference/api/searchable_attributes.md b/reference/api/searchable_attributes.md index 47c23fb47b..75a4613232 100644 --- a/reference/api/searchable_attributes.md +++ b/reference/api/searchable_attributes.md @@ -73,7 +73,7 @@ A match in title will make a document more relevant than another document with a } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). ## Reset searchable attributes @@ -101,4 +101,4 @@ All attributes found in the documents added to the index. } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). diff --git a/reference/api/settings.md b/reference/api/settings.md index 0cc23a4240..512e608eb1 100644 --- a/reference/api/settings.md +++ b/reference/api/settings.md @@ -145,7 +145,7 @@ If the provided index does not exist, it will be created. } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). ## Reset settings @@ -184,4 +184,4 @@ All settings will be reset to their default value. } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). diff --git a/reference/api/sortable_attributes.md b/reference/api/sortable_attributes.md index f288ec10b1..6a74d071eb 100644 --- a/reference/api/sortable_attributes.md +++ b/reference/api/sortable_attributes.md @@ -63,7 +63,7 @@ An array of strings containing the attributes that can be used to sort search re } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). ## Reset sortable attributes @@ -91,4 +91,4 @@ An empty array (`[]`). } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). diff --git a/reference/api/stop_words.md b/reference/api/stop_words.md index c4043139bc..f551799fef 100644 --- a/reference/api/stop_words.md +++ b/reference/api/stop_words.md @@ -66,7 +66,7 @@ If a list of stop-words already exists it will be overwritten (_replaced_). } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). ## Reset stop-words @@ -94,4 +94,4 @@ Empty array: `[]` } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). diff --git a/reference/api/synonyms.md b/reference/api/synonyms.md index 3001b83405..64fa1728c6 100644 --- a/reference/api/synonyms.md +++ b/reference/api/synonyms.md @@ -68,7 +68,7 @@ An object that contains all synonyms and their associated words. } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). ## Reset synonyms @@ -96,4 +96,4 @@ Empty object : `{}` } ``` -You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). diff --git a/reference/api/typo_tolerance.md b/reference/api/typo_tolerance.md index 1c9a224b22..e03a627339 100644 --- a/reference/api/typo_tolerance.md +++ b/reference/api/typo_tolerance.md @@ -115,7 +115,7 @@ An array of attributes for which the typo tolerance feature is disabled. } ``` -You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). ## Reset typo tolerance @@ -137,4 +137,4 @@ Reset an index's typo tolerance settings to their default value. The index [`uid } ``` -You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). diff --git a/resources/faq.md b/resources/faq.md index 15d42b41f0..5ae96febe2 100644 --- a/resources/faq.md +++ b/resources/faq.md @@ -63,7 +63,7 @@ All asynchronous operations return a summarized version of the [`task` object](/ } ``` -This response indicates that the operation has been taken into account and will be processed once it reaches the front of the queue. You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +This response indicates that the operation has been taken into account and will be processed once it reaches the front of the queue. You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). ## I am trying to add my documents but I keep receiving a `400 - Bad Request` response. From cf183765c48b2653be4ab542b9377f2cbb6e6306 Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Mon, 20 Jun 2022 19:20:00 +0200 Subject: [PATCH 037/150] Tasks: add get tasks by index example in filtering section Also delete code sample related to removed get one task by index endpoint. --- .code-samples.meilisearch.yaml | 5 +---- .vuepress/public/sample-template.yaml | 1 - reference/api/tasks.md | 16 +++++----------- 3 files changed, 6 insertions(+), 16 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 047cb60b9f..483320d012 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -79,9 +79,6 @@ search_post_1: |- search_get_1: |- curl \ -X GET 'http://localhost:7700/indexes/movies/search?q=american%20ninja' -get_task_by_index_1: |- - curl \ - -X GET 'http://localhost:7700/indexes/movies/tasks/1' get_all_tasks_1: |- curl \ -X GET 'http://localhost:7700/tasks' @@ -90,7 +87,7 @@ get_task_1: |- -X GET 'http://localhost:7700/tasks/1' get_all_tasks_by_index_1: |- curl \ - -X GET 'http://localhost:7700/indexes/movies/tasks' + -X GET 'http://localhost:7700/tasks?indexUid=movies' get_one_key_1: |- curl \ -X GET 'http://localhost:7700/keys/d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4' \ diff --git a/.vuepress/public/sample-template.yaml b/.vuepress/public/sample-template.yaml index 8b52eec657..c8498f22df 100644 --- a/.vuepress/public/sample-template.yaml +++ b/.vuepress/public/sample-template.yaml @@ -16,7 +16,6 @@ delete_all_documents_1: |- delete_one_document_1: |- delete_documents_1: |- search_post_1: |- -get_task_by_index_1: |- get_all_tasks_1: |- get_task_1: |- get_all_tasks_by_index_1: |- diff --git a/reference/api/tasks.md b/reference/api/tasks.md index 2774d11362..17e8ef9fd7 100644 --- a/reference/api/tasks.md +++ b/reference/api/tasks.md @@ -23,22 +23,16 @@ Task results are paginated and can be filtered. ### Filtering tasks -You can filter the task list by the value of the `status`, `type`, or `indexUid` fields. For example, this command would return only `enqueued` tasks: +You can filter the task list by the value of the `status`, `type`, or `indexUid` fields. For example, the following command returns all tasks belonging to the index `movies`: -```bash -curl -X GET 'http://localhost:7700/tasks?status=enqueued' -``` - -Use the ampersand character `&` to combine filters, equivalent to a logical `AND`. For example, the following command would return all `succeeded` tasks that also belong to the `movies` index: + -```bash -curl -X GET 'http://localhost:7700/tasks?status=succeeded&indexUid=movies' -``` +Use the ampersand character `&` to combine filters, equivalent to a logical `AND`. Use the comma character `,` to add multiple filter values for a single field. -Use the comma character `,` to add multiple filter values for a single field. For example, to get all tasks whose `type` is either `settingsUpdate` or `documentAdditionOrUpdate`, you would run the following command: +For example, the following command would return all `documentAdditionOrUpdate` tasks that either `succeeded` or `failed`: ```bash -curl -X GET 'http://localhost:7700/tasks?type=settingsUpdate,documentAdditionOrUpdate' +curl -X GET 'http://localhost:7700/tasks?status=succeeded,failed&type=documentAdditionOrUpdate' ``` [Read more about the possible values of these fields in our asynchronous operations guide.](/learn/advanced/asynchronous_operations.md) From 392266f0b2b82e9e473863ec3734cce1ae9ef2bd Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Mon, 20 Jun 2022 19:40:19 +0200 Subject: [PATCH 038/150] Fix updating guide table of contents --- learn/advanced/updating.md | 19 +++++-------------- 1 file changed, 5 insertions(+), 14 deletions(-) diff --git a/learn/advanced/updating.md b/learn/advanced/updating.md index 123a2dd904..ea1809bbe0 100644 --- a/learn/advanced/updating.md +++ b/learn/advanced/updating.md @@ -262,20 +262,11 @@ Since these versions predate the [dumps feature](/learn/advanced/dumps.md), the In this guide, we will: -- [Update to the latest Meilisearch version](#update-to-the-latest-meilisearch-version) - - [Verify your database version](#verify-your-database-version) - - [Proceed according to your database version](#proceed-according-to-your-database-version) - - [Updating from v0.15.0 or above](#updating-from-v0150-or-above) - - [Step 1: Set all fields as displayed attributes](#step-1-set-all-fields-as-displayed-attributes) - - [Step 2: Create the dump](#step-2-create-the-dump) - - [Step 3: Delete the database folder](#step-3-delete-the-database-folder) - - [Step 4: Import the dump](#step-4-import-the-dump) - - [Updating from v0.14.0 or below](#updating-from-v0140-or-below) - - [Step 1: Save your settings](#step-1-save-your-settings) - - [Step 2: Set all fields as displayed attributes](#step-2-set-all-fields-as-displayed-attributes) - - [Step 3: Save your documents](#step-3-save-your-documents) - - [Step 4: Delete the database folder](#step-4-delete-the-database-folder) - - [Step 5: Upload your data to the latest version of Meilisearch](#step-5-upload-your-data-to-the-latest-version-of-meilisearch) +1. [Save your settings](#step-1-save-your-settings) +2. [Set all fields as displayed attributes](#step-2-set-all-fields-as-displayed-attributes) +3. [Save your documents](#step-3-save-your-documents) +4. [Delete the database folder](#step-4-delete-the-database-folder) +5. [Upload your data to the latest version of Meilisearch](#step-5-upload-your-data-to-the-latest-version-of-meilisearch) If you don’t need to preserve index settings, skip directly to [step two](#step-2-set-all-fields-as-displayed-attributes). From 2212f10c6af287ca50a1df8638ee30d66728b78f Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Tue, 21 Jun 2022 14:34:37 +0200 Subject: [PATCH 039/150] Small improvements to asynchronous operations --- learn/advanced/asynchronous_operations.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/learn/advanced/asynchronous_operations.md b/learn/advanced/asynchronous_operations.md index da66d11ae4..7ade6102c4 100644 --- a/learn/advanced/asynchronous_operations.md +++ b/learn/advanced/asynchronous_operations.md @@ -10,9 +10,6 @@ For example, updating the `filterableAttributes` index setting will require as m Currently, these are Meilisearch's asynchronous operations: -- Updating index settings -- Adding documents to an index -- Updating documents in an index - Creating an index - Updating an index - Deleting an index @@ -24,9 +21,9 @@ Currently, these are Meilisearch's asynchronous operations: ## Understanding tasks -Most of Meilisearch's asynchronous operations belong to a category called "tasks". After you have requested an asynchronous operation, you can use the [task API](/reference/api/tasks.md) to find the detailed status of your request. To do so, you will need the task's unique identifier. +At this time, all of Meilisearch's asynchronous operations belong to a category called "tasks". After you have requested an asynchronous operation, you can use the [task API](/reference/api/tasks.md) to find the detailed status of your request. To do so, you will need the task's unique identifier. -### Response +### Task API response The response from the [task API](/reference/api/tasks.md) will always include the following fields in the stated order: @@ -137,7 +134,7 @@ Had the task failed, the response would have included an `error` object: ## Task workflow -1. When you make a task request, Meilisearch puts it in the task queue, sets the task's `status` to `enqueued` and returns a [`task` object](/learn/advanced/asynchronous_operations.md#response) +1. When you make an [asynchronous request](#which-operations-are-async), Meilisearch puts it in the task queue, sets the task's `status` to `enqueued` and returns a [summarized `task` object](/learn/advanced/asynchronous_operations.md#summarized-task-objects) 2. When your task reaches the front of the queue, Meilisearch begins working on it and changes the request `status` to `processing` 3. Once the task has completed processing, Meilisearch marks it as `succeeded`, if it was successful, or `failed`, if there was an error. 4. Tasks marked as `succeeded` or `failed` are not deleted and will remain visible in [the task list](/reference/api/tasks.md#get-tasks) @@ -156,8 +153,8 @@ Meilisearch's asynchronous tasks are atomic. This means that all operations conc What happens to an asynchronous operation when Meilisearch is terminated changes depending on the request's `status`: -- `enqueued`: the task will remain enqueued and will be processed as usual once is restarted -- `processing`: there will be no consequences, since no part of the task has been committed to the database. After restarting, will treat the task as `enqueued` +- `enqueued`: the task will remain enqueued and will be processed as usual once Meilisearch has been restarted +- `processing`: there will be no consequences, since no part of the task has been committed to the database. After restarting, the task will be treated as `enqueued` - `succeeded`: there will be no data loss since the request was successfully completed - `failed`: the task failed and nothing has been altered in the database From 0af7a00618814ff6003d3567255fda20d01a9cd0 Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Tue, 21 Jun 2022 14:57:04 +0200 Subject: [PATCH 040/150] Add new error codes, update links --- learn/advanced/asynchronous_operations.md | 2 +- reference/api/error_codes.md | 8 ++++++++ resources/faq.md | 2 +- 3 files changed, 10 insertions(+), 2 deletions(-) diff --git a/learn/advanced/asynchronous_operations.md b/learn/advanced/asynchronous_operations.md index 7ade6102c4..43501d6faa 100644 --- a/learn/advanced/asynchronous_operations.md +++ b/learn/advanced/asynchronous_operations.md @@ -44,7 +44,7 @@ If a task fails due to an error, all error fields will be appended to the task r ### Summarized task objects -All asynchronous operations return a summarized version of the [`task` object](#response). It contains the following fields in the stated order: +All asynchronous operations return a summarized version of [the full `task` object](#task-api-response). It contains the following fields in the stated order: | Field | Type | Description | |--------------|---------|---------------------------------------------------------------------------------------| diff --git a/reference/api/error_codes.md b/reference/api/error_codes.md index 0dcc2b22e9..e2bfc6bb8c 100644 --- a/reference/api/error_codes.md +++ b/reference/api/error_codes.md @@ -168,3 +168,11 @@ The requested task does not exist. Please ensure that you are using the correct ### `invalid_typo_tolerance_min_word_size_for_typos` The `minWordSizeForTypos` object is invalid. The value for both `oneTypo` and `twoTypos` should be between `0` and `255`, and `twoTypos` should be greater or equal to `oneTypo`. + +### `invalid_task_status` + +The requested task status is invalid. Please use one of [these four possible values](/learn/advanced/asynchronous_operations.md#task-status). + +### `invalid_task_type` + +The requested task type is invalid. Please use one of the values defined in our [asynchronous operations guide](/learn/advanced/asynchronous_operations.md#task-api-response). diff --git a/resources/faq.md b/resources/faq.md index 5ae96febe2..f683947224 100644 --- a/resources/faq.md +++ b/resources/faq.md @@ -51,7 +51,7 @@ More datasets and setting configurations are available [in this repository](http ## I did a call to an API route and got an object as a response. What does it mean? -All asynchronous operations return a summarized version of the [`task` object](/learn/advanced/asynchronous_operations.md#response). +All asynchronous operations return a [summarized version of the `task` object](/learn/advanced/asynchronous_operations.md#summarized-task-objects). ```json { From ed6f8c999201d43c72c824d040f782abdbb57967 Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Tue, 21 Jun 2022 17:17:54 +0400 Subject: [PATCH 041/150] Update learn/getting_started/quick_start.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Clémentine Urquizar - curqui --- learn/getting_started/quick_start.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/getting_started/quick_start.md b/learn/getting_started/quick_start.md index 0f7bad107c..fc0ab33600 100644 --- a/learn/getting_started/quick_start.md +++ b/learn/getting_started/quick_start.md @@ -104,7 +104,7 @@ Choose the release you want to use. You can find the full list [here](https://gi In the cloned repository, run the following command to access the most recent version of Meilisearch: ```bash -git checkout v0.28.0 +git checkout stable ``` Finally, update the rust toolchain, compile the project, and execute the binary. From 5b15eb32c404c776ee2d354cdf3fba08151fcbb8 Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Tue, 21 Jun 2022 15:35:38 +0200 Subject: [PATCH 042/150] Incorporate feedback from maryamsulemani97's review --- .code-samples.meilisearch.yaml | 2 +- reference/api/tasks.md | 99 +++++++++++++++++----------------- 2 files changed, 52 insertions(+), 49 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 483320d012..798a6e1f37 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -526,7 +526,7 @@ getting_started_add_documents_md: |- ``` getting_started_check_task_status: |- curl \ - -X GET 'http://localhost:7700/indexes/movies/tasks/0' + -X GET 'http://localhost:7700/tasks/0' getting_started_search_md: |- ```bash curl \ diff --git a/reference/api/tasks.md b/reference/api/tasks.md index 17e8ef9fd7..fb1d3acec5 100644 --- a/reference/api/tasks.md +++ b/reference/api/tasks.md @@ -10,20 +10,62 @@ The task `uid` is incremented **globally.** -List all tasks globally, regardless of index. The `task` objects are contained in the `results` array. Tasks are always returned in descending order of `uid`. +List all tasks globally, regardless of index. The `task` objects are contained in the `results` array. -Task results are paginated and can be filtered. +Tasks are always returned in descending order of `uid`. This means that by default, **the most recently created `task` objects appear first**. + +Task results are [paginated](#paginating-tasks) and can be [filtered](#filtering-tasks). #### Query parameters -| Query Parameter | Description | Default Value | -|-----------------|--------------------------------------|:----------------------------------:| -| **limit** | number of tasks to return | 20 | -| **from** | `uid` of the first task returned | `uid` of the last created task | +| Query Parameter | Description | Default Value | +|-----------------|----------------------------------------------------------------------|:------------------------------:| +| **limit** | number of tasks to return | 20 | +| **from** | `uid` of the first task returned | `uid` of the last created task | +| **status** | [filter tasks](#filtering-tasks) by their `status` | all statuses | +| **type** | [filter tasks](#filtering-tasks) by their `type` | all types | +| **indexUid** | [filter tasks](#filtering-tasks) by their `indexUid`. Case-sensitive | all indexes | + +### Example + + + +#### Response: `200 Ok` + +```json +{ + "results": [ + { + "uid": 1, + "indexUid": "movies_reviews", + "status": "enqueued", + "type": "documentAdditionOrUpdate", + "duration": null, + "enqueuedAt": "2021-08-12T10:00:00.000000Z", + "startedAt": null, + "finishedAt": null + }, + { + "uid": 0, + "indexUid": "movies", + "status": "succeeded", + "type": "documentAdditionOrUpdate", + "details": { + "receivedDocuments": 100, + "indexedDocuments": 100 + }, + "duration": "PT16S", + "enqueuedAt": "2021-08-11T09:25:53.000000Z", + "startedAt": "2021-08-11T10:03:00.000000Z", + "finishedAt": "2021-08-11T10:03:16.000000Z" + } + ] +} +``` ### Filtering tasks -You can filter the task list by the value of the `status`, `type`, or `indexUid` fields. For example, the following command returns all tasks belonging to the index `movies`: +You can filter the task list by the value of the `status`, `type`, or `indexUid` fields. For example, the following command returns all tasks belonging to the index `movies`. Note that the `indexUid` is case-sensitive: @@ -35,6 +77,8 @@ For example, the following command would return all `documentAdditionOrUpdate` t curl -X GET 'http://localhost:7700/tasks?status=succeeded,failed&type=documentAdditionOrUpdate' ``` +At this time, `OR` operations between different filters are not supported. For example, you cannot view only tasks which have a type of `documentAddition` **or** a status of `failed`. + [Read more about the possible values of these fields in our asynchronous operations guide.](/learn/advanced/asynchronous_operations.md) ### Paginating tasks @@ -95,47 +139,6 @@ curl -X GET 'http://localhost:7700/tasks?limit=2&from=8 When the returned value of `next` is `null`, you have reached the final page of results. -### Example - - - -#### Response: `200 Ok` - -```json -{ - "results": [ - { - "uid": 1, - "indexUid": "movies_reviews", - "status": "enqueued", - "type": "documentAdditionOrUpdate", - "duration": null, - "enqueuedAt": "2021-08-12T10:00:00.000000Z", - "startedAt": null, - "finishedAt": null - }, - { - "uid": 0, - "indexUid": "movies", - "status": "succeeded", - "type": "documentAdditionOrUpdate", - "details": { - "receivedDocuments": 100, - "indexedDocuments": 100 - }, - "duration": "PT16S", - "enqueuedAt": "2021-08-11T09:25:53.000000Z", - "startedAt": "2021-08-11T10:03:00.000000Z", - "finishedAt": "2021-08-11T10:03:16.000000Z" - } - ] -} -``` - -:::note -Tasks are displayed in descending order by `uid`. This means that **the most recently created `task` objects appear first**. -::: - ## Get one task From 2536b291d49918a751112f85e59d81749e48256e Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Tue, 21 Jun 2022 16:33:57 +0200 Subject: [PATCH 043/150] Dumps: adjust asynchronous operations page --- learn/advanced/asynchronous_operations.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/learn/advanced/asynchronous_operations.md b/learn/advanced/asynchronous_operations.md index 1b2b32f056..823cd08e48 100644 --- a/learn/advanced/asynchronous_operations.md +++ b/learn/advanced/asynchronous_operations.md @@ -20,7 +20,7 @@ Currently, these are Meilisearch's asynchronous operations: - Adding documents to an index - Updating documents in an index - Deleting documents from an index -- [Creating a dump](#dumps) +- Creating a dump ## Understanding tasks @@ -35,7 +35,7 @@ The response from the [task API](/reference/api/tasks.md) will always include th | `uid` | integer | The unique sequential identifier of the task | | `indexUid` | string | The unique index identifier | | `status` | string | The status of the task. Possible values are `enqueued`, `processing`, `succeeded`, `failed` | -| `type` | string | The type of task. Possible values are `indexCreation`, `indexUpdate`, `indexDeletion`, `documentAddition`, `documentPartial`, `documentDeletion`, `settingsUpdate`, `clearAll` | +| `type` | string | The type of task. Possible values are `indexCreation`, `indexUpdate`, `indexDeletion`, `documentAddition`, `documentPartial`, `documentDeletion`, `settingsUpdate`, `clearAll`, `dumpCreation` | | `details` | object | Detailed information on the task payload | | `error` | object | Error details and context. Only present when a task has the `failed` status | | `duration` | string | The total elapsed time the task spent in the `processing` state, in ISO 8601 format | @@ -142,11 +142,7 @@ Had the task failed, the response would have included an `error` object: 3. Once the task has completed processing, Meilisearch marks it as `succeeded`, if it was successful, or `failed`, if there was an error. 4. Tasks marked as `succeeded` or `failed` are not deleted and will remain visible in [the task list](/reference/api/tasks.md#get-all-tasks) -### Dumps - -While dumps and tasks are both asynchronous operations, they use separate queues and behave differently. For instance, creating a new dump will freeze the task queue until the dump has been generated. - -[You can read more about dumps in our dedicated guide.](/learn/advanced/dumps.md) +Tasks are processed in the order they were enqueued, with one exception: `dumpCreation`. Dumps are prioritized over all other tasks in the queue. Their `uid` still represents when they were enqueued relative to other tasks. ## Terminate Meilisearch while a task is being processed From fe32094bc6e44cc494df39f9c9bfe3f0a1d7bbd2 Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Tue, 21 Jun 2022 18:14:02 +0200 Subject: [PATCH 044/150] Dumps: update API ref --- reference/api/dump.md | 41 +++++++---------------------------------- 1 file changed, 7 insertions(+), 34 deletions(-) diff --git a/reference/api/dump.md b/reference/api/dump.md index b6258b3a7e..1ce1e03442 100644 --- a/reference/api/dump.md +++ b/reference/api/dump.md @@ -14,11 +14,7 @@ Dump imports must be performed when launching a Meilisearch instance [using the -Triggers a dump creation process. Once the process is complete, a dump is created in the [dumps directory](/learn/configuration/instance_options.md#dumps-destination). If the dumps directory does not exist yet, it will be created. - -**Meilisearch only processes one dump at a time.** If you attempt to create a dump while another dump is still processing, Meilisearch will throw a [`dump_already_processing` error](/reference/api/error_codes.md#dump-already-processing). - -The task queue will not process any further tasks during dump creation, but you can still add new requests to the queue. +Triggers a dump creation task. Once the process is complete, a dump is created in the [dumps directory](/learn/configuration/instance_options.md#dumps-destination). If the dumps directory does not exist yet, it will be created. ### Example @@ -28,35 +24,12 @@ The task queue will not process any further tasks during dump creation, but you ```json { - "uid": "20200929-114144097", - "status": "in_progress", - "startedAt": "2020-09-29T11:41:44.392327Z" + "taskUid": 0, + "indexUid": null, + "status": "enqueued", + "type": "dumpCreation", + "enqueuedAt": "2022-06-21T16:10:29.217688Z" } ``` -## Get dump status - - - -Get the status of a dump creation process using the uid returned after calling the [dump creation route](/reference/api/dump.md#create-a-dump). The dump `uid` is required. - -The returned status could be: - -- `in_progress`: Dump creation is in progress -- `failed`: An error occurred during dump process, and the task was aborted -- `done`: Dump creation is finished and was successful - -### Example - - - -#### Response: `200 Ok` - -```json -{ - "uid": "20200929-114144097", - "status": "done", - "startedAt": "2020-09-29T11:41:44.392327Z", - "finishedAt": "2020-09-29T11:41:50.792147Z" -} -``` +You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task) From ca9d7581b69d4b18302b18e432ad16f225d19c36 Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Tue, 21 Jun 2022 18:15:11 +0200 Subject: [PATCH 045/150] Dumps: delete get_dump_status_1 sample --- .code-samples.meilisearch.yaml | 3 --- .vuepress/public/sample-template.yaml | 1 - 2 files changed, 4 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 047cb60b9f..369f39d459 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -672,9 +672,6 @@ faceted_search_walkthrough_filter_1: |- post_dump_1: |- curl \ -X POST 'http://localhost:7700/dumps' -get_dump_status_1: |- - curl \ - -X GET 'http://localhost:7700/dumps/20201101-110357260/status' phrase_search_1: |- curl \ -X POST 'http://localhost:7700/indexes/movies/search' \ diff --git a/.vuepress/public/sample-template.yaml b/.vuepress/public/sample-template.yaml index 8b52eec657..66dcc76f95 100644 --- a/.vuepress/public/sample-template.yaml +++ b/.vuepress/public/sample-template.yaml @@ -94,7 +94,6 @@ faceted_search_facets_distribution_1: |- faceted_search_walkthrough_filter_1: |- add_movies_json_1: |- post_dump_1: |- -get_dump_status_1: |- phrase_search_1: |- sorting_guide_update_sortable_attributes_1: |- sorting_guide_update_ranking_rules_1: |- From f4401c92ea8e22ae4242bf288f61fc753bf33888 Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Tue, 21 Jun 2022 18:18:46 +0200 Subject: [PATCH 046/150] Dumps: delete dump_already_processing error --- reference/api/error_codes.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/reference/api/error_codes.md b/reference/api/error_codes.md index 0dcc2b22e9..3b4e9673ed 100644 --- a/reference/api/error_codes.md +++ b/reference/api/error_codes.md @@ -97,10 +97,6 @@ The Content-Type header does not match the request body payload format or the fo The Content-Type header was specified, but no request body was sent to the server or the request body is empty. -### `dump_already_processing` - -Dump creation is already in progress. A new dump creation process can be triggered after the current one has been completed. - ### `dump_not_found` The requested dump could not be found. From f3f36ec5c67d42bcb7a7e8377023cdc29f024c3c Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Tue, 21 Jun 2022 18:54:42 +0200 Subject: [PATCH 047/150] pagination guide: zeroth draft --- learn/advanced/pagination.md | 125 +++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 learn/advanced/pagination.md diff --git a/learn/advanced/pagination.md b/learn/advanced/pagination.md new file mode 100644 index 0000000000..ac7cd8adf1 --- /dev/null +++ b/learn/advanced/pagination.md @@ -0,0 +1,125 @@ +# Pagination of search results + +In a perfect world, users would not need to look beyond the first search result to find what they were looking for. In practice, this is difficult to achieve due to design constraints, performance trade-offs, and even inneffective query terms. Because of that, it is usually necessary to create a pagination interface so users can browse through long lists of results. + +In this guide, we will discuss some of Meilisearch's current limitations, how these limitations impact common pagination interface patterns, and the recommended way of handling pagination when using Meilisearch. + +## Choosing the right pagination interface + +For performance reasons, Meilisearch cannot provide you with the exact number of possible results for a query. Instead, you can only know the `estimatedTotalHits` when using our search API. As its name indicates, `estimatedTotalHits` is only an estimate of how many documents match your user's query. + +Additionally, Meilisearch is optimized to return the most relevant results as fast as possible. The negative side of this design decision is that queries might become slower the further away we get from the first results. + +Because you cannot know the number of total hits and slower queries the further we move from the first result, we do not recommend creating interfaces with page selectors that allow users to jump to any arbitrary result page. If this type of interface is crucial for your user's search experience, this document's last section lists a number of tips that might help you work around Meilisearch's current limitations. + +Instead of a full page selector, we recommend creating pagination interfaces centered around previous and next buttons. + +::: note +By default, Meilisearch only returns a maximum of 1000 search results. Consult our [index setting reference](/reference/api/settings.md) to know how to change this. +::: + +## Recommended: Previous and next buttons + +Pagination interfaces that rely solely on previous and next buttons are similar to page selectors, but do not allow users to jump to an arbitrary results page. + +![Placeholder image for prev/next interface]() + +Though this approach offers less precision than a full-blown page selector, it does not require knowing the number of total search results. + +### Implementation + +Previous and next buttons can be implemented using the [`limit`](/reference/api/search.md#limit) and [`offset`](/reference/api/search.md#offset) search parameters. + +Paginating requires providing an `offset` that is equal to your `limit` times the page number times: `offset = limit * page number`. + +For example, if you set `limit` to `20` and want the first page of search results, your `offset` must be 0: `offset = 0 * 20`. + +```sh +curl \ + -X POST 'http://localhost:7700/indexes/movies/search' \ + -H 'Content-Type: application/json' \ + --data-binary '{ + "q": "shifu", + "limit": 20, + "offset": 0 + }' +``` + +If you keep the same `limit` and want the third page of results, `offset` must be `40`: `offset = 2 * 20`. + +```sh +curl \ + -X POST 'http://localhost:7700/indexes/movies/search' \ + -H 'Content-Type: application/json' \ + --data-binary '{ + "q": "shifu", + "limit": 20, + "offset": 40 + }' +``` + +As you might have noticed, we start counting page numbers from 0. This means the first page of results is 0, the second page is 1, and so forth. + +It is often helpful to disable navigation buttons when the user cannot move to next or the "previous page. The "previous" button should be disabled whenever your `offset` is 0. + +To disable the "next" button, we recommend setting your `limit` to the number of displayed results plus 1. For example, if you want each page to display 20 search results, set `limit` to 21. If the number of returned items is less than 21, we can safely assume we are in the last page. + +```js +const results = await index.search("x", { limit: 21, offset: 0 }) + +// Previous button +if (offset === 0 ) { + // last page + document.querySelector("#previous_button").disabled +} + +// Next button +if (results.hits.length < limit ) { + // last page + document.querySelector("#next_button").disabled +} +``` + +## Not recommended: Page selection + +As its name states, this type of pagination is made of a numbered list of pages accompanied by next and previous buttons. + +[UI screenshot] + +![](https://vuejsexamples.com/content/images/2018/11/vue-pagination.gif) + +This is a very common type of interface and offers users a significant amount of precision when navigating results. Despite being similar to our recommended pagination solution, the page selector requires knowing the exact number of total matches. This makes it difficult to implement when using Meilisearch. + +### Implementation + +The general implementation of a page selection interface is similar to our recommended solution, using previous and next buttons: you must use the `limit` and `offset` search parameters to set your page size and navigate between search results. + +To create the page list, however, you must know the exact number of total results. For example, if you have 100 results and your search result pages contain 10 results each, your selector must show a list of numbers going from 1 to 10. Meilisearch, however, can only give you an estimate of the total number of search results. + +We recommend two different workarounds to create this kind of pagination interface with Meilisearch. + +#### Set a hard limit of results during your search + +By default, a search request returns 20 search results. You can change this value to a much higher number and treat it as the effective maximum of search results you will show a user. Doing so means the size of your `hits` array is the exact number of search results you have to paginate. + +For example, if you set `limit` to 300, every search request made to Meilisearch returns at most 300 documents. If a query returns a `hits` array with 200 items and you want each page to display 20 results, you can create a page selector with 10 pages. + +This method provides control and reliability. It also prevents users from paginating too far, which avoids performance loss. However, this limits the number of results your users can see. + +::: note +We do not recommend setting high values for `limit` as it can negatively impact performance. +::: + +#### Accept the unreliable number + +You can still use `estimatedTotalHits` to calculate the number of search result pages. This means your page count is likely to change until Meilisearch retrives the last search result. + +For example, a query's `estimatedTotalHits` might be `100` when you fetch the first page of search results. If you are showing 20 results per page, this means your interface will display a page selector with 5 pages. When you fetch the fifth and last page in Meilisearch's current estimate, however, `estimatedTotalHits` might change to `300`. Your page list, previously displaying 5 pages, must now show 10 total pages. + +This method gives users access to all search results. However, it also results in an interface that might occasionally change in front of the user. + +## Unsatisfied? Let us know + +We are actively working on improving Meilisearch pagination. Is our recommended pagination method not suitable for the application you're developing? Is page selection critical for your website? Please let us know in this GitHub discussion. + +Is creating pagination interfaces in Meilisearch for you this is a huge issue, please provide feedback on [this discussion](https://github.com/meilisearch/product/discussions/483). \ No newline at end of file From 5eaa56fd1262783fd88e7faf1c6a2f901c427df0 Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Wed, 22 Jun 2022 12:37:29 +0200 Subject: [PATCH 048/150] Dumps: update guide --- learn/advanced/dumps.md | 61 ++++++++++++++++++++--------------------- 1 file changed, 29 insertions(+), 32 deletions(-) diff --git a/learn/advanced/dumps.md b/learn/advanced/dumps.md index 3e6b067ade..8e31eb22fe 100644 --- a/learn/advanced/dumps.md +++ b/learn/advanced/dumps.md @@ -1,6 +1,8 @@ # Dumps -A dump is a compressed file containing an export of your Meilisearch instance. It contains all your indexes, documents, and settings, but in a raw unprocessed form. A dump isn't an exact copy of your database—it is closer to a blueprint that allows you to create an identical dataset. A dump can be imported when launching Meilisearch, but be advised that it may take some time to index all the documents within. +A dump is a compressed file containing an export of your Meilisearch instance. It contains all your indexes, documents, and settings, but in a raw unprocessed form. A dump isn't an exact copy of your database—it is closer to a blueprint that allows you to create an identical dataset. + +A dump can be imported when launching Meilisearch, but be advised that it may take some time to index. ## Creating a dump @@ -8,57 +10,52 @@ To create a dump of your dataset, you need to use the appropriate HTTP route: [` -The above code triggers a dump creation process. It also returns an object containing information about the dump: +The above code triggers a dump creation process. It also returns a [summarized task object](/learn/advanced/asynchronous_operations.md#summarized-task-objects) that you can use to check the status of your dump. -``` +```json { - "uid": "20200929-114144097", - "status": "in_progress", - "startedAt": "2020-09-29T11:41:44.392327Z" + "taskUid": 1, + "indexUid": null, + "status": "enqueued", + "type": "dumpCreation", + "enqueuedAt": "2022-06-21T16:10:29.217688Z" } ``` -You can use the returned `uid` (unique identifier indicating when the dump was triggered) to track its progress with the [get dump status route](/reference/api/dump.md#get-dump-status). The returned status could be: - -- `in_progress`: Dump creation is in progress -- `failed`: An error occurred during dump process, and the task was aborted -- `done`: Dump creation is finished and was successful +In the below code sample, replace `1` with the `taskUid` returned by the previous command. - + -The above code sample returns an object with the following details about the dump: +This command should return an object with detailed information about the dump operation: -``` +```json { - "uid": "20200929-114144097", - "status": "done", - "startedAt": "2020-09-29T11:41:44.392327Z", - "finishedAt": "2020-09-29T11:41:50.792147Z" + "uid": 1, + "indexUid": null, + "status": "succeeded", + "type": "dumpCreation", + "details": { + "dumpUid": "20220621-161029217" + }, + "duration": "PT0.025872S", + "enqueuedAt": "2022-06-21T16:10:29.217688Z", + "startedAt": "2022-06-21T16:10:29.218297Z", + "finishedAt": "2022-06-21T16:10:29.244169Z" } ``` -After dump creation is finished, the dump file is added to the dump directory. By default, this folder is named `dumps` and can be found in the same directory as your Meilisearch binary. You can customize [this using the `--dumps-dir` configuration option](/learn/configuration/instance_options.md#dumps-destination). **If the dump directory does not already exist when the dump creation process is called, Meilisearch will create it.** +After dump creation is finished—when `status` is `succeeded`—the dump file is added to the dump directory. By default, this folder is named `dumps` and can be found in the same directory as your Meilisearch binary. You can customize [this using the `--dumps-dir` configuration option](/learn/configuration/instance_options.md#dumps-destination). **If the dump directory does not already exist when the dump creation process is called, Meilisearch will create it.** If a dump file is visible in the file system, the dump process was successfully completed. **Meilisearch will never create a partial dump file**, even if you interrupt an instance while it is generating a dump. -::: note -Unlike [tasks](/learn/advanced/asynchronous_operations.md), dumps have no queue. **Meilisearch only processes one dump at a time.** If you attempt to create a dump while another dump is still processing, Meilisearch will throw an [error](/reference/api/error_codes.md#dump-already-processing). - -Meilisearch does not process tasks during dump creation, but you can still add new requests to the task queue. This is also true for [snapshots](/learn/advanced/snapshots.md#snapshots). -::: - -::: warning -If you restart Meilisearch after creating a dump, you will not be able to use the dumps endpoint to find out that dump's `status`. This has no effect on the dump file itself. -::: - ## Importing a dump When a dump is being imported, the API is not available to the task queue. As a result, no read or write operations can be performed until the importing process is complete. -Dumps in v0.20.0 and below are no longer compatible with the new versions. Before you start importing, check your [Meilisearch version](/reference/api/version.md#example) and proceed accordingly. +Dumps from v0.20.0 and below are no longer compatible with the new versions. Before you start importing, check your [Meilisearch version](/reference/api/version.md#example) and proceed accordingly. ::: note -We do not recommend using dumps from a new Meilisearch version to import an older version. +We do not recommend using dumps to migrate from a new Meilisearch version to an older one. For example, you can import a dump from Meilisearch v0.21 into v0.22 without any problems. Importing a dump generated in v0.22 into a v0.21 instance, however, can lead to unexpected behavior. ::: @@ -79,4 +76,4 @@ If you are using Meilisearch v0.20 or below, migration should be done in two ste ## Use cases -Dumps are used to restore your database after [updating Meilisearch](/learn/advanced/updating.md) or to copy your database to other Meilisearch instances without having to worry about their respective versions. +Dumps are used to restore your database after [updating Meilisearch](/learn/advanced/updating.md) or to copy your database to other Meilisearch instances without having to worry about their respective versions. For more on this subject, see a [comparison of snapshots and dumps](/learn/advanced/snapshots_vs_dumps.md). From 41af188fc185b4af93f370e3c1a3018dfadeea4a Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Wed, 22 Jun 2022 12:38:08 +0200 Subject: [PATCH 049/150] Dumps: delete get_dump_status_1 sample --- .code-samples.meilisearch.yaml | 5 ----- .vuepress/public/sample-template.yaml | 1 - 2 files changed, 6 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 369f39d459..bcd14828b9 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -921,11 +921,6 @@ updating_guide_create_dump: |- curl \ -X POST 'http://localhost:7700/dumps' \ -H 'Authorization: Bearer API_KEY' -updating_guide_get_dump_status: |- - # replace {dump_uid} with the uid returned by the previous command - curl \ - -X GET 'http://localhost:7700/dumps/{dump_uid}/status' \ - -H 'Authorization: Bearer API_KEY' updating_guide_get_settings_old: |- # the -o option saves the output as a local file curl \ diff --git a/.vuepress/public/sample-template.yaml b/.vuepress/public/sample-template.yaml index 66dcc76f95..551186075b 100644 --- a/.vuepress/public/sample-template.yaml +++ b/.vuepress/public/sample-template.yaml @@ -139,7 +139,6 @@ updating_guide_get_displayed_attributes_old: |- updating_guide_reset_displayed_attributes_old: |- updating_guide_reset_displayed_attributes_new: |- updating_guide_create_dump: |- -updating_guide_get_dump_status: |- updating_guide_get_settings_old: |- updating_guide_retrieve_documents_old: |- updating_guide_update_settings_old: |- From f59c8950074084bb3fecf6ee9ca430e5e73b706e Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Wed, 22 Jun 2022 12:48:29 +0200 Subject: [PATCH 050/150] Dumps: update response and status retrieval json --- learn/advanced/dumps.md | 2 +- learn/advanced/updating.md | 29 ++++++++++++++++++----------- reference/api/dump.md | 6 +++++- 3 files changed, 24 insertions(+), 13 deletions(-) diff --git a/learn/advanced/dumps.md b/learn/advanced/dumps.md index 8e31eb22fe..7bd1819321 100644 --- a/learn/advanced/dumps.md +++ b/learn/advanced/dumps.md @@ -22,7 +22,7 @@ The above code triggers a dump creation process. It also returns a [summarized t } ``` -In the below code sample, replace `1` with the `taskUid` returned by the previous command. +In the below command, replace `1` with the `taskUid` returned by the previous command. diff --git a/learn/advanced/updating.md b/learn/advanced/updating.md index 508f2a2969..d6ceaaed92 100644 --- a/learn/advanced/updating.md +++ b/learn/advanced/updating.md @@ -206,24 +206,31 @@ The server should return a response that looks like this: ```json { - "uid": "20210212-151153878", - "status": "in_progress", - "startedAt": "2021-02-12T15:11:53.402327Z" + "taskUid": 1, + "indexUid": null, + "status": "enqueued", + "type": "dumpCreation", + "enqueuedAt": "2022-06-21T16:10:29.217688Z" } ``` -This process can take some time. Since dump creation is an [asynchronous operation](/learn/advanced/asynchronous_operations.md), you can use the returned `uid` to [track its status](/reference/api/dump.md#get-dump-status). +This command returns a `taskUid`. You can use this to [track the status](/reference/api/tasks.md#get-one-task) of your dump. Keep in mind that the process can take some time to complete. - - -Once the response to the previous command looks like this (`"status": "done"`), move on. +Once the `dumpCreation` task shows `"status": "succeeded"`, you're ready to move on. ```json { - "uid": "20200929-114144097", - "status": "done", - "startedAt": "2020-09-29T11:41:44.392327Z", - "finishedAt": "2020-09-29T11:41:50.792147Z" + "uid": 1, + "indexUid": null, + "status": "succeeded", + "type": "dumpCreation", + "details": { + "dumpUid": "20220621-161029217" + }, + "duration": "PT0.025872S", + "enqueuedAt": "2022-06-21T16:10:29.217688Z", + "startedAt": "2022-06-21T16:10:29.218297Z", + "finishedAt": "2022-06-21T16:10:29.244169Z" } ``` diff --git a/reference/api/dump.md b/reference/api/dump.md index 1ce1e03442..70c90e562e 100644 --- a/reference/api/dump.md +++ b/reference/api/dump.md @@ -6,16 +6,20 @@ Creating a dump is also referred to as exporting it, whereas launching Meilisear During a [dump export](/reference/api/dump.md#create-a-dump), all indexes of the current instance are exported—together with their documents and settings—and saved as a single `.dump` file. -During a dump import, all indexes contained in the indicated `.dump` file are imported along with their associated documents and settings. Any existing index with the same uid as an index in the dump file will be overwritten. +During a dump import, all indexes contained in the indicated `.dump` file are imported along with their associated documents and settings. Any existing index with the same `uid` as an index in the dump file will be overwritten. Dump imports must be performed when launching a Meilisearch instance [using the `import-dump` command-line option](/learn/configuration/instance_options.md#import-dump). +[Learn more about dumps](/learn/advanced/dumps.md). + ## Create a dump Triggers a dump creation task. Once the process is complete, a dump is created in the [dumps directory](/learn/configuration/instance_options.md#dumps-destination). If the dumps directory does not exist yet, it will be created. +Dump tasks take priority over all other tasks in the queue. This means that a newly created dump task will be processed as soon as the current task is finished. [Learn more about asynchronous operations](/learn/advanced/asynchronous_operations.md). + ### Example From f727adbd6ab8017831b9c381e8a394416213b4e9 Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Wed, 22 Jun 2022 17:11:06 +0400 Subject: [PATCH 051/150] Update keys.md --- reference/api/keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/keys.md b/reference/api/keys.md index 109a484e30..4b2e3ac9ee 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -8,7 +8,7 @@ The `/keys` route allows you to create, manage, and delete API keys. To use thes -List all existing API keys. **Expired keys are included in the response**, but deleted keys are not. +List all existing API keys. **Expired keys are included in the response**, but deleted keys are not. Results can be paginated by using the `offset` and `limit` query parameters. [See below for an explanation of returned fields.](#description) From ab1c001ede9070759b8e453e4b6a68417d235383 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 22 Jun 2022 16:14:28 +0200 Subject: [PATCH 052/150] /documents API reference: address review feedback --- .code-samples.meilisearch.yaml | 2 +- reference/api/documents.md | 15 +++++++++++---- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 047cb60b9f..47b640812b 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -27,7 +27,7 @@ delete_an_index_1: |- -X DELETE 'http://localhost:7700/indexes/movies' get_one_document_1: |- curl \ - -X GET 'http://localhost:7700/indexes/movies/documents/25684' + -X GET 'http://localhost:7700/indexes/movies/documents/25684?fields=id,title,poster,release_date' get_documents_1: |- curl \ -X GET 'http://localhost:7700/indexes/movies/documents?limit=2' diff --git a/reference/api/documents.md b/reference/api/documents.md index 76f75a50bb..908e442047 100644 --- a/reference/api/documents.md +++ b/reference/api/documents.md @@ -10,6 +10,14 @@ The `/documents` route allows you to create, manage, and delete documents. Get one [document](/learn/core_concepts/documents.md) using its unique id. Both the index [`uid`](/learn/core_concepts/indexes.md#index-uid) and [document id](/learn/core_concepts/primary_key.md#document-id) are required. +You can use the optional `fields` query parameter to specify which document fields Meilisearch should include in the response body. `fields` accepts a case-sensitive list of document fields separated by a comma. + +#### Query parameters + +| Query Parameter | Description | Default Value | +| ------------------------ | ------------------------------ | :-----------: | +| **fields** | Document attributes to show | \* | + ### Example @@ -21,7 +29,6 @@ Get one [document](/learn/core_concepts/documents.md) using its unique id. Both "id": 25684, "title": "American Ninja 5", "poster": "https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg", - "overview": "When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.", "release_date": "1993-01-01" } ``` @@ -42,9 +49,9 @@ Documents are ordered by Meilisearch depending on the hash of their id. | Query Parameter | Description | Default Value | | ------------------------ | ------------------------------ | :-----------: | -| **offset** | number of documents to skip | 0 | -| **limit** | number of documents to return | 20 | -| **fields** | document attributes to show | \* | +| **offset** | Number of documents to skip | 0 | +| **limit** | Number of documents to return | 20 | +| **fields** | Document attributes to show | \* | ### Example From 4f76ad2430308914f5f16946b321aea88df5f04d Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 22 Jun 2022 19:50:09 +0200 Subject: [PATCH 053/150] pagination guide: slightly improved draft --- learn/advanced/pagination.md | 90 ++++++++++++++++-------------------- 1 file changed, 41 insertions(+), 49 deletions(-) diff --git a/learn/advanced/pagination.md b/learn/advanced/pagination.md index ac7cd8adf1..8cef0a8b82 100644 --- a/learn/advanced/pagination.md +++ b/learn/advanced/pagination.md @@ -4,18 +4,16 @@ In a perfect world, users would not need to look beyond the first search result In this guide, we will discuss some of Meilisearch's current limitations, how these limitations impact common pagination interface patterns, and the recommended way of handling pagination when using Meilisearch. -## Choosing the right pagination interface +## Choosing the right pagination UI -For performance reasons, Meilisearch cannot provide you with the exact number of possible results for a query. Instead, you can only know the `estimatedTotalHits` when using our search API. As its name indicates, `estimatedTotalHits` is only an estimate of how many documents match your user's query. +For performance reasons, Meilisearch cannot provide the exact number of possible results for a query. When using the search endpoint, responses contain an `estimatedTotalHits` field. As its name indicates, `estimatedTotalHits` is only an estimate of how many documents match your user's query. -Additionally, Meilisearch is optimized to return the most relevant results as fast as possible. The negative side of this design decision is that queries might become slower the further away we get from the first results. +Because of this, we do not recommend creating interfaces with page selectors that allow users to jump to an arbitrary results page. If page selection is crucial to the software you are developing, this document's last section lists a number of tips that might help you work around Meilisearch's current limitations. -Because you cannot know the number of total hits and slower queries the further we move from the first result, we do not recommend creating interfaces with page selectors that allow users to jump to any arbitrary result page. If this type of interface is crucial for your user's search experience, this document's last section lists a number of tips that might help you work around Meilisearch's current limitations. - -Instead of a full page selector, we recommend creating pagination interfaces centered around previous and next buttons. +Instead of a full page selector, [we recommend creating pagination interfaces centered around previous and next buttons](#recommended-previous-and-next-buttons). ::: note -By default, Meilisearch only returns a maximum of 1000 search results. Consult our [index setting reference](/reference/api/settings.md) to know how to change this. +By default, Meilisearch returns a maximum of 1000 search results. Consult our [index setting reference](/reference/api/settings.md) if you need to change this. ::: ## Recommended: Previous and next buttons @@ -30,53 +28,47 @@ Though this approach offers less precision than a full-blown page selector, it d Previous and next buttons can be implemented using the [`limit`](/reference/api/search.md#limit) and [`offset`](/reference/api/search.md#offset) search parameters. -Paginating requires providing an `offset` that is equal to your `limit` times the page number times: `offset = limit * page number`. +Paginating requires providing an `offset` that is equal to your `limit` times the page number times: `offset = limit * page number`. We recommend starting page count from 0 instead of 1 when calculating offset values. For example, if you set `limit` to `20` and want the first page of search results, your `offset` must be 0: `offset = 0 * 20`. -```sh -curl \ - -X POST 'http://localhost:7700/indexes/movies/search' \ - -H 'Content-Type: application/json' \ - --data-binary '{ - "q": "shifu", - "limit": 20, - "offset": 0 - }' +```js +const results = await index.search("x", { limit: 20, offset: 0 }); ``` If you keep the same `limit` and want the third page of results, `offset` must be `40`: `offset = 2 * 20`. -```sh -curl \ - -X POST 'http://localhost:7700/indexes/movies/search' \ - -H 'Content-Type: application/json' \ - --data-binary '{ - "q": "shifu", - "limit": 20, - "offset": 40 - }' +```js +const results = await index.search("x", { limit: 20, offset: 40 }); ``` -As you might have noticed, we start counting page numbers from 0. This means the first page of results is 0, the second page is 1, and so forth. +Once a query returns less than your configured `limit`, you have reached the last results page. -It is often helpful to disable navigation buttons when the user cannot move to next or the "previous page. The "previous" button should be disabled whenever your `offset` is 0. +It is often helpful to disable navigation buttons when the user cannot move to the "next" or "previous" page. The "previous" button should be disabled whenever your `offset` is 0. -To disable the "next" button, we recommend setting your `limit` to the number of displayed results plus 1. For example, if you want each page to display 20 search results, set `limit` to 21. If the number of returned items is less than 21, we can safely assume we are in the last page. +To disable the "next" button, we recommend setting your query's `limit` to the number of displayed results plus one. The extra result indicates that you have at least one item beyond what you can display in a single results page: ```js const results = await index.search("x", { limit: 21, offset: 0 }) -// Previous button if (offset === 0 ) { - // last page - document.querySelector("#previous_button").disabled + // If offset equals 0, we're on the first results page + // and can disable the "previous" buttons + document.querySelector("#previous_button").disabled = true; +} else { + document.querySelector("#previous_button").disabled = false; } -// Next button -if (results.hits.length < limit ) { - // last page - document.querySelector("#next_button").disabled +if (results.hits.length < 21 ) { + // If Meilisearch returns 20 items or less, + // we don't have any more results to + // and can disable the "next" + document.querySelector("#next_button").disabled = true; +} else { + // If Meilisearch returns exactly 21 results + // and our page can only show 20 items at a time, + // we have at least one more page with 1 result in it + document.querySelector("#next_button").disabled = false; } ``` @@ -84,17 +76,17 @@ if (results.hits.length < limit ) { As its name states, this type of pagination is made of a numbered list of pages accompanied by next and previous buttons. -[UI screenshot] - -![](https://vuejsexamples.com/content/images/2018/11/vue-pagination.gif) +![placeholder page selection UI](https://vuejsexamples.com/content/images/2018/11/vue-pagination.gif) -This is a very common type of interface and offers users a significant amount of precision when navigating results. Despite being similar to our recommended pagination solution, the page selector requires knowing the exact number of total matches. This makes it difficult to implement when using Meilisearch. +This is is a common UI pattern that offers users a significant amount of precision when navigating results. ### Implementation -The general implementation of a page selection interface is similar to our recommended solution, using previous and next buttons: you must use the `limit` and `offset` search parameters to set your page size and navigate between search results. +The general implementation of a page selection interface is similar to our [recommended solution](#recommended-previous-and-next-buttons), but you must also display a page list. -To create the page list, however, you must know the exact number of total results. For example, if you have 100 results and your search result pages contain 10 results each, your selector must show a list of numbers going from 1 to 10. Meilisearch, however, can only give you an estimate of the total number of search results. +To create the page list, however, you must know the exact number of total results. For example, if you have 100 results and your search result pages contain 10 results each, your selector must show a list of numbers going from 1 to 10. + +Since Meilisearch can only give you an estimate of total search results, it can be difficult to implement page selectors when using Meilisearch. We recommend two different workarounds to create this kind of pagination interface with Meilisearch. @@ -104,22 +96,22 @@ By default, a search request returns 20 search results. You can change this valu For example, if you set `limit` to 300, every search request made to Meilisearch returns at most 300 documents. If a query returns a `hits` array with 200 items and you want each page to display 20 results, you can create a page selector with 10 pages. +// perhaps a code sample here? + This method provides control and reliability. It also prevents users from paginating too far, which avoids performance loss. However, this limits the number of results your users can see. ::: note -We do not recommend setting high values for `limit` as it can negatively impact performance. +We do not recommend caution when setting high values for `limit` as it can negatively impact performance. ::: #### Accept the unreliable number -You can still use `estimatedTotalHits` to calculate the number of search result pages. This means your page count is likely to change until Meilisearch retrives the last search result. +You use `estimatedTotalHits` to calculate the number of search result pages. This means your page count is likely to change until Meilisearch retrives the last search result. -For example, a query's `estimatedTotalHits` might be `100` when you fetch the first page of search results. If you are showing 20 results per page, this means your interface will display a page selector with 5 pages. When you fetch the fifth and last page in Meilisearch's current estimate, however, `estimatedTotalHits` might change to `300`. Your page list, previously displaying 5 pages, must now show 10 total pages. +For example, a query's `estimatedTotalHits` might be `100` when you fetch the first page of search results. If you are showing 20 results per page, this means your interface will display a page selector with 5 pages. When you fetch the fifth and last page according to Meilisearch's current estimate, however, `estimatedTotalHits` might change to `300`. Your page list, previously displaying 5 pages, must now show 10 total pages. -This method gives users access to all search results. However, it also results in an interface that might occasionally change in front of the user. +This method gives users access to all search results. However, it also results in an interface that might feel unreliable due to constant and unpredictable changes. ## Unsatisfied? Let us know -We are actively working on improving Meilisearch pagination. Is our recommended pagination method not suitable for the application you're developing? Is page selection critical for your website? Please let us know in this GitHub discussion. - -Is creating pagination interfaces in Meilisearch for you this is a huge issue, please provide feedback on [this discussion](https://github.com/meilisearch/product/discussions/483). \ No newline at end of file +Is the current state of pagination in Meilisearch negatively impacting you? Please share your thoughts with us in this [GitHub discussion](https://github.com/meilisearch/product/discussions/483). We are actively working on improving this aspect of Meilisearch and your input is greatly appreciated. From 273e36bc3a4a455d7db9be63fc16f56643c345e5 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Thu, 23 Jun 2022 10:32:55 +0400 Subject: [PATCH 054/150] update based on review --- .code-samples.meilisearch.yaml | 4 ++-- reference/api/indexes.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index fcb90e2b9e..f7eebbac1f 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -19,7 +19,7 @@ create_an_index_1: |- }' update_an_index_1: |- curl \ - -X PUT 'http://localhost:7700/indexes/movies' \ + -X PATCH 'http://localhost:7700/indexes/movies' \ -H 'Content-Type: application/json' \ --data-binary '{ "primaryKey": "id" }' delete_an_index_1: |- @@ -832,7 +832,7 @@ primary_field_guide_add_document_primary_key: |- ]' primary_field_guide_update_document_primary_key: |- curl \ - -X PUT 'http://localhost:7700/indexes/books' \ + -X PATCH 'http://localhost:7700/indexes/books' \ -H 'Content-Type: application/json' \ --data-binary '{ "primaryKey": "title" }' tenant_token_guide_search_no_sdk_1: |- diff --git a/reference/api/indexes.md b/reference/api/indexes.md index 4b108640d0..16016f3964 100644 --- a/reference/api/indexes.md +++ b/reference/api/indexes.md @@ -112,7 +112,7 @@ You can use the response's `uid` to [track the status of your request](/referenc ## Update an index - + Update an [index's](/learn/core_concepts/indexes.md) [primary key](/learn/core_concepts/primary_key.md#primary-key). The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required. From 6ab97e70806784eb6187eaa6e273d4078b901894 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9mentine=20Urquizar?= Date: Thu, 23 Jun 2022 13:41:56 +0200 Subject: [PATCH 055/150] Update postman collection for v0.28.0 --- .../postman/meilisearch-collection.json | 303 +++++++++++++----- 1 file changed, 222 insertions(+), 81 deletions(-) diff --git a/.vuepress/public/postman/meilisearch-collection.json b/.vuepress/public/postman/meilisearch-collection.json index 5af874b190..747d7c1013 100644 --- a/.vuepress/public/postman/meilisearch-collection.json +++ b/.vuepress/public/postman/meilisearch-collection.json @@ -1,8 +1,9 @@ { "info": { - "_postman_id": "157465d2-dee4-4327-b787-6187d51fbe12", - "name": "Meilisearch v0.27", - "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" + "_postman_id": "453f3754-4b37-4654-8fe3-b2b3aef24048", + "name": "Meilisearch v0.28", + "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", + "_exporter_id": "8898306" }, "item": [ { @@ -23,6 +24,13 @@ "{{indexUID}}", "documents", "2" + ], + "query": [ + { + "key": "fields", + "value": "id", + "disabled": true + } ] } }, @@ -55,8 +63,8 @@ "disabled": true }, { - "key": "attributesToRetrieve", - "value": "*", + "key": "fields", + "value": "id", "disabled": true } ] @@ -278,12 +286,12 @@ "disabled": true }, { - "key": "matches", + "key": "showMatchesPosition", "value": "true", "disabled": true }, { - "key": "facetsDistribution", + "key": "facets", "value": "genre", "disabled": true }, @@ -358,6 +366,23 @@ ], "path": [ "tasks" + ], + "query": [ + { + "key": "type", + "value": "documentAdditionOrUpdate", + "disabled": true + }, + { + "key": "status", + "value": "failed", + "disabled": true + }, + { + "key": "indexUid", + "value": "books", + "disabled": true + } ] } }, @@ -380,45 +405,6 @@ } }, "response": [] - }, - { - "name": "Get all tasks of an index", - "request": { - "method": "GET", - "header": [], - "url": { - "raw": "{{url}}/indexes/{{indexUID}}/tasks", - "host": [ - "{{url}}" - ], - "path": [ - "indexes", - "{{indexUID}}", - "tasks" - ] - } - }, - "response": [] - }, - { - "name": "Get one task of an index", - "request": { - "method": "GET", - "header": [], - "url": { - "raw": "{{url}}/indexes/{{indexUID}}/tasks/0", - "host": [ - "{{url}}" - ], - "path": [ - "indexes", - "{{indexUID}}", - "tasks", - "0" - ] - } - }, - "response": [] } ] }, @@ -426,7 +412,7 @@ "name": "Indexes", "item": [ { - "name": "List all indexes", + "name": "Get indexes", "request": { "method": "GET", "header": [], @@ -437,6 +423,18 @@ ], "path": [ "indexes" + ], + "query": [ + { + "key": "offset", + "value": "0", + "disabled": true + }, + { + "key": "limit", + "value": "2", + "disabled": true + } ] } }, @@ -532,7 +530,7 @@ } }, "request": { - "method": "PUT", + "method": "PATCH", "header": [ { "key": "Content-Type", @@ -612,7 +610,7 @@ } }, "request": { - "method": "POST", + "method": "PUT", "header": [ { "key": "Content-Type", @@ -687,7 +685,7 @@ } }, "request": { - "method": "POST", + "method": "PUT", "header": [ { "key": "Content-Type", @@ -762,7 +760,7 @@ } }, "request": { - "method": "POST", + "method": "PUT", "header": [ { "key": "Content-Type", @@ -837,7 +835,7 @@ } }, "request": { - "method": "POST", + "method": "PUT", "header": [ { "key": "Content-Type", @@ -907,7 +905,7 @@ { "name": "Update synonyms", "request": { - "method": "POST", + "method": "PUT", "header": [ { "key": "Content-Type", @@ -1005,7 +1003,7 @@ } }, "request": { - "method": "POST", + "method": "PUT", "header": [ { "key": "Content-Type", @@ -1086,7 +1084,7 @@ } }, "request": { - "method": "POST", + "method": "PUT", "header": [ { "key": "Content-Type", @@ -1161,7 +1159,7 @@ } }, "request": { - "method": "POST", + "method": "PUT", "header": [ { "key": "Content-Type", @@ -1236,7 +1234,7 @@ } }, "request": { - "method": "POST", + "method": "PATCH", "header": [ { "key": "Content-Type", @@ -1246,7 +1244,7 @@ ], "body": { "mode": "raw", - "raw": "{\n \"minWordSizeForTypos\": {\n \"oneTypo\": 2,\n \"twoTypos\": 11\n },\n \"disableOnWords\": [\"Prince\"],\n \"disableOnAttributes\": [\"genre\"]\n\n}" + "raw": "{\n \"minWordSizeForTypos\": {\n \"oneTypo\": 2,\n \"twoTypos\": 11\n },\n \"disableOnWords\": [\"Prince\"],\n \"disableOnAttributes\": [\"genre\"]\n}" }, "url": { "raw": "{{url}}/indexes/{{indexUID}}/settings/typo-tolerance", @@ -1282,6 +1280,156 @@ } }, "response": [] + }, + { + "name": "Get pagination", + "request": { + "method": "GET", + "header": [], + "url": { + "raw": "{{url}}/indexes/{{indexUID}}/settings/pagination", + "host": [ + "{{url}}" + ], + "path": [ + "indexes", + "{{indexUID}}", + "settings", + "pagination" + ] + } + }, + "response": [] + }, + { + "name": "Update pagination", + "protocolProfileBehavior": { + "disabledSystemHeaders": { + "content-type": true + } + }, + "request": { + "method": "PATCH", + "header": [ + { + "key": "Content-Type", + "value": "application/json", + "type": "text" + } + ], + "body": { + "mode": "raw", + "raw": "{\n \"maxTotalHits\": 2000\n}" + }, + "url": { + "raw": "{{url}}/indexes/{{indexUID}}/settings/pagination", + "host": [ + "{{url}}" + ], + "path": [ + "indexes", + "{{indexUID}}", + "settings", + "pagination" + ] + } + }, + "response": [] + }, + { + "name": "Reset pagination", + "request": { + "method": "DELETE", + "header": [], + "url": { + "raw": "{{url}}/indexes/{{indexUID}}/settings/pagination", + "host": [ + "{{url}}" + ], + "path": [ + "indexes", + "{{indexUID}}", + "settings", + "pagination" + ] + } + }, + "response": [] + }, + { + "name": "Get faceting", + "request": { + "method": "GET", + "header": [], + "url": { + "raw": "{{url}}/indexes/{{indexUID}}/settings/faceting", + "host": [ + "{{url}}" + ], + "path": [ + "indexes", + "{{indexUID}}", + "settings", + "faceting" + ] + } + }, + "response": [] + }, + { + "name": "Update faceting", + "protocolProfileBehavior": { + "disabledSystemHeaders": { + "content-type": true + } + }, + "request": { + "method": "PATCH", + "header": [ + { + "key": "Content-Type", + "value": "application/json", + "type": "text" + } + ], + "body": { + "mode": "raw", + "raw": "{\n \"maxValuesPerFacet\": 3000\n}" + }, + "url": { + "raw": "{{url}}/indexes/{{indexUID}}/settings/faceting", + "host": [ + "{{url}}" + ], + "path": [ + "indexes", + "{{indexUID}}", + "settings", + "faceting" + ] + } + }, + "response": [] + }, + { + "name": "Reset faceting", + "request": { + "method": "DELETE", + "header": [], + "url": { + "raw": "{{url}}/indexes/{{indexUID}}/settings/faceting", + "host": [ + "{{url}}" + ], + "path": [ + "indexes", + "{{indexUID}}", + "settings", + "faceting" + ] + } + }, + "response": [] } ] }, @@ -1312,7 +1460,7 @@ } }, "request": { - "method": "POST", + "method": "PATCH", "header": [ { "key": "Content-Type", @@ -1380,6 +1528,18 @@ ], "path": [ "keys" + ], + "query": [ + { + "key": "offset", + "value": "0", + "disabled": true + }, + { + "key": "limit", + "value": "10", + "disabled": true + } ] } }, @@ -1416,7 +1576,7 @@ ], "body": { "mode": "raw", - "raw": "{\n \"description\": \"Key to add and delete documents, in `books` index.\",\n \"actions\": [\n \"documents.add\",\n \"documents.delete\" \n ],\n \"indexes\": [\n \"books\"\n ],\n \"expiresAt\": null\n}" + "raw": "{\n \"name\": \"docs-key\",\n \"description\": \"Key to add and delete documents, in `books` index.\",\n \"actions\": [\n \"documents.add\",\n \"documents.delete\" \n ],\n \"indexes\": [\n \"books\"\n ],\n \"expiresAt\": null\n}" }, "url": { "raw": "{{url}}/keys", @@ -1443,7 +1603,7 @@ ], "body": { "mode": "raw", - "raw": "{\n \"description\": \"Key to add and delete documents, but also to create indexes, in `book` index.\",\n \"actions\": [\n \"documents.add\",\n \"documents.delete\",\n \"indexes.create\"\n ]\n}" + "raw": "{\n \"description\": \"Key to add and delete documents, but also to create indexes, in `book` index.\"\n}" }, "url": { "raw": "{{url}}/keys/wYZjGJyBcdb0621b97999c233246a8ec0a35d0fcd9a6417ef8ccee0c8978b64b123af2dd", @@ -1562,25 +1722,6 @@ { "name": "Dumps", "item": [ - { - "name": "Get a dump status", - "request": { - "method": "GET", - "header": [], - "url": { - "raw": "{{url}}/dumps/20201001-110357260/status", - "host": [ - "{{url}}" - ], - "path": [ - "dumps", - "20201001-110357260", - "status" - ] - } - }, - "response": [] - }, { "name": "Create a dump", "protocolProfileBehavior": { @@ -1661,7 +1802,7 @@ }, { "key": "indexUID", - "value": "indexUID" + "value": "books" } ] } \ No newline at end of file From 025f3325c6e1e5b086a87571cb6b3360a880908d Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Thu, 23 Jun 2022 17:48:43 +0400 Subject: [PATCH 056/150] Apply suggestions from code review Co-authored-by: gui machiavelli --- learn/security/master_api_keys.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/learn/security/master_api_keys.md b/learn/security/master_api_keys.md index f4760a183c..5526c8108a 100644 --- a/learn/security/master_api_keys.md +++ b/learn/security/master_api_keys.md @@ -90,7 +90,7 @@ Though the default API keys are usually enough to manage the security needs of m You can only update the `name` and `description` of an API key, even after it expires. -We can update the `Default Search API Key` to change the description: +For example, we can update the `Default Search API Key` and change its description: @@ -163,7 +163,7 @@ We can query our instance to confirm which active keys can search our `patient_m "results": [ { "name": "Default Search API Key", - "description": "Default Search API Key", + "description": "Use it to search from the frontend", "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", "uid":"74c9c733-3368-4738-bbe5-1d18a5fecb37", "actions": [ @@ -178,7 +178,7 @@ We can query our instance to confirm which active keys can search our `patient_m }, { "name": "Default Admin API Key", - "description": "Default Admin API Key (Use it for all other operations. Caution! Do not share it on the client side)", + "description": "Use it for all other than search operations. Caution! Do not expose it on a public frontend", "key": "380689dd379232519a54d15935750cc7625620a2ea2fc06907cb40ba5b421b6f", "uid": "20f7e4c4-612c-4dd1-b783-7934cc038213", "actions": [ From cc00994bf18bae4ff886aa78393cdf15447bf113 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Thu, 23 Jun 2022 17:53:18 +0400 Subject: [PATCH 057/150] update based on feedback --- reference/api/keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/keys.md b/reference/api/keys.md index 4b2e3ac9ee..c0987ac998 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -1,6 +1,6 @@ # Keys -The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must either [set the master key](/learn/configuration/instance_options.md#master-key) and supply it in the header of the request, or use API keys that have access to the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. +The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must first [set the master key](/learn/configuration/instance_options.md#master-key).Once a master key is set, you caan access these endpoints by and supplying it in the header of the request, or use API keys that have access to the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. [Learn more about managing keys and their rights](/learn/security/master_api_keys.md). From 21880fca1e219186428a69c31606c1e60735e7ab Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Thu, 23 Jun 2022 17:53:53 +0400 Subject: [PATCH 058/150] Update reference/api/error_codes.md Co-authored-by: gui machiavelli --- reference/api/error_codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/error_codes.md b/reference/api/error_codes.md index 8af92c036a..9e52543da1 100644 --- a/reference/api/error_codes.md +++ b/reference/api/error_codes.md @@ -183,4 +183,4 @@ The given `uid` is invalid. The `uid` must follow the [uuid v4](https://www.soha ### `invalid_api_key_name` -The give `name` is invalid. It should either be a string or `null`. +The given `name` is invalid. It should either be a string or `null`. From 903d3cf28c431d92bcf344f677f9aba1573af08b Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Thu, 23 Jun 2022 17:58:48 +0400 Subject: [PATCH 059/150] Update reference/api/keys.md --- reference/api/keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/keys.md b/reference/api/keys.md index c0987ac998..d64aa16d3d 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -1,6 +1,6 @@ # Keys -The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must first [set the master key](/learn/configuration/instance_options.md#master-key).Once a master key is set, you caan access these endpoints by and supplying it in the header of the request, or use API keys that have access to the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. +The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must first [set the master key](/learn/configuration/instance_options.md#master-key). Once a master key is set, you can access these endpoints by supplying it in the header of the request, or use API keys that have access to the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. [Learn more about managing keys and their rights](/learn/security/master_api_keys.md). From 95642d8f74770a03a42d52e544aa5fd2ae3cd543 Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Thu, 23 Jun 2022 17:59:57 +0400 Subject: [PATCH 060/150] Update reference/api/keys.md --- reference/api/keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/keys.md b/reference/api/keys.md index d64aa16d3d..22b72b237d 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -1,6 +1,6 @@ # Keys -The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must first [set the master key](/learn/configuration/instance_options.md#master-key). Once a master key is set, you can access these endpoints by supplying it in the header of the request, or use API keys that have access to the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. +The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must first [set the master key](/learn/configuration/instance_options.md#master-key). Once a master key is set, you can access these endpoints by supplying it in the header of the request, or using API keys that have access to the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. [Learn more about managing keys and their rights](/learn/security/master_api_keys.md). From dde9a7c43c54b1424d504de97147c769fa109fbd Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Thu, 23 Jun 2022 18:23:35 +0400 Subject: [PATCH 061/150] update tables --- reference/api/search.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/reference/api/search.md b/reference/api/search.md index 24df0491b8..3ace364f00 100644 --- a/reference/api/search.md +++ b/reference/api/search.md @@ -33,7 +33,7 @@ This is the preferred route to perform search when an API key is required, as it | **[offset](#offset)** | Number of documents to skip | `0` | | **[limit](#limit)** | Maximum number of documents returned | `20` | | **[filter](#filter)** | Filter queries by an attribute's value | `null` | -| **[facets](#facets)** | Display the count of matches per facet | `null` | +| **[facets](#facets)** | Display the count of matches per facet | `null` | | **[attributesToRetrieve](#attributes-to-retrieve)** | Attributes to display in the returned documents | `["*"]` | | **[attributesToCrop](#attributes-to-crop)** | Attributes whose values have to be cropped | `null` | | **[cropLength](#crop-length)** | Maximum length of cropped value in words | `10` | @@ -58,15 +58,15 @@ Query terms enclosed in double quotes are treated as [phrase searches](#query-q) ### Response -| field | Description | type | -| -------------------- | ------------------------------ | :--------: | -| **hits** | Results of the query | `array of objects` | -| **offset** | Number of documents skipped | `number` | -| **limit** | Number of documents to take | `number` | -| **estimatedTotalHits** | Total number of matches | `number` | -| **facets** | **[Distribution of the given facets](#facets)** | `object` -| **processingTimeMs** | Processing time of the query | `number` | -| **query** | Query originating the response | `string` | +| field | Description | type | +| ------------------------| ----------------------------------------------- | :----------------: | +| **hits** | Results of the query | `array of objects` | +| **offset** | Number of documents skipped | `number` | +| **limit** | Number of documents to take | `number` | +| **estimatedTotalHits** | Total number of matches | `number` | +| **facets** | **[Distribution of the given facets](#facets)** | `object` | +| **processingTimeMs** | Processing time of the query | `number` | +| **query** | Query originating the response | `string` | ### Example @@ -144,15 +144,15 @@ Query terms enclosed in double quotes are treated as [phrase searches](#query-q) ### Response -| field | Description | type | -| -------------------- | ------------------------------ | :--------: | -| **hits** | Results of the query | `array of objects` | -| **offset** | Number of documents skipped | `number` | -| **limit** | Number of documents to take | `number` | -| **estimatedTotalHits** | Total number of matches | `number` | -| **facets** | **[Distribution of the given facets](#facets)** | `object` -| **processingTimeMs** | Processing time of the query | `number` | -| **query** | Query originating the response | `string` | +| field | Description | type | +| ----------------------- | ----------------------------------------------- | :----------------: | +| **hits** | Results of the query | `array of objects` | +| **offset** | Number of documents skipped | `number` | +| **limit** | Number of documents to take | `number` | +| **estimatedTotalHits** | Total number of matches | `number` | +| **facets** | **[Distribution of the given facets](#facets)** | `object` | +| **processingTimeMs** | Processing time of the query | `number` | +| **query** | Query originating the response | `string` | ### Example From 693de12bb7704b9773e910430bd29b39ffd29fb5 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 23 Jun 2022 18:13:55 +0200 Subject: [PATCH 062/150] pagination settings: API reference scaffolding --- reference/api/pagination.md | 90 +++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 reference/api/pagination.md diff --git a/reference/api/pagination.md b/reference/api/pagination.md new file mode 100644 index 0000000000..89fc2b8695 --- /dev/null +++ b/reference/api/pagination.md @@ -0,0 +1,90 @@ +# 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 + + + +Get the pagination settings of an index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required. + +### Example + + + +#### Response: `200 OK` + +```json +{ + +} +``` + +### Returned fields + +#### `field_name` + +[field explanation] + +## Update pagination settings + + + +Partially update the pagination settings for an index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required. + +### Body + +#### `field_name` + +[field explanation] + +#### Example + + + +#### Response: `200 OK` + +```json +{ + "uid": 1, + "indexUid": "books", + "status": "enqueued", + "type": "settingsUpdate", + "enqueuedAt": "2022-04-14T20:56:44.991039Z" +} +``` + +You can use the returned `uid` 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 + + + +#### Response: `200 OK` + +```json +{ + "uid": 1, + "indexUid": "books", + "status": "enqueued", + "type": "settingsUpdate", + "enqueuedAt": "2022-04-14T20:53:32.863107Z" +} +``` + +You can use the returned `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). + From a5c2e63a88b5176abe990a10acd222d008371bf7 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 23 Jun 2022 18:17:26 +0200 Subject: [PATCH 063/150] faceting settings: API reference scaffolding --- reference/api/faceting.md | 91 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 reference/api/faceting.md diff --git a/reference/api/faceting.md b/reference/api/faceting.md new file mode 100644 index 0000000000..3f06be1066 --- /dev/null +++ b/reference/api/faceting.md @@ -0,0 +1,91 @@ +# Faceting + +_Child route of the [settings route](/reference/api/settings.md)._ + +This route allows you to configure the faceting settings for an index. + +faceting 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 filtering and faceting, refer to our [dedicated guide](/learn/advanced/filtering_and_faceted_search.md). + +::: warning +Updating the settings means overwriting the default settings of Meilisearch. You can reset to default values using the `DELETE` routes. +::: + +## Get faceting settings + + + +Get the faceting settings of an index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required. + +### Example + + + +#### Response: `200 OK` + +```json +{ + +} +``` + +### Returned fields + +#### `field_name` + +[field explanation] + +## Update faceting settings + + + +Partially update the faceting settings for an index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required. + +### Body + +#### `field_name` + +[field explanation] + +#### Example + + + +#### Response: `200 OK` + +```json +{ + "uid": 1, + "indexUid": "books", + "status": "enqueued", + "type": "settingsUpdate", + "enqueuedAt": "2022-04-14T20:56:44.991039Z" +} +``` + +You can use the returned `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). + +## Reset faceting settings + +Reset an index's faceting settings to their default value. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required. + +#### Example + + + +#### Response: `200 OK` + +```json +{ + "uid": 1, + "indexUid": "books", + "status": "enqueued", + "type": "settingsUpdate", + "enqueuedAt": "2022-04-14T20:53:32.863107Z" +} +``` + +You can use the returned `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). + + From 3753d6ecb04a1f3cdb73686a64a7e4e566172717 Mon Sep 17 00:00:00 2001 From: Tommy <68053732+dichotommy@users.noreply.github.com> Date: Thu, 23 Jun 2022 18:33:30 +0200 Subject: [PATCH 064/150] Update reference/api/dump.md Co-authored-by: Maryam <90181761+maryamsulemani97@users.noreply.github.com> --- reference/api/dump.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/dump.md b/reference/api/dump.md index 70c90e562e..d764d01738 100644 --- a/reference/api/dump.md +++ b/reference/api/dump.md @@ -28,7 +28,7 @@ Dump tasks take priority over all other tasks in the queue. This means that a ne ```json { - "taskUid": 0, + "taskUid": 1, "indexUid": null, "status": "enqueued", "type": "dumpCreation", From bdf07bd06850603cce88ef56af7b887ad4db0766 Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Thu, 23 Jun 2022 18:37:59 +0200 Subject: [PATCH 065/150] indexUid for dumps is always null --- learn/advanced/asynchronous_operations.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/learn/advanced/asynchronous_operations.md b/learn/advanced/asynchronous_operations.md index 823cd08e48..555e9afd4b 100644 --- a/learn/advanced/asynchronous_operations.md +++ b/learn/advanced/asynchronous_operations.md @@ -33,7 +33,7 @@ The response from the [task API](/reference/api/tasks.md) will always include th | Field | Type | Description | |--------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------| | `uid` | integer | The unique sequential identifier of the task | -| `indexUid` | string | The unique index identifier | +| `indexUid` | string | The unique index identifier (always `null` for dumps) | | `status` | string | The status of the task. Possible values are `enqueued`, `processing`, `succeeded`, `failed` | | `type` | string | The type of task. Possible values are `indexCreation`, `indexUpdate`, `indexDeletion`, `documentAddition`, `documentPartial`, `documentDeletion`, `settingsUpdate`, `clearAll`, `dumpCreation` | | `details` | object | Detailed information on the task payload | @@ -52,7 +52,7 @@ All asynchronous operations return a summarized version of the [`task` object](# | Field | Type | Description | |------------|---------|--------------------------------- | | `uid` | integer | Unique sequential identifier | -| `indexUid` | string | Unique index identifier | +| `indexUid` | string | Unique index identifier (always `null` for dumps) | | `status` | string | Status of the task. Value is `enqueued` | | `type` | string | Type of task | | `enqueuedAt` | string | Represents the date and time in the RFC 3339 format when the task has been `enqueued` | @@ -142,7 +142,7 @@ Had the task failed, the response would have included an `error` object: 3. Once the task has completed processing, Meilisearch marks it as `succeeded`, if it was successful, or `failed`, if there was an error. 4. Tasks marked as `succeeded` or `failed` are not deleted and will remain visible in [the task list](/reference/api/tasks.md#get-all-tasks) -Tasks are processed in the order they were enqueued, with one exception: `dumpCreation`. Dumps are prioritized over all other tasks in the queue. Their `uid` still represents when they were enqueued relative to other tasks. +Tasks are processed in the order they were enqueued, with one exception: `dumpCreation`. Dumps are prioritized over all other tasks in the queue. Their `uid` still represents when they were enqueued relative to other tasks, and their `indexUid` is `null`. ## Terminate Meilisearch while a task is being processed From c6615a590042f190b7d9a1a747f1de0852e165c3 Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Thu, 23 Jun 2022 18:39:30 +0200 Subject: [PATCH 066/150] Small clarification --- learn/advanced/asynchronous_operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/advanced/asynchronous_operations.md b/learn/advanced/asynchronous_operations.md index 555e9afd4b..9a79a2c7f9 100644 --- a/learn/advanced/asynchronous_operations.md +++ b/learn/advanced/asynchronous_operations.md @@ -142,7 +142,7 @@ Had the task failed, the response would have included an `error` object: 3. Once the task has completed processing, Meilisearch marks it as `succeeded`, if it was successful, or `failed`, if there was an error. 4. Tasks marked as `succeeded` or `failed` are not deleted and will remain visible in [the task list](/reference/api/tasks.md#get-all-tasks) -Tasks are processed in the order they were enqueued, with one exception: `dumpCreation`. Dumps are prioritized over all other tasks in the queue. Their `uid` still represents when they were enqueued relative to other tasks, and their `indexUid` is `null`. +Tasks are processed in the order they were enqueued, with one exception: `dumpCreation`. Dumps are prioritized over all other tasks in the queue. Their task `uid` still reflects when they were enqueued relative to other tasks. ## Terminate Meilisearch while a task is being processed From ab5c36a688113c71bd4e425582401344553f48e3 Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Thu, 23 Jun 2022 18:41:53 +0200 Subject: [PATCH 067/150] Be less vague Co-authored w/ Gui Machiavelli --- learn/what_is_meilisearch/language.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/learn/what_is_meilisearch/language.md b/learn/what_is_meilisearch/language.md index 5e7521d818..266abcc059 100644 --- a/learn/what_is_meilisearch/language.md +++ b/learn/what_is_meilisearch/language.md @@ -25,10 +25,10 @@ If you'd like to help by developing a tokenizer pipeline yourself: first of all, Under the hood, Meilisearch relies on tokenizers that identify the most important parts of each document in a given dataset. We currently use four tokenization pipelines: -- A default one designed for languages that separate words with spaces -- One specifically tailored for Chinese -- One specifically tailored for Japanese -- One specifically tailored for Hebrew +- A default pipeline designed for languages that separate words with spaces +- A pipeline specifically tailored for Chinese +- A pipeline specifically tailored for Japanese +- A pipeline specifically tailored for Hebrew ### My language does not use whitespace to separate words. Can I still use Meilisearch? From e69848edfd9a8c0cb5413887926a29888905723f Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Thu, 23 Jun 2022 18:44:29 +0200 Subject: [PATCH 068/150] Remove unnecessary bold --- learn/what_is_meilisearch/language.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/learn/what_is_meilisearch/language.md b/learn/what_is_meilisearch/language.md index 266abcc059..e6ce5c5459 100644 --- a/learn/what_is_meilisearch/language.md +++ b/learn/what_is_meilisearch/language.md @@ -2,10 +2,10 @@ Meilisearch is multilingual, featuring optimized support for: -- **Any language that uses whitespace to separate words** -- **Chinese** -- **Japanese** -- **Hebrew** +- Any language that uses whitespace to separate words +- Chinese +- Japanese +- Hebrew We aim to provide global language support, and your feedback helps us move closer to that goal. If you notice inconsistencies in your search results or the way your documents are processed, please [open an issue in our tokenizer repo](https://github.com/meilisearch/charabia/issues/new). From 943d1afa6b0e63477c425b4729a087461b5676dc Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Thu, 23 Jun 2022 18:46:54 +0200 Subject: [PATCH 069/150] Remove outdated tokenizer image + link to contributing.md --- learn/advanced/tokenization.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/learn/advanced/tokenization.md b/learn/advanced/tokenization.md index 3a17cdcba2..67d5b4d7d7 100644 --- a/learn/advanced/tokenization.md +++ b/learn/advanced/tokenization.md @@ -8,8 +8,6 @@ This allows Meilisearch to function in several different languages with zero set ## Deep dive: The Meilisearch tokenizer -![Chart illustrating the architecture of Meilisearch's tokenizer](https://user-images.githubusercontent.com/6482087/102896344-8560d200-4466-11eb-8cfe-b4ae8741093b.jpg) - When you add documents to a Meilisearch index, the tokenization process is handled by an abstract interface called an **analyzer**. The analyzer is responsible for determining the primary language of each field based on the scripts (e.g., Latin alphabet, Chinese hanzi, etc.) that are present there. Then, it applies the corresponding **pipeline** to each field. We can break down the tokenization process like so: @@ -24,4 +22,4 @@ Pipelines include many language-specific operations. Currently, we have four pip 3. A specialized Japanese pipeline using [Lindera](https://github.com/lindera-morphology/lindera) 4. A specialized Hebrew pipeline based off the default Meilisearch pipeline. Uses [Niqqud](https://docs.rs/niqqud/latest/niqqud/) for normalization -For more details, check out the [feature specification](https://github.com/meilisearch/specifications/blob/master/text/0001-script-based-tokenizer.md). +For more details, check out the [tokenizer contribution guide](https://github.com/meilisearch/charabia/blob/main/CONTRIBUTING.md). From e6fb8515bdc42a1a8ce7ae33d3db019b04eb6212 Mon Sep 17 00:00:00 2001 From: Tommy <68053732+dichotommy@users.noreply.github.com> Date: Thu, 23 Jun 2022 18:52:36 +0200 Subject: [PATCH 070/150] Update learn/advanced/asynchronous_operations.md Co-authored-by: gui machiavelli --- learn/advanced/asynchronous_operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/advanced/asynchronous_operations.md b/learn/advanced/asynchronous_operations.md index 43501d6faa..c768b42760 100644 --- a/learn/advanced/asynchronous_operations.md +++ b/learn/advanced/asynchronous_operations.md @@ -21,7 +21,7 @@ Currently, these are Meilisearch's asynchronous operations: ## Understanding tasks -At this time, all of Meilisearch's asynchronous operations belong to a category called "tasks". After you have requested an asynchronous operation, you can use the [task API](/reference/api/tasks.md) to find the detailed status of your request. To do so, you will need the task's unique identifier. +All of Meilisearch's asynchronous operations belong to a category called "tasks". After you have requested an asynchronous operation, you can use the [task API](/reference/api/tasks.md) to find the detailed status of your request. To do so, you will need the task's unique identifier. ### Task API response From f0a47f316cd5a7510d1dcea1ed147e9b124e1758 Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Thu, 23 Jun 2022 19:06:39 +0200 Subject: [PATCH 071/150] Change code blocks to code samples Also rename get_all_tasks_by_index_1 --- .code-samples.meilisearch.yaml | 11 ++++++++++- .vuepress/public/sample-template.yaml | 5 ++++- reference/api/tasks.md | 14 ++++---------- 3 files changed, 18 insertions(+), 12 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 798a6e1f37..27a1758c4b 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -85,9 +85,18 @@ get_all_tasks_1: |- get_task_1: |- curl \ -X GET 'http://localhost:7700/tasks/1' -get_all_tasks_by_index_1: |- +get_all_tasks_filtering_1: |- curl \ -X GET 'http://localhost:7700/tasks?indexUid=movies' +get_all_tasks_filtering_2: |- + curl \ + -X GET 'http://localhost:7700/tasks?status=succeeded,failed&type=documentAdditionOrUpdate' +get_all_tasks_paginating_1: |- + curl \ + -X GET 'http://localhost:7700/tasks?limit=2&from=10 +get_all_tasks_paginating_2: |- + curl \ + -X GET 'http://localhost:7700/tasks?limit=2&from=8 get_one_key_1: |- curl \ -X GET 'http://localhost:7700/keys/d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4' \ diff --git a/.vuepress/public/sample-template.yaml b/.vuepress/public/sample-template.yaml index c8498f22df..5ff639bac0 100644 --- a/.vuepress/public/sample-template.yaml +++ b/.vuepress/public/sample-template.yaml @@ -18,7 +18,10 @@ delete_documents_1: |- search_post_1: |- get_all_tasks_1: |- get_task_1: |- -get_all_tasks_by_index_1: |- +get_all_tasks_filtering_1: |- +get_all_tasks_filtering_2: |- +get_all_tasks_paginating_1: |- +get_all_tasks_paginating_2: |- get_one_key_1: |- get_all_keys_1: |- create_a_key_1: |- diff --git a/reference/api/tasks.md b/reference/api/tasks.md index fb1d3acec5..eb1ebc1d1a 100644 --- a/reference/api/tasks.md +++ b/reference/api/tasks.md @@ -67,15 +67,13 @@ Task results are [paginated](#paginating-tasks) and can be [filtered](#filtering You can filter the task list by the value of the `status`, `type`, or `indexUid` fields. For example, the following command returns all tasks belonging to the index `movies`. Note that the `indexUid` is case-sensitive: - + Use the ampersand character `&` to combine filters, equivalent to a logical `AND`. Use the comma character `,` to add multiple filter values for a single field. For example, the following command would return all `documentAdditionOrUpdate` tasks that either `succeeded` or `failed`: -```bash -curl -X GET 'http://localhost:7700/tasks?status=succeeded,failed&type=documentAdditionOrUpdate' -``` + At this time, `OR` operations between different filters are not supported. For example, you cannot view only tasks which have a type of `documentAddition` **or** a status of `failed`. @@ -89,9 +87,7 @@ For each call to this endpoint, the response will include the `next` field: this This command returns tasks two at a time starting from task `uid` `10`. -```bash -curl -X GET 'http://localhost:7700/tasks?limit=2&from=10 -``` + **Response:** @@ -133,9 +129,7 @@ curl -X GET 'http://localhost:7700/tasks?limit=2&from=10 To view the next page of results, you would repeat the same query, replacing the value of `from` with the value of `next`: -```bash -curl -X GET 'http://localhost:7700/tasks?limit=2&from=8 -``` + When the returned value of `next` is `null`, you have reached the final page of results. From 1690f99df7bf28cd70032bf09beb936a97490288 Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Mon, 27 Jun 2022 13:53:24 +0400 Subject: [PATCH 072/150] Update reference/api/dump.md --- reference/api/dump.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/reference/api/dump.md b/reference/api/dump.md index d764d01738..c24242f157 100644 --- a/reference/api/dump.md +++ b/reference/api/dump.md @@ -18,7 +18,9 @@ Dump imports must be performed when launching a Meilisearch instance [using the Triggers a dump creation task. Once the process is complete, a dump is created in the [dumps directory](/learn/configuration/instance_options.md#dumps-destination). If the dumps directory does not exist yet, it will be created. -Dump tasks take priority over all other tasks in the queue. This means that a newly created dump task will be processed as soon as the current task is finished. [Learn more about asynchronous operations](/learn/advanced/asynchronous_operations.md). +Dump tasks take priority over all other tasks in the queue. This means that a newly created dump task will be processed as soon as the current task is finished. + +[Learn more about asynchronous operations](/learn/advanced/asynchronous_operations.md). ### Example From 6d624d5e7dddc510c0414019c2232580537b35a5 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 27 Jun 2022 16:30:05 +0200 Subject: [PATCH 073/150] pagination: new API reference page --- reference/api/pagination.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/reference/api/pagination.md b/reference/api/pagination.md index 89fc2b8695..c32f29d5cc 100644 --- a/reference/api/pagination.md +++ b/reference/api/pagination.md @@ -6,7 +6,8 @@ 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). + +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. @@ -26,27 +27,29 @@ Get the pagination settings of an index. The index [`uid`](/learn/core_concepts/ ```json { - + "maxTotalHits": 1000 } ``` ### Returned fields -#### `field_name` +#### `maxTotalHits` -[field explanation] +The maximum number of results Meilisearch can return. ## Update pagination settings - + Partially update the pagination settings for an index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required. ### Body -#### `field_name` +#### `maxTotalHits` -[field explanation] +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`. #### Example @@ -87,4 +90,3 @@ Reset an index's pagination settings to their default value. The index [`uid`](/ ``` You can use the returned `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). - From b2c4659e87f25a344cfeecc3632ca4d9986f0414 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 27 Jun 2022 16:30:31 +0200 Subject: [PATCH 074/150] pagination: new API code samples --- .code-samples.meilisearch.yaml | 13 +++++++++++++ .vuepress/public/sample-template.yaml | 3 +++ 2 files changed, 16 insertions(+) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 047cb60b9f..5bc68e942c 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -958,3 +958,16 @@ getting_started_typo_tolerance: |- --data-binary '{ "minWordSizeForTypos": { "oneTypo": 4 } }' +get_pagination_settings_1: |- + curl \ + -X GET 'http://localhost:7700/indexes/books/settings/pagination' +update_pagination_settings_1: |- + curl \ + -X POST 'http://localhost:7700/indexes/books/settings/pagination' \ + -H 'Content-Type: application/json' \ + --data-binary '{ + "maxTotalHits": 100 + }' +reset_typo_tolerance_1: |- + curl \ + -X DELETE 'http://localhost:7700/indexes/books/settings/pagination' \ No newline at end of file diff --git a/.vuepress/public/sample-template.yaml b/.vuepress/public/sample-template.yaml index 8b52eec657..544cf8048b 100644 --- a/.vuepress/public/sample-template.yaml +++ b/.vuepress/public/sample-template.yaml @@ -146,3 +146,6 @@ updating_guide_retrieve_documents_old: |- updating_guide_update_settings_old: |- updating_guide_add_documents_old: |- getting_started_typo_tolerance: |- +get_pagination_settings_1: |- +update_pagination_settings_1: |- +reset_typo_tolerance_1: |- \ No newline at end of file From dcd96bb37cd0f28dbee011ce2f1b24df04d589cf Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 27 Jun 2022 16:44:59 +0200 Subject: [PATCH 075/150] pagination: fix code sample key --- .code-samples.meilisearch.yaml | 2 +- .vuepress/public/sample-template.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 5bc68e942c..fd60dc3c2f 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -968,6 +968,6 @@ update_pagination_settings_1: |- --data-binary '{ "maxTotalHits": 100 }' -reset_typo_tolerance_1: |- +reset_pagination_settings_1: |- curl \ -X DELETE 'http://localhost:7700/indexes/books/settings/pagination' \ No newline at end of file diff --git a/.vuepress/public/sample-template.yaml b/.vuepress/public/sample-template.yaml index 544cf8048b..e9e857c693 100644 --- a/.vuepress/public/sample-template.yaml +++ b/.vuepress/public/sample-template.yaml @@ -148,4 +148,4 @@ updating_guide_add_documents_old: |- getting_started_typo_tolerance: |- get_pagination_settings_1: |- update_pagination_settings_1: |- -reset_typo_tolerance_1: |- \ No newline at end of file +reset_pagination_settings_1: |- From 6ce706895cd748c6ae67e50e2434c7165846c2c9 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 27 Jun 2022 16:50:50 +0200 Subject: [PATCH 076/150] pagination: add API reference to menu --- .vuepress/config.js | 1 + 1 file changed, 1 insertion(+) diff --git a/.vuepress/config.js b/.vuepress/config.js index 395bd548d8..c88b11d36c 100644 --- a/.vuepress/config.js +++ b/.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', From 88e9fc5ea8b1a98093880053d7f97b6c1f41ff55 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 27 Jun 2022 17:29:25 +0200 Subject: [PATCH 077/150] pagination: update global settings reference --- .code-samples.meilisearch.yaml | 3 ++ reference/api/pagination.md | 8 ++-- reference/api/settings.md | 83 ++++++++++++++++++---------------- 3 files changed, 53 insertions(+), 41 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index fd60dc3c2f..7f1a2450b1 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -183,6 +183,9 @@ update_settings_1: |- "twoTypos": 10 }, "disableOnAttributes": ["title"] + }, + "pagination": { + "maxTotalHits": 5000 } }' reset_settings_1: |- diff --git a/reference/api/pagination.md b/reference/api/pagination.md index c32f29d5cc..e4e066488a 100644 --- a/reference/api/pagination.md +++ b/reference/api/pagination.md @@ -6,7 +6,6 @@ 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 @@ -47,9 +46,12 @@ Partially update the pagination settings for an index. The index [`uid`](/learn/ #### `maxTotalHits` -An integer indicating the maximum number of search results Meilisearch can return. +**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`. -`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`. +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`. #### Example diff --git a/reference/api/settings.md b/reference/api/settings.md index 2d22e9b45b..c474bf25d7 100644 --- a/reference/api/settings.md +++ b/reference/api/settings.md @@ -7,6 +7,7 @@ These are the reference pages for the child routes: - [Displayed attributes](/reference/api/displayed_attributes.md) - [Distinct attribute](/reference/api/distinct_attribute.md) - [Filterable attributes](/reference/api/filterable_attributes.md) +- [Pagination](/reference/api/pagination.md) - [Ranking rules](/reference/api/ranking_rules.md) - [Searchable attributes](/reference/api/searchable_attributes.md) - [Sortable attributes](/reference/api/sortable_attributes.md) @@ -30,17 +31,18 @@ Get the settings of an index. The index [`uid`](/learn/core_concepts/indexes.md# ### Response body -| Variable | Type | Description | Default value | -| ------------------------ | --------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | -| **displayedAttributes** | [Strings] | Fields displayed in the returned documents | `["*"]` (all attributes) | -| **distinctAttribute** | String | Search returns documents with distinct (different) values of the given field | `null` | -| **filterableAttributes** | [Strings] | Attributes to use as [filters and facets](/learn/advanced/filtering_and_faceted_search.md) | `[]` | -| **rankingRules** | [Strings] | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#built-in-rules) | -| **searchableAttributes** | [Strings] | Fields in which to search for matching query words sorted by order of importance | `["*"]` (all attributes) | -| **sortableAttributes** | [Strings] | Attributes to use when [sorting](/learn/advanced/sorting.md) search results | `[]` | -| **stopWords** | [Strings] | List of words ignored by Meilisearch when present in search queries | `[]` | -| **synonyms** | Object | List of associated words treated similarly | `{}` | -| **typoTolerance** | Object | Typo tolerance settings | `{}` | +| Variable | Type | Description | Default value | +| ------------------------ | --------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | +| **displayedAttributes** | [Strings] | Fields displayed in the returned documents | `["*"]` (all attributes) | +| **distinctAttribute** | String | Search returns documents with distinct (different) values of the given field | `null` | +| **filterableAttributes** | [Strings] | Attributes to use as [filters and facets](/learn/advanced/filtering_and_faceted_search.md) | `[]` | +| **pagination** | Object | Pagination settings | `{}` | +| **rankingRules** | [Strings] | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#built-in-rules) | +| **searchableAttributes** | [Strings] | Fields in which to search for matching query words sorted by order of importance | `["*"]` (all attributes) | +| **sortableAttributes** | [Strings] | Attributes to use when [sorting](/learn/advanced/sorting.md) search results | `[]` | +| **stopWords** | [Strings] | List of words ignored by Meilisearch when present in search queries | `[]` | +| **synonyms** | Object | List of associated words treated similarly | `{}` | +| **typoTolerance** | Object | Typo tolerance settings | `{}` | [Learn more about the settings in this guide.](/learn/configuration/settings.md) @@ -92,12 +94,15 @@ List the settings. "typoTolerance": { "enabled": true, "minWordSizeForTypos": { - "oneTypo": 5, - "twoTypos": 10 + "oneTypo": 5, + "twoTypos": 10 }, - "disableOnWords": [], - "disableOnAttributes": [] - } + "disableOnWords": [], + "disableOnAttributes": [] + }, + "pagination": { + "maxTotalHits": 1000 + } } ``` @@ -117,17 +122,18 @@ If the provided index does not exist, it will be created. ### Body -| Variable | Type | Description | Default value | -| ------------------------ | --------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | -| **displayedAttributes** | [Strings] | Fields displayed in the returned documents | `["*"]` (all attributes) | -| **distinctAttribute** | String | Search returns documents with distinct (different) values of the given field | `null` | -| **filterableAttributes** | [Strings] | Attributes to use as [filters and facets](/learn/advanced/filtering_and_faceted_search.md) | `[]` | -| **rankingRules** | [Strings] | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#built-in-rules) | -| **searchableAttributes** | [Strings] | Fields in which to search for matching query words sorted by order of importance | `["*"]` (all attributes) | -| **sortableAttributes** | [Strings] | Attributes to use when [sorting](/learn/advanced/sorting.md) search results | `[]` | -| **stopWords** | [Strings] | List of words ignored by Meilisearch when present in search queries | `[]` | -| **synonyms** | Object | List of associated words treated similarly | `{}` | -| **typoTolerance** | Object | Typo tolerance settings | `{}` | +| Variable | Type | Description | Default value | +| ------------------------ | --------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | +| **displayedAttributes** | [Strings] | Fields displayed in the returned documents | `["*"]` (all attributes) | +| **distinctAttribute** | String | Search returns documents with distinct (different) values of the given field | `null` | +| **filterableAttributes** | [Strings] | Attributes to use as [filters and facets](/learn/advanced/filtering_and_faceted_search.md) | `[]` | +| **pagination** | Object | Pagination settings | `{}` | +| **rankingRules** | [Strings] | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#built-in-rules) | +| **searchableAttributes** | [Strings] | Fields in which to search for matching query words sorted by order of importance | `["*"]` (all attributes) | +| **sortableAttributes** | [Strings] | Attributes to use when [sorting](/learn/advanced/sorting.md) search results | `[]` | +| **stopWords** | [Strings] | List of words ignored by Meilisearch when present in search queries | `[]` | +| **synonyms** | Object | List of associated words treated similarly | `{}` | +| **typoTolerance** | Object | Typo tolerance settings | `{}` | ### Example @@ -155,17 +161,18 @@ Reset the settings of an index. The index [`uid`](/learn/core_concepts/indexes.m All settings will be reset to their default value. -| Variable | Type | Description | Default value | -| ------------------------ | --------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | -| **displayedAttributes** | [Strings] | Fields displayed in the returned documents | `["*"]` (all attributes) | -| **distinctAttribute** | String | Search returns documents with distinct (different) values of the given field | `null` | -| **filterableAttributes** | [Strings] | Attributes to use as [filters and facets](/learn/advanced/filtering_and_faceted_search.md) | `[]` | -| **rankingRules** | [Strings] | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#built-in-rules) | -| **searchableAttributes** | [Strings] | Fields in which to search for matching query words sorted by order of importance | `["*"]` (all attributes) | -| **sortableAttributes** | [Strings] | Attributes to use when [sorting](/learn/advanced/sorting.md) search results | `[]` | -| **stopWords** | [Strings] | List of words ignored by Meilisearch when present in search queries | `[]` | -| **synonyms** | Object | List of associated words treated similarly | `{}` | -| **typoTolerance** | Object | Typo tolerance settings | `{}` | +| Variable | Type | Description | Default value | +| ------------------------ | --------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | +| **displayedAttributes** | [Strings] | Fields displayed in the returned documents | `["*"]` (all attributes) | +| **distinctAttribute** | String | Search returns documents with distinct (different) values of the given field | `null` | +| **filterableAttributes** | [Strings] | Attributes to use as [filters and facets](/learn/advanced/filtering_and_faceted_search.md) | `[]` | +| **pagination** | Object | Pagination settings | `{}` | +| **rankingRules** | [Strings] | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#built-in-rules) | +| **searchableAttributes** | [Strings] | Fields in which to search for matching query words sorted by order of importance | `["*"]` (all attributes) | +| **sortableAttributes** | [Strings] | Attributes to use when [sorting](/learn/advanced/sorting.md) search results | `[]` | +| **stopWords** | [Strings] | List of words ignored by Meilisearch when present in search queries | `[]` | +| **synonyms** | Object | List of associated words treated similarly | `{}` | +| **typoTolerance** | Object | Typo tolerance settings | `{}` | [Learn more about the settings](/learn/configuration/settings.md). #### Example From 1beedf37d01bbbaabd78a056c891a19b900b0787 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 27 Jun 2022 19:27:38 +0200 Subject: [PATCH 078/150] faceting settings: add new API reference page --- .code-samples.meilisearch.yaml | 16 ++++++ .vuepress/public/sample-template.yaml | 3 + reference/api/faceting.md | 41 +++++++------- reference/api/settings.md | 80 ++++++++++++++------------- 4 files changed, 84 insertions(+), 56 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 047cb60b9f..154bededf4 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -183,6 +183,9 @@ update_settings_1: |- "twoTypos": 10 }, "disableOnAttributes": ["title"] + }, + "faceting": { + "maxValuesPerFacet": 200 } }' reset_settings_1: |- @@ -958,3 +961,16 @@ getting_started_typo_tolerance: |- --data-binary '{ "minWordSizeForTypos": { "oneTypo": 4 } }' +get_faceting_settings_1: |- + curl \ + -X GET 'http://localhost:7700/indexes/books/settings/faceting' +update_faceting_settings_1: |- + curl \ + -X POST 'http://localhost:7700/indexes/books/settings/faceting' \ + -H 'Content-Type: application/json' \ + --data-binary '{ + "maxValuesPerFacet": 2 + }' +reset_faceting_settings_1: |- + curl \ + -X DELETE 'http://localhost:7700/indexes/books/settings/faceting' \ No newline at end of file diff --git a/.vuepress/public/sample-template.yaml b/.vuepress/public/sample-template.yaml index 8b52eec657..00f2e97787 100644 --- a/.vuepress/public/sample-template.yaml +++ b/.vuepress/public/sample-template.yaml @@ -146,3 +146,6 @@ updating_guide_retrieve_documents_old: |- updating_guide_update_settings_old: |- updating_guide_add_documents_old: |- getting_started_typo_tolerance: |- +get_faceting_settings_1: |- +update_faceting_settings_1: |- +reset_faceting_settings_1: |- \ No newline at end of file diff --git a/reference/api/faceting.md b/reference/api/faceting.md index 3f06be1066..fd6c6c1ba0 100644 --- a/reference/api/faceting.md +++ b/reference/api/faceting.md @@ -26,41 +26,46 @@ Get the faceting settings of an index. The index [`uid`](/learn/core_concepts/in ```json { - + "maxValuesPerFacet": 100 } ``` ### Returned fields -#### `field_name` +#### `maxValuesPerFacet` -[field explanation] +Maximum number of facet values returned for each facet. ## Update faceting settings - + Partially update the faceting settings for an index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required. ### Body -#### `field_name` +#### `maxValuesPerFacet` + +**Type:** integer +**Default value:** `100` + +Configure the maximum number of facet values returned for each facet. Values are alphabetically sorted. -[field explanation] +For example, if a query's search results contain a total of three values for a `colors` facet—`blue`, `green`, and `red`—setting `maxValuesPerFacet` to `2` causes Meilisearch to return only the `blue` and `green` in the response body's `facetDistribution` object. #### Example -#### Response: `200 OK` +#### Response: `202 Accepted` ```json { - "uid": 1, - "indexUid": "books", - "status": "enqueued", - "type": "settingsUpdate", - "enqueuedAt": "2022-04-14T20:56:44.991039Z" + "uid": 1, + "indexUid": "books", + "status": "enqueued", + "type": "settingsUpdate", + "enqueuedAt": "2022-04-14T20:56:44.991039Z" } ``` @@ -78,14 +83,12 @@ Reset an index's faceting settings to their default value. The index [`uid`](/le ```json { - "uid": 1, - "indexUid": "books", - "status": "enqueued", - "type": "settingsUpdate", - "enqueuedAt": "2022-04-14T20:53:32.863107Z" + "uid": 1, + "indexUid": "books", + "status": "enqueued", + "type": "settingsUpdate", + "enqueuedAt": "2022-04-14T20:53:32.863107Z" } ``` You can use the returned `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). - - diff --git a/reference/api/settings.md b/reference/api/settings.md index 2d22e9b45b..78dd471bc3 100644 --- a/reference/api/settings.md +++ b/reference/api/settings.md @@ -30,17 +30,18 @@ Get the settings of an index. The index [`uid`](/learn/core_concepts/indexes.md# ### Response body -| Variable | Type | Description | Default value | -| ------------------------ | --------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | -| **displayedAttributes** | [Strings] | Fields displayed in the returned documents | `["*"]` (all attributes) | -| **distinctAttribute** | String | Search returns documents with distinct (different) values of the given field | `null` | -| **filterableAttributes** | [Strings] | Attributes to use as [filters and facets](/learn/advanced/filtering_and_faceted_search.md) | `[]` | -| **rankingRules** | [Strings] | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#built-in-rules) | -| **searchableAttributes** | [Strings] | Fields in which to search for matching query words sorted by order of importance | `["*"]` (all attributes) | -| **sortableAttributes** | [Strings] | Attributes to use when [sorting](/learn/advanced/sorting.md) search results | `[]` | -| **stopWords** | [Strings] | List of words ignored by Meilisearch when present in search queries | `[]` | -| **synonyms** | Object | List of associated words treated similarly | `{}` | -| **typoTolerance** | Object | Typo tolerance settings | `{}` | +| Variable | Type | Description | Default value | +| ------------------------ | --------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | +| **displayedAttributes** | [Strings] | Fields displayed in the returned documents | `["*"]` (all attributes) | +| **distinctAttribute** | String | Search returns documents with distinct (different) values of the given field | `null` | +| **faceting** | Object | Faceting settings | `{}` | +| **filterableAttributes** | [Strings] | Attributes to use as [filters and facets](/learn/advanced/filtering_and_faceted_search.md) | `[]` | +| **rankingRules** | [Strings] | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#built-in-rules) | +| **searchableAttributes** | [Strings] | Fields in which to search for matching query words sorted by order of importance | `["*"]` (all attributes) | +| **sortableAttributes** | [Strings] | Attributes to use when [sorting](/learn/advanced/sorting.md) search results | `[]` | +| **stopWords** | [Strings] | List of words ignored by Meilisearch when present in search queries | `[]` | +| **synonyms** | Object | List of associated words treated similarly | `{}` | +| **typoTolerance** | Object | Typo tolerance settings | `{}` | [Learn more about the settings in this guide.](/learn/configuration/settings.md) @@ -94,10 +95,13 @@ List the settings. "minWordSizeForTypos": { "oneTypo": 5, "twoTypos": 10 - }, - "disableOnWords": [], - "disableOnAttributes": [] - } + }, + "disableOnWords": [], + "disableOnAttributes": [] + }, + "faceting": { + "maxValuesPerFacet": 100 + } } ``` @@ -117,17 +121,18 @@ If the provided index does not exist, it will be created. ### Body -| Variable | Type | Description | Default value | -| ------------------------ | --------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | -| **displayedAttributes** | [Strings] | Fields displayed in the returned documents | `["*"]` (all attributes) | -| **distinctAttribute** | String | Search returns documents with distinct (different) values of the given field | `null` | -| **filterableAttributes** | [Strings] | Attributes to use as [filters and facets](/learn/advanced/filtering_and_faceted_search.md) | `[]` | -| **rankingRules** | [Strings] | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#built-in-rules) | -| **searchableAttributes** | [Strings] | Fields in which to search for matching query words sorted by order of importance | `["*"]` (all attributes) | -| **sortableAttributes** | [Strings] | Attributes to use when [sorting](/learn/advanced/sorting.md) search results | `[]` | -| **stopWords** | [Strings] | List of words ignored by Meilisearch when present in search queries | `[]` | -| **synonyms** | Object | List of associated words treated similarly | `{}` | -| **typoTolerance** | Object | Typo tolerance settings | `{}` | +| Variable | Type | Description | Default value | +| ------------------------ | --------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | +| **displayedAttributes** | [Strings] | Fields displayed in the returned documents | `["*"]` (all attributes) | +| **distinctAttribute** | String | Search returns documents with distinct (different) values of the given field | `null` | +| **faceting** | Object | Faceting settings | `{}` | +| **filterableAttributes** | [Strings] | Attributes to use as [filters and facets](/learn/advanced/filtering_and_faceted_search.md) | `[]` | +| **rankingRules** | [Strings] | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#built-in-rules) | +| **searchableAttributes** | [Strings] | Fields in which to search for matching query words sorted by order of importance | `["*"]` (all attributes) | +| **sortableAttributes** | [Strings] | Attributes to use when [sorting](/learn/advanced/sorting.md) search results | `[]` | +| **stopWords** | [Strings] | List of words ignored by Meilisearch when present in search queries | `[]` | +| **synonyms** | Object | List of associated words treated similarly | `{}` | +| **typoTolerance** | Object | Typo tolerance settings | `{}` | ### Example @@ -155,17 +160,18 @@ Reset the settings of an index. The index [`uid`](/learn/core_concepts/indexes.m All settings will be reset to their default value. -| Variable | Type | Description | Default value | -| ------------------------ | --------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | -| **displayedAttributes** | [Strings] | Fields displayed in the returned documents | `["*"]` (all attributes) | -| **distinctAttribute** | String | Search returns documents with distinct (different) values of the given field | `null` | -| **filterableAttributes** | [Strings] | Attributes to use as [filters and facets](/learn/advanced/filtering_and_faceted_search.md) | `[]` | -| **rankingRules** | [Strings] | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#built-in-rules) | -| **searchableAttributes** | [Strings] | Fields in which to search for matching query words sorted by order of importance | `["*"]` (all attributes) | -| **sortableAttributes** | [Strings] | Attributes to use when [sorting](/learn/advanced/sorting.md) search results | `[]` | -| **stopWords** | [Strings] | List of words ignored by Meilisearch when present in search queries | `[]` | -| **synonyms** | Object | List of associated words treated similarly | `{}` | -| **typoTolerance** | Object | Typo tolerance settings | `{}` | +| Variable | Type | Description | Default value | +| ------------------------ | --------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | +| **displayedAttributes** | [Strings] | Fields displayed in the returned documents | `["*"]` (all attributes) | +| **distinctAttribute** | String | Search returns documents with distinct (different) values of the given field | `null` | +| **faceting** | Object | Faceting settings | `{}` | +| **filterableAttributes** | [Strings] | Attributes to use as [filters and facets](/learn/advanced/filtering_and_faceted_search.md) | `[]` | +| **rankingRules** | [Strings] | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#built-in-rules) | +| **searchableAttributes** | [Strings] | Fields in which to search for matching query words sorted by order of importance | `["*"]` (all attributes) | +| **sortableAttributes** | [Strings] | Attributes to use when [sorting](/learn/advanced/sorting.md) search results | `[]` | +| **stopWords** | [Strings] | List of words ignored by Meilisearch when present in search queries | `[]` | +| **synonyms** | Object | List of associated words treated similarly | `{}` | +| **typoTolerance** | Object | Typo tolerance settings | `{}` | [Learn more about the settings](/learn/configuration/settings.md). #### Example From 5c28fbfbebf6097413b87892327e782b9d5039a7 Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Tue, 28 Jun 2022 11:17:10 +0400 Subject: [PATCH 079/150] Apply suggestions from code review Co-authored-by: Guillaume Mourier --- reference/api/keys.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/api/keys.md b/reference/api/keys.md index 22b72b237d..e1851fde7e 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -47,7 +47,7 @@ List all existing API keys. **Expired keys are included in the response**, but d }, { "name": "Default Search API Key", - "description": "Default Search API Key (Use it to search from the frontend code)", + "description": "Use it to search from the frontend code", "key": "0a6e572506c52ab0bd6195921575d23092b7f0c284ab4ac86d12346c33057f99", "uid": "74c9c733-3368-4738-bbe5-1d18a5fecb37", "actions": [ @@ -62,7 +62,7 @@ List all existing API keys. **Expired keys are included in the response**, but d }, { "name": "Default Admin API Key", - "description": "Default Admin API Key (Use it for all other operations. Caution! Do not share it on the client side)", + "description": "Use it for anything that is not a search operation. Caution! Do not expose it on a public frontend", "key": "380689dd379232519a54d15935750cc7625620a2ea2fc06907cb40ba5b421b6f", "uid": "20f7e4c4-612c-4dd1-b783-7934cc038213", "actions": [ From e22cb293e4e95c439ea0f66913bd411ca22066b6 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Tue, 28 Jun 2022 11:57:24 +0400 Subject: [PATCH 080/150] update based on gmourier's review --- learn/security/master_api_keys.md | 2 +- learn/security/tenant_tokens.md | 4 ++-- reference/api/keys.md | 14 +++++++------- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/learn/security/master_api_keys.md b/learn/security/master_api_keys.md index 5526c8108a..02aa839dab 100644 --- a/learn/security/master_api_keys.md +++ b/learn/security/master_api_keys.md @@ -150,7 +150,7 @@ It is good practice to always set an expiry date when creating a new API key. If You can use the [list keys endpoint](/reference/api/keys.md) to obtain information on any active key in your Meilisearch instance. This is useful when you need an overview of existing keys and their permissions. -[`GET /keys`](/reference/api/keys.md#get-all-keys) returns a full list of all existing keys. **Expired keys will appear in the response, but deleted keys will not**. As with creating, deleting, and updating API keys, you either need the master key or an API key with the `keys.get` action to access this endpoint. +By default, [`GET /keys`](/reference/api/keys.md#get-all-keys) returns the most recently created 20 keys. You can change this using the [`limit`](/reference/api/keys.html#get-all-keys) query parameter. **Expired keys will appear in the response, but deleted keys will not**. As with creating, deleting, and updating API keys, you either need the master key or an API key with the `keys.get` action to access this endpoint. [`GET /keys/{key_or_uid}`](/reference/api/keys.md#get-one-key) returns information on a single key. `{key_or_uid}` should be replaced with the full `key` or `uid` value obtained during key creation. diff --git a/learn/security/tenant_tokens.md b/learn/security/tenant_tokens.md index a88afbec2e..86406e3bd7 100644 --- a/learn/security/tenant_tokens.md +++ b/learn/security/tenant_tokens.md @@ -117,7 +117,7 @@ The token payload contains most of the relevant token data. It must be an object ```json { "exp": 1646756934, - "apiKeyUid": "12345678", + "apiKeyUid": "ac5cd97d-5a4b-4226-a868-2d0eb6d197ab", "searchRules": { "patient_medical_records": { "filter": "user_id = 1" @@ -188,7 +188,7 @@ The previous rules can be combined in one tenant token: ```json { - "apiKeyUid": "rkDxFUHd", + "apiKeyUid": "ac5cd97d-5a4b-4226-a868-2d0eb6d197ab", "exp": 1641835850, "searchRules": { "*": { diff --git a/reference/api/keys.md b/reference/api/keys.md index e1851fde7e..35e41c2f8e 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -8,7 +8,7 @@ The `/keys` route allows you to create, manage, and delete API keys. To use thes -List all existing API keys. **Expired keys are included in the response**, but deleted keys are not. Results can be paginated by using the `offset` and `limit` query parameters. +List the most recently created 20 keys. **Expired keys are included in the response**, but deleted keys are not. Results can be paginated by using the `offset` and `limit` query parameters. [See below for an explanation of returned fields.](#description) @@ -16,8 +16,8 @@ List all existing API keys. **Expired keys are included in the response**, but d | Query Parameter | Description | Default Value | | ------------------------ | --------------------------| ------------- | -| **offset** | number of keys to skip | 0 | -| **limit** | number of keys to return | 20 | +| **offset** | Number of keys to skip | 0 | +| **limit** | Number of keys to return | 20 | ### Example @@ -275,9 +275,9 @@ Date and time when the key will expire, represented in RFC 3339 format. `null` i ## Update a key - + -Update the name and description of an API key. A valid API [uid](/reference/api/keys.md#key) is required. +Update the name and description of an API key. A valid API [key](/reference/api/keys.md#key) or [uid](/reference/api/keys.md#uid) is required. To learn more about the variables sent in the body of the request, see the [create key](#body) endpoint. @@ -311,9 +311,9 @@ Updates to keys are **partial**. This means you should provide only the fields y ## Delete a key - + -Delete the specified API key. A valid API [uid](/reference/api/keys.md#uid) is required. +Delete the specified API key. A valid API [key](/reference/api/keys.md#key) or [uid](/reference/api/keys.md#uid) is required. ### Example From a349772c10c6d4ff27af17b9fb9b4b909d3f9f8d Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Tue, 28 Jun 2022 11:59:25 +0400 Subject: [PATCH 081/150] fix link --- learn/security/master_api_keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/security/master_api_keys.md b/learn/security/master_api_keys.md index 02aa839dab..23288e177b 100644 --- a/learn/security/master_api_keys.md +++ b/learn/security/master_api_keys.md @@ -150,7 +150,7 @@ It is good practice to always set an expiry date when creating a new API key. If You can use the [list keys endpoint](/reference/api/keys.md) to obtain information on any active key in your Meilisearch instance. This is useful when you need an overview of existing keys and their permissions. -By default, [`GET /keys`](/reference/api/keys.md#get-all-keys) returns the most recently created 20 keys. You can change this using the [`limit`](/reference/api/keys.html#get-all-keys) query parameter. **Expired keys will appear in the response, but deleted keys will not**. As with creating, deleting, and updating API keys, you either need the master key or an API key with the `keys.get` action to access this endpoint. +By default, [`GET /keys`](/reference/api/keys.md#get-all-keys) returns the most recently created 20 keys. You can change this using the [`limit`](/reference/api/keys.md#get-all-keys) query parameter. **Expired keys will appear in the response, but deleted keys will not**. As with creating, deleting, and updating API keys, you either need the master key or an API key with the `keys.get` action to access this endpoint. [`GET /keys/{key_or_uid}`](/reference/api/keys.md#get-one-key) returns information on a single key. `{key_or_uid}` should be replaced with the full `key` or `uid` value obtained during key creation. From cfe49f5ed0caef05cb530f788e04edab27beb20e Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Tue, 28 Jun 2022 12:43:43 +0200 Subject: [PATCH 082/150] faceting: add API reference to sidebar menu --- .vuepress/config.js | 1 + reference/api/faceting.md | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.vuepress/config.js b/.vuepress/config.js index 395bd548d8..5a0db71d9e 100644 --- a/.vuepress/config.js +++ b/.vuepress/config.js @@ -323,6 +323,7 @@ module.exports = { }, '/reference/api/displayed_attributes', '/reference/api/distinct_attribute', + '/reference/api/faceting', '/reference/api/filterable_attributes', '/reference/api/ranking_rules', '/reference/api/searchable_attributes', diff --git a/reference/api/faceting.md b/reference/api/faceting.md index fd6c6c1ba0..bafc08eb3b 100644 --- a/reference/api/faceting.md +++ b/reference/api/faceting.md @@ -4,7 +4,7 @@ _Child route of the [settings route](/reference/api/settings.md)._ This route allows you to configure the faceting settings for an index. -faceting settings can also be updated directly through the [global settings route](/reference/api/settings.md#update-settings) along with the other settings. +Faceting 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 filtering and faceting, refer to our [dedicated guide](/learn/advanced/filtering_and_faceted_search.md). @@ -51,7 +51,7 @@ Partially update the faceting settings for an index. The index [`uid`](/learn/co Configure the maximum number of facet values returned for each facet. Values are alphabetically sorted. -For example, if a query's search results contain a total of three values for a `colors` facet—`blue`, `green`, and `red`—setting `maxValuesPerFacet` to `2` causes Meilisearch to return only the `blue` and `green` in the response body's `facetDistribution` object. +For example, suppose a query's search results contain a total of three values for a `colors` facet: `blue`, `green`, and `red`. If you set `maxValuesPerFacet` to `2`, Meilisearch will only return `blue` and `green` in the response body's `facetDistribution` object. #### Example From 0a8faa653bbf893a44a2b9684d570fa9b690d583 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Tue, 28 Jun 2022 12:46:36 +0200 Subject: [PATCH 083/150] faceting: add newline at end of files --- .code-samples.meilisearch.yaml | 2 +- .vuepress/public/sample-template.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 154bededf4..01c25955c9 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -973,4 +973,4 @@ update_faceting_settings_1: |- }' reset_faceting_settings_1: |- curl \ - -X DELETE 'http://localhost:7700/indexes/books/settings/faceting' \ No newline at end of file + -X DELETE 'http://localhost:7700/indexes/books/settings/faceting' diff --git a/.vuepress/public/sample-template.yaml b/.vuepress/public/sample-template.yaml index 00f2e97787..44f0a2d788 100644 --- a/.vuepress/public/sample-template.yaml +++ b/.vuepress/public/sample-template.yaml @@ -148,4 +148,4 @@ updating_guide_add_documents_old: |- getting_started_typo_tolerance: |- get_faceting_settings_1: |- update_faceting_settings_1: |- -reset_faceting_settings_1: |- \ No newline at end of file +reset_faceting_settings_1: |- From 9cffdb11e6dfb9832de0445d47671b3a72d06231 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Tue, 28 Jun 2022 12:51:12 +0200 Subject: [PATCH 084/150] pagination: add guide placeholder --- learn/advanced/pagination.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 learn/advanced/pagination.md diff --git a/learn/advanced/pagination.md b/learn/advanced/pagination.md new file mode 100644 index 0000000000..e69de29bb2 From aec2da0bd3ff472abc2772fa2f92871e5feb2ca8 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Tue, 28 Jun 2022 13:38:02 +0200 Subject: [PATCH 085/150] pagination: update known limitations --- learn/advanced/known_limitations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/learn/advanced/known_limitations.md b/learn/advanced/known_limitations.md index e3743423b2..f76033d033 100644 --- a/learn/advanced/known_limitations.md +++ b/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-1). `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). From b0572e00bf229dd3ca4d3c08896daec2bc0ef2f7 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Tue, 28 Jun 2022 13:57:16 +0200 Subject: [PATCH 086/150] pagination: update HTTP method --- .code-samples.meilisearch.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 7f1a2450b1..509a6303bb 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -966,11 +966,11 @@ get_pagination_settings_1: |- -X GET 'http://localhost:7700/indexes/books/settings/pagination' update_pagination_settings_1: |- curl \ - -X POST 'http://localhost:7700/indexes/books/settings/pagination' \ + -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' \ No newline at end of file + -X DELETE 'http://localhost:7700/indexes/books/settings/pagination' From 04b53a46bdb3d1fc83c3fa63d1883e4ec52ac22f Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Tue, 28 Jun 2022 17:23:11 +0400 Subject: [PATCH 087/150] update code sample --- learn/security/tenant_tokens.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/learn/security/tenant_tokens.md b/learn/security/tenant_tokens.md index 86406e3bd7..aff1e6c2fd 100644 --- a/learn/security/tenant_tokens.md +++ b/learn/security/tenant_tokens.md @@ -58,6 +58,7 @@ Using a third-party library for tenant token generation is fairly similar to cre const jwt = require('jsonwebtoken'); const apiKey = 'my_api_key'; +const apiKeyUid = 'ac5cd97d-5a4b-4226-a868-2d0eb6d197ab'; const currentUserID = 'a_user_id'; const tokenPayload = { @@ -66,7 +67,7 @@ const tokenPayload = { 'filter': `user_id = ${currentUserID}` } }, - apiKeyUid: apiKey.substring(0, 8), + apiKeyUid: apiKeyUid, exp: parseInt(Date.now() / 1000) + 20 * 60 // 20 minutes }; From 9250fc03452414d8a562b546c16ccb744cf81d26 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Tue, 28 Jun 2022 16:47:30 +0200 Subject: [PATCH 088/150] Apply suggestions from code review Co-authored-by: Tommy <68053732+dichotommy@users.noreply.github.com> --- learn/advanced/pagination.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/learn/advanced/pagination.md b/learn/advanced/pagination.md index 8cef0a8b82..d2479e081b 100644 --- a/learn/advanced/pagination.md +++ b/learn/advanced/pagination.md @@ -1,16 +1,16 @@ # Pagination of search results -In a perfect world, users would not need to look beyond the first search result to find what they were looking for. In practice, this is difficult to achieve due to design constraints, performance trade-offs, and even inneffective query terms. Because of that, it is usually necessary to create a pagination interface so users can browse through long lists of results. +In a perfect world, users would not need to look beyond the first search result to find what they were looking for. In practice, however, it is usually necessary to create some kind of pagination interface so users can browse through long lists of results. In this guide, we will discuss some of Meilisearch's current limitations, how these limitations impact common pagination interface patterns, and the recommended way of handling pagination when using Meilisearch. ## Choosing the right pagination UI -For performance reasons, Meilisearch cannot provide the exact number of possible results for a query. When using the search endpoint, responses contain an `estimatedTotalHits` field. As its name indicates, `estimatedTotalHits` is only an estimate of how many documents match your user's query. +For performance reasons, Meilisearch cannot provide the exact number of results for a query. When using the search endpoint, responses contain an `estimatedTotalHits` field. As its name indicates, `estimatedTotalHits` is only an estimate of how many documents match your user's query. -Because of this, we do not recommend creating interfaces with page selectors that allow users to jump to an arbitrary results page. If page selection is crucial to the software you are developing, this document's last section lists a number of tips that might help you work around Meilisearch's current limitations. +Because of this, we do not recommend creating interfaces with page selectors that allow users to jump to a specific page. If page selection is crucial to the software you are developing, see the [last section of this page](#not-recommended-page-selection) for tips that might help you work around Meilisearch's current limitations. -Instead of a full page selector, [we recommend creating pagination interfaces centered around previous and next buttons](#recommended-previous-and-next-buttons). +We recommend creating pagination interfaces centered around previous and next buttons. ::: note By default, Meilisearch returns a maximum of 1000 search results. Consult our [index setting reference](/reference/api/settings.md) if you need to change this. @@ -18,11 +18,11 @@ By default, Meilisearch returns a maximum of 1000 search results. Consult our [i ## Recommended: Previous and next buttons -Pagination interfaces that rely solely on previous and next buttons are similar to page selectors, but do not allow users to jump to an arbitrary results page. +Using previous and next buttons for pagination means that users can easily page through results, but don't have the ability to jump to an arbitrary results page. ![Placeholder image for prev/next interface]() -Though this approach offers less precision than a full-blown page selector, it does not require knowing the number of total search results. +Though this approach offers less precision than a full-blown page selector, it does not require knowing the precise number of search results. This makes it a good fit for Meilisearch's current capabilities. ### Implementation @@ -36,17 +36,17 @@ For example, if you set `limit` to `20` and want the first page of search result const results = await index.search("x", { limit: 20, offset: 0 }); ``` -If you keep the same `limit` and want the third page of results, `offset` must be `40`: `offset = 2 * 20`. +If you want the third page of results, `offset` must be `40`: `offset = 2 * 20`. ```js const results = await index.search("x", { limit: 20, offset: 40 }); ``` -Once a query returns less than your configured `limit`, you have reached the last results page. +Once a query returns fewer `hits` than your configured `limit`, you have reached the last results page. It is often helpful to disable navigation buttons when the user cannot move to the "next" or "previous" page. The "previous" button should be disabled whenever your `offset` is 0. -To disable the "next" button, we recommend setting your query's `limit` to the number of displayed results plus one. The extra result indicates that you have at least one item beyond what you can display in a single results page: +To know when to disable the "next" button, we recommend setting your query's `limit` to the number of results you wish to display per page plus one. That extra `hit` should not be shown to the user; its purpose is to indicate that there is at least one more document to display on the next page: ```js const results = await index.search("x", { limit: 21, offset: 0 }) @@ -61,8 +61,8 @@ if (offset === 0 ) { if (results.hits.length < 21 ) { // If Meilisearch returns 20 items or less, - // we don't have any more results to - // and can disable the "next" + // we don't have any more results to display + // and can disable the "next" button document.querySelector("#next_button").disabled = true; } else { // If Meilisearch returns exactly 21 results @@ -74,15 +74,15 @@ if (results.hits.length < 21 ) { ## Not recommended: Page selection -As its name states, this type of pagination is made of a numbered list of pages accompanied by next and previous buttons. +This type of pagination consists of a numbered list of pages accompanied by next and previous buttons. ![placeholder page selection UI](https://vuejsexamples.com/content/images/2018/11/vue-pagination.gif) -This is is a common UI pattern that offers users a significant amount of precision when navigating results. +This is a common UI pattern that offers users a significant amount of precision when navigating results. However, due to Meilisearch's [limitations](#choosing-the-right-pagination-ui), it is not a good fit for pagination with Meilisearch. ### Implementation -The general implementation of a page selection interface is similar to our [recommended solution](#recommended-previous-and-next-buttons), but you must also display a page list. +The general implementation of a page selection interface is similar to our [recommended solution](#recommended-previous-and-next-buttons), but also includes a numbered page list. To create the page list, however, you must know the exact number of total results. For example, if you have 100 results and your search result pages contain 10 results each, your selector must show a list of numbers going from 1 to 10. @@ -90,7 +90,7 @@ Since Meilisearch can only give you an estimate of total search results, it can We recommend two different workarounds to create this kind of pagination interface with Meilisearch. -#### Set a hard limit of results during your search +#### Set a hard limit on search results By default, a search request returns 20 search results. You can change this value to a much higher number and treat it as the effective maximum of search results you will show a user. Doing so means the size of your `hits` array is the exact number of search results you have to paginate. @@ -101,7 +101,7 @@ For example, if you set `limit` to 300, every search request made to Meilisearch This method provides control and reliability. It also prevents users from paginating too far, which avoids performance loss. However, this limits the number of results your users can see. ::: note -We do not recommend caution when setting high values for `limit` as it can negatively impact performance. +We recommend caution when setting high values for `limit` as it can negatively impact performance. ::: #### Accept the unreliable number From a99a123bcb1128cb3fdb8bea2dea3b80fa86beab Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Tue, 28 Jun 2022 16:48:10 +0200 Subject: [PATCH 089/150] Apply suggestions from code review Co-authored-by: Tommy <68053732+dichotommy@users.noreply.github.com> --- learn/advanced/pagination.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/advanced/pagination.md b/learn/advanced/pagination.md index d2479e081b..fa35fab70a 100644 --- a/learn/advanced/pagination.md +++ b/learn/advanced/pagination.md @@ -106,7 +106,7 @@ We recommend caution when setting high values for `limit` as it can negatively i #### Accept the unreliable number -You use `estimatedTotalHits` to calculate the number of search result pages. This means your page count is likely to change until Meilisearch retrives the last search result. +In this pagination method, use `estimatedTotalHits` to calculate the number of search result pages. This means your number of results and page count are likely to change until Meilisearch retrieves the last search result. For example, a query's `estimatedTotalHits` might be `100` when you fetch the first page of search results. If you are showing 20 results per page, this means your interface will display a page selector with 5 pages. When you fetch the fifth and last page according to Meilisearch's current estimate, however, `estimatedTotalHits` might change to `300`. Your page list, previously displaying 5 pages, must now show 10 total pages. From d63d87d3d4e30a57bf5d50bd94be686ed97f0dcd Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Tue, 28 Jun 2022 17:11:44 +0200 Subject: [PATCH 090/150] Apply suggestions from code review Co-authored-by: Tommy <68053732+dichotommy@users.noreply.github.com> --- learn/advanced/pagination.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/advanced/pagination.md b/learn/advanced/pagination.md index fa35fab70a..0c6c78dbb8 100644 --- a/learn/advanced/pagination.md +++ b/learn/advanced/pagination.md @@ -28,7 +28,7 @@ Though this approach offers less precision than a full-blown page selector, it d Previous and next buttons can be implemented using the [`limit`](/reference/api/search.md#limit) and [`offset`](/reference/api/search.md#offset) search parameters. -Paginating requires providing an `offset` that is equal to your `limit` times the page number times: `offset = limit * page number`. We recommend starting page count from 0 instead of 1 when calculating offset values. +Paginating requires providing an `offset` that is equal to your `limit` times the page number: `offset = limit * page number`. We recommend starting page count from 0 instead of 1 when calculating offset values. For example, if you set `limit` to `20` and want the first page of search results, your `offset` must be 0: `offset = 0 * 20`. From eb937fb5616b40725cd9509e91eea1c4bd97abb6 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Wed, 29 Jun 2022 13:39:21 +0400 Subject: [PATCH 091/150] replace `uid` with `key` --- .code-samples.meilisearch.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 6c53c49064..92ff722538 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -112,7 +112,7 @@ create_a_key_1: |- }' update_a_key_1: |- curl \ - -X PATCH 'http://localhost:7700/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \ + -X PATCH 'http://localhost:7700/keys/d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4' \ -H 'Authorization: Bearer MASTER_KEY' \ -H 'Content-Type: application/json' \ --data-binary '{ From f76015b049929b173e37d4a9c894d079c92a1433 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Wed, 29 Jun 2022 13:59:08 +0400 Subject: [PATCH 092/150] v0.28: Telemetry updates --- learn/what_is_meilisearch/telemetry.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/learn/what_is_meilisearch/telemetry.md b/learn/what_is_meilisearch/telemetry.md index d61c619738..8ed791638a 100644 --- a/learn/what_is_meilisearch/telemetry.md +++ b/learn/what_is_meilisearch/telemetry.md @@ -152,7 +152,8 @@ This list is liable to change with every new version of Meilisearch. It's not be | `formatting.highlight_post_tag` | `true` if `highlightPostTag` is specified, otherwise `false` | false | `formatting.crop_length` | `true` if `cropLength` is specified, otherwise `false` | false | `formatting.crop_marker` | `true` if `cropMarker` is specified, otherwise `false` | false -| `formatting.matches` | `true` if `matches` is specified, otherwise `false` | false +| `formatting.show_matches_position` | `true` if `showMatchesPosition` is used in this batch, otherwise `false` | false +| `facets` | `true` if `facets` is used in this batch, otherwise `false` | false | `primary_key` | Name of primary key when explicitly set as part of document addition, document update, index creation, or index update. Otherwise `null` | id | `payload_type` | All values encountered in the `Content-Type` header, including invalid ones | ["application/json", "text/plain", "application/x-ndjson"] | `index_creation` | `true` if a document addition or update request triggered index creation, otherwise `false` | true @@ -163,8 +164,13 @@ This list is liable to change with every new version of Meilisearch. It's not be | `filterable_attributes.has_geo` | `true` if `_geo` is set as a filterable attribute, otherwise `false` | false | `searchable_attributes.total` | Number of searchable attributes | 4 | `per_task_uid` | `true` if a `uid` is used to fetch a particular task resource, otherwise `false` | true +| `filtered_by_index_uid` | `true` if the `GET /tasks` endpoint is filered by `indexUid`, otherwise `false` | false +| `filtered_by_type` | `true` if the `GET /tasks` endpoint is filered by `type`, otherwise `false` | false +| `filtered_by_status` | `true` if the `GET /tasks` endpoint is filered by `status`, otherwise `false` | false | `typo_tolerance.enabled` | `true` if typo tolerance is enabled, otherwise `false` | true | `typo_tolerance.disable_on_attributes` | `true` if at least one value is defined for `disableOnAttributes`, otherwise `false` | false | `typo_tolerance.disable_on_words` | `true` if at least one value is defined for `disableOnWords`, otherwise `false` | false | `typo_tolerance.min_word_size_for_typos.one_typo` | The defined value for the `minWordSizeForTypos.oneTypo` parameter | 5 | `typo_tolerance.min_word_size_for_typos.two_typos` | The defined value for the `minWordSizeForTypos.twoTypos` parameter | 9 +| `pagination.max_total_hits` | The defined value for the `pagination.maxTotalHits` property | 1000 +| `faceting.max_values_per_facet` | The defined value for the `faceting.maxValuesPerFacet` property | 100 From e5ab6cda87e33a130ed190366479b8fe93b21691 Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Wed, 29 Jun 2022 14:01:00 +0400 Subject: [PATCH 093/150] Update telemetry.md --- learn/what_is_meilisearch/telemetry.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/learn/what_is_meilisearch/telemetry.md b/learn/what_is_meilisearch/telemetry.md index 8ed791638a..ad6a3c2fdd 100644 --- a/learn/what_is_meilisearch/telemetry.md +++ b/learn/what_is_meilisearch/telemetry.md @@ -152,8 +152,8 @@ This list is liable to change with every new version of Meilisearch. It's not be | `formatting.highlight_post_tag` | `true` if `highlightPostTag` is specified, otherwise `false` | false | `formatting.crop_length` | `true` if `cropLength` is specified, otherwise `false` | false | `formatting.crop_marker` | `true` if `cropMarker` is specified, otherwise `false` | false -| `formatting.show_matches_position` | `true` if `showMatchesPosition` is used in this batch, otherwise `false` | false -| `facets` | `true` if `facets` is used in this batch, otherwise `false` | false +| `formatting.show_matches_position` | `true` if `showMatchesPosition` is used in this batch, otherwise `false` | false +| `facets` | `true` if `facets` is used in this batch, otherwise `false` | false | `primary_key` | Name of primary key when explicitly set as part of document addition, document update, index creation, or index update. Otherwise `null` | id | `payload_type` | All values encountered in the `Content-Type` header, including invalid ones | ["application/json", "text/plain", "application/x-ndjson"] | `index_creation` | `true` if a document addition or update request triggered index creation, otherwise `false` | true From 9d070d1ae09012b2e435c7505e722bd8c3b9de18 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 29 Jun 2022 12:45:36 +0200 Subject: [PATCH 094/150] pagination guide: first draft --- learn/advanced/pagination.md | 71 +++++++++++++++++++++--------------- 1 file changed, 42 insertions(+), 29 deletions(-) diff --git a/learn/advanced/pagination.md b/learn/advanced/pagination.md index 0c6c78dbb8..f2bff6a617 100644 --- a/learn/advanced/pagination.md +++ b/learn/advanced/pagination.md @@ -1,20 +1,18 @@ # Pagination of search results -In a perfect world, users would not need to look beyond the first search result to find what they were looking for. In practice, however, it is usually necessary to create some kind of pagination interface so users can browse through long lists of results. +In a perfect world, users would not need to look beyond the first search result to find what they were looking for. In practice, however, it is usually necessary to create some kind of pagination interface to browse through long lists of results. In this guide, we will discuss some of Meilisearch's current limitations, how these limitations impact common pagination interface patterns, and the recommended way of handling pagination when using Meilisearch. ## Choosing the right pagination UI -For performance reasons, Meilisearch cannot provide the exact number of results for a query. When using the search endpoint, responses contain an `estimatedTotalHits` field. As its name indicates, `estimatedTotalHits` is only an estimate of how many documents match your user's query. +There are quite a few pagination interfaces you might want to implement in your application. Many common UI patterns have a page selector allowing users to jump to any search results page. To create a page selector, you must know the exact number of total results so you can calculate the precise number of results pages. -Because of this, we do not recommend creating interfaces with page selectors that allow users to jump to a specific page. If page selection is crucial to the software you are developing, see the [last section of this page](#not-recommended-page-selection) for tips that might help you work around Meilisearch's current limitations. +For performance reasons, however, Meilisearch cannot provide the exact number of results for a query. Instead, When using the search endpoint, responses contain an `estimatedTotalHits` field. As its name indicates, `estimatedTotalHits` is only an estimate of how many documents match your user's query. -We recommend creating pagination interfaces centered around previous and next buttons. +Because of this, we do not recommend creating interfaces with page selectors. If page selection is crucial to the software you are developing, see the [last section of this page](#not-recommended-page-selection) for tips that might help you work around Meilisearch's current limitations. -::: note -By default, Meilisearch returns a maximum of 1000 search results. Consult our [index setting reference](/reference/api/settings.md) if you need to change this. -::: +We recommend creating pagination interfaces centered around [previous and next buttons](#recommended-previous-and-next-buttons). ## Recommended: Previous and next buttons @@ -26,48 +24,63 @@ Though this approach offers less precision than a full-blown page selector, it d ### Implementation +#### `limit` and `offset` + Previous and next buttons can be implemented using the [`limit`](/reference/api/search.md#limit) and [`offset`](/reference/api/search.md#offset) search parameters. -Paginating requires providing an `offset` that is equal to your `limit` times the page number: `offset = limit * page number`. We recommend starting page count from 0 instead of 1 when calculating offset values. +`limit` sets the size of page. If you set `limit` to 20, Meilisearch's response will contain a maximum of 20 search results. `offset` skips a number of search results. If you set `offset` to 40, Meilisearch's response will skip the first 40 search results. + +You can use both parameters together to effectively create search pages. + +#### Search pages and calculating `offset` -For example, if you set `limit` to `20` and want the first page of search results, your `offset` must be 0: `offset = 0 * 20`. +If you set `limit` to 20 and `offset` to 0, you get the first twenty results. We can call this our first page. ```js const results = await index.search("x", { limit: 20, offset: 0 }); ``` -If you want the third page of results, `offset` must be `40`: `offset = 2 * 20`. +Likewise, if you set `limit` to 20 and `offset` to 40, you skip the first 40 search results and get documents ranked from 41 through 60. We can call this the third results page. ```js const results = await index.search("x", { limit: 20, offset: 40 }); ``` +Use this formula to quickly calculate a page's offset value: `offset = limit * (page number - 1)`. + Once a query returns fewer `hits` than your configured `limit`, you have reached the last results page. -It is often helpful to disable navigation buttons when the user cannot move to the "next" or "previous" page. The "previous" button should be disabled whenever your `offset` is 0. +#### Disabling navigation buttons for first and last pages + +It is often helpful to disable navigation buttons when the user cannot move to the "next" or "previous" page. + +The "previous" button should be disabled whenever your `offset` is 0, as this indicates your user is on the first results page. -To know when to disable the "next" button, we recommend setting your query's `limit` to the number of results you wish to display per page plus one. That extra `hit` should not be shown to the user; its purpose is to indicate that there is at least one more document to display on the next page: +To know when to disable the "next" button, we recommend setting your query's `limit` to the number of results you wish to display per page plus one. That extra `hit` should not be shown to the user. Its purpose is to indicate that there is at least one more document to display on the next page: ```js const results = await index.search("x", { limit: 21, offset: 0 }) +// If offset equals 0, we're on the first results page if (offset === 0 ) { - // If offset equals 0, we're on the first results page - // and can disable the "previous" buttons document.querySelector("#previous_button").disabled = true; -} else { +} + +// If offset is bigger than 0, we're not on the first results page +if (offset > 0 ) { document.querySelector("#previous_button").disabled = false; } +// If Meilisearch returns 20 items or less, +// we are on the last page if (results.hits.length < 21 ) { - // If Meilisearch returns 20 items or less, - // we don't have any more results to display - // and can disable the "next" button document.querySelector("#next_button").disabled = true; -} else { - // If Meilisearch returns exactly 21 results - // and our page can only show 20 items at a time, - // we have at least one more page with 1 result in it +} + +// If Meilisearch returns exactly 21 results +// and our page can only show 20 items at a time, +// we have at least one more page with one result in it +if (results.hits.length === 21 ) { document.querySelector("#next_button").disabled = false; } ``` @@ -84,13 +97,13 @@ This is a common UI pattern that offers users a significant amount of precision The general implementation of a page selection interface is similar to our [recommended solution](#recommended-previous-and-next-buttons), but also includes a numbered page list. -To create the page list, however, you must know the exact number of total results. For example, if you have 100 results and your search result pages contain 10 results each, your selector must show a list of numbers going from 1 to 10. +To create a numbered page list, however, you must know the exact number of total results. For example, if you have 100 results and your search result pages contain 10 results each, your selector must show a list of numbers going from 1 to 10. -Since Meilisearch can only give you an estimate of total search results, it can be difficult to implement page selectors when using Meilisearch. +Since Meilisearch can only give you an estimate of total search results, it is difficult to implement page selectors when using Meilisearch. We recommend two different workarounds to create this kind of pagination interface with Meilisearch. -#### Set a hard limit on search results +#### Use `limit` to set a maximum number of search results By default, a search request returns 20 search results. You can change this value to a much higher number and treat it as the effective maximum of search results you will show a user. Doing so means the size of your `hits` array is the exact number of search results you have to paginate. @@ -98,15 +111,15 @@ For example, if you set `limit` to 300, every search request made to Meilisearch // perhaps a code sample here? -This method provides control and reliability. It also prevents users from paginating too far, which avoids performance loss. However, this limits the number of results your users can see. +This method provides control and reliability. It also prevents users from paginating too far, which might result in performance gains. However, it limits the number of results your users can see. Additionally, we recommend caution when setting high values for `limit` as it can negatively impact performance. ::: note -We recommend caution when setting high values for `limit` as it can negatively impact performance. +By default, Meilisearch returns a maximum of 1000 search results. Consult our [index setting reference](/reference/api/pagination.md#maxtotalhits-1) if you need to change this. ::: -#### Accept the unreliable number +#### Use `estimatedTotalHits` -In this pagination method, use `estimatedTotalHits` to calculate the number of search result pages. This means your number of results and page count are likely to change until Meilisearch retrieves the last search result. +Though we advise against it, you can use `estimatedTotalHits` to calculate the number of search result pages. This means your number of results and page count are likely to change until Meilisearch retrieves the last search result. For example, a query's `estimatedTotalHits` might be `100` when you fetch the first page of search results. If you are showing 20 results per page, this means your interface will display a page selector with 5 pages. When you fetch the fifth and last page according to Meilisearch's current estimate, however, `estimatedTotalHits` might change to `300`. Your page list, previously displaying 5 pages, must now show 10 total pages. From edb981aa72e173c8579cf20808dc2081f8714c83 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Wed, 29 Jun 2022 14:47:52 +0400 Subject: [PATCH 095/150] remove `dumps.get ` --- reference/api/keys.md | 1 - 1 file changed, 1 deletion(-) diff --git a/reference/api/keys.md b/reference/api/keys.md index 8716a20d18..0f83bffc39 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -175,7 +175,6 @@ A list of API actions permitted for the key. `["*"]` for all actions. | settings.update | Provides access to the [update settings](/reference/api/settings.md#update-settings) and [reset settings](/reference/api/settings.md#reset-settings) endpoints and equivalents for all subroutes on authorized indexes. | | stats.get | Provides access to the [get stats of an index](/reference/api/stats.md#get-stats-of-an-index) endpoint and the [get stats of all indexes](/reference/api/stats.md#get-stats-of-all-indexes) endpoint. For the latter, **non-authorized `indexes` are omitted from the response**. | | dumps.create | Provides access to the [create dump](/reference/api/dump.md#create-a-dump) endpoint. **Not restricted by `indexes`.** | -| dumps.get | Provides access to the [get dump status](/reference/api/dump.md#get-dump-status) endpoint. **Not restricted by `indexes`.** | | version | Provides access to the [get Meilisearch version](/reference/api/version.md#get-version-of-meilisearch) endpoint. | #### `indexes` From 6fdb452cb9fe59a9df11727a189d2163a31afecd Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 29 Jun 2022 13:08:01 +0200 Subject: [PATCH 096/150] Apply suggestions from code review Co-authored-by: Tommy <68053732+dichotommy@users.noreply.github.com> --- reference/api/search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/search.md b/reference/api/search.md index ffdd9e281f..ca7c171c25 100644 --- a/reference/api/search.md +++ b/reference/api/search.md @@ -464,7 +464,7 @@ Instead of supplying individual attributes, you can provide `["*"]` as a wildcar Suppose you have a field containing the following string: `Donatello is a skilled and smart turtle. Leonardo is the most skilled turtle. Raphael is the strongest turtle.` -Meilisearch respects sentence boundaries when cropping. For example, if your search term is `Leonardo` and your `cropLength` is 6, Meilisearch will prioritize keeping the sentence together and return: `Leonardo is the most skilled turtle.` +Meilisearch tries to respect sentence boundaries when cropping. For example, if your search term is `Leonardo` and your `cropLength` is 6, Meilisearch will prioritize keeping the sentence together and return: `Leonardo is the most skilled turtle.` If a query contains only a single search term, Meilisearch crops around the first occurrence of that term. If you search for `turtle` and your `cropLength` is 7, Meilisearch will return the first instance of that word: `Donatello is a skilled and smart turtle.` From 3cd5718fd4c40b8da64f3e340aac6bf39103ada8 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 29 Jun 2022 13:33:58 +0200 Subject: [PATCH 097/150] smart cropping: address review feedback --- reference/api/search.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/api/search.md b/reference/api/search.md index ca7c171c25..01713ab57a 100644 --- a/reference/api/search.md +++ b/reference/api/search.md @@ -460,7 +460,7 @@ Optionally, you can indicate a custom crop length for any attributes given to `a Instead of supplying individual attributes, you can provide `["*"]` as a wildcard: `attributesToCrop=["*"]`. This causes `_formatted` to include the cropped values of all attributes present in [`attributesToRetrieve`](#attributes-to-retrieve). -#### Cropping rules +#### Cropping algorithm Suppose you have a field containing the following string: `Donatello is a skilled and smart turtle. Leonardo is the most skilled turtle. Raphael is the strongest turtle.` @@ -470,7 +470,7 @@ If a query contains only a single search term, Meilisearch crops around the firs If a query contains multiple search terms, Meilisearch centers the crop around the largest number of unique matches, giving priority to terms that are closer to each other and follow the original query order. If you search for `skilled turtle` with a `cropLength` of 6, Meilisearch will return `Leonardo is the most skilled turtle`. -If Meilisearch does not find any query terms in a field, cropping begins at the first word in that field. If you search for `Michelangelo` with a `cropLength` of 4, Meilisearch will return `Donatello is a skilled …`. +If Meilisearch does not find any query terms in a field, cropping begins at the first word in that field. If you search for `Michelangelo` with a `cropLength` of 4 and this string is present in another field, Meilisearch will return `Donatello is a skilled …`. #### Example From 7e70b5c536619eb759dae96e2c969a9077322683 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Wed, 29 Jun 2022 16:42:38 +0400 Subject: [PATCH 098/150] update `geosearch_guide_filter_settings_1` --- .code-samples.meilisearch.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index f7eebbac1f..f9f10c57d6 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -744,7 +744,7 @@ search_parameter_guide_sort_1: |- }' geosearch_guide_filter_settings_1: |- curl \ - -X POST 'http://localhost:7700/indexes/restaurants/settings/filterable-attributes' \ + -X PUT 'http://localhost:7700/indexes/restaurants/settings/filterable-attributes' \ -H 'Content-type:application/json' \ --data-binary '["_geo"]' geosearch_guide_filter_usage_1: |- From 32b82c7906aa399a508cede300c40906e116969c Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 29 Jun 2022 15:09:05 +0200 Subject: [PATCH 099/150] Update reference/api/documents.md --- reference/api/documents.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/documents.md b/reference/api/documents.md index 908e442047..2becf9dc9f 100644 --- a/reference/api/documents.md +++ b/reference/api/documents.md @@ -79,7 +79,7 @@ Documents are ordered by Meilisearch depending on the hash of their id. ], "offset": 0, "limit": 2, - "total": 50134 + "total": 500134 } ``` From ae3eff9a51bf0347b9b576b21ee7376534226882 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 29 Jun 2022 15:27:46 +0200 Subject: [PATCH 100/150] rollback change to meilisearch-collection.json --- .vuepress/public/postman/meilisearch-collection.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.vuepress/public/postman/meilisearch-collection.json b/.vuepress/public/postman/meilisearch-collection.json index 08ae02eb1e..5af874b190 100644 --- a/.vuepress/public/postman/meilisearch-collection.json +++ b/.vuepress/public/postman/meilisearch-collection.json @@ -55,7 +55,7 @@ "disabled": true }, { - "key": "fields", + "key": "attributesToRetrieve", "value": "*", "disabled": true } From 1e88a917941a93a399874f86bd1a4927301c0caf Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 29 Jun 2022 15:56:18 +0200 Subject: [PATCH 101/150] Apply suggestions from code review Co-authored-by: Maryam <90181761+maryamsulemani97@users.noreply.github.com> --- reference/api/pagination.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/pagination.md b/reference/api/pagination.md index e4e066488a..1c0cf7aea6 100644 --- a/reference/api/pagination.md +++ b/reference/api/pagination.md @@ -83,7 +83,7 @@ Reset an index's pagination settings to their default value. The index [`uid`](/ ```json { - "uid": 1, + "taskUid": 1, "indexUid": "books", "status": "enqueued", "type": "settingsUpdate", From c6215aea5fe0cc439473f095e5f697f6e4a5661a Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Wed, 29 Jun 2022 18:01:01 +0400 Subject: [PATCH 102/150] Apply suggestions from code review Co-authored-by: gui machiavelli --- learn/security/master_api_keys.md | 2 +- reference/api/keys.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/learn/security/master_api_keys.md b/learn/security/master_api_keys.md index 23288e177b..8f3c1ec36f 100644 --- a/learn/security/master_api_keys.md +++ b/learn/security/master_api_keys.md @@ -150,7 +150,7 @@ It is good practice to always set an expiry date when creating a new API key. If You can use the [list keys endpoint](/reference/api/keys.md) to obtain information on any active key in your Meilisearch instance. This is useful when you need an overview of existing keys and their permissions. -By default, [`GET /keys`](/reference/api/keys.md#get-all-keys) returns the most recently created 20 keys. You can change this using the [`limit`](/reference/api/keys.md#get-all-keys) query parameter. **Expired keys will appear in the response, but deleted keys will not**. As with creating, deleting, and updating API keys, you either need the master key or an API key with the `keys.get` action to access this endpoint. +By default, [`GET /keys`](/reference/api/keys.md#get-all-keys) returns the 20 most recently created keys. You can change this using the [`limit`](/reference/api/keys.md#get-all-keys) query parameter. **Expired keys will appear in the response, but deleted keys will not**. As with creating, deleting, and updating API keys, you either need the master key or an API key with the `keys.get` action to access this endpoint. [`GET /keys/{key_or_uid}`](/reference/api/keys.md#get-one-key) returns information on a single key. `{key_or_uid}` should be replaced with the full `key` or `uid` value obtained during key creation. diff --git a/reference/api/keys.md b/reference/api/keys.md index 35e41c2f8e..886e170682 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -8,7 +8,7 @@ The `/keys` route allows you to create, manage, and delete API keys. To use thes -List the most recently created 20 keys. **Expired keys are included in the response**, but deleted keys are not. Results can be paginated by using the `offset` and `limit` query parameters. +List the 20 most recently created keys. **Expired keys are included in the response**, but deleted keys are not. Results can be paginated by using the `offset` and `limit` query parameters. [See below for an explanation of returned fields.](#description) @@ -116,7 +116,7 @@ A description for the key. Default value is `null`. #### `uid` -A [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) to identify the API key. If not specified, it is generated by Meilisearch. +A [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) to identify the API key. If not specified, it is automatically generated by Meilisearch. #### `key` From df1d260d1450dfbe284297af0d53451179699026 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 29 Jun 2022 16:05:53 +0200 Subject: [PATCH 103/150] pagination settings: address review feedback --- reference/api/pagination.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/reference/api/pagination.md b/reference/api/pagination.md index 1c0cf7aea6..48cacdc784 100644 --- a/reference/api/pagination.md +++ b/reference/api/pagination.md @@ -53,6 +53,10 @@ An integer indicating the maximum number of search results Meilisearch can retur 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. +::: + #### Example @@ -61,7 +65,7 @@ For example, if you set `maxTotalHits` to 100, you will not be able to access se ```json { - "uid": 1, + "taskUid": 1, "indexUid": "books", "status": "enqueued", "type": "settingsUpdate", From 3ffacec1198ae89b4c4ce4b2f9307aaf5acac725 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 29 Jun 2022 16:11:46 +0200 Subject: [PATCH 104/150] Apply suggestions from code review Co-authored-by: Maryam <90181761+maryamsulemani97@users.noreply.github.com> --- .code-samples.meilisearch.yaml | 2 +- reference/api/faceting.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 01c25955c9..d121406c65 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -966,7 +966,7 @@ get_faceting_settings_1: |- -X GET 'http://localhost:7700/indexes/books/settings/faceting' update_faceting_settings_1: |- curl \ - -X POST 'http://localhost:7700/indexes/books/settings/faceting' \ + -X PATCH 'http://localhost:7700/indexes/books/settings/faceting' \ -H 'Content-Type: application/json' \ --data-binary '{ "maxValuesPerFacet": 2 diff --git a/reference/api/faceting.md b/reference/api/faceting.md index bafc08eb3b..691680214d 100644 --- a/reference/api/faceting.md +++ b/reference/api/faceting.md @@ -83,7 +83,7 @@ Reset an index's faceting settings to their default value. The index [`uid`](/le ```json { - "uid": 1, + "taskUid": 1, "indexUid": "books", "status": "enqueued", "type": "settingsUpdate", From bb77d2d5b2861e69858328d2b342784f215d60ec Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 29 Jun 2022 16:12:00 +0200 Subject: [PATCH 105/150] Update reference/api/faceting.md Co-authored-by: Maryam <90181761+maryamsulemani97@users.noreply.github.com> --- reference/api/faceting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/faceting.md b/reference/api/faceting.md index 691680214d..1469d14598 100644 --- a/reference/api/faceting.md +++ b/reference/api/faceting.md @@ -61,7 +61,7 @@ For example, suppose a query's search results contain a total of three values fo ```json { - "uid": 1, + "taskUid": 1, "indexUid": "books", "status": "enqueued", "type": "settingsUpdate", From 100c17a3fa46d214fc5d4ddaa998e6974409fc77 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 29 Jun 2022 16:15:45 +0200 Subject: [PATCH 106/150] faceting settings: address review feedback --- reference/api/faceting.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/reference/api/faceting.md b/reference/api/faceting.md index 1469d14598..0baa25aad8 100644 --- a/reference/api/faceting.md +++ b/reference/api/faceting.md @@ -53,6 +53,10 @@ Configure the maximum number of facet values returned for each facet. Values are For example, suppose a query's search results contain a total of three values for a `colors` facet: `blue`, `green`, and `red`. If you set `maxValuesPerFacet` to `2`, Meilisearch will only return `blue` and `green` in the response body's `facetDistribution` object. +::: note +Settings `maxValuesPerFacet` to a high value might negatively impact performance. +::: + #### Example From 456eec5bc8dd568a6a9339d87f5d18975bb565f0 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 29 Jun 2022 16:16:07 +0200 Subject: [PATCH 107/150] faceting settings: address review feedback --- reference/api/settings.md | 1 + 1 file changed, 1 insertion(+) diff --git a/reference/api/settings.md b/reference/api/settings.md index 78dd471bc3..4d62369e92 100644 --- a/reference/api/settings.md +++ b/reference/api/settings.md @@ -6,6 +6,7 @@ These are the reference pages for the child routes: - [Displayed attributes](/reference/api/displayed_attributes.md) - [Distinct attribute](/reference/api/distinct_attribute.md) +- [Faceting](/reference/api/faceting.md) - [Filterable attributes](/reference/api/filterable_attributes.md) - [Ranking rules](/reference/api/ranking_rules.md) - [Searchable attributes](/reference/api/searchable_attributes.md) From f5653cf238eaeb5b00e19d6857925e7825d7e146 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 29 Jun 2022 16:17:24 +0200 Subject: [PATCH 108/150] pagination settings: improve note on side effects of high `maxTotalHits` --- reference/api/pagination.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/pagination.md b/reference/api/pagination.md index 48cacdc784..0e1debe2ce 100644 --- a/reference/api/pagination.md +++ b/reference/api/pagination.md @@ -54,7 +54,7 @@ An integer indicating the maximum number of search results Meilisearch can retur 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. +Setting `maxTotalHits` to a high value might negatively impact performance and expose instance data to malicious scraping. ::: #### Example From 9371bcb20abbe80d00be4038dd3cad9ee9e2952c Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Wed, 29 Jun 2022 18:20:08 +0400 Subject: [PATCH 109/150] update based on Gui's review --- reference/api/keys.md | 56 +++++++++++++++++++++++-------------------- 1 file changed, 30 insertions(+), 26 deletions(-) diff --git a/reference/api/keys.md b/reference/api/keys.md index 886e170682..417f3d29c3 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -160,8 +160,10 @@ Get information on the specified key. Attempting to use this endpoint with a non ```json { + "name": null, "description": "Add documents: Products API key", "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", + "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d", "actions": [ "documents.add" ], @@ -259,17 +261,19 @@ Date and time when the key will expire, represented in RFC 3339 format. `null` i ```json { - "description": "Add documents: Products API key", - "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", - "actions": [ - "documents.add" - ], - "indexes": [ - "products" - ], - "expiresAt": "2021-11-13T00:00:00Z", - "createdAt": "2021-11-12T10:00:00Z", - "updatedAt": "2021-11-12T10:00:00Z" + "name": null, + "description": "Manage documents: Products/Reviews API key", + "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", + "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d", + "actions": [ + "documents.add" + ], + "indexes": [ + "products" + ], + "expiresAt": "2021-11-13T00:00:00Z", + "createdAt": "2021-11-12T10:00:00Z", + "updatedAt": "2021-11-12T10:00:00Z" } ``` @@ -291,21 +295,21 @@ Updates to keys are **partial**. This means you should provide only the fields y ```json { - "name": "Products/Reviews API key", - "description": "Manage documents: Products/Reviews API key", - "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", - "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d", - "actions": [ - "documents.add", - "documents.delete" - ], - "indexes": [ - "products", - "reviews" - ], - "expiresAt": "2021-12-31T23:59:59Z", - "createdAt": "2021-10-12T00:00:00Z", - "updatedAt": "2021-10-13T15:00:00Z" + "name": "Products/Reviews API key", + "description": "Manage documents: Products/Reviews API key", + "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", + "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d", + "actions": [ + "documents.add", + "documents.delete" + ], + "indexes": [ + "products", + "reviews" + ], + "expiresAt": "2021-12-31T23:59:59Z", + "createdAt": "2021-10-12T00:00:00Z", + "updatedAt": "2021-10-13T15:00:00Z" } ``` From 2e8e715df688e99683c9df1cfb36bce28ad43742 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 29 Jun 2022 16:21:57 +0200 Subject: [PATCH 110/150] pagination settings: fix broken hash --- learn/advanced/known_limitations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/advanced/known_limitations.md b/learn/advanced/known_limitations.md index f76033d033..a383d0420c 100644 --- a/learn/advanced/known_limitations.md +++ b/learn/advanced/known_limitations.md @@ -99,4 +99,4 @@ user = 1 OR user = 2 […] OR user = 1500 OR user = 1501 […] OR user = 2000 OR **Limitation:** By default, Meilisearch returns up to 1000 documents per search. -**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-1). `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). +**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). From b397e1fd2c5c5d93df57d339d080ae8d392d987b Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 29 Jun 2022 16:31:39 +0200 Subject: [PATCH 111/150] pagination settings: update boxes with warnings on non-customizable maximum number of results --- reference/api/search.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/api/search.md b/reference/api/search.md index 491fc9aa8b..9d2a036608 100644 --- a/reference/api/search.md +++ b/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. From 6a618ad0f5f6810a5516b8b1f3306692d2921fb2 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 30 Jun 2022 12:37:16 +0200 Subject: [PATCH 112/150] Update reference/api/pagination.md Co-authored-by: Maryam <90181761+maryamsulemani97@users.noreply.github.com> --- reference/api/pagination.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/pagination.md b/reference/api/pagination.md index 0e1debe2ce..485e99c916 100644 --- a/reference/api/pagination.md +++ b/reference/api/pagination.md @@ -73,7 +73,7 @@ Setting `maxTotalHits` to a high value might negatively impact performance and e } ``` -You can use the returned `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +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 From f48fe20541a3b129dad1a23c135ea9ef54fa3e27 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 30 Jun 2022 12:37:30 +0200 Subject: [PATCH 113/150] Update reference/api/pagination.md Co-authored-by: Maryam <90181761+maryamsulemani97@users.noreply.github.com> --- reference/api/pagination.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/pagination.md b/reference/api/pagination.md index 485e99c916..f4d15d47b8 100644 --- a/reference/api/pagination.md +++ b/reference/api/pagination.md @@ -95,4 +95,4 @@ Reset an index's pagination settings to their default value. The index [`uid`](/ } ``` -You can use the returned `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). From 213c326c11ec7b1331adc9382b00515d8af6a25c Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Thu, 30 Jun 2022 14:38:14 +0400 Subject: [PATCH 114/150] Add pagination to core concepts/indexes --- learn/core_concepts/indexes.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/learn/core_concepts/indexes.md b/learn/core_concepts/indexes.md index 36f069949e..600bcd2c63 100644 --- a/learn/core_concepts/indexes.md +++ b/learn/core_concepts/indexes.md @@ -59,6 +59,7 @@ You can customize the following index settings: - [Stop words](#stop-words) - [Displayed and searchable attributes](#displayed-and-searchable-attributes) - [Typo tolerance](#typo-tolerance) +- [Pagination](#pagination) To change index settings, use the [update settings endpoint](/reference/api/settings.md#update-settings) or any of the [child routes](/reference/api/settings.md#all-settings). @@ -130,3 +131,11 @@ Typo tolerance is a built-in feature that helps you find relevant results even w You can update the typo tolerance settings using the [update settings endpoint](/reference/api/settings.md#update-settings) or the [update typo tolerance endpoint](/reference/api/typo_tolerance.md#update-typo-tolerance). [Learn more about typo tolerance](/learn/configuration/typo_tolerance.md) + +### Pagination + +To protect your database from malicious scraping, Meilisearch returns upto 1000 results for a search query. You can update this using the [update settings endpoint](/reference/api/settings.md#update-settings) or the [update pagination settings endpoint](/reference/api/pagination.md#update-pagination-settings). + +We recommend using the [`limit`](/reference/api/search.md#limit) and [`offset`](/reference/api/search.md#offset) search parameters to implement previous and next buttons for a pagination UI. + +[Learn more about pagination](/learn/advanced/pagination.md) From 4c6a5f9b447ce92e5b4cfb19dd61a497f727c9b4 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 30 Jun 2022 12:45:54 +0200 Subject: [PATCH 115/150] Apply suggestions from code review Co-authored-by: Maryam <90181761+maryamsulemani97@users.noreply.github.com> --- reference/api/faceting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/reference/api/faceting.md b/reference/api/faceting.md index 0baa25aad8..ef5622226f 100644 --- a/reference/api/faceting.md +++ b/reference/api/faceting.md @@ -54,7 +54,7 @@ Configure the maximum number of facet values returned for each facet. Values are For example, suppose a query's search results contain a total of three values for a `colors` facet: `blue`, `green`, and `red`. If you set `maxValuesPerFacet` to `2`, Meilisearch will only return `blue` and `green` in the response body's `facetDistribution` object. ::: note -Settings `maxValuesPerFacet` to a high value might negatively impact performance. +Setting `maxValuesPerFacet` to a high value might negatively impact performance. ::: #### Example @@ -73,7 +73,7 @@ Settings `maxValuesPerFacet` to a high value might negatively impact performance } ``` -You can use the returned `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). ## Reset faceting settings @@ -95,4 +95,4 @@ Reset an index's faceting settings to their default value. The index [`uid`](/le } ``` -You can use the returned `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). From da8c4a68caa628ece2a3bde8defae2aa5cd38706 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 30 Jun 2022 12:56:03 +0200 Subject: [PATCH 116/150] faceting settings: add note to faceting guide --- learn/advanced/filtering_and_faceted_search.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/learn/advanced/filtering_and_faceted_search.md b/learn/advanced/filtering_and_faceted_search.md index 5c7e83c362..0d12f434d7 100644 --- a/learn/advanced/filtering_and_faceted_search.md +++ b/learn/advanced/filtering_and_faceted_search.md @@ -316,6 +316,10 @@ Using the `facetsDistribution` search parameter adds two new keys to the returne `exhaustiveFacetsCount` is not currently implemented in and will always return `false`. ::: +::: note +By default, `facetDistribution` returns a maximum of 100 facet values for each faceted field. You can change this value using the `maxValuesPerFacet` property of the [`faceting` index settings](/reference/api/faceting.md). +::: + ##### Example You can write a search query that gives you the distribution of `batman` movies per genre: From 0a340c234a8b3810394623a4a580fb5dfe7142e5 Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Thu, 30 Jun 2022 15:23:55 +0400 Subject: [PATCH 117/150] Update learn/core_concepts/indexes.md Co-authored-by: gui machiavelli --- learn/core_concepts/indexes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/core_concepts/indexes.md b/learn/core_concepts/indexes.md index 600bcd2c63..82f89e944a 100644 --- a/learn/core_concepts/indexes.md +++ b/learn/core_concepts/indexes.md @@ -134,7 +134,7 @@ You can update the typo tolerance settings using the [update settings endpoint]( ### Pagination -To protect your database from malicious scraping, Meilisearch returns upto 1000 results for a search query. You can update this using the [update settings endpoint](/reference/api/settings.md#update-settings) or the [update pagination settings endpoint](/reference/api/pagination.md#update-pagination-settings). +To protect your database from malicious scraping, Meilisearch only returns up to 1000 results for a search query. You can change this limit using the [update settings endpoint](/reference/api/settings.md#update-settings) or the [update pagination settings endpoint](/reference/api/pagination.md#update-pagination-settings). We recommend using the [`limit`](/reference/api/search.md#limit) and [`offset`](/reference/api/search.md#offset) search parameters to implement previous and next buttons for a pagination UI. From 752f0b3f0cf4820d5b112f839214caa3004646a2 Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Thu, 30 Jun 2022 15:24:43 +0400 Subject: [PATCH 118/150] Update indexes.md --- learn/core_concepts/indexes.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/learn/core_concepts/indexes.md b/learn/core_concepts/indexes.md index 82f89e944a..41ad38db86 100644 --- a/learn/core_concepts/indexes.md +++ b/learn/core_concepts/indexes.md @@ -136,6 +136,4 @@ You can update the typo tolerance settings using the [update settings endpoint]( To protect your database from malicious scraping, Meilisearch only returns up to 1000 results for a search query. You can change this limit using the [update settings endpoint](/reference/api/settings.md#update-settings) or the [update pagination settings endpoint](/reference/api/pagination.md#update-pagination-settings). -We recommend using the [`limit`](/reference/api/search.md#limit) and [`offset`](/reference/api/search.md#offset) search parameters to implement previous and next buttons for a pagination UI. - [Learn more about pagination](/learn/advanced/pagination.md) From c93be15c2bdef6b8a307e158ac816734c046c54e Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 30 Jun 2022 13:31:23 +0200 Subject: [PATCH 119/150] Update learn/advanced/filtering_and_faceted_search.md Co-authored-by: Maryam <90181761+maryamsulemani97@users.noreply.github.com> --- learn/advanced/filtering_and_faceted_search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/advanced/filtering_and_faceted_search.md b/learn/advanced/filtering_and_faceted_search.md index 0d12f434d7..df47fc7dc4 100644 --- a/learn/advanced/filtering_and_faceted_search.md +++ b/learn/advanced/filtering_and_faceted_search.md @@ -317,7 +317,7 @@ Using the `facetsDistribution` search parameter adds two new keys to the returne ::: ::: note -By default, `facetDistribution` returns a maximum of 100 facet values for each faceted field. You can change this value using the `maxValuesPerFacet` property of the [`faceting` index settings](/reference/api/faceting.md). +By default, `facets` returns a maximum of 100 facet values for each faceted field. You can change this value using the `maxValuesPerFacet` property of the [`faceting` index settings](/reference/api/faceting.md). ::: ##### Example From 511f90451ae52f15211e645ee2b842d3fe47b1dd Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Thu, 30 Jun 2022 16:48:49 +0400 Subject: [PATCH 120/150] update setings --- .code-samples.meilisearch.yaml | 7 +++++++ .vuepress/public/sample-template.yaml | 1 + learn/configuration/settings.md | 17 +++++++++++++++++ 3 files changed, 25 insertions(+) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 047cb60b9f..b13b1ae4d0 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -958,3 +958,10 @@ getting_started_typo_tolerance: |- --data-binary '{ "minWordSizeForTypos": { "oneTypo": 4 } }' +. + curl \ + -X PATCH 'http://localhost:7700/indexes/movies/settings/pagination' \ + -H 'Content-Type: application/json' \ + --data-binary '{ + "maxTotalHits": 100 + }' \ No newline at end of file diff --git a/.vuepress/public/sample-template.yaml b/.vuepress/public/sample-template.yaml index 8b52eec657..2d1ad7ecd8 100644 --- a/.vuepress/public/sample-template.yaml +++ b/.vuepress/public/sample-template.yaml @@ -146,3 +146,4 @@ updating_guide_retrieve_documents_old: |- updating_guide_update_settings_old: |- updating_guide_add_documents_old: |- getting_started_typo_tolerance: |- +settings_guide_pagination_1: |- \ No newline at end of file diff --git a/learn/configuration/settings.md b/learn/configuration/settings.md index a0380f432d..82860a2eca 100644 --- a/learn/configuration/settings.md +++ b/learn/configuration/settings.md @@ -7,6 +7,7 @@ This page describes the **index-level settings** available in Meilisearch and ho | **[displayedAttributes](/learn/configuration/settings.md#displayed-attributes)** | Fields displayed in the returned documents | All attributes found in the documents | | **[distinctAttribute](/learn/configuration/settings.md#distinct-attribute)** | Search returns documents with distinct (different) values of the given field | `null` | | **[filterableAttributes](/learn/configuration/settings.md#filterable-attributes)** | List of attributes that can be used for filtering | `null` | +| **[pagination](/learn/advanced/pagination.md)** | Pagination settings | `{}` | **[rankingRules](/learn/configuration/settings.md#ranking-rules)** | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#built-in-rules) | | **[searchableAttributes](/learn/configuration/settings.md#searchable-attributes)** | Fields in which to search for matching query words sorted by order of importance | All attributes found in the documents | | | **[sortableAttributes](/learn/configuration/settings.md#sortable-attributes)** | List of attributes to use when sorting search results | `[]` | @@ -95,6 +96,22 @@ To be able to filter search results on `director` and `genres` in a movie databa +## Pagination + +The maximum number of results Meilisearch can return. By default, this value is `1000` which means you cannot access results beyond `1000`. + +[Learn more about pagination in our dedicated guide.](/learn/advanced/pagination.md) + +### Example + +The code sample below updates `maxTotalHits` to `50`: + + + +::: note +`maxTotalHits` takes priority over search parameters such as [`limit`](/reference/api/search.md#limit) and [`offset`](/reference/api/search.md#offset). +::: + ## Ranking rules Built-in ranking rules that **ensure relevancy in search results**. Ranking rules are applied in a default order which can be changed in the settings. You can add or remove rules and change their order of importance. From 8d01e108a525964c2d714c3eeb7fa1daf6a607ec Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Thu, 30 Jun 2022 16:51:11 +0400 Subject: [PATCH 121/150] settings_guide_pagination_1 --- .code-samples.meilisearch.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index b13b1ae4d0..b6769bcec9 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -958,7 +958,7 @@ getting_started_typo_tolerance: |- --data-binary '{ "minWordSizeForTypos": { "oneTypo": 4 } }' -. +settings_guide_pagination_1: |- curl \ -X PATCH 'http://localhost:7700/indexes/movies/settings/pagination' \ -H 'Content-Type: application/json' \ From 085dcb46c14e5997cca0f8fd15be3c1bcbd73517 Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Thu, 30 Jun 2022 16:52:35 +0400 Subject: [PATCH 122/150] Update .code-samples.meilisearch.yaml --- .code-samples.meilisearch.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index b6769bcec9..530540c2db 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -963,5 +963,5 @@ settings_guide_pagination_1: |- -X PATCH 'http://localhost:7700/indexes/movies/settings/pagination' \ -H 'Content-Type: application/json' \ --data-binary '{ - "maxTotalHits": 100 + "maxTotalHits": 50 }' \ No newline at end of file From 486e470fc4306b5d69c10dffb07a1af0d28e856c Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Thu, 30 Jun 2022 17:27:11 +0400 Subject: [PATCH 123/150] Update learn/core_concepts/indexes.md --- learn/core_concepts/indexes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/core_concepts/indexes.md b/learn/core_concepts/indexes.md index 41ad38db86..c32a7f8309 100644 --- a/learn/core_concepts/indexes.md +++ b/learn/core_concepts/indexes.md @@ -134,6 +134,6 @@ You can update the typo tolerance settings using the [update settings endpoint]( ### Pagination -To protect your database from malicious scraping, Meilisearch only returns up to 1000 results for a search query. You can change this limit using the [update settings endpoint](/reference/api/settings.md#update-settings) or the [update pagination settings endpoint](/reference/api/pagination.md#update-pagination-settings). +To protect your database from malicious scraping, Meilisearch only returns up to `1000` results for a search query. You can change this limit using the [update settings endpoint](/reference/api/settings.md#update-settings) or the [update pagination settings endpoint](/reference/api/pagination.md#update-pagination-settings). [Learn more about pagination](/learn/advanced/pagination.md) From 82182c7af401749704f3a98751711fcbacde3e6a Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Sun, 3 Jul 2022 16:10:42 +0400 Subject: [PATCH 124/150] add note about deterministic keys --- reference/api/keys.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/reference/api/keys.md b/reference/api/keys.md index 8efdca4797..f1695ddadf 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -120,10 +120,14 @@ A [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) to identify the #### `key` -An alphanumeric key value generated by Meilisearch using the `uid` and the master key on API key creation. Used for authorization when [making calls to a protected Meilisearch instance](/learn/security/master_api_keys.md#communicating-with-a-protected-instance). +An alphanumeric key value generated by Meilisearch by hasing the `uid` and the master key on API key creation. Used for authorization when [making calls to a protected Meilisearch instance](/learn/security/master_api_keys.md#communicating-with-a-protected-instance). This value is also used as the `{key}` path variable to [update](#update-a-key), [delete](#delete-a-key), or [get](#get-one-key) a specific key. +::: note +Since `key` is a hash of the `uid` and master key, `key` values are deterministic between instances sharing the same configuration. This means if the master key changes, all key values are automatically changed and that API key resources are propagated into dumps and snapshots without displaying the `key` field in clear. +::: + #### `actions` An array of API actions permitted for the key. `["*"]` for all actions. From 31a144341d56ac7a27c33fb515b2c2300f794704 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 4 Jul 2022 13:00:03 +0200 Subject: [PATCH 125/150] Apply suggestions from code review --- .code-samples.meilisearch.yaml | 3 ++- .vuepress/public/sample-template.yaml | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 530540c2db..b1c501cd1d 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -964,4 +964,5 @@ settings_guide_pagination_1: |- -H 'Content-Type: application/json' \ --data-binary '{ "maxTotalHits": 50 - }' \ No newline at end of file + }' + \ No newline at end of file diff --git a/.vuepress/public/sample-template.yaml b/.vuepress/public/sample-template.yaml index 2d1ad7ecd8..58cf6ba345 100644 --- a/.vuepress/public/sample-template.yaml +++ b/.vuepress/public/sample-template.yaml @@ -146,4 +146,4 @@ updating_guide_retrieve_documents_old: |- updating_guide_update_settings_old: |- updating_guide_add_documents_old: |- getting_started_typo_tolerance: |- -settings_guide_pagination_1: |- \ No newline at end of file +settings_guide_pagination_1: |- From 4827ac35d7ceb4cb09404f40a08c49e864337a16 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 4 Jul 2022 13:00:35 +0200 Subject: [PATCH 126/150] Update .code-samples.meilisearch.yaml --- .code-samples.meilisearch.yaml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index b1c501cd1d..530540c2db 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -964,5 +964,4 @@ settings_guide_pagination_1: |- -H 'Content-Type: application/json' \ --data-binary '{ "maxTotalHits": 50 - }' - \ No newline at end of file + }' \ No newline at end of file From 4257e9066200d8c2ad6d2ea893acac8d5acfd231 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 4 Jul 2022 13:00:52 +0200 Subject: [PATCH 127/150] Update .code-samples.meilisearch.yaml --- .code-samples.meilisearch.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 530540c2db..86ff7b1453 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -964,4 +964,5 @@ settings_guide_pagination_1: |- -H 'Content-Type: application/json' \ --data-binary '{ "maxTotalHits": 50 - }' \ No newline at end of file + }' + \ No newline at end of file From 3d3d3de845ead0d189c90c9d397966a684cb4e93 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 4 Jul 2022 13:02:24 +0200 Subject: [PATCH 128/150] add return to code samples file --- .code-samples.meilisearch.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 86ff7b1453..3253d71579 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -965,4 +965,3 @@ settings_guide_pagination_1: |- --data-binary '{ "maxTotalHits": 50 }' - \ No newline at end of file From be6cd5cb9b77ae0a7519a42cd9deda6ba713a420 Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Mon, 4 Jul 2022 16:39:59 +0400 Subject: [PATCH 129/150] v0.28: Add faceting to core concepts+index settings (#1767) * add faceting to index settings+core concepts * Update learn/configuration/settings.md * Update settings.md * Update learn/core_concepts/indexes.md * Update learn/core_concepts/indexes.md Co-authored-by: gui machiavelli Co-authored-by: gui machiavelli --- .code-samples.meilisearch.yaml | 7 +++++++ .vuepress/public/sample-template.yaml | 1 + learn/configuration/settings.md | 17 +++++++++++++++++ learn/core_concepts/indexes.md | 9 +++++++++ 4 files changed, 34 insertions(+) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 551d499812..821d99901f 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -972,3 +972,10 @@ update_faceting_settings_1: |- reset_faceting_settings_1: |- curl \ -X DELETE 'http://localhost:7700/indexes/books/settings/faceting' +settings_guide_faceting_1: |- + curl \ + -X PATCH 'http://localhost:7700/indexes/movies/settings/faceting' \ + -H 'Content-Type: application/json' \ + --data-binary '{ + "maxValuesPerFacet": 5 + }' diff --git a/.vuepress/public/sample-template.yaml b/.vuepress/public/sample-template.yaml index 1bd841fb4a..b2b8c439bc 100644 --- a/.vuepress/public/sample-template.yaml +++ b/.vuepress/public/sample-template.yaml @@ -149,3 +149,4 @@ getting_started_typo_tolerance: |- get_faceting_settings_1: |- update_faceting_settings_1: |- reset_faceting_settings_1: |- +settings_guide_faceting_1: |- diff --git a/learn/configuration/settings.md b/learn/configuration/settings.md index a0380f432d..b31a0094f2 100644 --- a/learn/configuration/settings.md +++ b/learn/configuration/settings.md @@ -7,6 +7,7 @@ This page describes the **index-level settings** available in Meilisearch and ho | **[displayedAttributes](/learn/configuration/settings.md#displayed-attributes)** | Fields displayed in the returned documents | All attributes found in the documents | | **[distinctAttribute](/learn/configuration/settings.md#distinct-attribute)** | Search returns documents with distinct (different) values of the given field | `null` | | **[filterableAttributes](/learn/configuration/settings.md#filterable-attributes)** | List of attributes that can be used for filtering | `null` | +| **[faceting](/learn/advanced/filtering_and_faceted_search.md)** | Faceting settings | `{}` | **[rankingRules](/learn/configuration/settings.md#ranking-rules)** | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#built-in-rules) | | **[searchableAttributes](/learn/configuration/settings.md#searchable-attributes)** | Fields in which to search for matching query words sorted by order of importance | All attributes found in the documents | | | **[sortableAttributes](/learn/configuration/settings.md#sortable-attributes)** | List of attributes to use when sorting search results | `[]` | @@ -95,6 +96,22 @@ To be able to filter search results on `director` and `genres` in a movie databa +## Faceting + +The faceting settings of an index. Facets are specific use-cases of filters that can be used to refine search results. + +::: tip +Like filters, you need to add your facets to [`filterableAttributes`](/reference/api/filterable_attributes.md#update-filterable-attributes) in order to use the [`filter`](/reference/api/search.md#filter) search parameter. +::: + +[Learn more about faceting](/learn/advanced/filtering_and_faceted_search.md) + +#### Example + +The following code sample will return a maximum of `5` facet values for each facet in the `movies` index: + + + ## Ranking rules Built-in ranking rules that **ensure relevancy in search results**. Ranking rules are applied in a default order which can be changed in the settings. You can add or remove rules and change their order of importance. diff --git a/learn/core_concepts/indexes.md b/learn/core_concepts/indexes.md index 9eb84d248a..70936859f5 100644 --- a/learn/core_concepts/indexes.md +++ b/learn/core_concepts/indexes.md @@ -58,6 +58,7 @@ You can customize the following index settings: - [Stop words](#stop-words) - [Displayed and searchable attributes](#displayed-and-searchable-attributes) - [Typo tolerance](#typo-tolerance) +- [Faceting](#faceting) To change index settings, use the [update settings endpoint](/reference/api/settings.md#update-settings) or any of the [child routes](/reference/api/settings.md#all-settings). @@ -129,3 +130,11 @@ Typo tolerance is a built-in feature that helps you find relevant results even w You can update the typo tolerance settings using the [update settings endpoint](/reference/api/settings.md#update-settings) or the [update typo tolerance endpoint](/reference/api/typo_tolerance.md#update-typo-tolerance). [Learn more about typo tolerance](/learn/configuration/typo_tolerance.md) + +### Faceting + +Facets are a specific use-case of filters in Meilisearch: whether something is a facet or filter depends on your UI and UX design. Like filters, you need to add your facets to [`filterableAttributes`](/reference/api/filterable_attributes.md#update-filterable-attributes), then make a search query using the [`filter` search parameter](/reference/api/search.md#filter). + +By default, Meilisearch returns `100` facet values for each faceted field. You can change this using the [update settings endpoint](/reference/api/settings.md#update-settings) or the [update faceting settings endpoint](/reference/api/faceting.md#update-faceting-settings). + +[Learn more about faceting](/learn/advanced/filtering_and_faceted_search.md) From 67e35799da96c8fc4b4ca73dae4ae107e0401429 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 4 Jul 2022 15:51:36 +0200 Subject: [PATCH 130/150] Update learn/advanced/asynchronous_operations.md Co-authored-by: Maryam <90181761+maryamsulemani97@users.noreply.github.com> --- learn/advanced/asynchronous_operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/advanced/asynchronous_operations.md b/learn/advanced/asynchronous_operations.md index f5b1d85618..c9491fcf3a 100644 --- a/learn/advanced/asynchronous_operations.md +++ b/learn/advanced/asynchronous_operations.md @@ -32,7 +32,7 @@ The response from the [task API](/reference/api/tasks.md) will always include th | `uid` | integer | The unique sequential identifier of the task | | `indexUid` | string | The unique index identifier (always `null` for dumps) | | `status` | string | The status of the task. Possible values are `enqueued`, `processing`, `succeeded`, `failed` | -| `type` | string | The type of task. Possible values are `indexCreation`, `indexUpdate`, `indexDeletion`, `documentAdditionOrUpdate`, `documentPartial`, `documentDeletion`, `settingsUpdate`, `clearAll`, `dumpCreation` | +| `type` | string | The type of task. Possible values are `indexCreation`, `indexUpdate`, `indexDeletion`, `documentAdditionOrUpdate`, `documentPartial`, `documentDeletion`, `settingsUpdate`, `dumpCreation` | | `details` | object | Detailed information on the task payload | | `error` | object | Error details and context. Only present when a task has the `failed` status | | `duration` | string | The total elapsed time the task spent in the `processing` state, in ISO 8601 format | From 655c2627f7b02dd63136117cb05a198351f736aa Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 4 Jul 2022 16:42:13 +0200 Subject: [PATCH 131/150] Update learn/advanced/pagination.md Co-authored-by: Guillaume Mourier --- learn/advanced/pagination.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/advanced/pagination.md b/learn/advanced/pagination.md index f2bff6a617..f1be11ad01 100644 --- a/learn/advanced/pagination.md +++ b/learn/advanced/pagination.md @@ -16,7 +16,7 @@ We recommend creating pagination interfaces centered around [previous and next b ## Recommended: Previous and next buttons -Using previous and next buttons for pagination means that users can easily page through results, but don't have the ability to jump to an arbitrary results page. +Using previous and next buttons for pagination means that users can easily navigate through results, but don't have the ability to jump to an arbitrary results page. ![Placeholder image for prev/next interface]() From 1727ede8d91fe0d12310e2f355e315f628bf331b Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Mon, 4 Jul 2022 23:18:45 +0400 Subject: [PATCH 132/150] Update reference/api/keys.md Co-authored-by: Many the fish --- reference/api/keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/keys.md b/reference/api/keys.md index f1695ddadf..643b83e3c1 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -120,7 +120,7 @@ A [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) to identify the #### `key` -An alphanumeric key value generated by Meilisearch by hasing the `uid` and the master key on API key creation. Used for authorization when [making calls to a protected Meilisearch instance](/learn/security/master_api_keys.md#communicating-with-a-protected-instance). +An alphanumeric key value generated by Meilisearch by hashing the `uid` and the master key on API key creation. Used for authorization when [making calls to a protected Meilisearch instance](/learn/security/master_api_keys.md#communicating-with-a-protected-instance). This value is also used as the `{key}` path variable to [update](#update-a-key), [delete](#delete-a-key), or [get](#get-one-key) a specific key. From 17bc0747bf6e87e37a78e4019ac80823738474b5 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Tue, 5 Jul 2022 15:17:47 +0400 Subject: [PATCH 133/150] update note wording --- reference/api/keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/keys.md b/reference/api/keys.md index 643b83e3c1..9f2fde25b5 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -125,7 +125,7 @@ An alphanumeric key value generated by Meilisearch by hashing the `uid` and the This value is also used as the `{key}` path variable to [update](#update-a-key), [delete](#delete-a-key), or [get](#get-one-key) a specific key. ::: note -Since `key` is a hash of the `uid` and master key, `key` values are deterministic between instances sharing the same configuration. This means if the master key changes, all key values are automatically changed and that API key resources are propagated into dumps and snapshots without displaying the `key` field in clear. +Since `key` is a hash of the `uid` and master key, `key` values are deterministic between instances sharing the same configuration. This means if the master key changes, all `key` values are automatically changed. The `key` field is computed at runtime and therefore is not propagated to dumps and snapshots. Even if someone does have access to your dumps or snapshot, they cannot make malicious requests. ::: #### `actions` From 6f14c78492d9ed20664f76314b89541ad153d173 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Tue, 5 Jul 2022 16:07:21 +0400 Subject: [PATCH 134/150] update based on gui's review --- reference/api/keys.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/reference/api/keys.md b/reference/api/keys.md index 9f2fde25b5..082a3b506b 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -125,7 +125,9 @@ An alphanumeric key value generated by Meilisearch by hashing the `uid` and the This value is also used as the `{key}` path variable to [update](#update-a-key), [delete](#delete-a-key), or [get](#get-one-key) a specific key. ::: note -Since `key` is a hash of the `uid` and master key, `key` values are deterministic between instances sharing the same configuration. This means if the master key changes, all `key` values are automatically changed. The `key` field is computed at runtime and therefore is not propagated to dumps and snapshots. Even if someone does have access to your dumps or snapshot, they cannot make malicious requests. +Since `key` is a hash of the `uid` and master key, `key` values are deterministic between instances sharing the same configuration. This means if the master key changes, all `key` values are automatically changed. + +Since the `key` field depends on the master key, it is computed at runtime and therefore not propagated to dumps and snapshots. As a result, even if a malicious user comes into possession of your dumps or snapshots, they will not have access to your instance's API keys. ::: #### `actions` From dc61d8ff1ac7be3037412e436a97b6dd94b562a2 Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Tue, 5 Jul 2022 16:32:34 +0400 Subject: [PATCH 135/150] Apply suggestions from code review Co-authored-by: Many the fish --- learn/what_is_meilisearch/language.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/what_is_meilisearch/language.md b/learn/what_is_meilisearch/language.md index e6ce5c5459..99191d9d66 100644 --- a/learn/what_is_meilisearch/language.md +++ b/learn/what_is_meilisearch/language.md @@ -15,7 +15,7 @@ We aim to provide global language support, and your feedback helps us move close While we have employees from all over the world at Meilisearch, we don't speak every language. We rely almost entirely on feedback from external contributors to understand how our engine is performing across different languages. -If you'd like to request optimized support for a language that we don't currently support, please [open a discussion in our product repository](https://github.com/meilisearch/product/discussions). +If you'd like to request optimized support for a language that we don't currently support, please upvote the related [discussion in our product repository](https://github.com/meilisearch/product/discussions?discussions_q=label%3Aproduct%3Acore%3Atokenizer) or [open a new one](https://github.com/meilisearch/product/discussions/new) if it doesn't exist. If you'd like to help by developing a tokenizer pipeline yourself: first of all, thank you! We recommend that you take a look at the [tokenizer contribution guide](https://github.com/meilisearch/charabia/blob/main/CONTRIBUTING.md) before making a PR. From 0425a2230b259987e7ae0e56c82badf731984c7e Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Tue, 5 Jul 2022 16:57:03 +0400 Subject: [PATCH 136/150] update based on ManyTheFish's review --- learn/advanced/tokenization.md | 6 +++--- learn/what_is_meilisearch/language.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/learn/advanced/tokenization.md b/learn/advanced/tokenization.md index 67d5b4d7d7..cf9db7c695 100644 --- a/learn/advanced/tokenization.md +++ b/learn/advanced/tokenization.md @@ -8,12 +8,12 @@ This allows Meilisearch to function in several different languages with zero set ## Deep dive: The Meilisearch tokenizer -When you add documents to a Meilisearch index, the tokenization process is handled by an abstract interface called an **analyzer**. The analyzer is responsible for determining the primary language of each field based on the scripts (e.g., Latin alphabet, Chinese hanzi, etc.) that are present there. Then, it applies the corresponding **pipeline** to each field. +When you add documents to a Meilisearch index, the tokenization process is handled by an abstract interface called the tokenizer. The tokenizer is responsible for splitting each field by script (e.g., Latin alphabet, Chinese hanzi, etc.). It then applies the corresponding pipeline to each part of each field. We can break down the tokenization process like so: -1. Crawl the document(s) and determine the primary language for each field -2. Go back over the documents field-by-field, running the corresponding tokenization pipeline, if it exists +1. Crawl the document(s), splitting each field by script +2. Go back over the documents part-by-part, running the corresponding tokenization pipeline, if it exists Pipelines include many language-specific operations. Currently, we have four pipelines: diff --git a/learn/what_is_meilisearch/language.md b/learn/what_is_meilisearch/language.md index 99191d9d66..a515fd0c9b 100644 --- a/learn/what_is_meilisearch/language.md +++ b/learn/what_is_meilisearch/language.md @@ -40,4 +40,4 @@ Yes—our users work with many different alphabets and writing systems, such as ### Does Meilisearch plan to support additional languages in the future? -Yes, we definitely do. The more feedback we get from native speakers, the easier it is for us to understand how to improve performance for those languages. Similarly, the more requests we get to improve support for a specific language, the more likely we are to devote resources to that project. +Yes, we definitely do. The more [feedback](https://github.com/meilisearch/product/discussions?discussions_q=label%3Aproduct%3Acore%3Atokenizer) we get from native speakers, the easier it is for us to understand how to improve performance for those languages. Similarly, the more requests we get to improve support for a specific language, the more likely we are to devote resources to that project. From 60890b667dbfd3d0f5bd0552081d70a0d0cfa6c8 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Tue, 5 Jul 2022 19:15:05 +0200 Subject: [PATCH 137/150] Address review feedback --- learn/advanced/pagination.md | 162 ++++++++++++++++++++++++++++------- 1 file changed, 129 insertions(+), 33 deletions(-) diff --git a/learn/advanced/pagination.md b/learn/advanced/pagination.md index f1be11ad01..2dc3a42524 100644 --- a/learn/advanced/pagination.md +++ b/learn/advanced/pagination.md @@ -1,4 +1,4 @@ -# Pagination of search results +# Search result pagination In a perfect world, users would not need to look beyond the first search result to find what they were looking for. In practice, however, it is usually necessary to create some kind of pagination interface to browse through long lists of results. @@ -6,13 +6,13 @@ In this guide, we will discuss some of Meilisearch's current limitations, how th ## Choosing the right pagination UI -There are quite a few pagination interfaces you might want to implement in your application. Many common UI patterns have a page selector allowing users to jump to any search results page. To create a page selector, you must know the exact number of total results so you can calculate the precise number of results pages. +There are quite a few pagination interfaces you might want to implement in your application. Many common UI patterns have a page selector allowing users to jump to any search results page. To create a page selector, you must know the exact number of total results so you can calculate the precise number of result pages. For performance reasons, however, Meilisearch cannot provide the exact number of results for a query. Instead, When using the search endpoint, responses contain an `estimatedTotalHits` field. As its name indicates, `estimatedTotalHits` is only an estimate of how many documents match your user's query. Because of this, we do not recommend creating interfaces with page selectors. If page selection is crucial to the software you are developing, see the [last section of this page](#not-recommended-page-selection) for tips that might help you work around Meilisearch's current limitations. -We recommend creating pagination interfaces centered around [previous and next buttons](#recommended-previous-and-next-buttons). +Many other pagination UIs are fully compatible with Meilisearch, such as infinite scrolling and buttons that manually load more results on click. For an experience similar to page selection, we recommend creating pagination interfaces centered around [previous and next buttons](#recommended-previous-and-next-buttons). ## Recommended: Previous and next buttons @@ -28,61 +28,106 @@ Though this approach offers less precision than a full-blown page selector, it d Previous and next buttons can be implemented using the [`limit`](/reference/api/search.md#limit) and [`offset`](/reference/api/search.md#offset) search parameters. -`limit` sets the size of page. If you set `limit` to 20, Meilisearch's response will contain a maximum of 20 search results. `offset` skips a number of search results. If you set `offset` to 40, Meilisearch's response will skip the first 40 search results. +`limit` sets the size of a page. If you set `limit` to 10, Meilisearch's response will contain a maximum of 10 search results. `offset` skips a number of search results. If you set `offset` to 20, Meilisearch's response will skip the first 20 search results. -You can use both parameters together to effectively create search pages. +For example, you can use Meilisearch's JavaScript SDK to get the first ten films in a movies database: + +```js +const results = await index.search("tarkovsky", { limit: 10, offset: 0 }); +``` +You can use both parameters together to effectively create search pages. #### Search pages and calculating `offset` -If you set `limit` to 20 and `offset` to 0, you get the first twenty results. We can call this our first page. +If you set `limit` to 20 and `offset` to 0, you get the first twenty search results. We can call this our first page. ```js -const results = await index.search("x", { limit: 20, offset: 0 }); +const results = await index.search("tarkovsky", { limit: 20, offset: 0 }); ``` Likewise, if you set `limit` to 20 and `offset` to 40, you skip the first 40 search results and get documents ranked from 41 through 60. We can call this the third results page. ```js -const results = await index.search("x", { limit: 20, offset: 40 }); +const results = await index.search("tarkovsky", { limit: 20, offset: 40 }); ``` -Use this formula to quickly calculate a page's offset value: `offset = limit * (page number - 1)`. +Use this formula to quickly calculate a page's offset value: `offset = limit * (target page number - 1)`. Once a query returns fewer `hits` than your configured `limit`, you have reached the last results page. +#### Keeping track of the current page number + +Even though this UI pattern does not allow users to jump to a specific page, it is still useful to keep track of the current page number. + +The following JavaScript snippet stores the page number in an HTML element, `.pagination`, and updates it every time the user moves to a different search results page: + +```js +function updatePageNumber(elem) { + const directionBtn = elem.id + // Get the page number stored in the pagination element + let pageNumber = parseInt(document.querySelector('.pagination').dataset.pageNumber) + + // Update page number + if (directionBtn === 'previous_button') { + pageNumber = pageNumber - 1 + } else if (directionBtn === 'next_button') { + pageNumber = pageNumber + 1 + } + + // Store new page number in the pagination element + document.querySelector('.pagination').dataset.pageNumber = pageNumber +} + +// Add data to our HTML element stating the user is on the first page +document.querySelector('.pagination').dataset.pageNumber = 0 +// Each time a user clicks on the previous or next buttons, update the page number +document.querySelector('#previous_button').onclick = function () { updatePageNumber(this) } +document.querySelector('#next_button').onclick = function () { updatePageNumber(this) } +``` + #### Disabling navigation buttons for first and last pages It is often helpful to disable navigation buttons when the user cannot move to the "next" or "previous" page. The "previous" button should be disabled whenever your `offset` is 0, as this indicates your user is on the first results page. -To know when to disable the "next" button, we recommend setting your query's `limit` to the number of results you wish to display per page plus one. That extra `hit` should not be shown to the user. Its purpose is to indicate that there is at least one more document to display on the next page: +To know when to disable the "next" button, we recommend setting your query's `limit` to the number of results you wish to display per page plus one. That extra `hit` should not be shown to the user. Its purpose is to indicate that there is at least one more document to display on the next page. -```js -const results = await index.search("x", { limit: 21, offset: 0 }) - -// If offset equals 0, we're on the first results page -if (offset === 0 ) { - document.querySelector("#previous_button").disabled = true; -} +The following JavaScript snippet runs checks whether we should disable a button every time the user navigates to another search results page: -// If offset is bigger than 0, we're not on the first results page -if (offset > 0 ) { - document.querySelector("#previous_button").disabled = false; +```js +function updatePageNumber() { + const pageNumber = parseInt(document.querySelector('.pagination').dataset.pageNumber) + + const offset = pageNumber * 20 + const results = await index.search('x', { limit: 21, offset }) + + // If offset equals 0, we're on the first results page + if (offset === 0 ) { + document.querySelector('#previous_button').disabled = true; + } + + // If offset is bigger than 0, we're not on the first results page + if (offset > 0 ) { + document.querySelector('#previous_button').disabled = false; + } + + // If Meilisearch returns 20 items or less, + // we are on the last page + if (results.hits.length < 21 ) { + document.querySelector('#next_button').disabled = true; + } + + // If Meilisearch returns exactly 21 results + // and our page can only show 20 items at a time, + // we have at least one more page with one result in it + if (results.hits.length === 21 ) { + document.querySelector('#next_button').disabled = false; + } } -// If Meilisearch returns 20 items or less, -// we are on the last page -if (results.hits.length < 21 ) { - document.querySelector("#next_button").disabled = true; -} - -// If Meilisearch returns exactly 21 results -// and our page can only show 20 items at a time, -// we have at least one more page with one result in it -if (results.hits.length === 21 ) { - document.querySelector("#next_button").disabled = false; -} +document.querySelector('#previous_button').onclick = function () { updatePageNumber(this) } +document.querySelector('#next_button').onclick = function () { updatePageNumber(this) } ``` ## Not recommended: Page selection @@ -109,7 +154,58 @@ By default, a search request returns 20 search results. You can change this valu For example, if you set `limit` to 300, every search request made to Meilisearch returns at most 300 documents. If a query returns a `hits` array with 200 items and you want each page to display 20 results, you can create a page selector with 10 pages. -// perhaps a code sample here? +In the following JavaScript snippet, each time a user searches, we make a new query with `limit` set to 300. Once we receive the search results, we store them in a variable and create a list of numbered pages. When users click on any number in the page list, we display a new page: + +```js +// Retrieve search results and create the page selector +function getSearchResults(searchTerm) { + // The amount of results we want to display in each page + const hitsPerPage = 10 + + // The maximum amount of results we will display + const { hits } = await index.search(searchTerm, { limit: 300 }) + + // Clear the previous buttons… + const pagination = document.querySelector('.pagination') + pagination.innerHTML = '' + + // …and create a new button for each search results page + for (let page = 0; page < hits.length; page += hitsPerPage) { + const numberBtn = document.createElement('button'); + numberBtn.innerText = page / hitsPerPage + + // When the user clicks on a page number, show that results page + numberBtn.onclick = function () { + const pageNumber = parseInt(this.innerText) + changePage(pageNumber, hits, hitsPerPage) + } + + pagination.appendChild(numberBtn) + } + + // Display first search results page + changePage(1, hits, hitsPerPage) +} + +// Display a page of search results +function changePage(pageNumber, hits, hitsPerPage) { + const offset = (pageNumber - 1) * hitsPerPage + const paginatedHits = hits.slice(offset, offset + hitsPerPage) + const resultList = document.querySelector('.results') + + resultList.innerHTML = '' + + paginatedHits.map(hit => { + const resultItem = document.createElement('div'); + resultItem.innerText = hit.title + resultList.appendChild(resultItem) + }) +} + +// Get the search bar and retrieve results every time the user makes a new query +const searchBar = document.querySelector('.searchBar') +searchBar.onChange(function () { getSearchResults('tarkovsky') }) +``` This method provides control and reliability. It also prevents users from paginating too far, which might result in performance gains. However, it limits the number of results your users can see. Additionally, we recommend caution when setting high values for `limit` as it can negatively impact performance. From 747d2e2c6fca067bdd62276e811395b1f39e8f6f Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Tue, 5 Jul 2022 21:53:28 +0400 Subject: [PATCH 138/150] update to add bash command --- learn/security/master_api_keys.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/learn/security/master_api_keys.md b/learn/security/master_api_keys.md index 8f3c1ec36f..83e45198f8 100644 --- a/learn/security/master_api_keys.md +++ b/learn/security/master_api_keys.md @@ -86,6 +86,14 @@ You can access the [`/keys` route](/reference/api/keys.md) using the master key Though the default API keys are usually enough to manage the security needs of most applications, this might not be the case when dealing with privacy-sensitive data. In these situations, the fine-grained control offered by the `/keys` endpoint allows you to clearly decide who can access what information and for how long. +The [`key`](/reference/api/keys.md#key) field is generated by hashing the master key and the [`uid`](/reference/api/keys.md#uid): + +```bash +echo -n $HYPHENATED_UUID | openssl dgst -sha256 -hmac $MASTER_KEY +``` + +As a result, `key` values are deterministic between instances sharing the same configuration. Since the `key` field depends on the master key, it is not propagated to dumps and snapshots. If a malicious user ever gets access to your dumps or snapshots, they will not have access to your instance's API keys. + ### Updating an API key You can only update the `name` and `description` of an API key, even after it expires. From 344a707a4f0368743aac8b4b5eb59568b1dfa6ee Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Wed, 6 Jul 2022 13:53:11 +0400 Subject: [PATCH 139/150] update based on gmourier's review --- learn/security/master_api_keys.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/learn/security/master_api_keys.md b/learn/security/master_api_keys.md index 83e45198f8..5f4179dc16 100644 --- a/learn/security/master_api_keys.md +++ b/learn/security/master_api_keys.md @@ -94,6 +94,8 @@ echo -n $HYPHENATED_UUID | openssl dgst -sha256 -hmac $MASTER_KEY As a result, `key` values are deterministic between instances sharing the same configuration. Since the `key` field depends on the master key, it is not propagated to dumps and snapshots. If a malicious user ever gets access to your dumps or snapshots, they will not have access to your instance's API keys. +This is also useful in continuous deployment processes as you know the value of the `key` field in advance. + ### Updating an API key You can only update the `name` and `description` of an API key, even after it expires. From 8fa84da4ae53782156864dfc6f45bbf628364a85 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 6 Jul 2022 12:45:00 +0200 Subject: [PATCH 140/150] Update reference/api/faceting.md Co-authored-by: Guillaume Mourier --- reference/api/faceting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/faceting.md b/reference/api/faceting.md index ef5622226f..a2d32ad122 100644 --- a/reference/api/faceting.md +++ b/reference/api/faceting.md @@ -49,7 +49,7 @@ Partially update the faceting settings for an index. The index [`uid`](/learn/co **Type:** integer **Default value:** `100` -Configure the maximum number of facet values returned for each facet. Values are alphabetically sorted. +Configure the maximum number of facet values returned for each facet. Values are sorted in ascending lexicographical order. For example, suppose a query's search results contain a total of three values for a `colors` facet: `blue`, `green`, and `red`. If you set `maxValuesPerFacet` to `2`, Meilisearch will only return `blue` and `green` in the response body's `facetDistribution` object. From 22d80322d26abe51aa2131157158c0ff3fb8f624 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Wed, 6 Jul 2022 15:32:03 +0400 Subject: [PATCH 141/150] update key `uid`s --- .code-samples.meilisearch.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index c42e2dc933..f162162d9f 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -99,7 +99,7 @@ get_all_tasks_paginating_2: |- -X GET 'http://localhost:7700/tasks?limit=2&from=8 get_one_key_1: |- curl \ - -X GET 'http://localhost:7700/keys/d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4' \ + -X GET 'http://localhost:7700/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \ -H 'Authorization: Bearer MASTER_KEY' get_all_keys_1: |- curl \ @@ -118,7 +118,7 @@ create_a_key_1: |- }' update_a_key_1: |- curl \ - -X PATCH 'http://localhost:7700/keys/d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4' \ + -X PATCH 'http://localhost:7700/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \ -H 'Authorization: Bearer MASTER_KEY' \ -H 'Content-Type: application/json' \ --data-binary '{ From 1f6241d891e735dad8f435eeb24bc7c71c57fe56 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Wed, 6 Jul 2022 15:37:54 +0400 Subject: [PATCH 142/150] update based on gmourier's review --- learn/security/master_api_keys.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/learn/security/master_api_keys.md b/learn/security/master_api_keys.md index 5f4179dc16..45df62d8e9 100644 --- a/learn/security/master_api_keys.md +++ b/learn/security/master_api_keys.md @@ -86,14 +86,14 @@ You can access the [`/keys` route](/reference/api/keys.md) using the master key Though the default API keys are usually enough to manage the security needs of most applications, this might not be the case when dealing with privacy-sensitive data. In these situations, the fine-grained control offered by the `/keys` endpoint allows you to clearly decide who can access what information and for how long. -The [`key`](/reference/api/keys.md#key) field is generated by hashing the master key and the [`uid`](/reference/api/keys.md#uid): +The [`key`](/reference/api/keys.md#key) field is generated by hashing the master key and the [`uid`](/reference/api/keys.md#uid). As a result, `key` values are deterministic between instances sharing the same configuration. Since the `key` field depends on the master key, it is not propagated to dumps and snapshots. If a malicious user ever gets access to your dumps or snapshots, they will not have access to your instance's API keys. + +It is, therefore, possible to determine the value of the `key` field by using the following command: ```bash echo -n $HYPHENATED_UUID | openssl dgst -sha256 -hmac $MASTER_KEY ``` -As a result, `key` values are deterministic between instances sharing the same configuration. Since the `key` field depends on the master key, it is not propagated to dumps and snapshots. If a malicious user ever gets access to your dumps or snapshots, they will not have access to your instance's API keys. - This is also useful in continuous deployment processes as you know the value of the `key` field in advance. ### Updating an API key From 29b9d16da42828960034b7d1860e75a3ba8a6a59 Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Wed, 6 Jul 2022 16:54:51 +0400 Subject: [PATCH 143/150] Update learn/advanced/tokenization.md Co-authored-by: gui machiavelli --- learn/advanced/tokenization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/advanced/tokenization.md b/learn/advanced/tokenization.md index cf9db7c695..8811f136a5 100644 --- a/learn/advanced/tokenization.md +++ b/learn/advanced/tokenization.md @@ -8,7 +8,7 @@ This allows Meilisearch to function in several different languages with zero set ## Deep dive: The Meilisearch tokenizer -When you add documents to a Meilisearch index, the tokenization process is handled by an abstract interface called the tokenizer. The tokenizer is responsible for splitting each field by script (e.g., Latin alphabet, Chinese hanzi, etc.). It then applies the corresponding pipeline to each part of each field. +When you add documents to a Meilisearch index, the tokenization process is handled by an abstract interface called the tokenizer. The tokenizer is responsible for splitting each field by writing system (e.g. Latin alphabet, Chinese hanzi). It then applies the corresponding pipeline to each part of each document field. We can break down the tokenization process like so: From 1693adaf93dc36e584c09cb966ba64958c9606c8 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 6 Jul 2022 15:42:00 +0200 Subject: [PATCH 144/150] Apply suggestions from code review Co-authored-by: Maryam <90181761+maryamsulemani97@users.noreply.github.com> --- learn/advanced/pagination.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/learn/advanced/pagination.md b/learn/advanced/pagination.md index 2dc3a42524..6defdf7338 100644 --- a/learn/advanced/pagination.md +++ b/learn/advanced/pagination.md @@ -8,7 +8,7 @@ In this guide, we will discuss some of Meilisearch's current limitations, how th There are quite a few pagination interfaces you might want to implement in your application. Many common UI patterns have a page selector allowing users to jump to any search results page. To create a page selector, you must know the exact number of total results so you can calculate the precise number of result pages. -For performance reasons, however, Meilisearch cannot provide the exact number of results for a query. Instead, When using the search endpoint, responses contain an `estimatedTotalHits` field. As its name indicates, `estimatedTotalHits` is only an estimate of how many documents match your user's query. +For performance reasons, however, Meilisearch cannot provide the exact number of results for a query. Instead, when using the [search endpoint](/reference/api/search.md), responses contain an `estimatedTotalHits` field. As its name indicates, `estimatedTotalHits` is only an estimate of how many documents match your user's query. Because of this, we do not recommend creating interfaces with page selectors. If page selection is crucial to the software you are developing, see the [last section of this page](#not-recommended-page-selection) for tips that might help you work around Meilisearch's current limitations. @@ -28,7 +28,7 @@ Though this approach offers less precision than a full-blown page selector, it d Previous and next buttons can be implemented using the [`limit`](/reference/api/search.md#limit) and [`offset`](/reference/api/search.md#offset) search parameters. -`limit` sets the size of a page. If you set `limit` to 10, Meilisearch's response will contain a maximum of 10 search results. `offset` skips a number of search results. If you set `offset` to 20, Meilisearch's response will skip the first 20 search results. +`limit` sets the size of a page. If you set `limit` to `10`, Meilisearch's response will contain a maximum of 10 search results. `offset` skips a number of search results. If you set `offset` to `20`, Meilisearch's response will skip the first 20 search results. For example, you can use Meilisearch's JavaScript SDK to get the first ten films in a movies database: @@ -37,15 +37,16 @@ const results = await index.search("tarkovsky", { limit: 10, offset: 0 }); ``` You can use both parameters together to effectively create search pages. + #### Search pages and calculating `offset` -If you set `limit` to 20 and `offset` to 0, you get the first twenty search results. We can call this our first page. +If you set `limit` to `20` and `offset` to `0`, you get the first twenty search results. We can call this our first page. ```js const results = await index.search("tarkovsky", { limit: 20, offset: 0 }); ``` -Likewise, if you set `limit` to 20 and `offset` to 40, you skip the first 40 search results and get documents ranked from 41 through 60. We can call this the third results page. +Likewise, if you set `limit` to `20` and `offset` to `40`, you skip the first 40 search results and get documents ranked from 40 through 59. We can call this the third results page. ```js const results = await index.search("tarkovsky", { limit: 20, offset: 40 }); @@ -89,9 +90,9 @@ document.querySelector('#next_button').onclick = function () { updatePageNumber( It is often helpful to disable navigation buttons when the user cannot move to the "next" or "previous" page. -The "previous" button should be disabled whenever your `offset` is 0, as this indicates your user is on the first results page. +The "Previous" button should be disabled whenever your `offset` is `0`, as this indicates your user is on the first results page. -To know when to disable the "next" button, we recommend setting your query's `limit` to the number of results you wish to display per page plus one. That extra `hit` should not be shown to the user. Its purpose is to indicate that there is at least one more document to display on the next page. +To know when to disable the "Next" button, we recommend setting your query's `limit` to the number of results you wish to display per page plus one. That extra `hit` should not be shown to the user. Its purpose is to indicate that there is at least one more document to display on the next page. The following JavaScript snippet runs checks whether we should disable a button every time the user navigates to another search results page: @@ -152,9 +153,9 @@ We recommend two different workarounds to create this kind of pagination interfa By default, a search request returns 20 search results. You can change this value to a much higher number and treat it as the effective maximum of search results you will show a user. Doing so means the size of your `hits` array is the exact number of search results you have to paginate. -For example, if you set `limit` to 300, every search request made to Meilisearch returns at most 300 documents. If a query returns a `hits` array with 200 items and you want each page to display 20 results, you can create a page selector with 10 pages. +For example, if you set `limit` to `300`, every search request made to Meilisearch returns at most 300 documents. If a query returns a `hits` array with 200 items and you want each page to display 20 results, you can create a page selector with 10 pages. -In the following JavaScript snippet, each time a user searches, we make a new query with `limit` set to 300. Once we receive the search results, we store them in a variable and create a list of numbered pages. When users click on any number in the page list, we display a new page: +In the following JavaScript snippet, each time a user searches, we make a new query with `limit` set to `300`. Once we receive the search results, we store them in a variable and create a list of numbered pages. When users click on any number in the page list, we display a new page: ```js // Retrieve search results and create the page selector From 7b8fbc741e88cd1cd091953d589322f95a9108e6 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 6 Jul 2022 15:44:10 +0200 Subject: [PATCH 145/150] Apply suggestions from code review Co-authored-by: Maryam <90181761+maryamsulemani97@users.noreply.github.com> --- learn/advanced/pagination.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/advanced/pagination.md b/learn/advanced/pagination.md index 6defdf7338..a8d7354594 100644 --- a/learn/advanced/pagination.md +++ b/learn/advanced/pagination.md @@ -224,4 +224,4 @@ This method gives users access to all search results. However, it also results i ## Unsatisfied? Let us know -Is the current state of pagination in Meilisearch negatively impacting you? Please share your thoughts with us in this [GitHub discussion](https://github.com/meilisearch/product/discussions/483). We are actively working on improving this aspect of Meilisearch and your input is greatly appreciated. +Is the current state of pagination in Meilisearch negatively impacting you? Please share your thoughts with us in this [GitHub discussion](https://github.com/meilisearch/product/discussions/483). We are actively working on improving this aspect of Meilisearch, and your input is greatly appreciated. From a12ddd348cf1477f67300954adb82bde59363629 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 6 Jul 2022 16:08:10 +0200 Subject: [PATCH 146/150] address review feedback --- .vuepress/config.js | 1 + learn/advanced/pagination.md | 14 +++++--------- 2 files changed, 6 insertions(+), 9 deletions(-) diff --git a/.vuepress/config.js b/.vuepress/config.js index 395bd548d8..95f02aa241 100644 --- a/.vuepress/config.js +++ b/.vuepress/config.js @@ -174,6 +174,7 @@ module.exports = { '/learn/advanced/asynchronous_operations', '/learn/advanced/filtering_and_faceted_search', '/learn/advanced/geosearch', + '/learn/advanced/pagination', '/learn/advanced/sorting', { title: 'Updating Meilisearch', diff --git a/learn/advanced/pagination.md b/learn/advanced/pagination.md index a8d7354594..9decfb54c8 100644 --- a/learn/advanced/pagination.md +++ b/learn/advanced/pagination.md @@ -14,12 +14,10 @@ Because of this, we do not recommend creating interfaces with page selectors. If Many other pagination UIs are fully compatible with Meilisearch, such as infinite scrolling and buttons that manually load more results on click. For an experience similar to page selection, we recommend creating pagination interfaces centered around [previous and next buttons](#recommended-previous-and-next-buttons). -## Recommended: Previous and next buttons +## Recommended: "Previous" and "Next" buttons Using previous and next buttons for pagination means that users can easily navigate through results, but don't have the ability to jump to an arbitrary results page. -![Placeholder image for prev/next interface]() - Though this approach offers less precision than a full-blown page selector, it does not require knowing the precise number of search results. This makes it a good fit for Meilisearch's current capabilities. ### Implementation @@ -52,7 +50,7 @@ Likewise, if you set `limit` to `20` and `offset` to `40`, you skip the first 40 const results = await index.search("tarkovsky", { limit: 20, offset: 40 }); ``` -Use this formula to quickly calculate a page's offset value: `offset = limit * (target page number - 1)`. +You can use this formula to calculate a page's offset value: `offset = limit * (target page number - 1)`. In the previous example, the calculation would look like this: `offset = 20 * (3 - 1)`. This gives us `40` as the result: `offset = 20 * 2 = 40`. Once a query returns fewer `hits` than your configured `limit`, you have reached the last results page. @@ -135,13 +133,11 @@ document.querySelector('#next_button').onclick = function () { updatePageNumber( This type of pagination consists of a numbered list of pages accompanied by next and previous buttons. -![placeholder page selection UI](https://vuejsexamples.com/content/images/2018/11/vue-pagination.gif) - This is a common UI pattern that offers users a significant amount of precision when navigating results. However, due to Meilisearch's [limitations](#choosing-the-right-pagination-ui), it is not a good fit for pagination with Meilisearch. ### Implementation -The general implementation of a page selection interface is similar to our [recommended solution](#recommended-previous-and-next-buttons), but also includes a numbered page list. +The general implementation of a page selection interface is similar to our [recommended solution](#recommended-previous-and-next-buttons), with one signficant addition: it includes a numbered page list. To create a numbered page list, however, you must know the exact number of total results. For example, if you have 100 results and your search result pages contain 10 results each, your selector must show a list of numbers going from 1 to 10. @@ -218,10 +214,10 @@ By default, Meilisearch returns a maximum of 1000 search results. Consult our [i Though we advise against it, you can use `estimatedTotalHits` to calculate the number of search result pages. This means your number of results and page count are likely to change until Meilisearch retrieves the last search result. -For example, a query's `estimatedTotalHits` might be `100` when you fetch the first page of search results. If you are showing 20 results per page, this means your interface will display a page selector with 5 pages. When you fetch the fifth and last page according to Meilisearch's current estimate, however, `estimatedTotalHits` might change to `300`. Your page list, previously displaying 5 pages, must now show 10 total pages. +For example, a query's `estimatedTotalHits` might be `100` when you fetch the first page of search results. If you are showing 20 results per page, this means your interface will display a page selector with 5 pages. When you fetch the fifth and last page according to Meilisearch's current estimate, however, `estimatedTotalHits` might change to `300`. Your page list, previously displaying 5 pages, must now show 15 total pages. This method gives users access to all search results. However, it also results in an interface that might feel unreliable due to constant and unpredictable changes. ## Unsatisfied? Let us know -Is the current state of pagination in Meilisearch negatively impacting you? Please share your thoughts with us in this [GitHub discussion](https://github.com/meilisearch/product/discussions/483). We are actively working on improving this aspect of Meilisearch, and your input is greatly appreciated. +Is the current state of pagination in Meilisearch creating problems for you? Please share your thoughts with us in this [GitHub discussion](https://github.com/meilisearch/product/discussions/483). We are actively working on improving this aspect of Meilisearch and your input is greatly appreciated. From 8483f25fc3b307de63b95b67ccc9cb45bf166b7e Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 7 Jul 2022 12:37:03 +0200 Subject: [PATCH 147/150] pagination: fix linter errors on guide, reference --- learn/advanced/pagination.md | 2 +- learn/configuration/settings.md | 1 - reference/api/faceting.md | 4 ++-- reference/api/pagination.md | 4 ++-- 4 files changed, 5 insertions(+), 6 deletions(-) diff --git a/learn/advanced/pagination.md b/learn/advanced/pagination.md index 9decfb54c8..a75d723a8b 100644 --- a/learn/advanced/pagination.md +++ b/learn/advanced/pagination.md @@ -207,7 +207,7 @@ searchBar.onChange(function () { getSearchResults('tarkovsky') }) This method provides control and reliability. It also prevents users from paginating too far, which might result in performance gains. However, it limits the number of results your users can see. Additionally, we recommend caution when setting high values for `limit` as it can negatively impact performance. ::: note -By default, Meilisearch returns a maximum of 1000 search results. Consult our [index setting reference](/reference/api/pagination.md#maxtotalhits-1) if you need to change this. +By default, Meilisearch returns a maximum of 1000 search results. Consult our [index setting reference](/reference/api/pagination.md) if you need to change this. ::: #### Use `estimatedTotalHits` diff --git a/learn/configuration/settings.md b/learn/configuration/settings.md index 01d58b35c5..8c31f449d7 100644 --- a/learn/configuration/settings.md +++ b/learn/configuration/settings.md @@ -129,7 +129,6 @@ The following code sample will return a maximum of `5` facet values for each fac - ## Ranking rules Built-in ranking rules that **ensure relevancy in search results**. Ranking rules are applied in a default order which can be changed in the settings. You can add or remove rules and change their order of importance. diff --git a/reference/api/faceting.md b/reference/api/faceting.md index a2d32ad122..5c8df72aca 100644 --- a/reference/api/faceting.md +++ b/reference/api/faceting.md @@ -73,7 +73,7 @@ Setting `maxValuesPerFacet` to a high value might negatively impact performance. } ``` -You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). ## Reset faceting settings @@ -95,4 +95,4 @@ Reset an index's faceting settings to their default value. The index [`uid`](/le } ``` -You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). diff --git a/reference/api/pagination.md b/reference/api/pagination.md index f4d15d47b8..f720402990 100644 --- a/reference/api/pagination.md +++ b/reference/api/pagination.md @@ -73,7 +73,7 @@ Setting `maxTotalHits` to a high value might negatively impact performance and e } ``` -You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). ## Reset pagination settings @@ -95,4 +95,4 @@ Reset an index's pagination settings to their default value. The index [`uid`](/ } ``` -You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task). From b07336f47dcc5062da2e3ae3c777368104a45e46 Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Thu, 7 Jul 2022 15:48:49 +0400 Subject: [PATCH 148/150] Update learn/what_is_meilisearch/language.md Co-authored-by: Many the fish --- learn/what_is_meilisearch/language.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/what_is_meilisearch/language.md b/learn/what_is_meilisearch/language.md index a515fd0c9b..a388d3fb7a 100644 --- a/learn/what_is_meilisearch/language.md +++ b/learn/what_is_meilisearch/language.md @@ -15,7 +15,7 @@ We aim to provide global language support, and your feedback helps us move close While we have employees from all over the world at Meilisearch, we don't speak every language. We rely almost entirely on feedback from external contributors to understand how our engine is performing across different languages. -If you'd like to request optimized support for a language that we don't currently support, please upvote the related [discussion in our product repository](https://github.com/meilisearch/product/discussions?discussions_q=label%3Aproduct%3Acore%3Atokenizer) or [open a new one](https://github.com/meilisearch/product/discussions/new) if it doesn't exist. +If you'd like to request optimized support for a language that we don't currently support, please upvote the related [discussion in our product repository](https://github.com/meilisearch/product/discussions?discussions_q=label%3Aproduct%3Acore%3Atokenizer) or [open a new one](https://github.com/meilisearch/product/discussions/new?category=feedback-feature-proposal) if it doesn't exist. If you'd like to help by developing a tokenizer pipeline yourself: first of all, thank you! We recommend that you take a look at the [tokenizer contribution guide](https://github.com/meilisearch/charabia/blob/main/CONTRIBUTING.md) before making a PR. From 72298e583de8bfd01f95aeb88c6b90152322833e Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 7 Jul 2022 17:53:36 +0200 Subject: [PATCH 149/150] language: update create issue link --- learn/what_is_meilisearch/language.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/learn/what_is_meilisearch/language.md b/learn/what_is_meilisearch/language.md index a388d3fb7a..ea5a004e63 100644 --- a/learn/what_is_meilisearch/language.md +++ b/learn/what_is_meilisearch/language.md @@ -7,7 +7,7 @@ Meilisearch is multilingual, featuring optimized support for: - Japanese - Hebrew -We aim to provide global language support, and your feedback helps us move closer to that goal. If you notice inconsistencies in your search results or the way your documents are processed, please [open an issue in our tokenizer repo](https://github.com/meilisearch/charabia/issues/new). +We aim to provide global language support, and your feedback helps us move closer to that goal. If you notice inconsistencies in your search results or the way your documents are processed, please [open an issue in the Meilisearch repository](https://github.com/meilisearch/meilisearch/issues/new/choose). [Read more about our tokenizer](/learn/advanced/tokenization.md) @@ -15,7 +15,7 @@ We aim to provide global language support, and your feedback helps us move close While we have employees from all over the world at Meilisearch, we don't speak every language. We rely almost entirely on feedback from external contributors to understand how our engine is performing across different languages. -If you'd like to request optimized support for a language that we don't currently support, please upvote the related [discussion in our product repository](https://github.com/meilisearch/product/discussions?discussions_q=label%3Aproduct%3Acore%3Atokenizer) or [open a new one](https://github.com/meilisearch/product/discussions/new?category=feedback-feature-proposal) if it doesn't exist. +If you'd like to request optimized support for a language, please upvote the related [discussion in our product repository](https://github.com/meilisearch/product/discussions?discussions_q=label%3Aproduct%3Acore%3Atokenizer) or [open a new one](https://github.com/meilisearch/product/discussions/new?category=feedback-feature-proposal) if it doesn't exist. If you'd like to help by developing a tokenizer pipeline yourself: first of all, thank you! We recommend that you take a look at the [tokenizer contribution guide](https://github.com/meilisearch/charabia/blob/main/CONTRIBUTING.md) before making a PR. From 68a11321a12d07624289ec062daf7c44e09d6958 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9mentine=20Urquizar?= Date: Mon, 11 Jul 2022 10:33:44 +0200 Subject: [PATCH 150/150] Add missing limit and from parameter to postman v0.28 --- .vuepress/public/postman/meilisearch-collection.json | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/.vuepress/public/postman/meilisearch-collection.json b/.vuepress/public/postman/meilisearch-collection.json index 747d7c1013..176f47bcaf 100644 --- a/.vuepress/public/postman/meilisearch-collection.json +++ b/.vuepress/public/postman/meilisearch-collection.json @@ -382,6 +382,16 @@ "key": "indexUid", "value": "books", "disabled": true + }, + { + "key": "limit", + "value": "2", + "disabled": true + }, + { + "key": "from", + "value": "10", + "disabled": true } ] }