Create your first rule

This guide shows you how to turn search rules on and build your first rule: pin one document to the top of your search results.

Set up from the Meilisearch Cloud dashboard

Open your project in the Meilisearch Cloud dashboard and select the Search rules tab.

Turn on search rules

Click Enable Search Rules. Your project can now store rules and apply them at search time.

Meilisearch Cloud Search rules tab with an "Enable Search Rules" button in the add-on panel

Create a new rule

Click New rule to open the rule editor.

Fill in the general information

Field	What it does
Rule ID	The unique identifier of the rule. You cannot change it later without recreating the rule
Description	A free text note, so your team knows why the rule exists
Rank	Decides which rule wins when several rules match the same search. The lowest number wins
Active	Turns the rule on and off. Keep it on to apply the rule at search time

General block of the rule editor with the Rule ID, Description, Rank, and Active fields

Choose the action

The Actions block decides what the rule does to your results.

Add action dialog with the pin, boost, deboost, and hide options

Select Pin a document, click Next, then fill in the three fields:

Index: the index that holds the document you want to promote. The rule then applies only to searches on this index.
Document: the document itself, selected by its primary key. Meilisearch promotes this exact document and no other one, even if similar documents exist.
Position: the rank the document takes in the results, starting at 1 for the first result. It stays at this rank every time the rule matches, even when it does not match what the user typed.

Pin a document dialog with an index dropdown, a document selector, and a position input

Click Add action. The Actions block now lists your action, with the index it targets, the documents you selected, the filter you used, and how many documents it finally affects. A rule can hold several actions: click Add action again to add another one.

Actions block listing one pin action with its index, document, filter, and affected documents

Choose the conditions

The Conditions block decides when the rule runs. A search must match every condition for the rule to take effect. With the default values, the rule applies to all searches. For this first rule, set Query to Empty query and leave the other conditions as they are.

Conditions block with the Query list open on the "Empty query" option

Save the rule

The bar at the bottom of the editor recaps what your rule contains.

Editor footer with the general, condition, and action recap next to the Create rule button

Click Create rule. Your rule is now live: every time a user opens the search on your index without typing anything, the document you selected appears at the top of the results. All the other results remain organic.

Review and manage your rules

The Search rules tab lists every rule with its conditions, actions, rank, and last update. Search the list by rule ID or description, use the row toggle to pause a rule without deleting it, or the icons on the right to edit or remove it.

Search rules list with one rule showing its conditions, pin action, rank, last update, and active toggle

Rule changes are applied asynchronously, so a rule you just created, updated, or deleted can take a moment to appear in the list.

Set up on a self-hosted instance

Turn on search rules

curl \
  -X PATCH 'MEILISEARCH_URL/experimental-features/' \
  -H 'Authorization: Bearer API_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "dynamicSearchRules": true
  }'

Until search rules are turned on, the /dynamic-search-rules routes reject your requests and stored rules do not apply at search time.

Create a rule

curl \
  -X PATCH 'MEILISEARCH_URL/dynamic-search-rules/invoice-help' \
  -H 'Authorization: Bearer API_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "description": "Promote billing help for invoice searches",
    "precedence": 0,
    "active": true,
    "conditions": {
      "query": {
        "words": "invoice"
      }
    },
    "actions": {
      "pin": [
        {
          "indexUid": "support",
          "id": "billing-workspace-overview",
          "position": 0
        }
      ]
    }
  }'

This rule means: every time a user searches the support index with a query containing the word invoice, the document billing-workspace-overview appears at the first position of the results.

The rule identifier comes from the URL, here invoice-help. The body does not contain it.
precedence decides which rule wins when several rules match the same search. The lowest number wins.
conditions.query.words makes the rule run only when every word it contains appears in the query, in any order.
actions.pin.indexUid limits the rule to searches on the support index. Without it, the rule applies to any index that contains a document with this ID.
actions.pin.position counts from 0, so 0 is the first result. The dashboard displays the same slot as position 1.

Meilisearch answers with a summarized task containing a taskUid, because creating a rule is an asynchronous operation. The rule only applies to searches once this task reaches the succeeded status. To follow its progress, pass the taskUid to the task API. For the full list of conditions and actions a rule accepts, see the search rules API reference.

Check the stored rule

curl \
  -X GET 'MEILISEARCH_URL/dynamic-search-rules/invoice-help' \
  -H 'Authorization: Bearer API_KEY'

Meilisearch returns the rule as it stored it:

{
  "uid": "invoice-help",
  "description": "Promote billing help for invoice searches",
  "lastUpdatedAt": "2026-10-20T09:25:53.965008429Z",
  "precedence": 0,
  "active": true,
  "conditions": {
    "query": {
      "words": "invoice"
    }
  },
  "actions": {
    "pin": [
      {
        "indexUid": "support",
        "id": "billing-workspace-overview",
        "position": 0
      }
    ]
  }
}

If Meilisearch answers that the rule does not exist, the creation task is probably still in progress. Wait a few moments, then try again.

Run a search

curl \
  -X POST 'MEILISEARCH_URL/indexes/support/search' \
  -H 'Authorization: Bearer API_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{ "q": "invoice settings" }'

The document billing-workspace-overview comes back first, followed by your organic results. If the document does not exist, or if the search filters exclude it, Meilisearch drops the pin and returns the organic results only.

Next steps

Boost documents

Rank a selection of documents higher during a campaign

Hide documents

Remove documents from the results without reindexing

How search rules work

See how Meilisearch builds the final result set

API reference

Endpoints, rule fields, and update behavior

Capabilities

Full-text search

Hybrid and semantic search

Geo search

Agentic search

Multi-search

Filtering, sorting, and faceting

Personalization

Analytics

Security and tenant tokens

Search rules

Platform

Indexing

Set up from the Meilisearch Cloud dashboard

Turn on search rules

Create a new rule

Fill in the general information

Choose the action

Choose the conditions

Save the rule

Review and manage your rules

Set up on a self-hosted instance

Turn on search rules

Create a rule

Check the stored rule

Run a search

Next steps

Boost documents

Hide documents

How search rules work

API reference

​Set up from the Meilisearch Cloud dashboard

​Turn on search rules

​Create a new rule

​Fill in the general information

​Choose the action

​Choose the conditions

​Save the rule

​Review and manage your rules

​Set up on a self-hosted instance

​Turn on search rules

​Create a rule

​Check the stored rule

​Run a search

​Next steps

Boost documents

Hide documents

How search rules work

API reference

Set up from the Meilisearch Cloud dashboard

Turn on search rules

Create a new rule

Fill in the general information

Choose the action

Choose the conditions

Save the rule

Review and manage your rules

Set up on a self-hosted instance

Turn on search rules

Create a rule

Check the stored rule

Run a search

Next steps