Guides / Managing results / Rules / Merchandising and promoting items

Dec. 18, 2020

Promoting Hits

Promoting a single item

Use Case

A book store wants to recommend a Harry Potter Box Set whenever the words Harry Potter form part of a search.

Rule

If query=Harry Potter then promote Harry Potter Box Set

Using the API

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// Turn JSON into an array
$rule = array(
  'objectID' => 'promote-harry-potter-box-set',
  'conditions' => array(array(
    'pattern' => 'Harry Potter',
    'anchoring' => 'contains'
  )),
  'consequence' => array(
    'promote' => array(
       array(
          'objectID' => 'HP-12345',
          'position'=> 0 // objectID 'HP-12345' ==> Harry Potter Box Set
       )
    )
  )
);

// Push Rule to index
$index->saveRule($rule);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
rule = {
    objectID: 'promote-harry-potter-box-set',
    conditions: [{
      pattern: 'Harry Potter',
      anchoring: 'contains'
    }],
    consequence: {
      promote: [{
        objectID: 'HP-12345',
        position: 0 # objectID 'HP-12345' ==> Harry Potter Box Set
      }]
    }
  }

  index.save_rule('promote-harry-potter-box-set', rule)

1
2
3
4
5
6
7
8
9
10
11
12
13
index.saveRule({
  objectID: 'promote-harry-potter-box-set',
  condition: {
    pattern: 'Harry Potter',
    anchoring: 'contains',
  },
  consequence: {
    promote: [{
        objectID: 'HP-12345',
        position: 0 // objectID 'HP-12345' ==> Harry Potter Box Set
      }]
  },
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
rule = {
    "objectID": "promote-harry-potter-box-set",
    "condition": {
        "anchoring": "contains",
        "pattern": "Harry Potter",
    },
    "consequence": {
        "promote": [
            {
                "objectID": "HP-12345",
                "position": 0,
            },
        ],
    },
}

response = index.save_rule(rule)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
let rule = Rule(objectID: "promote-harry-potter-box-set")
  .set(\.conditions, to: [
    Rule.Condition()
      .set(\.anchoring, to: .contains)
      .set(\.pattern, to: .literal("Harry Potter"))
  ])
  .set(\.consequence, to: Rule.Consequence()
    .set(\.promote, to: [
      // objectID 'HP-12345' ==> Harry Potter Box Set
      .init(objectID: "HP-12345", position: 0)
    ])
  )
index.saveRule(rule) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
var rule = new Rule
{
  ObjectID = "Promote Harry Potter Box Set",
  Condition = new Condition { Anchoring = "contains", Pattern = "Harry Potter" },
  Consequence = new Consequence
  {
    Promote = new List<ConsequencePromote>
    {
      new ConsequencePromote
      {
        ObjectID = "HP-12345",
        Position = 0
      }
    }
  }
};

index.SaveRule(rule);

// Asynchronous
await index.SaveRuleAsync(rule);

1
2
3
4
5
6
7
8
9
10
11
Condition condition = new Condition().setPattern("Harry Potter").setAnchoring("contains");
ConsequencePromote promote = new ConsequencePromote().setObjectID("HP-12345").setPosition(0);
Consequence consequence = new Consequence().setPromote(Collections.singletonList(promote));

Rule rule =
    new Rule()
        .setObjectID("Promote Harry Potter Box Set")
        .setConditions(Collections.singletonList(condition))
        .setConsequence(consequence);

index.saveRule(rule);

1
2
3
4
5
6
7
8
9
10
11
rule := search.Rule{
	ObjectID:  "promote-harry-potter-box-set",
	Condition: search.RuleCondition{Anchoring: search.Contains, Pattern: "Harry Potter"},
	Consequence: search.RuleConsequence{
		Promote: []search.PromotedObject{
			{"HP-12345", 0}, // objectID 'HP-12345' ==> Harry Potter Box Set
		},
	},
}

res, err := index.SaveRule(rule, false)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
val rule = Rule(
  objectID = "promote-harry-potter-box-set",
  condition = Some(
    Condition(
      pattern = "Harry Potter",
      anchoring = "contains"
    )
  ),
  consequence = Consequence(
    promote = Some(Seq(ConsequencePromote("HP-12345", 0)))
  )
)

client.execute {
  save rule rule inIndex "indexName"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
val rules = rules {
    rule(
        objectID = "Promote Harry Potter Box Set",
        conditions = conditions {
            condition(anchoring = Anchoring.Contains, pattern = Pattern.Literal("Harry Potter"))
        },
        consequence = consequence(
            promote = promotions {
                +ObjectID("HP-12345")(0)
            }
        )
    )
}

index.saveRules(rules)

Using the dashboard

Visual Editor

Select the Rules section from the left sidebar menu in the Algolia dashboard.
Under the heading Rules, select the index you are adding a Rule to.
Select Create your first rule or New rule. In the dropdown, click on the Visual Editor option.
In the It all starts here section:
- Click Set search query button.
- In the sidepanel, type “Harry Potter” in the input field and click Save.
In the What do you want to do? section:
- Click the Pin item button.
- In the sidepanel, find the product ‘HP-12345’ you want to pin in the input field and press Save.
Don’t forget to review and publish your changes.

Manual Editor

Select the Rules section from the left sidebar menu in the Algolia dashboard.
Under the heading Rules, select the index you are adding a Rule to.
Select Create your first rule or New rule. In the dropdown, click on the Manual Editor option.
In the Condition(s) section, keep Query contains and enter “Harry Potter” in the input field.
In the Consequence(s) section:
- Click the Add consequence button and select Pin an item.
- Find the product ‘HP-12345’ you want to pin the input field and press Enter.
Don’t forget to save your changes.

Promoting the newest release

Use Case

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 telling the engine that whenever iPhone is searched for, place the newest version at the top, but for the rest of the same brand phones, continue sorting by most-sold.

Rule

If query = iphone then promote newest iphone release

Using the API

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// Turn JSON into an array
$rule = array(
  'objectID' => 'Promote-iPhone-X',
  'conditions' => array(array(
    'pattern' => 'iPhone',
    'anchoring' => 'contains'
  )),
  'consequence' => array(
    'promote' => array(
      array(
        'objectID' => 'iPhone-12345',
        'position' => 0 // objectID 'iPhone-12345' ==> iPhone X (newest release)
      )
    )
  )
);

// Push Rule to index
$index->saveRule($rule);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
index.save_rule('Promote-iPhone-X', {
  objectID: 'Promote-iPhone-X',
  conditions: [{
    pattern: 'iPhone',
    anchoring: 'contains',
  }],
  consequence: {
    promote: [
      {
        objectID: 'iPhone-12345',
        # objectID 'iPhone-12345' ==> iPhone X (newest release)
        position: 0
      }
    ]
  }
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
index.saveRule({
  objectID: 'Promote-iPhone-X',
  condition: {
    pattern: 'iPhone',
    anchoring: 'contains',
  },
  consequence: {
    promote: [
      {
        objectID: 'iPhone-12345',
        // objectID 'iPhone-12345' ==> iPhone X (newest release)
        position: 0,
      },
    ],
  },
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
rule = {
    "objectID": "Promote-iPhone-X",
    "condition": {
        "anchoring": "contains",
        "pattern": "iPhone",
    },
    "consequence": {
        "promote": [
            {
                "objectID": "iPhone-12345",
                # objectID 'iPhone-12345' ==> iPhone X (newest release)
                "position": 0,
            },
        ],
    },
}

response = index.save_rule(rule)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
let rule = Rule(objectID: "Promote-iPhone-X")
  .set(\.conditions, to: [
    Rule.Condition()
      .set(\.anchoring, to: .contains)
      .set(\.pattern, to: .literal("iPhone"))
  ])
  .set(\.consequence, to: Rule.Consequence()
    .set(\.promote, to: [
       // objectID 'iPhone-12345' ==> iPhone X (newest release)
      .init(objectID: "iPhone-12345", position: 0)
    ])
  )

index.saveRule(rule) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
var rule = new Rule
{
    ObjectID = "Promote-iPhone-X",
    Conditions = new List<Condition> {
        new Condition { Anchoring = "contains", Pattern = "iPhone" }
    },
    Consequence = new Consequence
    {
        Promote = new List<ConsequencePromote>
        {
            new ConsequencePromote
            {
                ObjectID = "iPhone-12345",
                // objectID 'iPhone-12345' ==> iPhone X (newest release)
                Position = 0
            }
        }
    }
};

index.SaveRule(rule);

// Asynchronous
await index.SaveRuleAsync(rule);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
Condition condition = new Condition()
    .setAnchoring("contains")
    .setPattern("iPhone");

ConsequencePromote promote = new ConsequencePromote()
    .setObjectID("iPhone-12345")
    // objectID 'iPhone-12345' ==> iPhone X (newest release)
    .setPosition(0);

Consequence consequence = new Consequence()
    .setPromote(Collections.singletonList(promote));

Rule rule = new Rule()
        .setObjectID("Promote-iPhone-X")
        .setConditions(Collections.singletonList(condition))
        .setConsequence(consequence);

index.saveRule(rule);

// Asynchronous
index.saveRuleAsync(rule);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
rule := search.Rule{
  ObjectID:  "Promote-iPhone-X",
  Condition: search.RuleCondition{Anchoring: search.Contains, Pattern: "iPhone"},
  Consequence: search.RuleConsequence{
    Promote: []search.PromotedObject{
      {
        ObjectID: "iPhone-12345",
        Position: 0, // objectID 'iPhone-12345' ==> iPhone X (newest release)
      },
    },
  },
}

res, err := index.SaveRule(rule)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
val rule = Rule(
  objectID = "Promote-iPhone-X",
  condition = Some(
    Condition(
      pattern = "iPhone",
      anchoring = "contains"
    )
  ),
  consequence = Consequence(
    promote = Some(Seq(ConsequencePromote("iPhone-12345", 0)))
    // objectID 'iPhone-12345' ==> iPhone X (newest release)
  )
)

client.execute {
  save rule rule inIndex "indexName"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
val rules = rules {
    rule(
        objectID = "Promote-iPhone-X",
        conditions = conditions {
            condition(anchoring = Anchoring.Contains, pattern = Pattern.Literal("iPhone"))
        },
        consequence = consequence(
            promote = promotions {
                // objectID 'iPhone-12345' ==> iPhone X (newest release)
                +ObjectID("iPhone-12345")(0)
            }
        )
    )
}

index.saveRules(rules)

Using the dashboard

Visual Editor

Select the Rules section from the left sidebar menu in the Algolia dashboard.
Under the heading Rules, select the index you are adding a Rule to.
Select Create your first rule or New rule. In the dropdown, click on the Visual Editor option.
In the It all starts here section:
- Click Set search query button.
- In the sidepanel, type “iPhone” in the input field and click Save.
In the What do you want to do? section:
- Click the Pin item button.
- In the sidepanel, find the product “iPhone-12345” you want to pin in the input field and press Save.
Don’t forget to review and publish your changes.

Manual Editor

Select the Rules section from the left sidebar menu in the Algolia dashboard.
Under the heading Rules, select the index you are adding a Rule to.
Select Create your first rule or New rule. In the dropdown, click on the Manual Editor option.
In the Condition(s) section, keep Query toggled on, select Contains in the dropdown, and enter “iPhone” in the input field.
In the Consequence(s) section:
- Click the Add consequence button and select Pin an item.
- Find the product “iPhone-12345” you want to pin the input field and press Enter.
Don’t forget to save your changes.

Promoting some results over others

Note: This only applies to Premium plans.

Use Case

Tomato: A simple search, but one that may never return the fruit (or vegetable) because too many Tomato Soup brands are selling better than cherry tomatoes.

Rule

If query=tomato then put fruits higher than the rest

Using the API

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Turn JSON into an array
$rule = array(
    'objectID' => 'tomato-fruit',
    'conditions' => array(array(
        'pattern' => 'tomato',
        'anchoring' => 'contains'
    )),
    'consequence' => array(
        'params' => array(
            'optionalFilters' => 'food_group:fruit'
        )
    )
);
// Push Rule to index
$index->saveRule($rule);

1
2
3
4
5
6
7
8
9
10
11
12
index.save_rule('tomato-fruit', {
      objectID: 'tomato-fruit',
      conditions: [{
          pattern: 'tomato',
          anchoring: 'contains'
      }],
      consequence: {
          params: {
              optionalFilters: 'food_group:fruit'
          }
      }
  })

1
2
3
4
5
6
7
8
9
10
index.saveRule({
  objectID: 'tomato-fruit',
  condition: {
    pattern: 'tomato',
    anchoring: 'contains',
  },
  consequence: {
    optionalFilters: 'food_group:fruit',
  },
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
rule = {
    "objectID": "tomato-fruit",
    "condition": {
        "anchoring": "contains",
        "pattern": "tomato",
    },
    "consequence": {
        "params": {
            "optionalFilters": "food_group:fruit",
        },
    },
}

response = index.save_rule(rule)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
let rule = Rule(objectID: "tomato-fruit")
  .set(\.conditions, to: [
    Rule.Condition()
      .set(\.anchoring, to: .contains)
      .set(\.pattern, to: .literal("tomato"))
  ])
  .set(\.consequence, to: Rule.Consequence().set(\.query, to: Query().set(\.filters, to: "food_group:fruit"))
)

index.saveRule(rule) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
var rule = new Rule
{
    ObjectID = "tomato-fruit",
    Conditions = new List<Condition> {
        new Condition { Anchoring = "contains", Pattern = "tomato" }
    },
    Consequence = new Consequence
    {
        Params = new ConsequenceParams {
            
            OptionalFilters = new List<List<string>> { new List<string> { "food_group:fruit" } },
        }
    }
};

index.SaveRule(rule);

// Asynchronous
await index.SaveRuleAsync(rule);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
Condition condition = new Condition()
    .setAnchoring("contains")
    .setPattern("tomato");

ConsequenceParams params =
    new ConsequenceParams()
        .setFilters("food_group:fruit");

Consequence consequence = new Consequence()
    .setParams(params);

Rule rule = new Rule()
        .setObjectID("tomato-fruit")
        .setConditions(Collections.singletonList(condition))
        .setConsequence(consequence);

index.saveRule(rule);

// Asynchronous
index.saveRuleAsync(rule);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
rule := search.Rule{
  ObjectID:  "tomato-fruit",
  Condition: search.RuleCondition{Anchoring: search.Contains, Pattern: "tomato"},
  Consequence: search.RuleConsequence{
    Params: &search.RuleParams{
      Query: search.NewRuleQueryObject(
        search.RuleQueryObjectQuery{
          Edits: []search.QueryEdit{
            search.RemoveEdit("t-shirt"),
          },
        },
      ),
      QueryParams: search.QueryParams{
        OptionalFilters: opt.OptionalFilterAnd("food_group:fruit"),
      },
    },
  },
}

res, err := index.SaveRule(rule)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
val rule = Rule(
  objectID = "tomato-fruit",
  condition = Some(
    Condition(
      pattern = "tomato",
      anchoring = "contains"
    )
  ),
  consequence = Consequence(
    params = Some(
      Map(
        "optionalFilters" -> "food_group:fruit"
      )
    )
  )
)

client.execute {
  save rule rule inIndex "indexName"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
val rules = rules {
    rule(
        objectID = "tomato-fruit",
        conditions = conditions {
            condition(anchoring = Anchoring.Contains, pattern = Pattern.Literal("tomato"))
        },
        consequence = consequence(
            query = query {
                filters = "food_group:fruit"
            }
        )
    )
}

index.saveRules(rules)

Using the dashboard

Visual Editor

Select the Rules section from the left sidebar menu in the Algolia dashboard.
Under the heading Rules, select the index you are adding a Rule to.
Select Create your first rule or New rule. In the dropdown, click on the Visual Editor option.
In the It all starts here section:
- Click Set search query button.
- In the sidepanel, type “tomato” in the input field and click Save.
In the What do you want to do? section:
- Click the Boost Categories button.
- In the side panel, type “food_group” in the input field for category, then “fruit” in the second input field and press Save.
Don’t forget to review and publish your changes.

Manual Editor

Select the Rules section from the left sidebar menu in the Algolia dashboard.
Under the heading Rules, select the index you are adding a Rule to.
Select Create your first rule or New rule. In the dropdown, click on the Manual Editor option.
In the Condition(s) section, keep Query toggled on, select Contains in the dropdown, and enter “tomato” in the input field.
In the Consequence(s) section:
- Click the Add consequence button and select Add Query Parameter.
- Type {"optionalFilters":"food_group:fruit"}.
Don’t forget to save your changes.

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

PHP

Ruby

JavaScript

Python

Swift

Kotlin

Android

.NET

Java

Golang

Scala

InstantSearch.js

React InstantSearch

Vue InstantSearch

Angular InstantSearch

InstantSearch iOS

InstantSearch Android

Autocomplete

Crawler Configuration API

Index settings and search parameters

A full reference of API Endpoints

Rails

Symfony

Django

Laravel

Crawler

Magento 2

WordPress

Shopify

Salesforce Commerce Cloud B2C

Netlify

Promoting Hits

On this page

Promoting a single item

Use Case

Rule

Using the API

Using the dashboard

Visual Editor

Manual Editor

Promoting the newest release

Use Case

Rule

Using the API

Using the dashboard

Visual Editor

Manual Editor

Promoting some results over others

Use Case

Rule

Using the API

Using the dashboard

Visual Editor

Manual Editor

Did you find this page helpful?

On this page