Rules overview

Search needs to be flexible. Product promotions should be seamless: search setting adjustments or record updates aren’t needed. If one of your products isn’t appearing where you want it to in your search results, you can reposition it. Rules let you make precise and (if desired) temporary modifications to your search results. Relevance and settings provide the general structure for your search results. Rules let you optimize and dynamically adjust that structure.

Rules are no substitute for a well-configured index. Make sure you adjust your general relevance before adding rules.

Index rules and composition rules

Algolia uses two different types of rules: index rules and composition rules. This section describes index rules. For more information about composition rules, see Smart Groups.

What are rules used for?

Rules let you make precise, predetermined changes to your search results. For example, you can pin or hide items, boost or bury categories, or results based on the query. You can also enable rules for a fixed time, making rules a great way of implementing sales or promotions. Rules are typically used either for merchandising or fine-tuning your search and relevance. For more information about typical uses for rules, see Merchandising and Detecting intent.

The maximum number of rules per index depends on your Algolia plan.

Rule structure

Three elements define a rule: conditions, consequences, and a validity period. Of these three elements, only a consequence is mandatory. When a rule’s condition is satisfied, Algolia applies its consequences. If a rule doesn’t have any conditions (a conditionless rule), Algolia always applies its consequences. For more information, see:

Conditions

A rule can have up to 25 conditions. A rule with several conditions activates when any condition is satisfied. In other words, conditions have an or relationship to one another. Conditions may contain a pattern string, anchoring, context, or filters. To determine if a rule’s consequences apply:

Algolia compares the user’s query to the condition’s pattern. It bases the comparison on the condition’s anchoring. Values for anchoring are: is, contains, starts with, and ends with. The anchoring determines what part of the query the pattern must match: all of it, part of it, the beginning, or the end. If you enable alternatives in the condition, user queries can match the condition’s pattern, even if the query is a plural, synonym, or typo of the pattern. Without alternatives, queries must precisely match the condition’s pattern and anchoring.
It compares the condition’s filters to the filters applied to the search.
It compares the condition’s context to the search’s ruleContexts.

If a single condition includes a pattern string, filters, and a context, a search must match all three for the condition to be satisfied. With three conditions, a rule activates if any is met. If a condition uses is anchoring with an empty pattern, Algolia applies the rule if users haven’t yet entered a query. If a condition doesn’t include a pattern, anchoring, context, or filters, it’s a conditionless rule, and Algolia applies it to every search. Rules can respond to different types of conditions:

Query patterns
Filters
Context-only
Conditionless.

Example conditions

Using a pattern with is anchoring

Trigger a rule with this condition whenever the query string is the word sale and nothing else. If the query contains other words, the rule isn’t triggered.

JSON

{
  "pattern": "sale",
  "anchoring": "is"
}

A pattern with contains anchoring

Trigger a rule with this condition whenever the query string contains the word featured. The query can include other words.

JSON

{
  "pattern": "featured",
  "anchoring": "contains"
}

A context

Trigger a rule when the search includes mobile in the ruleContexts.

JSON

{
  "context": "mobile"
}

Filters

Trigger a rule when the filter { "filters": "category:TV" } applies to the query.

JSON

{
  "filters": "category:TV"
}

The filters condition rejects an OR combination of different attributes. For example, "filters": "brand:Guess OR color:orange" returns an error. You also can’t use numeric filters in conditions.

Pattern, filters, and context

Trigger a rule when:

The query contains the word featured
filters includes category:TV
ruleContexts includes mobile.

JSON

{
  "pattern": "featured",
  "anchoring": "contains",
  "filters": "category:TV",
  "context": "mobile"
}

An empty string pattern

Trigger a rule when there is an empty search. The rule turns off as soon as a user starts typing.

JSON

{
  "pattern": "",
  "anchoring": "is"
}

Consequences

Though conditions aren’t required, rules must have at least one consequence. Consequences change the search results. Examples of consequences include:

Pin an item. Insert an item at a specific position. If the item is already in the results, it moves to that position.
Hide an item. Remove a specific result from the list of results.
Add a query parameter. Add a query parameter to your user’s search. For example, you could decrease the aroundRadius if your user’s query includes the words “near me”.
Remove word. Remove a specific word from your user’s (for search, not display purposes).
Replace word. Replace a word from your user’s search query with another word (for search, not display purposes).
Replace query. Replace the entire user search query with another query (for search, not display purposes).
Return custom data. Add custom JSON data to the search response.
Filter/Boost matching attributes. Apply filters or optionalFilters matching the query to the results.

