Enhance search results with query-based rules

You can use rules to enhance the user experience based on what they search for. For example, if you’re building an app to search for airports, Algolia’s geolocation feature helpfully ranks results by proximity. However, the nearest airport isn’t necessarily the best choice. In Paris, a search based on proximity might rank Le Bourget, a small airport for private jets, over large airports like Charles de Gaulle or Orly. As a solution, you could prioritize other factors over proximity. For example, you could rank airports by their number of airline connections. However, if you also set a geolocation parameter like aroundLatLngViaIP, proximity remains the primary factor in determining the order of search results. A better solution is to create a rule so that when users search for a specific city or country, it turns off the aroundLatLngViaIP parameter for that query.

Before you begin

Before creating the rule, ensure that:

nb_airline_connections is the custom ranking attribute
city and country are set as attributes for faceting, so you can detect whenever a query matches them

Create the rule

Using the dashboard

This example assumes you’re using the sample dataset. You can add these rules from the Algolia dashboard using either the Visual Editor or the Manual Editor.

Custom ranking and attributes for faceting

Go to the Algolia dashboard and select your Algolia .
On the left sidebar, select Search.
Select your Algolia index.
On the Configuration tab, click Ranking and Sorting.
Click Add custom ranking attribute and select the nb_airline_connections attribute from the drop-down menu.
Click Facets, under Filtering and faceting, then click Add an Attribute and select country and city from the drop-down menu.
Save your changes.

Visual Editor
Manual Editor

After configuring custom ranking and attributes for faceting, create a rule for each facet:

Open Rules and select New rule > Visual Editor.
Click Set query condition(s) and select contains. Select Match any value of a facet, choose country, and click Apply.
In Consequences, expand More consequences and select Apply search parameters. Enter { "aroundLatLngViaIP": false } in Value and click Apply.
Click Review and Publish, then Publish.

Repeat these steps to create the second rule, but choose city instead of country as the facet.

In the Manual Editor, create a separate rule for the country and city facets.

Open Rules, select Create your first rule or New rule, and select Manual Editor.
In Condition(s), keep Query selected, select Contains, and select country. The input displays {facet:country}.
In Consequence(s), click Add consequence and select Add Query Parameter. Enter { "aroundLatLngViaIP": false }.
Save your changes.

Repeat these steps to create the second rule, but select city so the condition displays {facet:city}.

Using the API

To run the code examples on this page, install the latest API client. Before creating the rule, set custom ranking and the attributes for faceting. This example assumes you’re using the sample dataset.

Custom ranking and attributes for faceting

var response = await client.SetSettingsAsync(
  "INDEX_NAME",
  new IndexSettings
  {
    CustomRanking = new List<string> { "desc(nb_airline_liaisons)" },
    AttributesForFaceting = new List<string> { "city, country" },
  }
);

final response = await client.setSettings(
  indexName: "INDEX_NAME",
  indexSettings: IndexSettings(
    customRanking: [
      "desc(nb_airline_liaisons)",
    ],
    attributesForFaceting: [
      "city, country",
    ],
  ),
);

response, err := client.SetSettings(client.NewApiSetSettingsRequest(
  "INDEX_NAME",
  search.NewEmptyIndexSettings().SetCustomRanking(
    []string{"desc(nb_airline_liaisons)"}).SetAttributesForFaceting(
    []string{"city, country"})))
if err != nil {
  // handle the eventual error
  panic(err)
}

UpdatedAtResponse response = client.setSettings(
  "INDEX_NAME",
  new IndexSettings()
    .setCustomRanking(Arrays.asList("desc(nb_airline_liaisons)"))
    .setAttributesForFaceting(Arrays.asList("city, country"))
);

const response = await client.setSettings({
  indexName: 'theIndexName',
  indexSettings: { customRanking: ['desc(nb_airline_liaisons)'], attributesForFaceting: ['city, country'] },
});

var response =
  client.setSettings(
    indexName = "INDEX_NAME",
    indexSettings =
      IndexSettings(
        customRanking = listOf("desc(nb_airline_liaisons)"),
        attributesForFaceting = listOf("city, country"),
      ),
  )

$response = $client->setSettings(
    'INDEX_NAME',
    ['customRanking' => [
        'desc(nb_airline_liaisons)',
    ],
        'attributesForFaceting' => [
            'city, country',
        ],
    ],
);

