Dynamic filtering with Rules

Use rules to apply facet and numeric filters automatically based on search queries.

To help users find what they’re looking for straight from the search box, you can use Algolia Rules to automatically apply a filter to results if the query matches a facet value.

Before you begin

Add the records from the example dataset to an Algolia index. Configure color, product_type, and brand as attributes for faceting.

How to create a dynamic filtering rule

In this example for a product catalog, you create a rule that displays products with the “red” value in the color facet if the query contains the word “red”.

With the example dataset, this rule limits results to records with “red” in the color attribute. It ignores “red” in other attributes such as brand.

Query	Results
red	FM, Clothing, LondonLook, Red, 21.99 The Mandal 800w, Toaster, Black & Decker, Red, 149.99

Create the rule in the dashboard

You can add this rule from the Algolia dashboard using either the Visual Editor or the Manual Editor.

Visual Editor

1. In the Algolia dashboard, select your application and index, open Rules, and select New rule > Visual Editor.
2. Click Set query condition(s), select contains, enter red, and click Apply.
3. In Consequences, select Filter results. Select the color attribute and the red value, then click Apply. To boost red products while keeping other colors in the results, use Boost categories instead.
4. Click Add Consequence, expand More consequences, and select Remove word. Enter red in Word(s) and click Apply.
5. Review the results, click Review and Publish, and click Publish.

Manual Editor

1. Go to the Algolia dashboard and select your Algolia .

   On the left sidebar, select Search, select your index, and open Rules. Select Create your first rule or New rule, then select Manual Editor.

2. In Condition(s), keep Query selected, select Contains, and enter red.

3. In Consequence(s), click Add consequence and select Add Query Parameter. Enter {"filters":"color:red"}. To promote red products without excluding products of other colors, see Optional filters.

4. Click Add consequence and select Remove Word. Enter red.

5. Save your changes.

Create the rule with the API

To run the code examples on this page, install the latest API client.

This example uses the filters parameter. With this approach, you need one rule per filter value. If you have 10 color options, you need 10 rules, one for each color.

C#

var response = await client.SaveRuleAsync(
  "INDEX_NAME",
  "red-color",
  new Rule
  {
    ObjectID = "red-color",
    Conditions = new List<Condition>
    {
      new Condition { Pattern = "red", Anchoring = Enum.Parse<Anchoring>("Contains") },
    },
    Consequence = new Consequence
    {
      Params = new ConsequenceParams
      {
        Query = new ConsequenceQuery(
          new ConsequenceQueryObject { Remove = new List<string> { "red" } }
        ),
        Filters = "color:red",
      },
    },
  }
);

Example: one rule per facet

Use one rule to detect values of the color facet and apply the corresponding filter. For example, the query red applies color:red, while black applies color:black. This avoids creating a separate rule for each color.

Query	Results
red	FM, Clothing, LondonLook, Red, 21.99
red	The Mandal 800w, Toaster, Black & Decker, Red, 149.99
black	Will Carpenter, T-shirt, Red or Dead, Black, 199.99

Create the rule in the dashboard

You can add this rule from the Algolia dashboard using either the Visual Editor or the Manual Editor.

Visual Editor

1. Create a rule with Visual Editor.
2. Click Set query condition(s) and select contains. Select Match any value of a facet and choose color. Click Apply.
3. In Consequences, expand More consequences and select Filter / Boost matching attribute. Select color in Facet. The facet must be present in every query condition.
4. Choose Filter to keep only matching records or Boost to promote them without excluding other records. Set Score from 1 to 50 to control the filter score. If your plan doesn’t support optional filters in rules, select Filter facets to filter the results.
5. Under Filter type, select Conjunctive to require all matching values or Disjunctive to accept any of them. Click Apply.
6. Review the results for different color queries, click Review and Publish, and click Publish.

Manual Editor

1. Create a rule with the Manual Editor. See how to create a dynamic filtering rule.
2. In Condition(s), click the box next to Query contains and select Add Facet “color”.
3. In Consequence(s), click Add consequence and select Filter/Boost Matching Attributes. Click Filter and select Add Facet “color”.
4. Save your changes.

Create the rule with the API

C#

var response = await client.SaveRuleAsync(
  "INDEX_NAME",
  "color-facets",
  new Rule
  {
    ObjectID = "color-facets",
    Conditions = new List<Condition> { new Condition { Pattern = "{facet:color}" } },
    Consequence = new Consequence
    {
      Params = new ConsequenceParams
      {
        AutomaticFacetFilters = new AutomaticFacetFilters(
          new List<AutomaticFacetFilter> { new AutomaticFacetFilter { Facet = "color" } }
        ),
      },
    },
  }
);

To show the filters applied by this rule as selected options in your search UI, see Show automatically applied filters.

Numerical dynamic filtering

For the query cheap toaster 800w, use one rule to filter by product_type:toaster and another to filter by price < 15. Remove toaster and cheap from the query so the search uses 800w to find matching products.

With the example dataset, the query returns the Essentials 800w toaster, priced at $14.99.

Query	Results
cheap toaster 800w	Essentials 800w, Toaster, Daewoo, Black, 14.99

Create the rules in the dashboard

You can add these rules from the Algolia dashboard using either the Visual Editor or the Manual Editor.

Visual Editor

1. Open Rules and select New rule > Visual Editor.
2. Click Set query condition(s), select contains, enter toaster, and click Apply.
3. In Consequences, select Filter results. Select product_type as the attribute and toaster as the value, then click Apply.
4. Click Add Consequence, expand More consequences, and select Remove word. Enter toaster in Word(s) and click Apply.
5. Review the results, click Review and Publish, and click Publish.

