Create your first rule

Turn on search rules and create a rule that pins a document to the top of your search results.

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.

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

Choose the action

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

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.

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.

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.

Save the rule

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

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.

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

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

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

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

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