Merchandise on empty queries

You can create rules that promote or hide items, boost, or bury categories, or activate filters even when users haven’t typed anything yet. This guide shows you how to create a rule that boosts the category clearance:true, whenever there is an empty query and the context is set to landing. You can use other consequences, such as promoting or hiding items, and boosting or burying categories, with the same condition. To trigger this rule, you must send landing as a ruleContexts on the frontend. As soon as user begins typing, the rule is turned off. If you want a rule that’s always active for a particular context regardless of the query string, create a context-only rule. For more information, see Using rules to customize search results by platform.

To boost, bury, or on values of a certain attribute, you must declare that attribute as an attributesForFaceting.

Rules on empty queries are useful for landing or category pages. Use either filters or context to determine which category pages should trigger these rules. For more information, see:

Using the API

To run the code examples on this page, install the latest API client. To create a rule with one of the API clients, use the saveRule method on a rule object with an empty search as the condition.

var response = await client.SaveRuleAsync(
  "INDEX_NAME",
  "clearance-category-filter",
  new Rule
  {
    ObjectID = "clearance-category-filter",
    Conditions = new List<Condition>
    {
      new Condition
      {
        Pattern = "",
        Anchoring = Enum.Parse<Anchoring>("Is"),
        Context = "landing",
      },
    },
    Consequence = new Consequence
    {
      Params = new ConsequenceParams
      {
        OptionalFilters = new OptionalFilters("clearance:true"),
      },
    },
  }
);

final response = await client.saveRule(
  indexName: "INDEX_NAME",
  objectID: "clearance-category-filter",
  rule: Rule(
    objectID: "clearance-category-filter",
    conditions: [
      Condition(
        pattern: "",
        anchoring: Anchoring.fromJson("is"),
        context: "landing",
      ),
    ],
    consequence: Consequence(
      params: ConsequenceParams(
        optionalFilters: "clearance:true",
      ),
    ),
  ),
);

response, err := client.SaveRule(client.NewApiSaveRuleRequest(
  "INDEX_NAME", "clearance-category-filter",
  search.NewEmptyRule().SetObjectID("clearance-category-filter").SetConditions(
    []search.Condition{*search.NewEmptyCondition().SetPattern("").SetAnchoring(search.Anchoring("is")).SetContext("landing")}).SetConsequence(
    search.NewEmptyConsequence().SetParams(
      search.NewEmptyConsequenceParams().SetOptionalFilters(search.StringAsOptionalFilters("clearance:true"))))))
if err != nil {
  // handle the eventual error
  panic(err)
}

UpdatedAtResponse response = client.saveRule(
  "INDEX_NAME",
  "clearance-category-filter",
  new Rule()
    .setObjectID("clearance-category-filter")
    .setConditions(Arrays.asList(new Condition().setPattern("").setAnchoring(Anchoring.IS).setContext("landing")))
    .setConsequence(new Consequence().setParams(new ConsequenceParams().setOptionalFilters(OptionalFilters.of("clearance:true"))))
);

const response = await client.saveRule({
  indexName: 'indexName',
  objectID: 'clearance-category-filter',
  rule: {
    objectID: 'clearance-category-filter',
    conditions: [{ pattern: '', anchoring: 'is', context: 'landing' }],
    consequence: { params: { optionalFilters: 'clearance:true' } },
  },
});

var response =
  client.saveRule(
    indexName = "INDEX_NAME",
    objectID = "clearance-category-filter",
    rule =
      Rule(
        objectID = "clearance-category-filter",
        conditions =
          listOf(
            Condition(
              pattern = "",
              anchoring = Anchoring.entries.first { it.value == "is" },
              context = "landing",
            )
          ),
        consequence =
          Consequence(
            params = ConsequenceParams(optionalFilters = OptionalFilters.of("clearance:true"))
          ),
      ),
  )

$response = $client->saveRule(
    'INDEX_NAME',
    'clearance-category-filter',
    ['objectID' => 'clearance-category-filter',
        'conditions' => [
            ['pattern' => '',
                'anchoring' => 'is',
                'context' => 'landing',
            ],
        ],
        'consequence' => ['params' => ['optionalFilters' => 'clearance:true',
        ],
        ],
    ],
);

response = client.save_rule(
    index_name="INDEX_NAME",
    object_id="clearance-category-filter",
    rule={
        "objectID": "clearance-category-filter",
        "conditions": [
            {
                "pattern": "",
                "anchoring": "is",
                "context": "landing",
            },
        ],
        "consequence": {
            "params": {
                "optionalFilters": "clearance:true",
            },
        },
    },
)

response = client.save_rule(
  "INDEX_NAME",
  "clearance-category-filter",
  Algolia::Search::Rule.new(
    algolia_object_id: "clearance-category-filter",
    conditions: [Algolia::Search::Condition.new(pattern: "", anchoring: "is", context: "landing")],
    consequence: Algolia::Search::Consequence.new(
      params: Algolia::Search::ConsequenceParams.new(optional_filters: "clearance:true")
    )
  )
)

val response = Await.result(
  client.saveRule(
    indexName = "INDEX_NAME",
    objectID = "clearance-category-filter",
    rule = Rule(
      objectID = "clearance-category-filter",
      conditions = Some(
        Seq(
          Condition(
            pattern = Some(""),
            anchoring = Some(Anchoring.withName("is")),
            context = Some("landing")
          )
        )
      ),
      consequence = Consequence(
        params = Some(
          ConsequenceParams(
            optionalFilters = Some(OptionalFilters("clearance:true"))
          )
        )
      )
    )
  ),
  Duration(100, "sec")
)

let response = try await client.saveRule(
    indexName: "INDEX_NAME",
    objectID: "clearance-category-filter",
    rule: Rule(
        objectID: "clearance-category-filter",
        conditions: [SearchCondition(pattern: "", anchoring: SearchAnchoring.`is`, context: "landing")],
        consequence: SearchConsequence(params: SearchConsequenceParams(optionalFilters: SearchOptionalFilters
                .string("clearance:true")))
    )
)

Using the dashboard

You can create this rule from the Algolia dashboard using either the Visual Editor or the Manual Editor. To match empty queries regardless of context, omit the context in either editor.

Visual Editor
Manual Editor

In the Algolia dashboard, select your application and index, open Rules, and select New rule > Visual Editor.
In Conditions, click Set query condition(s). Keep Query toggled on, select is, and leave the search input empty. Toggle Context on, enter landing, and click Apply.
In Consequences, select Boost categories. Select clearance as the attribute and true as its value, then click Apply.
Review the results and click Review and Publish. To forward the rule to replicas or other indices, select them under Copy this rule to other indices and/or replicas. Click Publish, or use Save as Draft to keep the rule inactive.

In the Algolia dashboard, select your application and index, open Rules, and select New rule > Manual Editor.
In Condition(s), keep Query toggled on, select Is, and leave the search input empty. Toggle Context on and enter landing.
In Consequence(s), click Add consequence and select Add Query Parameter. Enter { "optionalFilters": ["clearance:true"] }.
To forward the rule to replicas or other indices, toggle Copy this rule to other indices and/or replicas and select the indices. Save your changes.

In JSON, you must write string values inside quotation marks, and number values and booleans without quotations.

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Merchandise on empty queries

Using the API

Using the dashboard

​Using the API

​Using the dashboard

Using the API

Using the dashboard