From 2da21f73a380c1f46227cdc4d6ef5e8015532438 Mon Sep 17 00:00:00 2001 From: Tommy Melvin Date: Tue, 22 Dec 2020 19:26:53 -0500 Subject: [PATCH 1/2] Improved documentation for searchable attributes and attribute ranking --- guides/advanced_guides/field_properties.md | 44 +++++++++++++++++++--- guides/main_concepts/relevancy.md | 29 ++++---------- references/searchable_attributes.md | 3 +- 3 files changed, 48 insertions(+), 28 deletions(-) diff --git a/guides/advanced_guides/field_properties.md b/guides/advanced_guides/field_properties.md index 85ceeecee5..2fcb528bf4 100644 --- a/guides/advanced_guides/field_properties.md +++ b/guides/advanced_guides/field_properties.md @@ -1,16 +1,50 @@ # Field Properties -By default, every field in a document is **searchable** and **displayed**. These properties can be modified in the [settings](/references/settings.md). +By default, whenever a document is added to MeiliSearch, all new attributes found in it are automatically added to two lists: + +- **The [searchable attributes list](/guides/advanced_guides/field_properties.md#the-searchable-attributes-list)**: Attributes whose fields are searched for matching query words. +- **The [displayed attributes list](/guides/advanced_guides/field_properties.md#displayed-fields)**: Attributes whose fields are displayed in documents. + +This means that by default, every field in a document is **searchable** and **displayed**. These properties can be modified in the [settings](/references/settings.md). ## Searchable Fields -The **values** of the fields whose attributes are added to the [searchable-attributes list](/references/searchable_attributes.md) are **searched for matching query words**. +A field can either be **searchable** or **non-searchable**. + +When you perform a search, all searchable fields are searched for matching query words and used to assess document relevancy, while non-searchable fields are ignored entirely. **By default, all fields are searchable.** + +Non-searchable fields are most useful for internal information that's not relevant to the search experience, such as URLs, sales numbers, or ratings used exclusively for sorting results. + +::: tip +Even if you make a field non-searchable, it will remain on the server and can be made searchable again at a later time. +::: + +### The Searchable Attributes List + +MeiliSearch uses an ordered list to determine which attributes are searchable. The order in which attributes appear in this list also determines their [impact on relevancy](/guides/main_concepts/relevancy.md#attribute-ranking-order), from most impactful to least. + +In other words, the `searchableAttributes` list serves two purposes: + +1. It designates the fields that are searchable. +2. It dictates the [attribute ranking order](/guides/main_concepts/relevancy.md#attribute-ranking-order). + +There are two possible modes for the `searchableAttributes` list. + +#### Default: Automatic + +**By default, all attributes are automatically added to the `searchableAttributes` list in their order of appearance.** This means that the initial order will be based on the order of attributes in the first document indexed, with each new attribute found in subsequent documents added at the end of this list. + +This default behavior is indicated by a `searchableAttributes` value of `["*"]`. To verify the current value of your `searchableAttributes` list, use the [get searchable attributes endpoint](/references/searchable_attributes.md#get-searchable-attributes). + +If you'd like to restore your searchable attributes list to this default behavior, simply [set `searchableAttributes` to an empty array `[]`](/references/searchable_attributes.md#update-searchable-attributes) or use the [reset searchable attributes endpoint](/references/searchable_attributes.md#reset-searchable-attributes). -Their content is used by MeiliSearch to assess the relevancy of a document. +#### Manual -**By default, all field attributes are set as searchable**. +You may want to make some attributes non-searchable, or change the [attribute ranking order](/guides/main_concepts/relevancy.md#attribute-ranking-order) after documents have been indexed. To do so, simply place the attributes in the desired order and send the updated list using the [update searchable attributes endpoint](/references/searchable_attributes.md#update-searchable-attributes). -Therefore, if a field attribute is not in the searchable-attributes list, the field will be ignored from searches but will remain stored in the server. This list can be restricted to a selected set of attributes in the settings. +::: warning +Be aware that after manually updating the `searchableAttributes` list, subsequent new attributes will no longer be automatically added unless the settings are [reset](/references/searchable_attributes.md#reset-searchable-attributes). +::: #### Example diff --git a/guides/main_concepts/relevancy.md b/guides/main_concepts/relevancy.md index f46f4147d9..d3d2af9625 100644 --- a/guides/main_concepts/relevancy.md +++ b/guides/main_concepts/relevancy.md @@ -32,7 +32,7 @@ It is now mandatory that all query terms are present in the returned documents. Results are sorted by **increasing distance between matched query terms**: find documents that contain more query terms found close together (close proximity between two query terms) and appearing in the original order specified in the query string first. **4. Attribute** -Results are sorted according to **[the order of importance of the attributes](/guides/main_concepts/relevancy.md#importance-of-the-attributes)**: find documents that contain query terms in more important attributes first. +Results are sorted according to the **[attribute ranking order](/guides/main_concepts/relevancy.md#attribute-ranking-order)**: find documents that contain query terms in more important attributes first. **5. Words Position** Results are sorted by **the position of the query words in the attributes**: find documents that contain query terms earlier in their attributes first. @@ -75,7 +75,7 @@ The `proximity` rule sorts the results by increasing distance between matched qu `If It's Tuesday, This must be Belgium` is the first document because the matched word `Belgium`, is found in the `title` attribute and not the `description`. -The `attribute` rule sorts the results by [attribute importance](/guides/main_concepts/relevancy.md#importance-of-the-attributes). +The `attribute` rule sorts the results by [attribute importance](/guides/main_concepts/relevancy.md#attribute-ranking-order). ::: @@ -157,31 +157,18 @@ To add a rule to the existing ranking rule, you have to add the rule to the exis ] ``` -## Importance of the attributes +## Attribute Ranking Order -In a dataset, some fields are more relevant to the search than others. A `title`, for example, has a value more meaningful to a movie search than its `description` or its `director` name. +In a typical dataset, some fields are more relevant to search than others. A `title`, for example, has a value more meaningful to a movie search than its `description` or its `release_date`. -By default, the order of importance of the attributes is based on their order of appearance in the first document added. Then, each new attribute found in new documents will be added at the end of this ordered list. +By default, the attribute ranking order is generated automatically based on the attributes' order of appearance in the indexed documents. However, it can also be set manually. -If you wish to specify the order of the attributes you can either define them in the settings or set the correct order in the first document indexed. - -### Changing the order of the attributes - -You may want to change the order once the documents have been ingested. This is still very possible using the [searchable attributes list](/guides/advanced_guides/field_properties.md#searchable-fields). - -Whenever a document is added to MeiliSearch, all new attributes found in it are automatically added to two lists: - -- **The [searchable attributes list](/references/searchable_attributes.md)**: Attributes of the fields in which to search for matching query words. -- **The [displayed attributes list](/references/displayed_attributes.md)**: Attributes of the fields displayed in documents. - -This searchable attributes list is **ordered**, which means the order in which the attributes appear in the list determines their relevancy. Attributes are arranged from the most important attribute to the least important attribute. - -Place the attributes in the desired order and send this updated list using the [settings routes](/references/settings.md). Attributes will be re-ordered. +For a more detailed look at this subject, see our reference page for [the searchable attributes list](/guides/advanced_guides/field_properties.md#the-searchable-attributes-list). #### Example ```json -["title", "description", "director"] +["title", "description", "release_date"] ``` -If you take a look at the above order, the matching words found in `title` will make the document more relevant than one with the same matching words found in `description` or `director`. +With the above attribute ranking order, matching words found in the `title` field would have a higher impact on relevancy than the same words found in `description` or `release_date`. If you searched "1984", for example, results like Michael Radford's film "1984" would be ranked higher than movies released in the year 1984. diff --git a/references/searchable_attributes.md b/references/searchable_attributes.md index 08bfdfb3ce..202cf39bc7 100644 --- a/references/searchable_attributes.md +++ b/references/searchable_attributes.md @@ -2,8 +2,7 @@ _Child route of the [settings route](/references/settings.md)._ -The values of the fields whose attributes are added to the searchable-attributes list are **searched for matching query words**. -By default, all fields are considered to be `searchableAttributes`. This behavior is represented by the `["*"]` in the settings. Setting `searchableAttributes` to an empty array `[]` will reset the setting to its default value. +The values associated with attributes in the `searchableAttributes` list are **searched for matching query words**. The order of the list also determines the [attribute ranking order](/guides/main_concepts/relevancy.md#attribute-ranking-order). Searchable attributes can also be updated directly through the [global settings route](/references/settings.md#update-settings) along with the other settings. From ef59aea5768a9f9b5aacba67458b5f874a318408 Mon Sep 17 00:00:00 2001 From: Tommy <68053732+react-learner@users.noreply.github.com> Date: Wed, 6 Jan 2021 09:47:03 -0500 Subject: [PATCH 2/2] Update guides/advanced_guides/field_properties.md Co-authored-by: cvermand <33010418+bidoubiwa@users.noreply.github.com> --- guides/advanced_guides/field_properties.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/advanced_guides/field_properties.md b/guides/advanced_guides/field_properties.md index 2fcb528bf4..43a11e5361 100644 --- a/guides/advanced_guides/field_properties.md +++ b/guides/advanced_guides/field_properties.md @@ -16,7 +16,7 @@ When you perform a search, all searchable fields are searched for matching query Non-searchable fields are most useful for internal information that's not relevant to the search experience, such as URLs, sales numbers, or ratings used exclusively for sorting results. ::: tip -Even if you make a field non-searchable, it will remain on the server and can be made searchable again at a later time. +Even if you make a field non-searchable, it will remain stored in the database and can be made searchable again at a later time. ::: ### The Searchable Attributes List