Use the Visual Editor to configure rules with guided controls and preview their effect on search results. The Manual Editor offers a more technical workflow for configuring rule conditions, consequences, and search parameters directly. Both editors use the Rules API. The Visual Editor supports custom data, search parameters, query edits, matching-attribute filters, and merchandising actions such as pinning, hiding, and displaying banners. Custom data and search parameters use JSON inputs in both editors. For more information, see:

Validity period

If you want to apply a rule temporarily, you can set a validity period. The validity period determines how long a rule remains active. Use this to ensure promotions and sales end automatically.

Rules responding to user queries

Rules can parse user queries and apply consequences if the query matches the rule’s condition. Queries can match with conditions in the following ways:

is: the entire query matches the condition string.
contains: the entire query contains the condition string.
startsWith: the query starts with the condition string.
endsWith: the query ends with the condition string.

To trigger a rule on an empty query, use is anchoring and set the condition’s pattern to an empty string.

Rules responding to applied filters

If a rule’s condition includes filters, Algolia applies that rule’s consequences only if the filters in a search’s query parameters exactly match the condition’s filters. For example, Algolia only triggers a rule with the condition {"filters": "category:TV"} if the category value is TV. Other filters like "category:Smartphone" or "category:TV OR category:Smartphone" don’t trigger the rule. The primary goal of this condition is to create rules that trigger on specific category pages or when a user applies specific filters. For example, you can define a rule with the condition {"filters": "category:TV"} and a consequence to promote specific items. The rule triggers when a user lands on the TV category page. For more information, see Filters can trigger rules.

To use an attribute in a rule condition with filters, you must first declare it in attributesForFaceting.

Context-only rules

If a rule’s condition only includes a context, the consequence only applies if the rule’s context exactly matches a value in the ruleContexts parameter of a user’s search.

What are contexts?

Contexts provide information about your user’s search environment: for example, what section of a website they’re currently visiting or what device they’re using. A context can be any string value that doesn’t include whitespace characters. The search condition it specifies must be identifiable at search time. You need to implement logic for sending contexts with queries. You can pass contexts through the ruleContexts search parameter.

Implementation

To create a rule with a context condition, you must:

Create the rule (with the dashboard or the API).
Conditionally assign its associated context to your user’s searches.

To clarify the process, consider the example of an electronics store. By looking at analytics tags, it’s clear that mobile users rarely find what they’re searching for on the first page of results. Testing indicates this is because vague searches for accessories like “chargers” or “cases” return laptop chargers and cases first. If mobile users search for cases, you can assume that they prefer phone cases over laptop cases. If they search for chargers, phone chargers should show up first. To remedy this, add a rule that promotes all items with the “phone” tag but only for users searching from a mobile platform. To learn more, see Using rules to customize search results by device.

Conditionless rules

Rules without conditions apply to every search. They’re an effective way of temporarily modifying search for a predefined time, for example, for seasonal promotions. For more information, see Add default search parameters with rules. You can create conditionless rules from the Algolia dashboard or with one of the API clients.

Using the dashboard

You can create a conditionless rule from the Algolia dashboard using either the Visual Editor or the Manual Editor.

Visual Editor
Manual Editor

In the Algolia dashboard, select your application and index, open Rules, and select New rule > Visual Editor. If you’re using the Merchandising Studio Visual Merchandiser instead, select Actions > Create new rule.
In Conditions, select Create conditionless rule, review its scope, and click Apply. A conditionless rule applies to every search. Leaving a query field empty instead creates an empty-query condition.
Select the consequences you want to apply. Optional: select Add a date range to limit when the rule applies.
Click Review and Publish, review the rule, and click Publish.

Using the API

To run the code examples on this page, install the latest API client. To create a conditionless rule with an API client, use the saveRule method on a rule object but without a condition.

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 UseConditionlessRule
{
  async Task Main(string[] args)
  {
    var client = new SearchClient(new SearchConfig("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY"));

    var objectID = "a-rule-id";

    var rule = new Rule
    {
      ObjectID = objectID,
      Consequence =
        new Consequence( /* Set relevant consequence */
        ),
      // Set validity (optional)
      Validity = [new TimeRange { From = 1688774400L, Until = 1738972800L }],
    };

    await client.SaveRuleAsync("INDEX_NAME", objectID, rule);
  }
}

import 'package:algolia_client_search/algolia_client_search.dart';

void useConditionlessRule() async {
  final client =
      SearchClient(appId: 'ALGOLIA_APPLICATION_ID', apiKey: 'ALGOLIA_API_KEY');

  final objectID = "a-rule-id";

  final rule = Rule(
      objectID: objectID,
      consequence: Consequence(
          // Set relevant consequence
          ),
      // Set validity (optional)
      validity: [TimeRange(from: 1688774400, until: 1738972800)]);

  await client.saveRule(
    indexName: "INDEX_NAME",
    objectID: objectID,
    rule: rule,
  );
}

