> ## Documentation Index
> Fetch the complete documentation index at: https://www.meilisearch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 on Search Rules 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](https://cloud.meilisearch.com) 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](https://mintcdn.com/meilisearch-6b28dec2/pjgozmedxQwKwpe_/assets/images/cloud-search-rules/enable-search-rules.png?fit=max\&auto=format\&n=pjgozmedxQwKwpe_\&q=85\&s=5fe6bb03d617687f0e5bd671efaeaa65)

### Open the visual editor

Click **New rule**.

![Search rules list with a "New rule" button above the table of rules](https://mintcdn.com/meilisearch-6b28dec2/mjti93v8MIChJpXx/assets/images/cloud-search-rules/new-rule-button.png?fit=max\&auto=format\&n=mjti93v8MIChJpXx\&q=85\&s=789c664b922120047e8303aa887e921a)

The visual editor opens. You build the rule on your real documents:

* On the left, a preview of your search results. Choose the index and type a search, as your users would.
* On the right, the **Your rule** panel. It shows which searches trigger the rule and what the rule changes.

![Visual editor with the index selector, the search bar, the result cards, and the "Your rule" panel](https://mintcdn.com/meilisearch-6b28dec2/mjti93v8MIChJpXx/assets/images/cloud-search-rules/visual-editor.png?fit=max\&auto=format\&n=mjti93v8MIChJpXx\&q=85\&s=c5de3435d4471d8847e091dc349e7b0f)

> [!NOTE]
>
> The visual editor requires Meilisearch v1.55 or newer. On older versions, **New rule** opens the manual editor. To use the manual editor on a newer version, click **Switch to manual editor**.

### Choose which searches trigger the rule

In the **Which searches** section, choose when the rule runs:

* **These words**: the search must contain every word you enter, in any order. Other words are allowed.
* **Anything**: the rule runs on every search, whatever the user types.
* **Nothing**: the rule runs only when the search box is empty.

For this first rule, select **These words**, then type `foundation` in the search bar. The search words in the panel follow the search bar, so the preview always shows the results your rule changes. To enter different words in the panel, click the link icon in the search words field to unlink it.

To limit the rule to filtered searches, click **Add filter**. The rule then runs only when users filter the results by all of these values. Leave the filters empty for this first rule.

### Pin a document

Hover a result card to show its icons: pin, boost, deboost, and hide.

![Result card with the pin, boost, deboost, and hide icons in its top-right corner](https://mintcdn.com/meilisearch-6b28dec2/mjti93v8MIChJpXx/assets/images/cloud-search-rules/card-actions.png?fit=max\&auto=format\&n=mjti93v8MIChJpXx\&q=85\&s=61e944b04037255c9ac3c9bf81b6efed)

You can pin a document in two ways:

* Drag its card onto another card. The document takes that position.
* Click its pin icon. The document keeps its current position.

Drag the document you want to promote onto the first card. It moves to position 1 and shows a filled pin. The message **Your rule applies to these results** confirms that your rule changes this search. To compare, switch between **Without rule** and **With rule**.

![Visual editor with a pinned document at position 1, the "Your rule applies to these results" message, and the pin listed in the "What changes" section](https://mintcdn.com/meilisearch-6b28dec2/mjti93v8MIChJpXx/assets/images/cloud-search-rules/pinned-document.png?fit=max\&auto=format\&n=mjti93v8MIChJpXx\&q=85\&s=0b518a6296a000aad6e304fcbb866a14)

Meilisearch pins this exact document, using its primary key. It does not pin documents that look similar. The document stays at this position every time the rule matches, even when it does not match what the user typed. The rule applies only to searches on the index you chose.

### Save the rule

The **Your rule** panel now lists the pin in the **What changes** section. In **When it runs**, keep **Always**. To run the rule during a campaign, select **Between dates** instead.

![Your rule panel with the search words, the pin in "What changes", the "Always" schedule, and the "Save rule" button](https://mintcdn.com/meilisearch-6b28dec2/mjti93v8MIChJpXx/assets/images/cloud-search-rules/rule-panel.png?fit=max\&auto=format\&n=mjti93v8MIChJpXx\&q=85\&s=9a96f21baae6364a42495dc75bf1c51c)

Click **Save rule**. The **Review and save** dialog shows what the rule does. Fill in the fields:

| Field | What it does |
| - | - |
| **Name** | The unique identifier of the rule. You cannot change it after you save the rule |
| **Note for your team** | Optional free text, so your team knows why the rule exists |
| **Rank** | Decides which rule wins when several rules match the same search. The lowest number wins |
| **Status** | **Active** applies the rule as soon as you save it. **Inactive** saves the rule without applying it |

![Review and save dialog with the rule summary, and the Name, Note for your team, Rank, and Status fields](https://mintcdn.com/meilisearch-6b28dec2/mjti93v8MIChJpXx/assets/images/cloud-search-rules/review-and-save.png?fit=max\&auto=format\&n=mjti93v8MIChJpXx\&q=85\&s=bf9e934542def09c70e509a8792be72d)

Click **Save and activate**.

Your rule is now live: every time a user searches for `foundation` on your index, the document you pinned appears first. 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. Editing a rule opens it in the visual editor.

![Search rules list with the new rule, its query condition, pin action, rank, last update, and active toggle](https://mintcdn.com/meilisearch-6b28dec2/mjti93v8MIChJpXx/assets/images/cloud-search-rules/rules-list.png?fit=max\&auto=format\&n=mjti93v8MIChJpXx\&q=85\&s=76500eb54a0fa3f91d141a456f0ecae5)

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

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

Until you turn on Search Rules, the `/dynamic-search-rules` routes reject your requests and stored rules do not apply at search time.

### Create a rule

```bash cURL theme={null}
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](https://www.meilisearch.com/docs/capabilities/indexing/tasks_and_batches/async_operations.md). The rule only applies to searches once this task reaches the `succeeded` status. To follow its progress, pass the `taskUid` to the [task API](https://www.meilisearch.com/docs/reference/api/tasks/get-task.md).

For the full list of conditions and actions a rule accepts, see the [Search Rules API reference](https://www.meilisearch.com/docs/reference/api/search-rules/create-or-update-a-search-rule.md).

### Check the stored rule

```bash cURL theme={null}
curl \
  -X GET 'MEILISEARCH_URL/dynamic-search-rules/invoice-help' \
  -H 'Authorization: Bearer API_KEY'
```

Meilisearch returns the rule as it stored it:

```json theme={null}
{
  "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

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

```bash CLI theme={null}
meili search \
  --project-url MEILISEARCH_URL --project-api-key API_KEY \
  --index support --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

> [card] [Boost documents](https://www.meilisearch.com/docs/capabilities/search_rules/how_to/boost_documents.md)
>
> Rank a selection of documents higher during a campaign

> [card] [Hide documents](https://www.meilisearch.com/docs/capabilities/search_rules/how_to/hide_documents.md)
>
> Remove documents from the results without reindexing

> [card] [How Search Rules work](https://www.meilisearch.com/docs/capabilities/search_rules/advanced/how_search_rules_work.md)
>
> See how Meilisearch builds the final result set

> [card] [API reference](https://www.meilisearch.com/docs/reference/api/search-rules/create-or-update-a-search-rule.md)
>
> Endpoints, rule fields, and update behavior


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.