response = client.set_settings(
    index_name="INDEX_NAME",
    index_settings={
        "customRanking": [
            "desc(nb_airline_liaisons)",
        ],
        "attributesForFaceting": [
            "city, country",
        ],
    },
)

response = client.set_settings(
  "INDEX_NAME",
  Algolia::Search::IndexSettings.new(
    custom_ranking: ["desc(nb_airline_liaisons)"],
    attributes_for_faceting: ["city, country"]
  )
)

val response = Await.result(
  client.setSettings(
    indexName = "INDEX_NAME",
    indexSettings = IndexSettings(
      customRanking = Some(Seq("desc(nb_airline_liaisons)")),
      attributesForFaceting = Some(Seq("city, country"))
    )
  ),
  Duration(100, "sec")
)

let response = try await client.setSettings(
    indexName: "INDEX_NAME",
    indexSettings: IndexSettings(
        attributesForFaceting: ["city, country"],
        customRanking: ["desc(nb_airline_liaisons)"]
    )
)

Create the rules

Use the batch-rules method to create rules that detect matches in facets city and country, and change the search parameters accordingly.

var response = await client.SaveRulesAsync(
  "INDEX_NAME",
  new List<Rule>
  {
    new Rule
    {
      ObjectID = "country",
      Conditions = new List<Condition>
      {
        new Condition
        {
          Pattern = "{facet:country}",
          Anchoring = Enum.Parse<Anchoring>("Contains"),
        },
      },
      Consequence = new Consequence
      {
        Params = new ConsequenceParams { AroundLatLngViaIP = false },
      },
    },
    new Rule
    {
      ObjectID = "city",
      Conditions = new List<Condition>
      {
        new Condition
        {
          Pattern = "{facet:city}",
          Anchoring = Enum.Parse<Anchoring>("Contains"),
        },
      },
      Consequence = new Consequence
      {
        Params = new ConsequenceParams { AroundLatLngViaIP = false },
      },
    },
  }
);

final response = await client.saveRules(
  indexName: "INDEX_NAME",
  rules: [
    Rule(
      objectID: "country",
      conditions: [
        Condition(
          pattern: "{facet:country}",
          anchoring: Anchoring.fromJson("contains"),
        ),
      ],
      consequence: Consequence(
        params: ConsequenceParams(
          aroundLatLngViaIP: false,
        ),
      ),
    ),
    Rule(
      objectID: "city",
      conditions: [
        Condition(
          pattern: "{facet:city}",
          anchoring: Anchoring.fromJson("contains"),
        ),
      ],
      consequence: Consequence(
        params: ConsequenceParams(
          aroundLatLngViaIP: false,
        ),
      ),
    ),
  ],
);

response, err := client.SaveRules(client.NewApiSaveRulesRequest(
  "INDEX_NAME",
  []search.Rule{*search.NewEmptyRule().SetObjectID("country").SetConditions(
    []search.Condition{*search.NewEmptyCondition().SetPattern("{facet:country}").SetAnchoring(search.Anchoring("contains"))}).SetConsequence(
    search.NewEmptyConsequence().SetParams(
      search.NewEmptyConsequenceParams().SetAroundLatLngViaIP(false))), *search.NewEmptyRule().SetObjectID("city").SetConditions(
    []search.Condition{*search.NewEmptyCondition().SetPattern("{facet:city}").SetAnchoring(search.Anchoring("contains"))}).SetConsequence(
    search.NewEmptyConsequence().SetParams(
      search.NewEmptyConsequenceParams().SetAroundLatLngViaIP(false)))}))
if err != nil {
  // handle the eventual error
  panic(err)
}

UpdatedAtResponse response = client.saveRules(
  "INDEX_NAME",
  Arrays.asList(
    new Rule()
      .setObjectID("country")
      .setConditions(Arrays.asList(new Condition().setPattern("{facet:country}").setAnchoring(Anchoring.CONTAINS)))
      .setConsequence(new Consequence().setParams(new ConsequenceParams().setAroundLatLngViaIP(false))),
    new Rule()
      .setObjectID("city")
      .setConditions(Arrays.asList(new Condition().setPattern("{facet:city}").setAnchoring(Anchoring.CONTAINS)))
      .setConsequence(new Consequence().setParams(new ConsequenceParams().setAroundLatLngViaIP(false)))
  )
);

