Getting started with search rules

Enable search rules, create your first rule, and verify how pinned results appear in search.

This guide walks you through enabling the experimental flag, creating your first rule, and checking how it affects search results. You can do this from the Meilisearch Cloud dashboard or directly against the API.

Set up from the Meilisearch Cloud dashboard

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

Activate the feature

Search rules are an add-on. On the Search rules tab, click Enable Search Rules to turn on the dynamicSearchRules experimental flag for the project.

Create your first rule

Once the feature is active, the Search rules tab shows a short explainer and a New rule button. Click it to start building a rule.

Fill in the rule’s general information

Give the rule a Rule ID (used as the uid), an optional Description, and a Priority if several rules might match the same query. Keep the Active toggle on to apply the rule at search time.

Add conditions

In the Conditions block, click Add condition to open the condition dialog. Pick a type (Query contains, Query is empty, or Time window) and fill in the value. Every condition you add is combined with AND, so the rule fires only when all conditions are true at the same time.

Pin documents to fixed positions

In the Actions block, click Add pin. Choose the source Index, pick the Document to promote, and set its target Position in the result list. Repeat for each document you want to pin. When the rule is ready, click Create rule.

Review and manage your rules

Back on the Search rules tab, every rule you have created is listed with its conditions, actions, priority, and active state. Use the row toggle to pause a rule without deleting it, or the icons on the right to edit or remove it.

Set up from the API

Prefer the API? The same flow maps directly to the /dynamic-search-rules routes.

Enable the experimental flag

Send a PATCH /experimental-features to turn on the feature:

{
  "dynamicSearchRules": true
}

While the flag is disabled, the /dynamic-search-rules routes reject requests and saved rules do not apply at search time.

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 rule pins the document billing-workspace-overview in the support index to the first position whenever a query contains the substring invoice.

The 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

Check the stored rule

Retrieve the rule you just created with GET /dynamic-search-rules/invoice-help. The response should include the uid, conditions, and actions you sent:

{
  "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 }
    }
  ]
}

Run a matching search

Send a normal search request to the index, for example POST /indexes/support/search:

{
  "q": "invoice settings"
}

If billing-workspace-overview exists in the support index and survives the current filters, Meilisearch inserts it at position 0. The rest of the response is the normal organic result set, with duplicates removed.

Search rules do not replace organic results. Meilisearch still computes them, then inserts the pinned documents on top.

Next steps

Pin one result for a query

Promote a landing page or help article for a query

Advanced

Learn how search rules interact with ranking and filters

API reference

Review endpoints and request fields

Experimental features

Learn more about experimental feature management