Guides / Managing results / Rules / Merchandising

Promote results with rules

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

To promote groups of results dynamically, see Smart Groups.

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

Promote a single item

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 query is Harry Potter, promote the Harry Potter box set.

By default, you can pin up to 300 items per rule.

With the API

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
var response = await client.SaveRuleAsync(
  "ALGOLIA_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 }),
      },
    },
  }
);

With the Visual Editor

  1. Go to the Algolia dashboard and select your Algolia application.
  2. On the left sidebar, select Algolia Search Search.
  3. Select your Algolia index:

    Select your Algolia application and index

  4. Select 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 and select your Algolia application.
  2. On the left sidebar, select Algolia Search Search.
  3. Select your Algolia index:

    Select your Algolia application and index

  4. Select 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. 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.

With the API

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
var response = await client.SaveRuleAsync(
  "ALGOLIA_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 }),
      },
    },
  }
);

With the Visual Editor

  1. Go to the Algolia dashboard and select your Algolia application.
  2. On the left sidebar, select Algolia Search Search.
  3. Select your Algolia index:

    Select your Algolia application and index

  4. Select 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 and select your Algolia application.
  2. On the left sidebar, select Algolia Search Search.
  3. Select your Algolia index:

    Select your Algolia application and index

  4. Select 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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
var response = await client.SaveRuleAsync(
  "ALGOLIA_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,
          }
        ),
      },
    },
  }
);

With the Visual Editor

  1. Go to the Algolia dashboard and select your Algolia application.
  2. On the left sidebar, select Algolia Search Search.
  3. Select your Algolia index:

    Select your Algolia application and index

  4. Select 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.

You can’t promote more than one item with the Manual Editor.

Promote results matching active filters

For example, you only want to promote items if they match the user’s active filters, 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

Set filterPromotes to true in the rule consequence. The following example pins an item at position 0 and ensures it only appears if it matches active filters.

1
2
3
4
5
6
7
8
9
10
11
12
{
  "objectID": "pin-with-filters",
  "conditions": [
    { "anchoring": "is", "pattern": "{facet:brand}" }
  ],
  "consequence": {
    "filterPromotes": true,
    "promote": [
      { "objectID": "SKU-123", "position": 0 }
    ]
  }
}

For code samples in all supported languages, see the filterPromotes API reference.

With the Visual Editor

  1. Go to the Algolia dashboard and select your Algolia application.
  2. On the left sidebar, select Algolia Search Search.
  3. Select your Algolia index:

    Select your Algolia application and index

  4. Select 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. Select the Search icon on your dashboard and then select your index.
  2. Select the Rules section from the left sidebar menu in the Algolia dashboard.
  3. Select Create your first Rule or New rule.
  4. Click Manual Editor.
  5. In the Condition(s) section, enter the query (for example, shoes) in the Query field.
  6. 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).
  7. In the Additional settings section, keep the checkbox Pinned items must match active filters to be displayed selected.
  8. Save your rule.
Did you find this page helpful?