Skip to main content
Search rules are easiest to reason about as a curation layer that runs alongside normal search. This page covers the behavior that matters most when you build production workflows around them.

​
Pinning does not change ranking

In the current implementation, pinning does not rewrite your ranking rules or assign artificial scores to pinned documents. Meilisearch still computes organic results first, then inserts the surviving pinned documents at their requested positions. This behavior is specific to pinning. Other action types, such as boosting or burying, would affect ranking differently, but search rules do not support those actions today. Organic ranking still decides the order of every non-pinned hit.

​
Pinned documents do not need to match the query text

A pinned document can appear even if it is not a lexical match for the full query. As long as the rule matches, the document exists, and it survives filters, Meilisearch can insert it into the result list. This is often what you want for help centers, promotions, and landing pages.

​
Filters still apply

Pinned documents do not bypass filters. If the current search filters exclude a pinned document, Meilisearch drops it instead of forcing it into the response. Use this behavior to keep search rules compatible with visibility restrictions, safety controls, and authenticated content.

​
Matching behavior of contains

The query condition contains is a strict substring match. Describe it as a case-insensitive literal substring match, not as fuzzy, semantic, or pattern-aware matching. For example, contains: "call history" matches where is call history, but it should not be described as matching history of calls. Search rules do not currently support regex, wildcards, or numeric-pattern matching such as “any 6-digit code”.

​
Precedence between rules

Use priority to control which rule wins when several matching rules compete. Lower numeric values take precedence over higher ones. If you omit priority, treat the rule as having the lowest precedence.

​
Result-set behavior

Search rules preserve normal response behavior:
  • A document should not appear twice if it is both organic and pinned
  • Pagination remains coherent
  • Facet distribution stays consistent with the final surviving result set
  • Search rules work in regular search, hybrid search, federated search, and network search

​
Current scope

Search rules are currently instance-level rules. They are not stored as per-index settings. Selectors can optionally include indexUid when you need to target a document in a specific index.

​
Current limitations

Search rules do not currently support:
  • Activation from request filters
  • Activation from selected facets
  • Activation from locale, user context, or page context
  • Actions other than pinning
This makes the current feature well suited to curated pinning, but not to full personalization or broader contextual merchandising.