diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml
index 6095601cf..c8e0e228d 100644
--- a/.code-samples.meilisearch.yaml
+++ b/.code-samples.meilisearch.yaml
@@ -160,8 +160,9 @@ update_settings_1: |-
"words",
"typo",
"proximity",
- "attribute",
+ "attributeRank",
"sort",
+ "attributePosition",
"exactness",
"release_date:desc",
"rank:desc"
@@ -268,8 +269,9 @@ update_ranking_rules_1: |-
"words",
"typo",
"proximity",
- "attribute",
+ "attributeRank",
"sort",
+ "attributePosition",
"exactness",
"release_date:asc",
"rank:desc"
@@ -1060,7 +1062,8 @@ sorting_guide_update_ranking_rules_1: |-
"sort",
"typo",
"proximity",
- "attribute",
+ "attributeRank",
+ "attributePosition",
"exactness"
]'
sorting_guide_sort_nested_1: |-
diff --git a/assets/open-api/meilisearch-openapi-mintlify.json b/assets/open-api/meilisearch-openapi-mintlify.json
index 89051f2c4..f26b0f373 100644
--- a/assets/open-api/meilisearch-openapi-mintlify.json
+++ b/assets/open-api/meilisearch-openapi-mintlify.json
@@ -17534,10 +17534,18 @@
},
{
"type": "string",
- "description": "Documents with quey words contained in more important\nattributes are considered better.",
- "enum": [
- "Attribute"
- ]
+ "description": "Documents with query words contained in more important\nattributes are considered better.",
+ "enum": ["AttributeRank"]
+ },
+ {
+ "type": "string",
+ "description": "Documents with query words at the beginning of an attribute\nare considered better.",
+ "enum": ["AttributePosition"]
+ },
+ {
+ "type": "string",
+ "description": "Legacy rule combining AttributeRank and AttributePosition.\nDocuments with query words contained in more important\nattributes are considered better.",
+ "enum": ["Attribute"]
},
{
"type": "string",
diff --git a/guides/relevancy/interpreting_ranking_scores.mdx b/guides/relevancy/interpreting_ranking_scores.mdx
index 8aec35cc7..98a76cba5 100644
--- a/guides/relevancy/interpreting_ranking_scores.mdx
+++ b/guides/relevancy/interpreting_ranking_scores.mdx
@@ -96,7 +96,7 @@ Let's see how moving Sort **one position** in your ranking rules changes which r
We’ve set up our ranking rules to have sort after our Group 1 wide net rules.
```json
-["words", "typo", "proximity", "sort", "attribute", "exactness"]
+["words", "typo", "proximity", "sort", "attributeRank", "attributePosition", "exactness"]
```
With this set up Meilisearch evaluates the text relevance rules first, *then* uses Sort.
@@ -196,7 +196,7 @@ Also notice: Sort shows a `value` instead of a `score`. That's because Sort does
Now let's move `sort` to the top of our ranking rules:
```json
-["sort", "words", "typo", "proximity", "attribute", "exactness"]
+["sort", "words", "typo", "proximity", "attributeRank", "attributePosition", "exactness"]
```
### 🥇 Result #1 — Chicken Stew with Curry Spices and Vegetables
diff --git a/guides/relevancy/ordering_ranking_rules.mdx b/guides/relevancy/ordering_ranking_rules.mdx
index 53e9b6822..a0726a735 100644
--- a/guides/relevancy/ordering_ranking_rules.mdx
+++ b/guides/relevancy/ordering_ranking_rules.mdx
@@ -37,12 +37,13 @@ This covers things like:
**These three rules cast a wide net and return lots of results.** That's good—you want to start broad and then narrow down, not the other way around. If you start too narrow you can lose relevancy easily.
-**Group 2 - Fine-tuning : Exactness, Attribute (included in ranking score)**
+**Group 2 - Fine-tuning : Exactness, Attribute Rank, Attribute Position (included in ranking score)**
This covers things like:
- **Exactness**: Did the document match your whole search term or just pieces of it? Whole matches rank higher, especially when an entire field matches exactly or starts with your query. Documents containing extra content beyond the search term are ranked lower.
-- **Attribute**: Matches in your most important fields rank higher, and matches near the beginning of a field rank higher. You set field priority in `searchableAttributes`, with fields at the top of the list treated as the most important.
+- **Attribute Rank**: Matches in your most important fields rank higher. You set field priority in `searchableAttributes`, with fields at the top of the list treated as the most important.
+- **Attribute Position**: Matches near the beginning of a field rank higher.
**These are your fine-tuning filters.** They return fewer, more precise results. Use these after Group 1 rules to refine your large result set into something more precise.
@@ -75,8 +76,9 @@ Ranking rules:
"words",
"typo",
"proximity",
- "attribute",
+ "attributeRank",
"sort", // "price:asc" "author:desc" gets swapped in here
+ "attributePosition",
"exactness",
"release_date:asc",
"movie_ranking:desc"
@@ -99,7 +101,7 @@ These three rules cast a wide net and pass a large pool of relevant results thro
### Place Sort strategically
-We recommend putting Sort after your Group 1 rules and before your Group 2 rules (Attribute, Exactness). This way, Meilisearch finds relevant results first and then uses your sort field to order documents that have similar text relevance, giving you a balance of match quality and sorting.
+We recommend putting Sort after your Group 1 rules and before your Group 2 rules (Attribute Rank, Attribute Position, Exactness). This way, Meilisearch finds relevant results first and then uses your sort field to order documents that have similar text relevance, giving you a balance of match quality and sorting.
If sorting matters more than text relevance for your use case - like an e-commerce price filter where users expect strict price ordering - move Sort higher. Just remember that Sort only activates when you include the `sort` parameter in your search query. Without it, the Sort rule has no effect.
@@ -114,7 +116,7 @@ Place custom ranking rules at the end of your sequence. They work best for addin
Each ranking rule has its own settings you can fine-tune beyond just ordering. For example, you can adjust which fields take priority in attribute ranking, or configure how aggressively typo tolerance matches similar words. If you want to dig into the specifics:
- [Built-in ranking rules](https://www.meilisearch.com/docs/learn/relevancy/ranking_rules#list-of-built-in-ranking-rules) — how each rule works and what it evaluates
-- [Attribute ranking order](https://www.meilisearch.com/docs/learn/relevancy/attribute_ranking_order) — controlling which fields matter most
+- [Attribute ranking order](https://www.meilisearch.com/docs/learn/relevancy/attribute_ranking_order) — controlling which fields matter most with `attributeRank` and `attributePosition`
- [Typo tolerance settings](https://www.meilisearch.com/docs/learn/relevancy/typo_tolerance_settings) — adjusting how flexible matching behaves
**Want to see these rules in action?** In our next guide, [How Do I Interpret Ranking Score Details?](/guides/relevancy/interpreting_ranking_scores), we walk through a real example showing exactly how Meilisearch evaluates each rule — and how moving Sort one position can flip your results.
diff --git a/learn/filtering_and_sorting/sort_search_results.mdx b/learn/filtering_and_sorting/sort_search_results.mdx
index 724e3e304..c992c9c60 100644
--- a/learn/filtering_and_sorting/sort_search_results.mdx
+++ b/learn/filtering_and_sorting/sort_search_results.mdx
@@ -83,8 +83,9 @@ This is the default configuration of Meilisearch's ranking rules:
"words",
"typo",
"proximity",
- "attribute",
+ "attributeRank",
"sort",
+ "attributePosition",
"exactness"
]
```
diff --git a/learn/relevancy/attribute_ranking_order.mdx b/learn/relevancy/attribute_ranking_order.mdx
index d71d1e5ed..c309408bd 100644
--- a/learn/relevancy/attribute_ranking_order.mdx
+++ b/learn/relevancy/attribute_ranking_order.mdx
@@ -38,5 +38,7 @@ By default, nested fields share the same weight as their parent attribute. Use d
With the above ranking order, `review.critic` becomes more important than its sibling `review.user` when calculating a document's ranking score.
-The `attribute` rule's position in [`rankingRules`](/learn/relevancy/ranking_rules) 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.**
+The `attributeRank` and `attributePosition` rules' positions in [`rankingRules`](/learn/relevancy/ranking_rules) determine how the results are sorted. Meaning, **if `attributeRank` is at the bottom of the ranking rules list, it will have almost no impact on your search results.**
+
+The legacy `attribute` rule combines both `attributeRank` and `attributePosition`. If you use `attribute`, its position determines the impact of both attribute ranking order and position within attributes.
diff --git a/learn/relevancy/custom_ranking_rules.mdx b/learn/relevancy/custom_ranking_rules.mdx
index 29cab65b2..67579caf1 100644
--- a/learn/relevancy/custom_ranking_rules.mdx
+++ b/learn/relevancy/custom_ranking_rules.mdx
@@ -51,8 +51,9 @@ The following array includes all built-in ranking rules and places the custom ru
"words",
"typo",
"proximity",
- "attribute",
+ "attributeRank",
"sort",
+ "attributePosition",
"exactness",
"release_date:asc",
"movie_ranking:desc"
diff --git a/learn/relevancy/ranking_rules.mdx b/learn/relevancy/ranking_rules.mdx
index 5dc782f5a..843755470 100644
--- a/learn/relevancy/ranking_rules.mdx
+++ b/learn/relevancy/ranking_rules.mdx
@@ -10,15 +10,16 @@ Built-in ranking rules are the core of Meilisearch's relevancy calculations.
## List of built-in ranking rules
-Meilisearch contains six built-in ranking rules in the following order:
+Meilisearch contains seven built-in ranking rules in the following order:
```json
[
"words",
"typo",
"proximity",
- "attribute",
+ "attributeRank",
"sort",
+ "attributePosition",
"exactness"
]
```
@@ -47,13 +48,29 @@ Results are sorted by **increasing distance between matched query terms**. Retur
[It is possible to lower the precision of this ranking rule.](/reference/api/settings#proximity-precision) 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
+## 4. Attribute rank
Results are sorted according to the **[attribute ranking order](/learn/relevancy/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.
+This ranking rule ignores the position of the matched words within the attribute.
-## 5. Sort
+## 5. Attribute position
+
+Results are sorted by the **position of query terms within the attributes**. Returns documents that contain query terms closer to the beginning of an attribute first.
+
+This ranking rule ignores the attribute ranking order.
+
+## Attribute
+
+`attribute` is an older built-in ranking rule equivalent to using both `attributeRank` and `attributePosition` together. When you use `attribute`, Meilisearch first sorts results by the attribute ranking order, then uses the position within attributes as a tiebreaker.
+
+
+You cannot use `attribute` together with `attributeRank` or `attributePosition`. If you try to configure ranking rules with both, Meilisearch will return an error. We recommend using a combination of the `attributeRank` and `attributePosition` rules.
+
+
+For most use-cases, we recommend using `attributeRank` and `attributePosition` separately. This gives you more control over result ordering by allowing you to place other ranking rules (like `sort` or custom ranking rules) between them.
+
+## 6. 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.
@@ -61,7 +78,7 @@ Results are sorted **according to parameters decided at query time**. When the `
Differently from other ranking rules, sort is only active for queries containing the [`sort` search parameter](/reference/api/search#sort). If a search request does not contain `sort`, or if its value is invalid, this rule will be ignored.
-## 6. Exactness
+## 7. 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.
@@ -95,16 +112,16 @@ The reason why `Creature` is listed before `Mississippi Grind` is because of the
The `proximity` rule sorts the results by increasing distance between matched query terms.
-
+
- 
+
-### Attribute
+### Attribute rank
`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 `overview`.
-The `attribute` rule sorts the results by [attribute importance](/learn/relevancy/attribute_ranking_order).
+The `attributeRank` rule sorts the results by [attribute importance](/learn/relevancy/attribute_ranking_order).
diff --git a/learn/relevancy/ranking_score.mdx b/learn/relevancy/ranking_score.mdx
index 87541bbf3..5796fd51d 100644
--- a/learn/relevancy/ranking_score.mdx
+++ b/learn/relevancy/ranking_score.mdx
@@ -6,7 +6,7 @@ description: This article explains how the order of attributes in the `searchabl
When using the [`showRankingScore` search parameter](/reference/api/search#ranking-score), 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`.
+Ranking rules sort documents either by relevancy (`words`, `typo`, `proximity`, `exactness`, `attributeRank`, `attributePosition`) or by the value of a field (`sort`). Since `sort` doesn't rank documents by relevancy, it does not influence the `_rankingScore`.
A document's ranking score does not change based on the scores of other documents in the same index.
@@ -16,10 +16,11 @@ For example, if a document A has a score of `0.5` for a query term, this value r
The table below details all the index settings that can influence the `_rankingScore`. **Unlisted settings do not influence the ranking score.**
-| Index setting | Influences if | Rationale |
-| :--------------------- | :----------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `searchableAttributes` | The `attribute` ranking rule is used | The `attribute` ranking rule rates the document depending on the attribute in which the query terms show up. The order is determined by `searchableAttributes` |
-| `rankingRules` | Always | The score is computed by computing the subscore of each ranking rule with a weight that depends on their order |
-| `stopWords` | Always | Stop words influence the `words` ranking rule, which is almost always used |
-| `synonyms` | Always | Synonyms influence the `words` ranking rule, which is almost always used |
-| `typoTolerance` | The `typo` ranking rule is used | Used to compute the maximum number of typos for a query |
+| Index setting | Influences if | Rationale |
+| :--------------------- | :--------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `searchableAttributes` | The `attributeRank` ranking rule is used | The `attributeRank` ranking rule rates the document depending on the attribute in which the query terms show up. The order is determined by `searchableAttributes` |
+| `searchableAttributes` | The `attributePosition` ranking rule is used | The `attributePosition` ranking rule rates the document based on the position of query terms within attributes |
+| `rankingRules` | Always | The score is computed by computing the subscore of each ranking rule with a weight that depends on their order |
+| `stopWords` | Always | Stop words influence the `words` ranking rule, which is almost always used |
+| `synonyms` | Always | Synonyms influence the `words` ranking rule, which is almost always used |
+| `typoTolerance` | The `typo` ranking rule is used | Used to compute the maximum number of typos for a query |
diff --git a/learn/resources/telemetry.mdx b/learn/resources/telemetry.mdx
index e2e707ae1..87154bce0 100644
--- a/learn/resources/telemetry.mdx
+++ b/learn/resources/telemetry.mdx
@@ -167,6 +167,8 @@ This list is liable to change with every new version of Meilisearch. It's not be
| `ranking_rules.typo_position` | Position of the `typo` ranking rule if any, otherwise `null` | 2
| `ranking_rules.proximity_position` | Position of the `proximity` ranking rule if any, otherwise `null` | 3
| `ranking_rules.attribute_position` | Position of the `attribute` ranking rule if any, otherwise `null` | 4
+| `ranking_rules.attribute_rank_position` | Position of the `attributeRank` ranking rule if any, otherwise `null` | 4
+| `ranking_rules.attribute_position_position` | Position of the `attributePosition` ranking rule if any, otherwise `null` | 6
| `ranking_rules.sort_position` | Position of the `sort` ranking rule | 5
| `ranking_rules.exactness_position` | Position of the `exactness` ranking rule if any, otherwise `null` | 6
| `ranking_rules.values` | A string representing the ranking rules without the custom asc-desc rules | "words, typo, attribute, sort, exactness"
diff --git a/reference/api/settings.mdx b/reference/api/settings.mdx
index 150528a3a..4374a4bc1 100644
--- a/reference/api/settings.mdx
+++ b/reference/api/settings.mdx
@@ -100,8 +100,9 @@ By default, the settings object looks like this. All fields are modifiable.
"words",
"typo",
"proximity",
- "attribute",
+ "attributeRank",
"sort",
+ "attributePosition",
"exactness"
],
"stopWords": [],
@@ -238,7 +239,7 @@ If the provided index does not exist, it will be created.
| **[`proximityPrecision`](#proximity-precision)** | String | `"byWord"` | Precision level when calculating the proximity ranking rule |
| **[`facetSearch`](#facet-search)** | Boolean | `true` | Enable or disable [facet search](/reference/api/facet_search) functionality |
| **[`prefixSearch`](#prefix-search)** | String | `"indexingTime"` | When Meilisearch should return results only matching the beginning of query |
-| **[`rankingRules`](#ranking-rules)** | Array of strings | `["words",`
`"typo",`
`"proximity",`
`"attribute",`
`"sort",`
`"exactness"]` | List of ranking rules in order of importance |
+| **[`rankingRules`](#ranking-rules)** | Array of strings | `["words",`
`"typo",`
`"proximity",`
`"attributeRank",`
`"sort",`
`"attributePosition",`
`"exactness"]` | List of ranking rules in order of importance |
| **[`searchableAttributes`](#searchable-attributes)** | Array of strings | All attributes: `["*"]` | Fields in which to search for matching query words sorted by order of importance |
| **[`searchCutoffMs`](#search-cutoff)** | Integer | `null`, or 1500ms | Maximum duration of a search query |
| **[`separatorTokens`](#separator-tokens)** | Array of strings | Empty | List of characters delimiting where one term begins and ends |
@@ -1467,14 +1468,16 @@ Ranking rules are built-in rules that rank search results according to certain c
### Ranking rules array
-| Name | Description |
-| :---------------- | :------------------------------------------------------------------------------ |
-| **`"words"`** | Sorts results by decreasing number of matched query terms |
-| **`"typo"`** | Sorts results by increasing number of typos |
-| **`"proximity"`** | Sorts results by increasing distance between matched query terms |
-| **`"attribute"`** | Sorts results based on the attribute ranking order |
-| **`"sort"`** | Sorts results based on parameters decided at query time |
-| **`"exactness"`** | Sorts results based on the similarity of the matched words with the query words |
+| Name | Description |
+| :----------------------- | :------------------------------------------------------------------------------ |
+| **`"words"`** | Sorts results by decreasing number of matched query terms |
+| **`"typo"`** | Sorts results by increasing number of typos |
+| **`"proximity"`** | Sorts results by increasing distance between matched query terms |
+| **`"attributeRank"`** | Sorts results by the attribute rank of the query terms within attributes |
+| **`"attributePosition"`**| Sorts results by the position of query terms within attributes |
+| **`"attribute"`** | Legacy rule combining `attributeRank` and `attributePosition` |
+| **`"sort"`** | Sorts results based on parameters decided at query time |
+| **`"exactness"`** | Sorts results based on the similarity of the matched words with the query words |
#### Default order
@@ -1483,8 +1486,9 @@ Ranking rules are built-in rules that rank search results according to certain c
"words",
"typo",
"proximity",
- "attribute",
+ "attributeRank",
"sort",
+ "attributePosition",
"exactness"
]
```
@@ -1512,8 +1516,9 @@ Get the ranking rules of an index.
"words",
"typo",
"proximity",
- "attribute",
+ "attributeRank",
"sort",
+ "attributePosition",
"exactness",
"release_date:desc"
]
@@ -1548,6 +1553,8 @@ To create a custom ranking rule, give an attribute followed by a colon (`:`) and
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`.
+
+You cannot use the `attribute` ranking rule together with `attributeRank` or `attributePosition`. If you try to configure ranking rules with both, Meilisearch will return an error. We recommend using a combination of the `attributeRank` and `attributePosition` rules.
[To learn more about ranking rules, refer to our dedicated guide.](/learn/relevancy/ranking_rules)
diff --git a/snippets/generated-code-samples/code_samples_compact_index_1.mdx b/snippets/generated-code-samples/code_samples_compact_index_1.mdx
index 976bfbc32..29a9dd481 100644
--- a/snippets/generated-code-samples/code_samples_compact_index_1.mdx
+++ b/snippets/generated-code-samples/code_samples_compact_index_1.mdx
@@ -9,6 +9,10 @@ curl \
client.index('movies').compact()
```
+```php PHP
+$client->index('movies')->compact();
+```
+
```java Java
client.index("INDEX_NAME").compact();
```
diff --git a/snippets/generated-code-samples/code_samples_sorting_guide_update_ranking_rules_1.mdx b/snippets/generated-code-samples/code_samples_sorting_guide_update_ranking_rules_1.mdx
index bf942ce3b..6ae29a642 100644
--- a/snippets/generated-code-samples/code_samples_sorting_guide_update_ranking_rules_1.mdx
+++ b/snippets/generated-code-samples/code_samples_sorting_guide_update_ranking_rules_1.mdx
@@ -9,7 +9,8 @@ curl \
"sort",
"typo",
"proximity",
- "attribute",
+ "attributeRank",
+ "attributePosition",
"exactness"
]'
```
diff --git a/snippets/generated-code-samples/code_samples_update_ranking_rules_1.mdx b/snippets/generated-code-samples/code_samples_update_ranking_rules_1.mdx
index a104e9aac..82078086b 100644
--- a/snippets/generated-code-samples/code_samples_update_ranking_rules_1.mdx
+++ b/snippets/generated-code-samples/code_samples_update_ranking_rules_1.mdx
@@ -8,8 +8,9 @@ curl \
"words",
"typo",
"proximity",
- "attribute",
+ "attributeRank",
"sort",
+ "attributePosition",
"exactness",
"release_date:asc",
"rank:desc"
diff --git a/snippets/generated-code-samples/code_samples_update_settings_1.mdx b/snippets/generated-code-samples/code_samples_update_settings_1.mdx
index 57c219eb5..b06017371 100644
--- a/snippets/generated-code-samples/code_samples_update_settings_1.mdx
+++ b/snippets/generated-code-samples/code_samples_update_settings_1.mdx
@@ -9,8 +9,9 @@ curl \
"words",
"typo",
"proximity",
- "attribute",
+ "attributeRank",
"sort",
+ "attributePosition",
"exactness",
"release_date:desc",
"rank:desc"