Repeat these steps to create the second rule. Use cheap for the condition and removed word, and filter on price < 15.

Manual Editor

1. Open Rules, select New rule, and select Manual Editor.
2. In Condition(s), keep Query selected, select Contains, and enter toaster.
3. In Consequence(s), click Add consequence and select Add Query Parameter. Enter {"filters":"product_type:toaster"}.
4. Click Add consequence and select Remove Word. Enter toaster.
5. Save your changes.

Repeat these steps to create the second rule. Use cheap for the condition and removed word, and enter {"filters":"price < 15"} as the query parameter.

Create the rules with the API

C#

var response = await client.SaveRulesAsync(
  "INDEX_NAME",
  new List<Rule>
  {
    new Rule
    {
      ObjectID = "toaster",
      Conditions = new List<Condition>
      {
        new Condition { Pattern = "toaster", Anchoring = Enum.Parse<Anchoring>("Contains") },
      },
      Consequence = new Consequence
      {
        Params = new ConsequenceParams
        {
          Query = new ConsequenceQuery(
            new ConsequenceQueryObject { Remove = new List<string> { "toaster" } }
          ),
          Filters = "product_type:toaster",
        },
      },
    },
    new Rule
    {
      ObjectID = "cheap",
      Conditions = new List<Condition>
      {
        new Condition { Pattern = "cheap", Anchoring = Enum.Parse<Anchoring>("Contains") },
      },
      Consequence = new Consequence
      {
        Params = new ConsequenceParams
        {
          Query = new ConsequenceQuery(
            new ConsequenceQueryObject { Remove = new List<string> { "cheap" } }
          ),
          Filters = "price < 15",
        },
      },
    },
  }
);

Filter by brand

Users can enter apple headphones to search for Apple headphones. The rule applies a filter for the Apple brand and removes the matched brand value from the query, leaving headphones as the search term.

This extends one rule per facet by also removing the matched brand value from the query. With the example dataset, the query returns Airpods Max. It excludes the Sony headphones, even though their color attribute contains Apple.

Query	Results
apple headphones	Airpods Max, Headphones, Apple, Gray, 548.99

Create the rule in the dashboard

You can add this rule from the Algolia dashboard using either the Visual Editor or the Manual Editor.

Visual Editor

1. Open Rules and select New rule > Visual Editor.
2. Click Set query condition(s) and select contains. Select Match any value of a facet and choose brand. Clear the checkbox for matching plurals, synonyms, and typos, then click Apply.
3. In Consequences, expand More consequences and select Filter / Boost matching attribute. Select brand in Facet, choose Filter, and click Apply.
4. Click Add Consequence, expand More consequences, and select Remove word. Select {facet:brand} in Word(s) and click Apply.
5. Review the results, click Review and Publish, and click Publish.

Manual Editor

1. Create a rule with the Manual Editor.
2. In Condition(s), click the box next to Query contains and select Add Facet “brand”. Clear Apply to plurals, synonyms and typos to ensure precise brand matching.
3. In Consequence(s), click Add consequence and select Filter/Boost Matching Attributes. Click Filter and select Add Facet “brand”.
4. Click Add consequence and select Remove word. Select Remove {facet:brand}.
5. Save your changes.

Create the rule with the API

C#

var response = await client.SaveRuleAsync(
  "INDEX_NAME",
  "tagged-brand-rule",
  new Rule
  {
    Conditions = new List<Condition>
    {
      new Condition
      {
        Pattern = "brand: {facet:brand}",
        Anchoring = Enum.Parse<Anchoring>("Contains"),
        Alternatives = false,
      },
    },
    Consequence = new Consequence
    {
      Params = new ConsequenceParams
      {
        AutomaticFacetFilters = new AutomaticFacetFilters(
          new List<AutomaticFacetFilter> { new AutomaticFacetFilter { Facet = "brand" } }
        ),
        Query = new ConsequenceQuery(
          new ConsequenceQueryObject
          {
            Remove = new List<string> { "brand:", "{facet:brand}" },
          }
        ),
      },
    },
    Description = "filter on brand: {brand}",
    ObjectID = "tagged-brand-rule",
  }
);

Example dataset

The examples on this page use the following product catalog records:

JSON

[
  {
    "product_name": "FM",
    "product_type": "T-shirt",
    "brand": "LondonLook",
    "color": "Red",
    "price": 21.99
  },
  {
    "product_name": "Caveman",
    "product_type": "T-shirt",
    "brand": "Red or Dead",
    "color": "Brown",
    "price": 9.99
  },
  {
    "product_name": "iPhone 13 Pro Max",
    "product_type": "Phone",
    "brand": "Apple",
    "color": "Blue",
    "price": 1824.61
  },
  {
    "product_name": "Will Carpenter",
    "product_type": "T-shirt",
    "brand": "Red or Dead",
    "color": "Black",
    "price": 199.99
  },
  {
    "product_name": "The Mandal 800w",
    "product_type": "Toaster",
    "brand": "Black & Decker",
    "color": "Red",
    "price": 149.99
  },
  {
    "product_name": "Essentials 800w",
    "product_type": "Toaster",
    "brand": "Daewoo",
    "color": "Black",
    "price": 14.99
  },
  {
    "product_name": "Airpods Max",
    "product_type": "Headphones",
    "brand": "Apple",
    "color": "Gray",
    "price": 548.99
  },
  {
    "product_name": "WH-CH520",
    "product_type": "Headphones",
    "brand": "Sony",
    "color": "Apple",
    "price": 39.99
  }
]

See also

• Adding filters based on the query
• Faceting