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

# Promote results with rules

> Use rules to promote (pin) specific search results or display a banner at the top of your search results.

export const SearchQuery = () => <Tooltip tip="The text users enter into a search box. In the Search API, this corresponds to the query parameter. A search query is often used with filters, facets, and other parameters, but these aren't part of the query text itself.">
    search query
  </Tooltip>;

export const Records = () => <Tooltip tip="A record is a searchable object in an Algolia index. Each record consists of named attributes." cta="Algolia records" href="/doc/guides/sending-and-managing-data/prepare-your-data#algolia-records">
    records
  </Tooltip>;

export const Index = () => <Tooltip tip="An Algolia index is a searchable dataset that consists of records and configuration settings. These settings define how the records are searched and ranked.">
    index
  </Tooltip>;

export const Filter = () => <Tooltip tip="A filter is a condition that limits which records Algolia returns. Filters often use one or more facet-value pairs, such as brand:Apple AND color:red. You can also filter by numeric values, dates, tags, booleans, or geographic constraints." cta="Filtering" href="/doc/guides/managing-results/refine-results/faceting">
    filter
  </Tooltip>;

export const Application = () => <Tooltip tip="An Algolia application is a self-contained environment with its own indices, configuration, and API keys. Applications don't share data or settings with each other.">
    application
  </Tooltip>;

export const AlgoliaSearch = () => <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 80 80" width="20" height="20" className="inline" fill="none" role="presentation" ariaLabel="Algolia Search">
    <circle cx="40" cy="32" r="28" fill="#5468FF"></circle>
    <rect x="30" y="22" width="20" height="20" rx="10" fill="#fff"></rect>
    <path d="M43 63.5 54.5 60l6 17h-12L43 63.5Z" fill="#36395A"></path>
  </svg>;

To promote groups of results dynamically, see [Smart Groups](/doc/guides/managing-results/compositions/smart-groups).

<Note>
  If `typoTolerance` is `min` or `strict`,
  promoted results might not appear if they contain more typos than the top results.
</Note>

## Promote a single items

For example, a book store wants to recommend a Harry Potter box set whenever the words "Harry Potter" form part of a search.

### Rule

If the <SearchQuery /> is `Harry Potter`,
promote the Harry Potter box set.

<Note>
  By default, you can pin up to 300 <Records /> per rule.
</Note>

### With the API

To run the code examples on this page, [install the latest API client](/doc/libraries/sdk/install).

