Relevancy

    Relevancy refers to the accuracy and effectiveness of search results. If search results are almost always appropriate, then they can be considered relevant, and vice versa.

    Meilisearch has a number of features for fine-tuning the relevancy of search results. The most important tool among them is ranking rules.

    Ranking rules

    In order to ensure relevant results, search responses are sorted based on a set of consecutive rules called ranking rules.

    Behavior

    Each index possesses a list of ranking rules stored as an array in the settings object. This array is fully customizable, meaning you can delete existing rules, add new ones, and reorder them as needed.

    Meilisearch uses a bucket sort algorithm to rank documents whenever a search query is made. The first ranking rule applies to all documents, while each subsequent rule is only applied to documents considered equal under the previous rule as a tiebreaker.

    The order in which ranking rules are applied matters. The first rule in the array has the most impact, and the last rule has the least. Our default configuration meets most standard needs, but you can change it.

    Deleting a rule means that Meilisearch will no longer sort results based on that rule. For example, if you delete the typo ranking rule, documents with typos will still be considered during search, but they will no longer be sorted by increasing number of typos.

    Built-in rules

    Meilisearch contains six built-in ranking rules in the following order:

    [
      "words",
      "typo",
      "proximity",
      "attribute",
      "sort",
      "exactness"
    ]
    

    Depending on your needs, you might want to change this order. To do so, you can use the update settings endpoint or update ranking rules endpoint.

    1. Words

    Results are sorted by decreasing number of matched query terms. Returns documents that contain all query terms first.

    NOTE

    The words rule works from right to left. Therefore, the order of the query string impacts the order of results.

    For example, if someone were to search batman dark knight, the words rule would rank documents containing all three terms first, documents containing only batman and dark second, and documents containing only batman third.

    2. Typo

    Results are sorted by increasing number of typos. Returns documents that match query terms with fewer typos first.

    3. Proximity

    Results are sorted by increasing distance between matched query terms. Returns documents where query terms occur close together and in the same order as the query string first.

    It is possible to lower the precision of this ranking rule. This may significantly improve indexing performance. In a minority of use cases, lowering precision may also lead to lower search relevancy for queries using multiple search terms.

    4. Attribute

    Results are sorted according to the attribute ranking order. Returns documents that contain query terms in more important attributes first.

    Also, note the documents with attributes containing the query words at the beginning of the attribute will be considered more relevant than documents containing the query words at the end of the attributes.

    5. Sort

    Results are sorted according to parameters decided at query time. When the sort ranking rule is in a higher position, sorting is exhaustive: results will be less relevant but follow the user-defined sorting order more closely. When sort is in a lower position, sorting is relevant: results will be very relevant but might not always follow the order defined by the user.

    NOTE

    Differently from other ranking rules, sort is only active for queries containing the sort search parameter. If a search request does not contain sort, or if its value is invalid, this rule will be ignored.

    6. Exactness

    Results are sorted by the similarity of the matched words with the query words. Returns documents that contain exactly the same terms as the ones queried first.

    Examples

    Demonstrating the typo ranking rule by searching for 'vogli'

    Typo
    • vogli: 0 typo
    • volli: 1 typo

    The typo rule sorts the results by increasing number of typos on matched query words.

    Custom rules

    For now, Meilisearch supports two custom rules: one for ascending sort and one for descending sort.

    To add a custom ranking rule, you have to communicate the attribute name followed by a colon (:) and either asc for ascending order or desc for descending order.

    The attribute must have either a numeric or a string value in all of the documents contained in that index.

    You can add this rule to the existing list of ranking rules using the update settings endpoint or update ranking rules endpoint.

    Example

    Let's say you have a movie dataset. The documents contain the fields release_date with a timestamp as value, and movie_ranking, an integer that represents its ranking.

    The following example will create a rule that makes older movies more relevant than recent ones. A movie released in 1999 will appear before a movie released in 2020.

    release_date:asc
    

    The following example will create a rule that makes movies with a good rank more relevant than movies with a lower rank. Movies with a higher ranking will appear first.

    movie_ranking:desc
    

    To add a rule to the existing ranking rule, you have to add the rule to the existing ordered rules array using the settings route,

    [
      "words",
      "typo",
      "proximity",
      "attribute",
      "sort",
      "exactness",
      "release_date:asc",
      "movie_ranking:desc"
    ]
    

    Sorting and custom ranking rules

    Meilisearch allows users to define sorting order at query time by using the sort search parameter. There is some overlap between sorting and custom ranking rules, but the two do have different uses.

    In general, sort will be most useful when you want to allow users to define what type of results they want to see first. A good use-case for sort is creating a webshop interface where customers can sort products by descending or ascending product price.

    Custom ranking rules, instead, are always active once configured and will be useful when you want to promote certain types of results. A good use-case for custom ranking rules is ensuring discounted products in a webshop always feature among the top results.

    Promoting search results and document pinning

    Meilisearch does not offer native support for promoting, pinning, and boosting specific documents so they are displayed more prominently than other search results. Consult these Meilisearch blog articles for workarounds on implementing promoted search results with React InstantSearch and document boosting.

    Ranking score

    When using the showRankingScore search parameter, Meilisearch adds a global ranking score field, _rankingScore, to each document. The _rankingScore is between 0.0 and 1.0. The higher the ranking score, the more relevant the document.

    Ranking rules sort documents either by relevancy (words, typo, proximity, exactness, attribute) or by the value of a field (sort). Since sort doesn't rank documents by relevancy, it does not influence the _rankingScore.

    NOTE

    A document's ranking score does not change based on the scores of other documents in the same index.

    For example, if a document A has a score of 0.5 for a query term, this value remains constant no matter the score of documents B, C, or D.```

    The table below details all the index settings that can influence the _rankingScore. Unlisted settings do not influence the ranking score.

    Index settingInfluences ifRationale
    searchableAttributesThe attribute ranking rule is usedThe attribute ranking rule rates the document depending on the attribute in which the query terms show up. The order is determined by searchableAttributes
    rankingRulesAlwaysThe score is computed by computing the subscore of each ranking rule with a weight that depends on their order
    stopWordsAlwaysStop words influence the words ranking rule, which is almost always used
    synonymsAlwaysSynonyms influence the words ranking rule, which is almost always used
    typoToleranceThe typo ranking rule is usedUsed to compute the maximum number of typos for a query

    Attribute ranking order

    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 overview or its release_date.

    By default, the attribute ranking order is generated automatically based on the order in which Meilisearch encounters attributes in the indexed documents. In other words, if your first indexed document looks like this:

    {
      "a": "some data",
      "b": "more data",
      "c": "other data"
    }
    

    The automatically generated attribute ranking order will be ["a", "b", "c"]. If you then add a second document that looks like this:

    {
      "c": "other data",
      "d": "surprise data!",
      "a": "some data",
      "b": "more data"
    }
    

    The attribute ranking order will be updated to ["a", "b", "c", "d"]. In other words, when Meilisearch encounters new attributes in subsequently indexed documents, they are added to the bottom of the attribute ranking order.

    The attribute ranking order can also be set manually. For a more detailed look at this subject, see the searchable attributes list.

    Example

    [
      "title",
      "overview",
      "release_date"
    ]
    

    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 overview 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.

    NOTE

    The attribute rule's position in rankingRules determines how the results are sorted. Meaning, if attribute is at the bottom of the ranking rules list, it will have almost no impact on your search results.