package main

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

func useConditionlessRule() {
	client, err := search.NewClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
	if err != nil {
		// The client can fail to initialize if you pass an invalid parameter.
		panic(err)
	}

	objectID := "a-rule-id"

	rule := search.NewRule(
		objectID,
		*search.NewConsequence( /* Set relevant consequence */ ),
	). // Set validity (optional)
		SetValidity(
			[]search.TimeRange{{
				From:  utils.ToPtr(int64(1_688_774_400)),
				Until: utils.ToPtr(int64(1_738_972_800)),
			}},
		)

	_, err = client.SaveRule(client.NewApiSaveRuleRequest(
		"INDEX_NAME", objectID, rule))
	if err != nil {
		panic(err)
	}
}

package com.algolia;

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

public class useConditionlessRule {

  public static void main(String[] args) throws Exception {
    try (SearchClient client = new SearchClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")) {
      String objectID = "a-rule-id";

      Rule rule = new Rule().setObjectID(objectID).setConsequence(new Consequence(/* Set relevant consequence */));

      // Set validity (optional)
      rule.setValidity(List.of(new TimeRange().setFrom(1688774400L).setUntil(1738972800L)));

      client.saveRule("INDEX_NAME", objectID, rule);
    } catch (Exception e) {
      System.out.println("An error occurred: " + e.getMessage());
    }
  }
}

import { algoliasearch } from 'algoliasearch';

import type { Rule } from 'algoliasearch';

const client = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_API_KEY');

const objectID = 'a-rule-id';

const rule: Rule = {
  objectID,
  consequence: {
    // Set relevant consequence
  },
};

// Set validity (optional)
rule.validity = [
  {
    from: 1688774400,
    until: 1738972800,
  },
];

await client.saveRule({ indexName: 'indexName', objectID: objectID, rule: rule });

import com.algolia.client.api.SearchClient
import com.algolia.client.configuration.*
import com.algolia.client.extensions.*
import com.algolia.client.model.search.*
import com.algolia.client.transport.*

suspend fun useConditionlessRule() {
  val client = SearchClient(appId = "ALGOLIA_APPLICATION_ID", apiKey = "ALGOLIA_API_KEY")

  val objectID = "a-rule-id"

  val rule =
    Rule(
      objectID = objectID,
      consequence =
        Consequence(
          // Set relevant consequence
        ),
      // Set validity (optional)
      validity = listOf(TimeRange(from = 1_688_774_400, until = 1_738_972_800)),
    )

  client.saveRule(indexName = "INDEX_NAME", objectID = objectID, rule = rule)
}

<?php

require __DIR__.'/../vendor/autoload.php';
use Algolia\AlgoliaSearch\Api\SearchClient;
use Algolia\AlgoliaSearch\Model\Search\Consequence;
use Algolia\AlgoliaSearch\Model\Search\Rule;
use Algolia\AlgoliaSearch\Model\Search\TimeRange;

$client = SearchClient::create('ALGOLIA_APPLICATION_ID', 'ALGOLIA_API_KEY');

$objectID = 'a-rule-id';

$rule = (new Rule())
    ->setObjectID($objectID)
    ->setConsequence(new Consequence(/* Set relevant consequence */))
;

// Set validity (optional)
$rule->setValidity(
    [
        (new TimeRange())
            ->setFrom(1688774400)
            ->setUntil(1738972800),
    ]
);

$client->saveRule(
    'INDEX_NAME',
    $objectID,
    $rule,
);

from algoliasearch.search.client import SearchClientSync

from algoliasearch.search.models.consequence import Consequence
from algoliasearch.search.models.rule import Rule
from algoliasearch.search.models.time_range import TimeRange

_client = SearchClientSync("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")


object_id = "a-rule-id"

rule = Rule(
    object_id=object_id,
    consequence=Consequence(
        # Set relevant consequence
    ),
)

# Set validity (optional)
rule.validity = [
    TimeRange(
        var_from=1688774400,
        until=1738972800,
    ),
]

_client.save_rule(
    index_name="INDEX_NAME",
    object_id=object_id,
    rule=rule,
)

require "algolia"

client = Algolia::SearchClient.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")

object_id = "a-rule-id"

rule = Algolia::Search::Rule.new(
  object_id: object_id,
  consequence: Algolia::Search::Consequence.new
  # Set relevant consequence
)

# Set validity (optional)
rule.validity = [
  Algolia::Search::TimeRange.new(
    from: 1688774400,
    until: 1738972800
  )
]

client.save_rule("INDEX_NAME", algolia_object_id, rule)