<CodeGroup>
  ```cs C# theme={"system"}
  var response = await client.SaveRuleAsync(
    "INDEX_NAME",
    "promote-harry-potter-box-set",
    new Rule
    {
      ObjectID = "promote-harry-potter-box-set",
      Conditions = new List<Condition>
      {
        new Condition { Pattern = "Harry Potter", Anchoring = Enum.Parse<Anchoring>("Contains") },
      },
      Consequence = new Consequence
      {
        Promote = new List<Promote>
        {
          new Promote(new PromoteObjectID { ObjectID = "HP-12345", Position = 0 }),
        },
      },
    }
  );
  ```

  ```dart Dart theme={"system"}
  final response = await client.saveRule(
    indexName: "INDEX_NAME",
    objectID: "promote-harry-potter-box-set",
    rule: Rule(
      objectID: "promote-harry-potter-box-set",
      conditions: [
        Condition(
          pattern: "Harry Potter",
          anchoring: Anchoring.fromJson("contains"),
        ),
      ],
      consequence: Consequence(
        promote: [
          PromoteObjectID(
            objectID: "HP-12345",
            position: 0,
          ),
        ],
      ),
    ),
  );
  ```

  ```go Go theme={"system"}
  response, err := client.SaveRule(client.NewApiSaveRuleRequest(
    "INDEX_NAME", "promote-harry-potter-box-set",
    search.NewEmptyRule().SetObjectID("promote-harry-potter-box-set").SetConditions(
      []search.Condition{*search.NewEmptyCondition().SetPattern("Harry Potter").SetAnchoring(search.Anchoring("contains"))}).SetConsequence(
      search.NewEmptyConsequence().SetPromote(
        []search.Promote{*search.PromoteObjectIDAsPromote(
          search.NewEmptyPromoteObjectID().SetObjectID("HP-12345").SetPosition(0))}))))
  if err != nil {
    // handle the eventual error
    panic(err)
  }
  ```

  ```java Java theme={"system"}
  UpdatedAtResponse response = client.saveRule(
    "INDEX_NAME",
    "promote-harry-potter-box-set",
    new Rule()
      .setObjectID("promote-harry-potter-box-set")
      .setConditions(Arrays.asList(new Condition().setPattern("Harry Potter").setAnchoring(Anchoring.CONTAINS)))
      .setConsequence(new Consequence().setPromote(Arrays.asList(new PromoteObjectID().setObjectID("HP-12345").setPosition(0))))
  );
  ```

  ```js JavaScript theme={"system"}
  const response = await client.saveRule({
    indexName: 'indexName',
    objectID: 'promote-harry-potter-box-set',
    rule: {
      objectID: 'promote-harry-potter-box-set',
      conditions: [{ pattern: 'Harry Potter', anchoring: 'contains' }],
      consequence: { promote: [{ objectID: 'HP-12345', position: 0 }] },
    },
  });
  ```

  ```kotlin Kotlin theme={"system"}
  var response =
    client.saveRule(
      indexName = "INDEX_NAME",
      objectID = "promote-harry-potter-box-set",
      rule =
        Rule(
          objectID = "promote-harry-potter-box-set",
          conditions =
            listOf(
              Condition(
                pattern = "Harry Potter",
                anchoring = Anchoring.entries.first { it.value == "contains" },
              )
            ),
          consequence =
            Consequence(promote = listOf(PromoteObjectID(objectID = "HP-12345", position = 0))),
        ),
    )
  ```

  ```php PHP theme={"system"}
  $response = $client->saveRule(
      'INDEX_NAME',
      'promote-harry-potter-box-set',
      ['objectID' => 'promote-harry-potter-box-set',
          'conditions' => [
              ['pattern' => 'Harry Potter',
                  'anchoring' => 'contains',
              ],
          ],
          'consequence' => ['promote' => [
              ['objectID' => 'HP-12345',
                  'position' => 0,
              ],
          ],
          ],
      ],
  );
  ```

  ```python Python theme={"system"}
  response = client.save_rule(
      index_name="INDEX_NAME",
      object_id="promote-harry-potter-box-set",
      rule={
          "objectID": "promote-harry-potter-box-set",
          "conditions": [
              {
                  "pattern": "Harry Potter",
                  "anchoring": "contains",
              },
          ],
          "consequence": {
              "promote": [
                  {
                      "objectID": "HP-12345",
                      "position": 0,
                  },
              ],
          },
      },
  )
  ```

  ```ruby Ruby theme={"system"}
  response = client.save_rule(
    "INDEX_NAME",
    "promote-harry-potter-box-set",
    Algolia::Search::Rule.new(
      algolia_object_id: "promote-harry-potter-box-set",
      conditions: [Algolia::Search::Condition.new(pattern: "Harry Potter", anchoring: "contains")],
      consequence: Algolia::Search::Consequence.new(
        promote: [Algolia::Search::PromoteObjectID.new(algolia_object_id: "HP-12345", position: 0)]
      )
    )
  )
  ```

  ```scala Scala theme={"system"}
  val response = Await.result(
    client.saveRule(
      indexName = "INDEX_NAME",
      objectID = "promote-harry-potter-box-set",
      rule = Rule(
        objectID = "promote-harry-potter-box-set",
        conditions = Some(
          Seq(
            Condition(
              pattern = Some("Harry Potter"),
              anchoring = Some(Anchoring.withName("contains"))
            )
          )
        ),
        consequence = Consequence(
          promote = Some(
            Seq(
              PromoteObjectID(
                objectID = "HP-12345",
                position = 0
              )
            )
          )
        )
      )
    ),
    Duration(100, "sec")
  )
  ```

  ```swift Swift theme={"system"}
  let response = try await client.saveRule(
      indexName: "INDEX_NAME",
      objectID: "promote-harry-potter-box-set",
      rule: Rule(
          objectID: "promote-harry-potter-box-set",
          conditions: [SearchCondition(pattern: "Harry Potter", anchoring: SearchAnchoring.contains)],
          consequence: SearchConsequence(promote: [SearchPromote.searchPromoteObjectID(SearchPromoteObjectID(
              objectID: "HP-12345",
              position: 0
          ))])
      )
  )
  ```
