Skip to main content
This guide walks you through enabling search rules, creating your first rule, and checking how it affects search results.

​
Prerequisites

  • A running Meilisearch instance
  • An admin API key
  • An index with documents. This guide uses a support index

​
Step 1: Enable search rules

Search rules are experimental. Enable them with PATCH /experimental-features: 
{
  "dynamicSearchRules": true
}
If the feature is disabled, the /dynamic-search-rules routes are not usable and saved rules do not apply at search time.

​
Step 2: Create a rule

Create a rule with PATCH /dynamic-search-rules/invoice-help: 
{
  "description": "Promote billing help for invoice searches",
  "active": true,
  "conditions": [
    { "scope": "query", "contains": "invoice" }
  ],
  "actions": [
    {
      "selector": { "indexUid": "support", "id": "billing-workspace-overview" },
      "action": { "type": "pin", "position": 0 }
    }
  ]
}
This route behaves as an upsert:
  • It returns 201 Created when the rule does not exist yet
  • It returns 200 OK when you update an existing rule

​
Step 3: Check the stored rule

Retrieve the rule with GET /dynamic-search-rules/invoice-help. The response should include the rule’s uid, conditions, and actions: 
{
  "uid": "invoice-help",
  "description": "Promote billing help for invoice searches",
  "active": true,
  "conditions": [
    { "scope": "query", "contains": "invoice" }
  ],
  "actions": [
    {
      "selector": { "indexUid": "support", "id": "billing-workspace-overview" },
      "action": { "type": "pin", "position": 0 }
    }
  ]
}
Send a normal search request to your index, for example with POST /indexes/support/search: 
{
  "q": "invoice settings"
}
If billing-workspace-overview exists and survives the current filters, Meilisearch inserts it at position 0. Search rules do not replace the rest of the result set. Meilisearch still computes the normal organic results, then inserts the pinned documents and removes duplicates.

​
Next steps

How to

Explore common query, empty-query, and time-window patterns

Reference

Review endpoints, rule fields, and update behavior

Advanced

Learn how search rules interact with ranking and filters

Experimental features

Learn more about experimental feature management