import scala.concurrent.ExecutionContext.Implicits.global
import scala.concurrent.Future

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

def useConditionlessRule(): Future[Unit] = {
  val client = SearchClient(appId = "ALGOLIA_APPLICATION_ID", apiKey = "ALGOLIA_API_KEY")

  val objectID = "a-rule-id";

  val rule = Rule(
    objectID = objectID,
    consequence = Consequence(
      // Set relevant consequence
    ),
    // Set validity (optional)
    validity = Some(
      Seq(
        TimeRange(
          from = Some(1_688_774_400),
          until = Some(1_738_972_800)
        )
      )
    )
  )

  client
    .saveRule(
      indexName = "INDEX_NAME",
      objectID = objectID,
      rule = rule
    )
    .map { response =>
      println(response)
    }
    .recover { case ex: Exception =>
      println(s"An error occurred: ${ex.getMessage}")
    }
}

import Foundation
#if os(Linux) // For linux interop
    import FoundationNetworking
#endif

import AlgoliaCore
import AlgoliaSearch

func useConditionlessRule() async throws {
    let client = try SearchClient(appID: "ALGOLIA_APPLICATION_ID", apiKey: "ALGOLIA_API_KEY")

    let objectID = "a-rule-id"

    let rule = Rule(
        objectID: objectID,
        consequence: SearchConsequence(
            // Set relevant consequence
        ),
        // Set validity (optional)
        validity: [
            SearchTimeRange(
                from: 1_688_774_400,
                until: 1_738_972_800
            ),
        ]
    )

    try await client.saveRule(indexName: "INDEX_NAME", objectID: objectID, rule: rule)
}

Context-only and conditionless rules deactivate consequences

Since conditionless and context-only rules don’t have a query as a condition, these consequences are deactivated.

Consequence	Why is it deactivated?
Pin an item	The same item would always appear in the same position, usually at the top, for all queries and all users. Instead, consider adding a banner to promote items you want to pin.
Remove word, Replace word, Replace query	Since there’s no query, there are no words to remove or replace.
Filter/Boost matching attributes	Rules that filter and boost facets require users to type a attribute into the query. Since there’s no query or facet in the condition, there’s no filter for the rule to boost.

These limitations only apply to context-only and conditionless rules. Other rules can use the full range of consequences.

Choose a rule editor

Use the Visual Editor for most rules. It supports the same conditions and consequences as the Manual Editor and lets you preview their effect on search results. Choose another option when you need a different workflow.

Option	Use it when
Visual Editor	You want a guided workflow and an instant preview of how a rule affects search results.
Manual Editor	You want to enter rule details directly, including JSON values, and don’t need an instant preview.
Rules API	You want to create or update rules in bulk, automate rule management, or build a custom interface.

Rule tags

Create and manage rule tags in the Algolia dashboard or Merchandising Studio. On the Rules page, click Manage tags. A rule tag includes:

Attribute	Required	Description
Name	Yes	Unique within the index.
Description	No	Describes the tag’s purpose.
Color	No	Color shown for the tag in the dashboard.

By default, indices may contain up to 100 rule tags. After you create a rule tag, you can add it to individual rules in the Visual Editor and Manual Editor.

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Index rules and composition rules

What are rules used for?

Rule structure

Conditions

Example conditions

Using a pattern with is anchoring

A pattern with contains anchoring

A context

Filters

Pattern, filters, and context

An empty string pattern

Consequences

Validity period

Rules responding to user queries

Rules responding to applied filters

Context-only rules

What are contexts?

Implementation

Conditionless rules

Using the dashboard

Using the API

Context-only and conditionless rules deactivate consequences

Choose a rule editor

Rule tags

​Index rules and composition rules

​What are rules used for?

​Rule structure

​Conditions

​Example conditions

​Using a pattern with is anchoring

​A pattern with contains anchoring

​A context

​Filters

​Pattern, filters, and context

​An empty string pattern

​Consequences

​Validity period

​Rules responding to user queries

​Rules responding to applied filters

​Context-only rules

​What are contexts?

​Implementation

​Conditionless rules

​Using the dashboard

​Using the API

​Context-only and conditionless rules deactivate consequences

​Choose a rule editor

​Rule tags

Index rules and composition rules

What are rules used for?

Rule structure

Conditions

Example conditions

Using a pattern with is anchoring

A pattern with contains anchoring

A context

Filters

Pattern, filters, and context

An empty string pattern

Consequences

Validity period

Rules responding to user queries

Rules responding to applied filters

Context-only rules

What are contexts?

Implementation

Conditionless rules

Using the dashboard

Using the API

Context-only and conditionless rules deactivate consequences

Choose a rule editor

Rule tags