diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index c67b025e64..62c5ee7dcb 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -454,81 +454,6 @@ search_parameter_guide_show_matches_position_1: |- "q": "winter feast", "showMatchesPosition": true }' -settings_guide_synonyms_1: |- - curl \ - -X PATCH 'http://localhost:7700/indexes/tops/settings' \ - -H 'Content-Type: application/json' \ - --data-binary '{ - "synonyms": { - "sweater": ["jumper"], - "jumper": ["sweater"] - } - }' -settings_guide_stop_words_1: |- - curl \ - -X PATCH 'http://localhost:7700/indexes/movies/settings' \ - -H 'Content-Type: application/json' \ - --data-binary '{ - "stopWords": [ - "the", - "a", - "an" - ] - }' -settings_guide_ranking_rules_1: |- - curl \ - -X PATCH 'http://localhost:7700/indexes/movies/settings' \ - -H 'Content-Type: application/json' \ - --data-binary '{ - "rankingRules": [ - "words", - "typo", - "proximity", - "attribute", - "sort", - "exactness", - "release_date:asc", - "rank:desc" - ] - }' -settings_guide_distinct_1: |- - curl \ - -X PATCH 'http://localhost:7700/indexes/jackets/settings' \ - -H 'Content-Type: application/json' \ - --data-binary '{ "distinctAttribute": "product_id" }' -settings_guide_searchable_1: |- - curl \ - -X PATCH 'http://localhost:7700/indexes/movies/settings' \ - -H 'Content-Type: application/json' \ - --data-binary '{ - "searchableAttributes": [ - "title", - "overview", - "genres" - ] - }' -settings_guide_displayed_1: |- - curl \ - -X PATCH 'http://localhost:7700/indexes/movies/settings' \ - -H 'Content-Type: application/json' \ - --data-binary '{ - "displayedAttributes": [ - "title", - "overview", - "genres", - "release_date" - ] - }' -settings_guide_sortable_1: |- - curl \ - -X PATCH 'http://localhost:7700/indexes/books/settings' \ - -H 'Content-Type: application/json' \ - --data-binary '{ - "sortableAttributes": [ - "price", - "author" - ] - }' add_movies_json_1: |- curl \ -X POST 'http://localhost:7700/indexes/movies/documents'\ @@ -898,16 +823,6 @@ typo_tolerance_guide_4: |- "twoTypos": 10 } }' -settings_guide_typo_tolerance_1: |- - curl \ - -X PATCH 'http://localhost:7700/indexes/movies/settings/typo-tolerance' \ - -H 'Content-Type: application/json' \ - --data-binary '{ - "minWordSizeForTypos": { - "twoTypos": 12 - }, - "disableOnAttributes": ["title"] - }' updating_guide_check_version_new_authorization_header: |- curl \ -X GET 'http://localhost:7700/version' \ @@ -936,13 +851,6 @@ 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' \ - --data-binary '{ - "maxTotalHits": 50 - }' get_pagination_settings_1: |- curl \ -X GET 'http://localhost:7700/indexes/books/settings/pagination' @@ -969,13 +877,6 @@ 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 - }' synonyms_guide_1: |- curl \ -X PUT 'http://localhost:7700/indexes/movies/settings/synonyms' \ diff --git a/.vuepress/public/sample-template.yaml b/.vuepress/public/sample-template.yaml index 50ff3f3426..afeaf3af91 100644 --- a/.vuepress/public/sample-template.yaml +++ b/.vuepress/public/sample-template.yaml @@ -68,13 +68,6 @@ search_parameter_guide_retrieve_1: |- search_parameter_guide_crop_1: |- search_parameter_guide_highlight_1: |- search_parameter_guide_show_matches_position_1: |- -settings_guide_synonyms_1: |- -settings_guide_stop_words_1: |- -settings_guide_ranking_rules_1: |- -settings_guide_distinct_1: |- -settings_guide_searchable_1: |- -settings_guide_displayed_1: |- -settings_guide_sortable_1: |- getting_started_add_documents_md: |- getting_started_search_md: |- getting_started_check_task_status: |- @@ -133,21 +126,18 @@ typo_tolerance_guide_1: |- typo_tolerance_guide_2: |- typo_tolerance_guide_3: |- typo_tolerance_guide_4: |- -settings_guide_typo_tolerance_1: |- updating_guide_check_version_new_authorization_header: |- updating_guide_check_version_old_authorization_header: |- updating_guide_get_displayed_attributes_new: |- updating_guide_reset_displayed_attributes_new: |- updating_guide_create_dump: |- getting_started_typo_tolerance: |- -settings_guide_pagination_1: |- get_pagination_settings_1: |- update_pagination_settings_1: |- reset_pagination_settings_1: |- get_faceting_settings_1: |- update_faceting_settings_1: |- reset_faceting_settings_1: |- -settings_guide_faceting_1: |- synonyms_guide_1: |- getting_started_faceting: |- getting_started_pagination: |- diff --git a/learn/advanced/filtering_and_faceted_search.md b/learn/advanced/filtering_and_faceted_search.md index d11c7c0c14..83ebc8f0be 100644 --- a/learn/advanced/filtering_and_faceted_search.md +++ b/learn/advanced/filtering_and_faceted_search.md @@ -276,7 +276,7 @@ Please note that **synonyms don't apply to filters.** Meaning, if you have `SF` #### Example -Suppose you have added `director` and `genres` to the [`filterableAttributes` list](/learn/configuration/settings.md#filterable-attributes), and you want to get movies classified as either `Horror` **or** `Mystery` **and** directed by `Jordan Peele`. +Suppose you have added `director` and `genres` to the [`filterableAttributes` list](/reference/api/settings.md#filterable-attributes), and you want to get movies classified as either `Horror` **or** `Mystery` **and** directed by `Jordan Peele`. ```SQL [["genres = horror", "genres = mystery"], "director = 'Jordan Peele'"] diff --git a/learn/advanced/indexing.md b/learn/advanced/indexing.md index f56755ace5..b86ad160dc 100644 --- a/learn/advanced/indexing.md +++ b/learn/advanced/indexing.md @@ -57,7 +57,7 @@ If you encounter performance issues during indexing, we recommend trying the fol ] ``` -- When creating a new index, first [configure its settings](/learn/configuration/settings.md) and only then add your documents. Following this order will significantly reduce indexing time. +- When creating a new index, first [configure its settings](/reference/api/settings.md) and only then add your documents. Following this order will significantly reduce indexing time. - Since indexing speed is tightly connected to the size of your payload, using lightweight dataset formats such as CSV and NDJSON can lead to increased performance. diff --git a/learn/configuration/settings.md b/learn/configuration/settings.md index e38da32091..e3b73ceba4 100644 --- a/learn/configuration/settings.md +++ b/learn/configuration/settings.md @@ -1,272 +1,17 @@ # Index settings -This page describes the **index-level settings** available in Meilisearch and how to customize them. - -| Variable | Description | Default value | -| :----------------------------------------------------------------------------------- | :------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------- | -| **[`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 | `[]` | -| **[`pagination`](/learn/advanced/pagination.md)** | Pagination settings | `{"maxTotalHits": 1000}` | -| **[`faceting`](/learn/advanced/filtering_and_faceted_search.md)** | Faceting settings | `{"maxValuesPerFacet": 100}` | -| **[`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 | `[]` | -| **[`stopWords`](/learn/configuration/settings.md#stop-words)** | List of words ignored by Meilisearch when present in search queries | `[]` | -| **[`synonyms`](/learn/configuration/settings.md#synonyms)** | List of associated words treated similarly | `{}` | -| **[`typoTolerance`](/learn/configuration/settings.md#typo-tolerance)** | Object containing typo tolerance settings | Enabled. One typo allowed for words of 5+ characters; two for words of 9+ characters. | - -## Displayed attributes - -The fields whose attributes are added to the [displayed attributes list](/learn/configuration/displayed_searchable_attributes.md) are **contained in each matching document**. - -Documents returned upon search contain only displayed fields. - -`displayedAttributes=[, , ...]` - -- `[, , ...]` (Array of strings, defaults to all attributes found in the documents) - - An array of strings that contains attributes of an index to display. - -[Learn more about displayed attributes](/learn/configuration/displayed_searchable_attributes.md#displayed-fields) - -#### Example - -By adding the following settings, documents returned upon search will contain the fields `title`, `overview`, `genres` and `release_date`. - - - -## Distinct attribute - -The **value of a field** whose attribute is set as a distinct attribute will always be **unique** in the returned documents. - -`distinctAttribute=` - -- `` (String, defaults to `null`) - - The field name. - -[Learn more about the distinct attribute](/learn/configuration/distinct.md) - -#### Example - -Suppose you have an e-commerce dataset. For an index that contains information about jackets, you may have several identical items in different variations (color or size). - -As shown below, you have 2 documents that contain information about the same jacket. One of the jackets is brown and the other one is black. - -```json -[ - { - "id": 1, - "description": "Leather jacket", - "brand": "Lee jeans", - "color": "brown", - "product_id": "123456" - }, - { - "id": 2, - "description": "Leather jacket", - "brand": "Lee jeans", - "color": "black", - "product_id": "123456" - } -] -``` - -You may want to ignore the different colors of an item. To do so, you can set `product_id` as a `distinctAttribute`. - - - -With the settings in the example above, only one of the two documents will be returned if you search `Lee leather jacket`. - -## Filterable attributes - -List of attributes that can be used for [filtering and faceted search](/learn/advanced/filtering_and_faceted_search.md). - -By default, `filterableAttributes` is an empty array. It expects an array of attributes whose corresponding values are either numbers or strings. `null` fields or fields that contain empty arrays are silently ignored, but an error will be thrown if the field's value is an object. - -::: tip -Configuring `filterableAttributes` is necessary in order to use the [`filter` search parameter](/reference/api/search.md#filter). -::: - -[Learn more about filtering and faceted search in our dedicated guide.](/learn/advanced/filtering_and_faceted_search.md) - -#### Example - -To be able to filter search results on `director` and `genres` in a movie database, you must first add these attributes to the `filterableAttributes` list: - - - -## 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` is a hard limit that takes precedence over search parameters such as [`limit`](/reference/api/search.md#limit) and [`offset`](/reference/api/search.md#offset). This means that queries with an `offset` equal to or greater than `maxTotalHits` will return an empty array. -::: - -## 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/settings.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. - -`rankingRules=[, , ...]` - -- `[, , ...]` (Array of strings, see default value below) - - An array of strings that contains the ranking rules sorted by order of importance (arranged from the most important rule to the least important rule). - -Default value (the ranking rules in the default order): - -```json -[ - "words", - "typo", - "proximity", - "attribute", - "sort", - "exactness" -] -``` - -[Read this guide to know more about what each ranking rules does](/learn/core_concepts/relevancy.md) - -### Custom ranking rule - -You can add a custom ranking rule anywhere in the list of ranking rules. A custom ranking rule is composed of an attribute and an ascending or descending order. The attribute **must have a numeric value** in the documents. - -::: warning - -If some documents do not contain the attribute defined in a custom ranking rule, the application of the ranking rule is undefined and the search results might not be sorted as you expected. - -We recommend that all your documents contain any attribute used in a custom ranking rule. For example, if you set the custom ranking rule `desc(year)`, make sure that all your documents contain the attribute `year`. - -::: - -#### Example - -To add your ranking rules to the settings, send: - - - -With the settings in the example above, documents will be sorted by decreasing number of matched query terms first. If too many documents have the same number of query terms, the `typo` rule will be applied. This operation will be repeated with the next rule until the requested number of documents has been reached (default: 20). - -## Searchable attributes - -The content of the fields whose attributes are added to the [searchable attributes list](/reference/api/settings.md#searchable-attributes) are **searched for matching query words**. - -`searchableAttributes=[, , ...]` - -- `[, , ...]` (Array of strings, defaults to all attributes found in the documents) - - An array of strings that contains searchable attributes ordered by importance (arranged from the most important attribute to the least important attribute). - -[Learn more about searchable attributes](/learn/configuration/displayed_searchable_attributes.md#searchable-fields) - -#### Example - -By adding the following settings, the fields `title`, `overview` and `genres` will be searched. - - - -## Sortable attributes - -List of attributes that can be used for [sorting](/learn/advanced/sorting.md). - -By default, `sortableAttributes` is an empty array. It expects an array of attributes whose corresponding values are either numbers or strings. `null` fields or fields that contain empty arrays are silently ignored, but an error will be thrown if the field's value is an object. - -::: tip -Configuring `sortableAttributes` is necessary in order to use the [`sort` search parameter](/reference/api/search.md#sort). -::: - -[Learn more about sorting in our dedicated guide.](/learn/advanced/sorting.md) - -#### Example - -To be able to sort search results according to the attributes `price` and `author` in a webshop, you must first add them to the `sortableAttributes` list: - - - -## Stop words - -A set of words defined for an index. Because some words neither add semantic value nor context, you may want to ignore them from your search. Stop words are **ignored during search**. - -`stopWords=[, , ...]` - -- `[, , ...]` (Array of strings, defaults to `[]`) - - An array of strings that contains the stop words. - -[Learn more about stop words](/reference/api/settings.md#stop-words) - -#### Example - -To add `the`, `a` and `an` to the stop words list, send: - - - -With the settings in the example above, `the`, `a` and `an` are now ignored by the sorting algorithm if they are present in search queries. - -Suppose you would like to search `the mask` in a movie database. Since `the` is ignored during search, Meilisearch will look for every movie containing `mask` and not the millions ones containing `the`. `the` is a less relevant term than `mask` and also a very frequent word in English. By adding `the` to the stop words list, Meilisearch will ignore this word, and thus be faster to answer without losing in relevancy. - -## Synonyms - -A set of words defined for an index. Synonyms are **different words that have the same meaning**, and thus are treated similarly. When searching for one word, you will also get some of the same results as the other associated word. - -`synonyms=` - -- `` (Object, defaults to `{}`) : `{ : [, , ...], ... }` - - An object that contains words with a list of their associated synonyms. Synonym strings are [normalized](/learn/configuration/synonyms.md#normalization). - -[Learn more about synonyms](/learn/configuration/synonyms.md) - -#### Example - -Suppose you have an e-commerce dataset. For an index that contains information about tops, you decide to create synonyms for `sweater` and `jumper` since these two items are very similar. - - - -By doing so, when searching for `black sweater`, results for `black jumper` will also be returned. - -## Typo tolerance - -The typo tolerance settings for an index. Typo tolerance helps users find relevant results even when their search queries contain spelling mistakes or typos. - -The `typoTolerance` object allows you to: - -- Enable or disable the typo tolerance feature with the `enabled` field -- Configure the minimum word size for typos to be handled with `minWordSizeForTypos` -- Disable typos on specific words with `disableOnWords` -- Disable typos on specific document attributes with `disableOnAttributes` - -[Learn more about typo tolerance](/learn/configuration/typo_tolerance.md) - -### Example - -Adding the following settings disables typo tolerance for the `title` attribute and sets the minimum word size for 2 typos to `12` characters. - - +The table below shows the **index-level settings** available in Meilisearch. + +| Name | Type | Default value | Description | +| :----------------------------------------------------------------------------- | :--------------- | :----------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------- | +| **[`displayedAttributes`](/reference/api/settings.md#displayed-attributes)** | Array of strings | All attributes: `["*"]` | Fields displayed in the returned documents | +| **[`distinctAttribute`](/reference/api/settings.md#distinct-attribute)** | String | `null` | Search returns documents with distinct (different) values of the given field | +| **[`faceting`](/reference/api/settings.md#faceting)** | Object | [Default object](/reference/api/settings.md#faceting-object) | Faceting settings | +| **[`filterableAttributes`](/reference/api/settings.md#filterable-attributes)** | Array of strings | Empty | Attributes to use as filters and facets | +| **[`pagination`](/reference/api/settings.md#pagination)** | Object | [Default object](/reference/api/settings.md#pagination-object) | Pagination settings | +| **[`rankingRules`](/reference/api/settings.md#ranking-rules)** | Array of strings | `["words",`
`"typo",`
`"proximity",`
`"attribute",`
`"sort",`
`"exactness"]` | List of ranking rules in order of importance | +| **[`searchableAttributes`](/reference/api/settings.md#searchable-attributes)** | Array of strings | All attributes: `["*"]` | Fields in which to search for matching query words sorted by order of importance | +| **[`sortableAttributes`](/reference/api/settings.md#sortable-attributes)** | Array of strings | Empty | Attributes to use when sorting search results | +| **[`stopWords`](/reference/api/settings.md#stop-words)** | Array of strings | Empty | List of words ignored by Meilisearch when present in search queries | +| **[`synonyms`](/reference/api/settings.md#synonyms)** | Object | Empty | List of associated words treated similarly | +| **[`typoTolerance`](/reference/api/settings.md#typo-tolerance)** | Object | [Default object](/reference/api/settings.md#typo-tolerance-object) | Typo tolerance settings | diff --git a/learn/core_concepts/documents.md b/learn/core_concepts/documents.md index 405957d111..d1fb2b3db8 100644 --- a/learn/core_concepts/documents.md +++ b/learn/core_concepts/documents.md @@ -24,7 +24,7 @@ Every field has a data type dictated by its value. Every value must be a valid [ If a field contains an object, Meilisearch flattens it during indexing using dot notation and brings the object's keys and values to the root level of the document itself. This flattened object is only an intermediary representation—you will get the original structure upon search. You can read more about this in our [dedicated guide](/learn/advanced/datatypes.md#objects). -With [ranking rules](/learn/core_concepts/relevancy.md#ranking-rules), you can decide what fields are more relevant than others. For example, you may decide recent movies should be more relevant than older ones. You can also configure how Meilisearch handles certain fields at an [index level](/learn/configuration/settings.md) in the settings. +With [ranking rules](/learn/core_concepts/relevancy.md#ranking-rules), you can decide which fields are more relevant than others. For example, you may decide recent movies should be more relevant than older ones. You can also designate certain fields as displayed or searchable. ### Displayed and searchable fields diff --git a/learn/getting_started/algolia_migration.md b/learn/getting_started/algolia_migration.md index aa5ce8e798..72999a5080 100644 --- a/learn/getting_started/algolia_migration.md +++ b/learn/getting_started/algolia_migration.md @@ -160,7 +160,7 @@ const BATCH_SIZE = 1000; Meilisearch's default settings are designed to deliver a fast and relevant search experience that works for most use-cases. -To customize your index settings, we recommend following [this guide](/learn/configuration/settings.md). To learn more about the differences between settings in Algolia and Meilisearch, read on. +To customize your index settings, we recommend following [this guide](/learn/core_concepts/indexes.md#index-settings). To learn more about the differences between settings in Algolia and Meilisearch, read on. ### Index settings vs. search parameters @@ -168,7 +168,7 @@ One of the key usage differences between Algolia and Meilisearch is how they app **In Algolia,** [API parameters](https://www.algolia.com/doc/api-reference/api-parameters/) is a flexible category that includes both index settings and search parameters. Many API parameters can be used both at indexing time—to set default behavior—or at search time—to override that behavior. -**In Meilisearch,** [index settings](/learn/configuration/settings.md) and [search parameters](/reference/api/search.md#search-parameters) are two distinct categories. Settings affect all searches on an index, while parameters affect the results of a single search. +**In Meilisearch,** [index settings](/reference/api/settings.md) and [search parameters](/reference/api/search.md#search-parameters) are two distinct categories. Settings affect all searches on an index, while parameters affect the results of a single search. Some Meilisearch parameters require index settings to be configured beforehand. For example, you must first configure the index setting `sortableAttributes` to use the search parameter `sort`. However, unlike in Algolia, an index setting can never be used as a parameter and vice versa. diff --git a/learn/getting_started/filtering_and_sorting.md b/learn/getting_started/filtering_and_sorting.md index 0222a597ef..5c76408e8c 100644 --- a/learn/getting_started/filtering_and_sorting.md +++ b/learn/getting_started/filtering_and_sorting.md @@ -18,7 +18,7 @@ The `settings` object contains two arrays for this purpose: `filterableAttribute The above code sample adds `mass` and `_geo` to `filterableAttributes` and `sortableAttributes` setting you up for the next sections. -To learn more about the `settings` object and how to configure it, refer to our [dedicated guide](/learn/configuration/settings.md). +To learn more about the `settings` object and how to configure it, check out the [API reference](/reference/api/settings.md). ## Filtering diff --git a/learn/what_is_meilisearch/features.md b/learn/what_is_meilisearch/features.md index 0fe7ddd416..1692092527 100644 --- a/learn/what_is_meilisearch/features.md +++ b/learn/what_is_meilisearch/features.md @@ -47,7 +47,7 @@ Meilisearch allows you to define [filters](/learn/advanced/filtering_and_faceted ## Placeholder search -If you make a search without inputting any query words, Meilisearch will return all the documents in that index sorted by its [custom ranking rules](/learn/configuration/settings.md#custom-ranking-rule) and [sorting rules](/learn/advanced/sorting.md#sorting). This feature is called **placeholder search**. +If you make a search without inputting any query words, Meilisearch will return all the documents in that index sorted by its [custom ranking rules](/learn/core_concepts/relevancy.md#custom-rules) and [sorting rules](/learn/advanced/sorting.md#sorting). This feature is called **placeholder search**. Placeholder searches are particularly effective when used with other features such as [faceting or filtering](/learn/advanced/filtering_and_faceted_search.md#filters-or-facets), which allow users to narrow their searches and browse by category. You can read more about this feature in our article on [search parameters](/reference/api/search.md#placeholder-search). diff --git a/reference/api/search.md b/reference/api/search.md index 6507e6c4b6..5512c8d79a 100644 --- a/reference/api/search.md +++ b/reference/api/search.md @@ -271,7 +271,7 @@ Additionally, keep in mind queries go through a normalization process that strip #### Placeholder search -When `q` isn't specified, Meilisearch performs a **placeholder search**. A placeholder search returns all searchable documents in an index, modified by any search parameters used and sorted by that index's [custom ranking rules](/learn/configuration/settings.md#custom-ranking-rule). Since there is no query term, the [built-in ranking rules](/learn/core_concepts/relevancy.md#ranking-rules) **do not apply.** +When `q` isn't specified, Meilisearch performs a **placeholder search**. A placeholder search returns all searchable documents in an index, modified by any search parameters used and sorted by that index's [custom ranking rules](/learn/core_concepts/relevancy.md#custom-rules). Since there is no query term, the [built-in ranking rules](/learn/core_concepts/relevancy.md#ranking-rules) **do not apply.** If the index has no sort or custom ranking rules, the results are returned in the order of their internal database position. @@ -507,7 +507,7 @@ You would get the following response: Configures which attributes will be retrieved in the returned documents. -If no value is specified, `attributesToRetrieve` uses the [`displayedAttributes` list](/learn/configuration/settings.md#displayed-attributes), which by default contains all attributes found in the documents. +If no value is specified, `attributesToRetrieve` uses the [`displayedAttributes` list](/reference/api/settings.md#displayed-attributes), which by default contains all attributes found in the documents. ::: note If an attribute has been removed from `displayedAttributes`, `attributesToRetrieve` will silently ignore it and the field will not appear in your returned documents. diff --git a/reference/api/settings.md b/reference/api/settings.md index 0b32984d97..71237d849b 100644 --- a/reference/api/settings.md +++ b/reference/api/settings.md @@ -245,6 +245,10 @@ Update the displayed attributes of an index. #### Body +``` +[, , …] +``` + An array of strings. Each string should be an attribute that exists in the selected index. If an attribute contains an object, you can use dot notation to specify one or more of its keys, for example, `"displayedAttributes": ["release_date.year"]`. @@ -347,6 +351,10 @@ Update the distinct attribute field of an index. #### Body +``` + +``` + A string. The string should be an attribute that exists in the selected index. If an attribute contains an object, you can use dot notation to set one or more of its keys as a value for this setting, for example, `"distinctAttribute": "product.skuid"`. @@ -455,6 +463,10 @@ Partially update the faceting settings for an index. Any parameters not provided #### Body +``` +{maxValuesPerFacet: } +``` + | Name | Type | Default value | Description | | :---------------------- | :------ | :------------ | :----------------------------------------------------------------------------------------------------------- | | **`maxValuesPerFacet`** | Integer | `100` | Maximum number of facet values returned for each facet. Values are sorted in ascending lexicographical order | @@ -561,6 +573,10 @@ Update an index's filterable attributes list. #### Body +``` +[, , …] +``` + An array of strings containing the attributes that can be used as filters at query time. If an attribute contains an object, you can use dot notation to set one or more of its keys as a value for this setting: `"filterableAttributes": ["release_date.year"]`. @@ -673,6 +689,10 @@ Partially update the pagination settings for an index. #### Body +``` +{maxTotalHits: } +``` + | Name | Type | Default value | Description | | :----------------- | :------ | :------------ | :---------------------------------------------------------- | | **`maxTotalHits`** | Integer | `1000` | The maximum number of search results Meilisearch can return | @@ -801,6 +821,10 @@ Update the ranking rules of an index. #### Body +``` +[, , …] +``` + An array that contains ranking rules in order of importance. To create a custom ranking rule, give an attribute followed by a colon (`:`) and either `asc` for ascending order or `desc` for descending order. @@ -808,6 +832,12 @@ To create a custom ranking rule, give an attribute followed by a colon (`:`) and - To apply an **ascending sort** (results sorted by increasing value): `attribute_name:asc` - To apply a **descending sort** (results sorted by decreasing value): `attribute_name:desc` +::: warning +If some documents do not contain the attribute defined in a custom ranking rule, the application of the ranking rule is undefined and the search results might not be sorted as you expected. + +Make sure that any attribute used in a custom ranking rule is present in all of your documents. For example, if you set the custom ranking rule `desc(year)`, make sure that all your documents contain the attribute `year`. +::: + [To learn more about ranking rules, refer to our dedicated guide.](/learn/core_concepts/relevancy.md#ranking-rules) #### Example @@ -919,6 +949,10 @@ Due to an implementation bug, manually updating `searchableAttributes` will chan #### Body +``` +[, , …] +``` + An array of strings. Each string should be an attribute that exists in the selected index. The array should be given in [order of importance](/learn/core_concepts/relevancy.md#attribute-ranking-order): from the most important attribute to the least important attribute. If an attribute contains an object, you can use dot notation to set one or more of its keys as a value for this setting: `"searchableAttributes": ["release_date.year"]`. @@ -1030,6 +1064,10 @@ Update an index's sortable attributes list. #### Body +``` +[, , …] +``` + An array of strings. Each string should be an attribute that exists in the selected index. If an attribute contains an object, you can use dot notation to set one or more of its keys as a value for this setting: `"sortableAttributes": ["author.surname"]`. @@ -1142,6 +1180,10 @@ Update the list of stop words of an index. #### Body +``` +[, , …] +``` + An array of strings. Each string should be a single word. If a list of stop words already exists, it will be overwritten (_replaced_). @@ -1248,6 +1290,13 @@ Update the list of synonyms of an index. Synonyms are [normalized](/learn/config #### Body +``` +{ + : [, , …], + … +} +``` + An object that contains all synonyms and their associated words. Add the associated words in an array to set a synonym for a word. [To learn more about synonyms, refer to our dedicated guide.](/learn/configuration/synonyms.md) @@ -1360,6 +1409,18 @@ Partially update the typo tolerance settings for an index. #### Body +``` +{ + "enabled": , + "minWordSizeForTypos": { + "oneTypo": , + "twoTypos": + }, + "disableOnWords": [, , …], + "disableOnAttributes": [, , …] +} +``` + | Name | Type | Default Value | Description | | :--------------------------------- | :--------------- | :------------ | :------------------------------------------------------------------------------- | | **`enabled`** | Boolean | `true` | Whether typo tolerance is enabled or not | diff --git a/resources/faq.md b/resources/faq.md index 15b4f802a2..f48cb55c75 100644 --- a/resources/faq.md +++ b/resources/faq.md @@ -138,7 +138,7 @@ In general, we recommend the former. However, if you need to reduce the size of - **More relevancy rules => a larger database** - The proximity [ranking rule](/learn/core_concepts/relevancy.md#ranking-rules) alone can be responsible for almost 80% of database size -- Adding many attributes to [`filterableAttributes`](/learn/configuration/settings.md#filterable-attributes) also consumes a large amount of disk space +- Adding many attributes to [`filterableAttributes`](/reference/api/settings.md#filterable-attributes) also consumes a large amount of disk space - Multi-lingual datasets are costly, so split your dataset—one language per index - [Stop words](/reference/api/settings.md#stop-words) are essential to reducing database size - Not all attributes need to be [searchable](/learn/configuration/displayed_searchable_attributes.md#searchable-fields). Avoid indexing unique IDs.