</CodeGroup>

### With the Visual Editor

1. Go to the [Algolia dashboard](https://dashboard.algolia.com/explorer/browse) and select your Algolia <Application />.

2. On the left sidebar, select <AlgoliaSearch /> **Search**.

3. Select your Algolia <Index />.

4. Select [**Rules**](https://dashboard.algolia.com/rules) from the left sidebar.

5. Select **Create your first Rule** or **New rule**.

6. Click **Visual Editor**.

7. Under **Conditions**:

   1. Click **Set query condition(s)**.
   2. In **Your search**, type `Harry Potter` and click **Apply**.

8. Under **Consequences**:

   1. Click **Pin items**.
   2. In **Pinned items**, find and select the item you want to promote (for example, `HP-12345`) and click **Apply**.

9. **Review and Publish** your rule.

### With the Manual Editor

1. Go to the [Algolia dashboard](https://dashboard.algolia.com/explorer/browse) and select your Algolia application.

2. On the left sidebar, select <AlgoliaSearch /> **Search**.

3. Select your Algolia index.

4. Select [**Rules**](https://dashboard.algolia.com/rules) from the left sidebar.

5. Select **Create your first Rule** or **New rule**.

6. Click **Manual Editor**.

7. In the **Condition(s)** section, enter `Harry Potter` in the **Query** field.

8. In the **Consequence(s)** section:

   1. Click **Add consequence** and select **Pin an item**.
   2. Find and select the item you want to promote. For example, `HP-12345`.

9. **Save** your rule.

## Promote the newest release

For example, you've placed "best-selling items" at the top of your search results by using [custom ranking](/doc/guides/managing-results/must-do/custom-ranking).
But the newest release?
Set up a rule that promotes the newest iPhone for searches containing `iPhone`,
while keeping other phones sorted by most-sold.

### Rule

If query is `iphone`,
promote the newest iPhone release.

{/* vale Google.Headings = NO  */}

### With the API

<CodeGroup>
  ```cs C# theme={"system"}
  var response = await client.SaveRuleAsync(
    "INDEX_NAME",
    "Promote-iPhone-X",
    new Rule
    {
      ObjectID = "Promote-iPhone-X",
      Conditions = new List<Condition>
      {
        new Condition { Pattern = "iPhone", Anchoring = Enum.Parse<Anchoring>("Contains") },
      },
      Consequence = new Consequence
      {
        Promote = new List<Promote>
        {
          new Promote(new PromoteObjectID { ObjectID = "iPhone-12345", Position = 0 }),
        },
      },
    }
  );
  ```

  ```dart Dart theme={"system"}
  final response = await client.saveRule(
    indexName: "INDEX_NAME",
    objectID: "Promote-iPhone-X",
    rule: Rule(
      objectID: "Promote-iPhone-X",
      conditions: [
        Condition(
          pattern: "iPhone",
          anchoring: Anchoring.fromJson("contains"),
        ),
      ],
      consequence: Consequence(
        promote: [
          PromoteObjectID(
            objectID: "iPhone-12345",
            position: 0,
          ),
        ],
      ),
    ),
  );
  ```

  ```go Go theme={"system"}
  response, err := client.SaveRule(client.NewApiSaveRuleRequest(
    "INDEX_NAME", "Promote-iPhone-X",
    search.NewEmptyRule().SetObjectID("Promote-iPhone-X").SetConditions(
      []search.Condition{*search.NewEmptyCondition().SetPattern("iPhone").SetAnchoring(search.Anchoring("contains"))}).SetConsequence(
      search.NewEmptyConsequence().SetPromote(
        []search.Promote{*search.PromoteObjectIDAsPromote(
          search.NewEmptyPromoteObjectID().SetObjectID("iPhone-12345").SetPosition(0))}))))
  if err != nil {
    // handle the eventual error
    panic(err)
  }
  ```

  ```java Java theme={"system"}
  UpdatedAtResponse response = client.saveRule(
    "INDEX_NAME",
    "Promote-iPhone-X",
    new Rule()
      .setObjectID("Promote-iPhone-X")
      .setConditions(Arrays.asList(new Condition().setPattern("iPhone").setAnchoring(Anchoring.CONTAINS)))
      .setConsequence(new Consequence().setPromote(Arrays.asList(new PromoteObjectID().setObjectID("iPhone-12345").setPosition(0))))
  );
  ```

  ```js JavaScript theme={"system"}
  const response = await client.saveRule({
    indexName: 'indexName',
    objectID: 'Promote-iPhone-X',
    rule: {
      objectID: 'Promote-iPhone-X',
      conditions: [{ pattern: 'iPhone', anchoring: 'contains' }],
      consequence: { promote: [{ objectID: 'iPhone-12345', position: 0 }] },
    },
  });
  ```

  ```kotlin Kotlin theme={"system"}
  var response =
    client.saveRule(
      indexName = "INDEX_NAME",
      objectID = "Promote-iPhone-X",
      rule =
        Rule(
          objectID = "Promote-iPhone-X",
          conditions =
            listOf(
              Condition(
                pattern = "iPhone",
                anchoring = Anchoring.entries.first { it.value == "contains" },
              )
            ),
          consequence =
            Consequence(
              promote = listOf(PromoteObjectID(objectID = "iPhone-12345", position = 0))
            ),
        ),
    )
  ```

  ```php PHP theme={"system"}
  $response = $client->saveRule(
      'INDEX_NAME',
      'Promote-iPhone-X',
      ['objectID' => 'Promote-iPhone-X',
          'conditions' => [
              ['pattern' => 'iPhone',
                  'anchoring' => 'contains',
              ],
          ],
          'consequence' => ['promote' => [
              ['objectID' => 'iPhone-12345',
                  'position' => 0,
              ],
          ],
          ],
      ],
  );
  ```

  ```python Python theme={"system"}
  response = client.save_rule(
      index_name="INDEX_NAME",
      object_id="Promote-iPhone-X",
      rule={
          "objectID": "Promote-iPhone-X",
          "conditions": [
              {
                  "pattern": "iPhone",
                  "anchoring": "contains",
              },
          ],
          "consequence": {
              "promote": [
                  {
                      "objectID": "iPhone-12345",
                      "position": 0,
                  },
              ],
          },
      },
  )
  ```

  ```ruby Ruby theme={"system"}
  response = client.save_rule(
    "INDEX_NAME",
    "Promote-iPhone-X",
    Algolia::Search::Rule.new(
      algolia_object_id: "Promote-iPhone-X",
      conditions: [Algolia::Search::Condition.new(pattern: "iPhone", anchoring: "contains")],
      consequence: Algolia::Search::Consequence.new(
        promote: [Algolia::Search::PromoteObjectID.new(algolia_object_id: "iPhone-12345", position: 0)]
      )
    )
  )
  ```

  ```scala Scala theme={"system"}
  val response = Await.result(
    client.saveRule(
      indexName = "INDEX_NAME",
      objectID = "Promote-iPhone-X",
      rule = Rule(
        objectID = "Promote-iPhone-X",
        conditions = Some(
          Seq(
            Condition(
              pattern = Some("iPhone"),
              anchoring = Some(Anchoring.withName("contains"))
            )
          )
        ),
        consequence = Consequence(
          promote = Some(
            Seq(
              PromoteObjectID(
                objectID = "iPhone-12345",
                position = 0
              )
            )
          )
        )
      )
    ),
    Duration(100, "sec")
  )
  ```

  ```swift Swift theme={"system"}
  let response = try await client.saveRule(
      indexName: "INDEX_NAME",
      objectID: "Promote-iPhone-X",
      rule: Rule(
          objectID: "Promote-iPhone-X",
          conditions: [SearchCondition(pattern: "iPhone", anchoring: SearchAnchoring.contains)],
          consequence: SearchConsequence(promote: [SearchPromote.searchPromoteObjectID(SearchPromoteObjectID(
              objectID: "iPhone-12345",
              position: 0
          ))])
      )
  )
  ```
</CodeGroup>

### With the Visual Editor

1. Go to the [Algolia dashboard](https://dashboard.algolia.com/explorer/browse) and select your Algolia application.
2. On the left sidebar, select <AlgoliaSearch /> **Search**.
3. Select your Algolia index.
4. Select [**Rules**](https://dashboard.algolia.com/rules) from the left sidebar.
5. Select **Create your first Rule** or **New rule**.
6. Click **Visual Editor**.
7. Under **Conditions**:
   1. Click **Set query condition(s)**.
   2. In **Your search**, type `iPhone` and click **Apply**.
8. Under **Consequences**:
   1. Click **Pin item**.
   2. In **Pinned items**, find and select the item you want to promote (for example, `iPhone-12345`) and then click **Apply**.
9. **Review and Publish** your rule.

### With the Manual Editor

1. Go to the [Algolia dashboard](https://dashboard.algolia.com/explorer/browse) and select your Algolia application.
2. On the left sidebar, select <AlgoliaSearch /> **Search**.
3. Select your Algolia index.
4. Select [**Rules**](https://dashboard.algolia.com/rules) from the left sidebar.
5. Select **Create your first Rule** or **New rule**.
6. Click **Manual Editor**.
7. In the **Condition(s)** section, enter `iPhone` in the **Query** field and change the drop-down from **Is** to **Contains**.
8. In the **Consequence(s)** section:
   1. Click **Add consequence** and select **Pin an item**.
   2. Find and select the item you want to promote (for example, `iPhone-12345`).
9. **Save** your rule.

## Promote several results

For example, you're running a promotion on the newest Apple products.
Set up a rule that promotes the newest Apple releases at the top of results for searches containing `apple`.

### Rule

If query is `apple`,
promote the newest Apple releases.

### With the API

<CodeGroup>
  ```cs C# theme={"system"}
  var response = await client.SaveRuleAsync(
    "INDEX_NAME",
    "Promote-Apple-Newest",
    new Rule
    {
      ObjectID = "Promote-Apple-Newest",
      Conditions = new List<Condition>
      {
        new Condition { Pattern = "apple", Anchoring = Enum.Parse<Anchoring>("Is") },
      },
      Consequence = new Consequence
      {
        Promote = new List<Promote>
        {
          new Promote(
            new PromoteObjectIDs
            {
              ObjectIDs = new List<string> { "iPhone-12345", "watch-123" },
              Position = 0,
            }
          ),
        },
      },
    }
  );
  ```

  ```dart Dart theme={"system"}
  final response = await client.saveRule(
    indexName: "INDEX_NAME",
    objectID: "Promote-Apple-Newest",
    rule: Rule(
      objectID: "Promote-Apple-Newest",
      conditions: [
        Condition(
          pattern: "apple",
          anchoring: Anchoring.fromJson("is"),
        ),
      ],
      consequence: Consequence(
        promote: [
          PromoteObjectIDs(
            objectIDs: [
              "iPhone-12345",
              "watch-123",
            ],
            position: 0,
          ),
        ],
      ),
    ),
  );
  ```

  ```go Go theme={"system"}
  response, err := client.SaveRule(client.NewApiSaveRuleRequest(
    "INDEX_NAME", "Promote-Apple-Newest",
    search.NewEmptyRule().SetObjectID("Promote-Apple-Newest").SetConditions(
      []search.Condition{*search.NewEmptyCondition().SetPattern("apple").SetAnchoring(search.Anchoring("is"))}).SetConsequence(
      search.NewEmptyConsequence().SetPromote(
        []search.Promote{*search.PromoteObjectIDsAsPromote(
          search.NewEmptyPromoteObjectIDs().SetObjectIDs(
            []string{"iPhone-12345", "watch-123"}).SetPosition(0))}))))
  if err != nil {
    // handle the eventual error
    panic(err)
  }
  ```

  ```java Java theme={"system"}
  UpdatedAtResponse response = client.saveRule(
    "INDEX_NAME",
    "Promote-Apple-Newest",
    new Rule()
      .setObjectID("Promote-Apple-Newest")
      .setConditions(Arrays.asList(new Condition().setPattern("apple").setAnchoring(Anchoring.IS)))
      .setConsequence(
        new Consequence().setPromote(
          Arrays.asList(new PromoteObjectIDs().setObjectIDs(Arrays.asList("iPhone-12345", "watch-123")).setPosition(0))
        )
      )
  );
  ```

  ```js JavaScript theme={"system"}
  const response = await client.saveRule({
    indexName: 'indexName',
    objectID: 'Promote-Apple-Newest',
    rule: {
      objectID: 'Promote-Apple-Newest',
      conditions: [{ pattern: 'apple', anchoring: 'is' }],
      consequence: { promote: [{ objectIDs: ['iPhone-12345', 'watch-123'], position: 0 }] },
    },
  });
  ```

  ```kotlin Kotlin theme={"system"}
  var response =
    client.saveRule(
      indexName = "INDEX_NAME",
      objectID = "Promote-Apple-Newest",
      rule =
        Rule(
          objectID = "Promote-Apple-Newest",
          conditions =
            listOf(
              Condition(
                pattern = "apple",
                anchoring = Anchoring.entries.first { it.value == "is" },
              )
            ),
          consequence =
            Consequence(
              promote =
                listOf(
                  PromoteObjectIDs(objectIDs = listOf("iPhone-12345", "watch-123"), position = 0)
                )
            ),
        ),
    )
  ```

  ```php PHP theme={"system"}
  $response = $client->saveRule(
      'INDEX_NAME',
      'Promote-Apple-Newest',
      ['objectID' => 'Promote-Apple-Newest',
          'conditions' => [
              ['pattern' => 'apple',
                  'anchoring' => 'is',
              ],
          ],
          'consequence' => ['promote' => [
              ['objectIDs' => [
                  'iPhone-12345',

                  'watch-123',
              ],
                  'position' => 0,
              ],
          ],
          ],
      ],
  );
  ```

  ```python Python theme={"system"}
  response = client.save_rule(
      index_name="INDEX_NAME",
      object_id="Promote-Apple-Newest",
      rule={
          "objectID": "Promote-Apple-Newest",
          "conditions": [
              {
                  "pattern": "apple",
                  "anchoring": "is",
              },
          ],
          "consequence": {
              "promote": [
                  {
                      "objectIDs": [
                          "iPhone-12345",
                          "watch-123",
                      ],
                      "position": 0,
                  },
              ],
          },
      },
  )
  ```

  ```ruby Ruby theme={"system"}
  response = client.save_rule(
    "INDEX_NAME",
    "Promote-Apple-Newest",
    Algolia::Search::Rule.new(
      algolia_object_id: "Promote-Apple-Newest",
      conditions: [Algolia::Search::Condition.new(pattern: "apple", anchoring: "is")],
      consequence: Algolia::Search::Consequence.new(
        promote: [Algolia::Search::PromoteObjectIDs.new(object_ids: ["iPhone-12345", "watch-123"], position: 0)]
      )
    )
  )
  ```

  ```scala Scala theme={"system"}
  val response = Await.result(
    client.saveRule(
      indexName = "INDEX_NAME",
      objectID = "Promote-Apple-Newest",
      rule = Rule(
        objectID = "Promote-Apple-Newest",
        conditions = Some(
          Seq(
            Condition(
              pattern = Some("apple"),
              anchoring = Some(Anchoring.withName("is"))
            )
          )
        ),
        consequence = Consequence(
          promote = Some(
            Seq(
              PromoteObjectIDs(
                objectIDs = Seq("iPhone-12345", "watch-123"),
                position = 0
              )
            )
          )
        )
      )
    ),
    Duration(100, "sec")
  )
  ```

  ```swift Swift theme={"system"}
  let response = try await client.saveRule(
      indexName: "INDEX_NAME",
      objectID: "Promote-Apple-Newest",
      rule: Rule(
          objectID: "Promote-Apple-Newest",
          conditions: [SearchCondition(pattern: "apple", anchoring: SearchAnchoring.`is`)],
          consequence: SearchConsequence(promote: [SearchPromote.searchPromoteObjectIDs(SearchPromoteObjectIDs(
              objectIDs: ["iPhone-12345", "watch-123"],
              position: 0
          ))])
      )
  )
  ```
</CodeGroup>

### With the Visual Editor

1. Go to the [Algolia dashboard](https://dashboard.algolia.com/explorer/browse) and select your Algolia application.
2. On the left sidebar, select <AlgoliaSearch /> **Search**.
3. Select your Algolia index.
4. Select [**Rules**](https://dashboard.algolia.com/rules) from the left sidebar.
5. Select **Create your first Rule** or **New rule**.
6. Click **Visual Editor**.
7. Under **Conditions**:
   1. Click **Set query condition(s)**.
   2. In **Your search**, type `apple` and click **Apply**.
8. Under **Consequences**:
   1. Click **Pin items**.
   2. Click **Pin multiple items**.
   3. One per line, enter the object IDs of the items you want to pin, for example, `iPhone-12345` and `watch-123`, in the input field and then click **Pin items**.
   4. Click **Apply**.
9. **Review and Publish** your rule.

<Note>
  You can't promote more than one item with the Manual Editor.
</Note>

## Promote results matching active filters

For example, you only want to promote items if they match a user's active <Filter />,
such as stock availability, color, or category.
This prevents irrelevant items such as out-of-stock products from appearing.

### Rule

Create a rule with a consequence that pins the item only if it matches active filters.

### With the API

To pin an item only if it matches active filters,
set [`filterPromotes`](/doc/rest-api/search/save-rule#body-consequence-filter-promotes) to `true` in the rule's consequence.

<CodeGroup>
  ```cs C# theme={"system"}
  namespace Algolia;

  using System;
  using System.Collections.Generic;
  using System.Net.Http;
  using System.Text.Json;
  using Algolia.Search.Clients;
  using Algolia.Search.Http;
  using Algolia.Search.Models.Search;

  class EnableFilterPromote
  {
    async Task Main(string[] args)
    {
      var condition = new Condition { Anchoring = Anchoring.Is, Pattern = "{facet:brand}" };

      var consequence = new Consequence { FilterPromotes = true };

      var rule = new Rule
      {
        ObjectID = "rule_with_filterPromotes",
        Conditions = [condition],
        Consequence = consequence,
      };
    }
  }

  ```

  ```dart Dart theme={"system"}
  import 'package:algolia_client_search/algolia_client_search.dart';

  void enableFilterPromote() async {
    final condition = Condition(
      pattern: "{facet:brand}",
      anchoring: Anchoring.is_,
    );

    final consequence = Consequence(filterPromotes: true);

    // ignore: unused_local_variable
    final rule = Rule(
        objectID: "rule_with_filterPromotes",
        conditions: [condition],
        consequence: consequence);
  }

  ```

  ```go Go theme={"system"}
  package main

  import (
  	"fmt"

  	"github.com/algolia/algoliasearch-client-go/v4/algolia/search"
  )

  func enableFilterPromote() {
  	condition := search.NewCondition().
  		SetPattern("{facet:brand}").
  		SetAnchoring(search.ANCHORING_IS)

  	rule := search.NewRule(
  		"rule_with_filterPromotes",
  		*search.NewConsequence().SetFilterPromotes(true),
  	).SetEnabled(true).SetConditions([]search.Condition{*condition})

  	fmt.Printf("Rule: %#v\n", rule)
  }

  ```

  ```java Java theme={"system"}
  package com.algolia;

  import com.algolia.config.*;
  import com.algolia.model.search.*;
  import java.util.List;

  public class enableFilterPromote {

    public static void main(String[] args) throws Exception {
      Condition condition = new Condition().setAnchoring(Anchoring.IS).setPattern("{facet:brand}");

      Consequence consequence = new Consequence().setFilterPromotes(true);

      Rule rule = new Rule().setObjectID("rule_with_filterPromotes").setConditions(List.of(condition)).setConsequence(consequence);
    }
  }

  ```

  ```js JavaScript theme={"system"}
  import type { Condition, Consequence } from 'algoliasearch';

  const condition: Condition = {
    anchoring: 'is',
    pattern: '{facet:brand}',
  };

  const consequence: Consequence = {
    filterPromotes: true,
  };

  ```

  ```kotlin Kotlin theme={"system"}
  import com.algolia.client.configuration.*
  import com.algolia.client.extensions.*
  import com.algolia.client.model.search.*
  import com.algolia.client.transport.*

  suspend fun enableFilterPromote() {
    val condition = Condition(pattern = "{facet:brand}", anchoring = Anchoring.Is)

    val consequence = Consequence(filterPromotes = true)

    val rule =
      Rule(
        objectID = "rule_with_filterPromotes",
        conditions = listOf(condition),
        consequence = consequence,
      )
  }

  ```

  ```php PHP theme={"system"}
  <?php

  require __DIR__.'/../vendor/autoload.php';

  use Algolia\AlgoliaSearch\Model\Search\Anchoring;
  use Algolia\AlgoliaSearch\Model\Search\Condition;
  use Algolia\AlgoliaSearch\Model\Search\Consequence;
  use Algolia\AlgoliaSearch\Model\Search\Rule;

  $condition = (new Condition())
      ->setAnchoring((new Anchoring())::IS)
      ->setPattern('{facet:brand}')
  ;

  $consequence = (new Consequence())
      ->setFilterPromotes(true)
  ;

  $rule = (new Rule())
      ->setObjectID('rule_with_filterPromotes')
      ->setConditions([$condition])
      ->setConsequence($consequence);

  ```

  ```python Python theme={"system"}
  from algoliasearch.search.models.anchoring import Anchoring
  from algoliasearch.search.models.condition import Condition
  from algoliasearch.search.models.consequence import Consequence
  from algoliasearch.search.models.rule import Rule


  condition = Condition(
      anchoring=Anchoring.IS,
      pattern="{facet:brand}",
  )

  consequence = Consequence(
      filter_promotes=True,
  )

  rule = Rule(
      enabled=True,
      object_id="rule_with_filterPromotes",
      conditions=[condition],
      consequence=consequence,
  )

  ```

  ```ruby Ruby theme={"system"}
  condition = Algolia::Search::Condition.new(
    anchoring: Algolia::Search::Anchoring::IS,
    pattern: "{facet:brand}"
  )

  consequence = Algolia::Search::Consequence.new(
    filter_promotes: true
  )

  rule = Algolia::Search::Rule.new(
    enabled: true,
    object_id: "rule_with_filterPromotes",
    conditions: [condition],
    consequence: consequence
  )

  ```

  ```scala Scala theme={"system"}
  import scala.concurrent.ExecutionContext.Implicits.global

  import algoliasearch.api.SearchClient
  import algoliasearch.config.*
  import algoliasearch.extension.SearchClientExtensions
  import algoliasearch.search.{Anchoring, Condition, Consequence, Rule}

  def enableFilterPromote(): Unit = {
    val condition = Condition(
      pattern = Some("{facet:brand}"),
      anchoring = Some(Anchoring.Is)
    )

    val consequence = Consequence(
      filterPromotes = Some(true)
    )

    val rule = Rule(
      objectID = "rule_with_filterPromotes",
      conditions = Some(Seq(condition)),
      consequence = consequence
    )
  }

  ```

  ```swift Swift theme={"system"}
  import Foundation
  #if os(Linux) // For linux interop
      import FoundationNetworking
  #endif

  import AlgoliaCore
  import AlgoliaSearch

  func enableFilterPromote() async throws {
      let condition = SearchCondition(
          pattern: "{facet:brand}",
          anchoring: .is
      )

      let consequence = SearchConsequence(
          filterPromotes: true
      )

      let rule = Rule(objectID: "rule_with_filterPromotes", conditions: [condition], consequence: consequence)
      print(rule)
  }

  ```
</CodeGroup>

### With the Visual Editor

1. Go to the [Algolia dashboard](https://dashboard.algolia.com/explorer/browse) and select your Algolia application.
2. On the left sidebar, select <AlgoliaSearch /> **Search**.
3. Select your Algolia index.
4. Select [**Rules**](https://dashboard.algolia.com/rules) from the left sidebar.
5. Select **Create your first Rule** or **New rule**.
6. Click **Visual Editor**.
7. Under **Conditions**:
   1. Click **Set query condition(s)**.
   2. In **Your search**, enter the item you want to promote (for example, `shoes`) and click **Apply**.
8. Under **Consequences**:
   1. Click **Pin items**.
   2. In **Pinned items**, find and select the item you want to promote.
   3. Keep the checkbox **Pinned items must match active filters to be displayed** selected and click **Apply**.
9. **Review and Publish** your rule.

### With the Manual Editor

1. Go to the [Algolia dashboard](https://dashboard.algolia.com/explorer/browse) and select your Algolia application.
2. On the left sidebar, select <AlgoliaSearch /> **Search**.
3. Select your Algolia index.
4. Select [**Rules**](https://dashboard.algolia.com/rules) from the left sidebar.
5. Select **Create your first Rule** or **New rule**.
6. Click **Manual Editor**.
7. In the **Condition(s)** section, enter the query (for example, `shoes`) in the **Query** field.
8. In the **Consequence(s)** section:
   1. Click **Add consequence** and select **Pin an item**.
   2. Find and select the item you want to promote (for example, `brogue-12345`).
9. In the **Additional settings** section, keep the checkbox **Pinned items must match active filters to be displayed** selected.
10. **Save** your rule.