const response = await client.saveRules({
  indexName: 'INDEX_NAME',
  rules: [
    {
      objectID: 'country',
      conditions: [{ pattern: '{facet:country}', anchoring: 'contains' }],
      consequence: { params: { aroundLatLngViaIP: false } },
    },
    {
      objectID: 'city',
      conditions: [{ pattern: '{facet:city}', anchoring: 'contains' }],
      consequence: { params: { aroundLatLngViaIP: false } },
    },
  ],
});

var response =
  client.saveRules(
    indexName = "INDEX_NAME",
    rules =
      listOf(
        Rule(
          objectID = "country",
          conditions =
            listOf(
              Condition(
                pattern = "{facet:country}",
                anchoring = Anchoring.entries.first { it.value == "contains" },
              )
            ),
          consequence = Consequence(params = ConsequenceParams(aroundLatLngViaIP = false)),
        ),
        Rule(
          objectID = "city",
          conditions =
            listOf(
              Condition(
                pattern = "{facet:city}",
                anchoring = Anchoring.entries.first { it.value == "contains" },
              )
            ),
          consequence = Consequence(params = ConsequenceParams(aroundLatLngViaIP = false)),
        ),
      ),
  )

$response = $client->saveRules(
    'INDEX_NAME',
    [
        ['objectID' => 'country',
            'conditions' => [
                ['pattern' => '{facet:country}',
                    'anchoring' => 'contains',
                ],
            ],
            'consequence' => ['params' => ['aroundLatLngViaIP' => false,
            ],
            ],
        ],

        ['objectID' => 'city',
            'conditions' => [
                ['pattern' => '{facet:city}',
                    'anchoring' => 'contains',
                ],
            ],
            'consequence' => ['params' => ['aroundLatLngViaIP' => false,
            ],
            ],
        ],
    ],
);

response = client.save_rules(
    index_name="INDEX_NAME",
    rules=[
        {
            "objectID": "country",
            "conditions": [
                {
                    "pattern": "{facet:country}",
                    "anchoring": "contains",
                },
            ],
            "consequence": {
                "params": {
                    "aroundLatLngViaIP": False,
                },
            },
        },
        {
            "objectID": "city",
            "conditions": [
                {
                    "pattern": "{facet:city}",
                    "anchoring": "contains",
                },
            ],
            "consequence": {
                "params": {
                    "aroundLatLngViaIP": False,
                },
            },
        },
    ],
)

response = client.save_rules(
  "INDEX_NAME",
  [
    Algolia::Search::Rule.new(
      algolia_object_id: "country",
      conditions: [Algolia::Search::Condition.new(pattern: "{facet:country}", anchoring: "contains")],
      consequence: Algolia::Search::Consequence.new(
        params: Algolia::Search::ConsequenceParams.new(around_lat_lng_via_ip: false)
      )
    ),
    Algolia::Search::Rule.new(
      algolia_object_id: "city",
      conditions: [Algolia::Search::Condition.new(pattern: "{facet:city}", anchoring: "contains")],
      consequence: Algolia::Search::Consequence.new(
        params: Algolia::Search::ConsequenceParams.new(around_lat_lng_via_ip: false)
      )
    )
  ]
)

val response = Await.result(
  client.saveRules(
    indexName = "INDEX_NAME",
    rules = Seq(
      Rule(
        objectID = "country",
        conditions = Some(
          Seq(
            Condition(
              pattern = Some("{facet:country}"),
              anchoring = Some(Anchoring.withName("contains"))
            )
          )
        ),
        consequence = Consequence(
          params = Some(
            ConsequenceParams(
              aroundLatLngViaIP = Some(false)
            )
          )
        )
      ),
      Rule(
        objectID = "city",
        conditions = Some(
          Seq(
            Condition(
              pattern = Some("{facet:city}"),
              anchoring = Some(Anchoring.withName("contains"))
            )
          )
        ),
        consequence = Consequence(
          params = Some(
            ConsequenceParams(
              aroundLatLngViaIP = Some(false)
            )
          )
        )
      )
    )
  ),
  Duration(100, "sec")
)

let response = try await client.saveRules(
    indexName: "INDEX_NAME",
    rules: [
        Rule(objectID: "country", conditions: [SearchCondition(
            pattern: "{facet:country}",
            anchoring: SearchAnchoring.contains
        )], consequence: SearchConsequence(params: SearchConsequenceParams(aroundLatLngViaIP: false))),
        Rule(
            objectID: "city",
            conditions: [SearchCondition(pattern: "{facet:city}", anchoring: SearchAnchoring.contains)],
            consequence: SearchConsequence(params: SearchConsequenceParams(aroundLatLngViaIP: false))
        ),
    ]
)

Query time

If a user query exactly matches a city or a country in your dataset, the rule sets aroundLatLngViaIP to false overriding any other parameters in the query. For example, if a user searches for “Paris” or “China”, matching airports are ranked by nb_airline_connections. When not searching for either a city or a country, airports are ranked by distance from the user’s location.

var response = await client.SearchSingleIndexAsync<Hit>(
  "INDEX_NAME",
  new SearchParams(new SearchParamsObject { AroundLatLngViaIP = true })
);

final response = await client.searchSingleIndex(
  indexName: "INDEX_NAME",
  searchParams: SearchParamsObject(
    aroundLatLngViaIP: true,
  ),
);

response, err := client.SearchSingleIndex(client.NewApiSearchSingleIndexRequest(
  "INDEX_NAME").WithSearchParams(search.SearchParamsObjectAsSearchParams(
  search.NewEmptySearchParamsObject().SetAroundLatLngViaIP(true))))
if err != nil {
  // handle the eventual error
  panic(err)
}

SearchResponse response = client.searchSingleIndex("INDEX_NAME", new SearchParamsObject().setAroundLatLngViaIP(true), Hit.class);

const response = await client.searchSingleIndex({
  indexName: 'indexName',
  searchParams: { aroundLatLngViaIP: true },
});

var response =
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = SearchParamsObject(aroundLatLngViaIP = true),
  )

$response = $client->searchSingleIndex(
    'INDEX_NAME',
    ['aroundLatLngViaIP' => true,
    ],
);

response = client.search_single_index(
    index_name="INDEX_NAME",
    search_params={
        "aroundLatLngViaIP": True,
    },
)

response = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(around_lat_lng_via_ip: true)
)

val response = Await.result(
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = Some(
      SearchParamsObject(
        aroundLatLngViaIP = Some(true)
      )
    )
  ),
  Duration(100, "sec")
)

let response: SearchResponse<Hit> = try await client.searchSingleIndex(
    indexName: "INDEX_NAME",
    searchParams: SearchSearchParams.searchSearchParamsObject(SearchSearchParamsObject(aroundLatLngViaIP: true))
)

Example dataset

JSON

[
  {
    "name": "Orly",
    "city": "Paris",
    "country": "France",
    "_geoloc": { "lat": 48.725278, "lng": 2.359444 },
    "nb_airline_connections": 404
  },
  {
    "name": "Charles De Gaulle",
    "city": "Paris",
    "country": "France",
    "_geoloc": { "lat": 49.012779, "lng": 2.55 },
    "nb_airline_connections": 1041
  },
  {
    "name": "Le Bourget",
    "city": "Paris",
    "country": "France",
    "_geoloc": { "lat": 48.961487, "lng": 2.436966 },
    "nb_airline_connections": 0
  },
  {
    "name": "Ben Gurion",
    "city": "Tel-Aviv",
    "country": "Israel",
    "_geoloc": { "lat": 32.011389, "lng": 34.886667 },
    "nb_airline_connections": 271
  },
  {
    "name": "Haifa",
    "city": "Haifa",
    "country": "Israel",
    "_geoloc": { "lat": 32.809444, "lng": 35.043056 },
    "nb_airline_connections": 4
  },
  {
    "name": "Pudong",
    "city": "Shanghai",
    "country": "China",
    "_geoloc": { "lat": 31.143378, "lng": 121.805214 },
    "nb_airline_connections": 825
  },
  {
    "name": "Hongqiao Intl",
    "city": "Shanghai",
    "country": "China",
    "_geoloc": { "lat": 31.197875, "lng": 121.336319 },
    "nb_airline_connections": 411
  }
]

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Enhance search results with query-based rules

Before you begin

Create the rule

Using the dashboard

Custom ranking and attributes for faceting

Using the API

Custom ranking and attributes for faceting

Create the rules

Query time

Example dataset

See also

​Before you begin

​Create the rule

​Using the dashboard

​Custom ranking and attributes for faceting

​Using the API

​Custom ranking and attributes for faceting

​Create the rules

​Query time

​Example dataset

​See also

Before you begin

Create the rule

Using the dashboard

Custom ranking and attributes for faceting

Using the API

Custom ranking and attributes for faceting

Create the rules

Query time

Example dataset

See also