Guides / Managing results / Rules / Detecting intent

Nov. 10, 2020

Adding Search Parameters Dynamically

Imagine you’re developing an app to search for airports. Algolia lets you use geolocation functionality to rank results based how far or distant an item is from a given point. The problem with this approach is that, depending on your search, the closest airport might not be the most relevant result. For example, let’s say a user is in Paris. With a geo-located search experience, the first result they may get is Le Bourget, a small airport near the center of the city that services private jets and air shows. This is an unlikely choice for a top result. Most users will be looking for Roissy CDG or Orly.

Distance-based ranking is convenient when you’re looking for airports based on your location. Yet, as soon as you start looking for specific cities or countries, distance-based ranking doesn’t necessarily work anymore. What we want is to keep geo-located results, but disable it as soon as we search for a specific city or country. In that case, we want to fall back on some other metric, like the number of liaisons. Because many Algolia settings, like aroundLatLngViaIP, are available at query time, you can use Rules to detect a search for a specific city or country and change search parameters on the fly.

Dataset Example

Back to the airports example. Imagine we have the following dataset:

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

The first thing we could do is use nb_airline_liaisons for custom ranking, so we prioritize airports with many liaisons. Yet, as soon as we set aroundLatLngViaIP to true in our search code, this custom ranking would be overridden in favor of geographical proximity, which is part of ranking formula.

For example, we would still have the Paris problem because Le Bourget, even if it has the lowest number of liaisons, has the closest geo proximity to the user.

Other examples: if a user is in Paris and searches for “israel”, they would first get Haifa airport, because this is the Israeli airport that’s the closest to Paris. Yet, it wouldn’t make sense, as Haifa airport is relatively small. “Ben Gurion” is a better choice. Same goes if they were looking for “shanghai”. Hongqiao airport is geographically closer to Paris, but not as big as Pudong airport, which is only 30 km away from Hongqiao.

We can fix this by setting a Rule that detects searches for a specific city or country and disables aroundLatLngViaIP as a consequence. Whenever a user specifically looks for a city or country name, like “paris”, “israel”, or “shanghai”, the distance-based search would be disabled, falling back on custom ranking by number of liaisons.

Using the API

To achieve this, you first need to use nb_airline_liaisons for custom ranking. You also need to set city and country as attributes for faceting, so we can detect whenever a query matches any of them.

Copy

1
2
3
4
5
6
7
$index->setSettings([
  'customRanking' => [
    'desc(nb_airline_liaisons)'
  ],
  'attributesForFaceting' => [
    'city', 'country'
]);

1
2
3
4
5
6
7
8
9
index.set_settings({
    'customRanking': [
        'desc(nb_airline_liaisons)'
    ],
    'attributesForFaceting': [
        'city',
        'country'
    ]
})

1
2
3
4
5
6
7
8
9
let settings = Settings()
  .set(\.customRanking, to: [.desc("nb_airline_liaisons")])
  .set(\.attributesForFaceting, to: ["city", "country"])

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

1
2
3
4
5
6
7
8
9
10
11
12
13
final JSONObject res = index.setSettings(
  new JSONObject().put(
    "attributesForFaceting",
    new JSONArray()
      .put("city")
      .put("country")
  )
  .put(
    "customRanking",
    new JSONArray()
      .put("desc(nb_airline_liaisons)")
  )
);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
IndexSettings settings = new IndexSettings
{
    AttributesForFaceting = new List<string>
    {
      "city",
      "country"
    },
    CustomRanking = new List<string>
    {
      "desc(nb_airline_liaisons)"
    }
};

index.SetSettings(settings);

// Asynchronous
await index.SetSettingsAsync(settings);

1
2
3
4
5
6
7
8
9
index.setSettings(
  new IndexSettings()
    .setCustomRanking(Collections.singletonList(
      "desc(nb_airline_liaisons)"
    ))
    .setAttributesForFaceting(Arrays.asList(
      "city", "country"
    ))
);

1
2
3
4
res, err := index.SetSettings(search.Settings{
  CustomRanking:         opt.CustomRanking("desc(nb_airline_liaisons)"),
  AttributesForFaceting: opt.AttributesForFaceting("city", "country"),
})

1
2
3
4
5
6
7
8
9
10
11
client.execute {
  changeSettings of "myIndex" `with` IndexSettings(
    customRanking = Some(Seq(
      CustomRanking.desc("nb_airline_liaisons")
    )),
    attributesForFaceting = Some(Seq(
      "city",
      "country"
    ))
  )
}

1
2
3
4
5
6
7
8
9
10
11
val settings = settings {
    customRanking {
        +Desc("nb_airline_liaisons")
    }
    attributesForFaceting {
        +"city"
        +"country"
    }
}

index.setSettings(settings)

Then, you can set a Rule that detects matches in facets city and country, and changes the search parameters accordingly. For this, you need to use the batchRules method.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
$index->saveRules([
  [
    'objectID' => 'country',
    'conditions' => array(array(
      'pattern' => '{facet:country}',
      'anchoring' => 'contains'
    )),
    'consequence' => [
      'params' => [
        'aroundLatLngViaIP' => false
      ]
    ]
  ],
  [
    'objectID' => 'city',
    'conditions' => array(array(
      'pattern' => '{facet:city}',
      'anchoring' => 'contains'
    )),
    'consequence' => [
      'params' => [
        'aroundLatLngViaIP' => false
      ]
    ]
  ]
]);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
index.batch_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
      }
    }
  }
])

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
index.saveRules([
  {
    objectID: 'country',
    conditions: [{
      pattern: '{facet:country}',
      anchoring: 'contains'
    }],
    consequence: {
      params: {
        aroundLatLngViaIP: false
      }
    }
  },
  {
    objectID: 'city',
    conditions: [{
      pattern: '{facet:city}',
      anchoring: 'contains'
    }],
    consequence: {
      params: {
        aroundLatLngViaIP: false
      }
    }
  }
]).then(() => {
  // done
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
index.save_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
            }
        }
    }
])

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
let rules: [Rule] = [
  Rule(objectID: "country")
    .set(\.conditions, to: [
      Rule.Condition()
        .set(\.anchoring, to: .contains)
        .set(\.pattern, to: .facet("country"))
    ])
    .set(\.consequence, to: Rule.Consequence()
      .set(\.query, to: Query()
        .set(\.aroundLatLngViaIP, to: false)
      )
    ),
  Rule(objectID: "country")
    .set(\.conditions, to: [
      Rule.Condition()
        .set(\.anchoring, to: .contains)
        .set(\.pattern, to: .facet("city"))
    ])
    .set(\.consequence, to: Rule.Consequence()
      .set(\.query, to: Query()
        .set(\.aroundLatLngViaIP, to: false)
      )
    )
]

index.saveRules(rules) { 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
25
26
27
28
29
30
31
32
33
34
35
36
var rule1 = new Rule
{
  ObjectID = "country",
  Conditions = new List<Condition>
  {
    new Condition { Anchoring = "contains", Pattern = "{facet:country}" }
  },
  Consequence = new Consequence
  {
    Params = new ConsequenceParams
    {
        AroundLatLngViaIP = false
    }
  }
};

var rule2 = new Rule
{
  ObjectID = "city",
  Conditions = new List<Condition>
  {
    new Condition { Anchoring = "contains", Pattern = "{facet:city}" }
  },
  Consequence = new ConsequenceParams
  {
    Params = new ConsequenceParams
    {
        AroundLatLngViaIP = false
    }
  }
};

index.SaveRules(new List<Rule> { rule1, rule2 });

// Asynchronous
await index.SaveRulesAsync(new List<Rule> { rule1, rule2 });

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
ConsequenceParams params = new ConsequenceParams();
params.setAroundLatLngViaIP(false);

index.saveRules(
    Arrays.asList(
        new Rule()
            .setObjectID("country")
            .setConditions(Collections.singletonList(
                new Condition().setPattern("{facet:country}").setAnchoring("contains"))
            )
            .setConsequence(new Consequence().setParams(params)),
        new Rule()
            .setObjectID("city")
            .setCondition(new Condition().setPattern("{facet:city}").setAnchoring("contains"))
            .setConsequence(new Consequence().setParams(params))));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
rules := []search.Rule{
	{
		ObjectID:  "country",
		Condition: []search.RuleCondition{{Anchoring: search.Contains, Pattern: "{facet:country}"}},
		Consequence: search.RuleConsequence{
			Params: &search.RuleParams{
				QueryParams: search.QueryParams{
					AroundLatLngViaIP: opt.AroundLatLngViaIP(true),
				},
			},
		},
	},
	{
		ObjectID:  "city",
		Conditions: []search.RuleCondition{{Anchoring: search.Contains, Pattern: "{facet:city}"}},
		Consequence: search.RuleConsequence{
			Params: &search.RuleParams{
				QueryParams: search.QueryParams{
					AroundLatLngViaIP: opt.AroundLatLngViaIP(true),
				},
			},
		},
	},
}

res, err := index.SaveRules(rules)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
client.execute {
  save rules Seq(
    Rule(
      objectID = "country",
      conditions = Some(Seq(Condition(
        pattern = "{facet:country}",
        anchoring = "contains"
      ))),
      consequence = Consequence(
        params = Some(Map("aroundLatLngViaIP" -> true))
      )
    ),
    Rule(
      objectID = "city",
      conditions = Some(Seq(Condition(
        pattern = "{facet:city}",
        anchoring = "contains"
      ))),
      consequence = Consequence(
        params = Some(Map("aroundLatLngViaIP" -> true))
      )
    )
  ) inIndex "myIndex"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
val country = Attribute("country")
val city = Attribute("city")
val rules = listOf(
    Rule(
        objectID = ObjectID("country"),
        conditions = listOf(Condition(Anchoring.Contains, Pattern.Facet(country))),
        consequence = Consequence(
            query = Query(aroundLatLngViaIP = false)
        )
    ),
    Rule(
        objectID = ObjectID("city"),
        conditions = listOf(ondition(Anchoring.Contains, Pattern.Facet(city))),
        consequence = Consequence(
            query = Query(aroundLatLngViaIP = false)
        )
    )
)

index.saveRules(rules)

Using the Dashboard

You can also add your Rules in your Algolia dashboard.

Custom ranking

Go to your dashboard and select your target index.
Click on the Configuration tab.
In the Ranking and Sorting section, click the “Add a Custom Ranking” button and select the nb_airline_liaisons attribute from the dropdown.
In the Facets subsection of Filtering and Faceting, click the “Add an attribute” button and select the country and city attributes from the dropdown.
Save your changes.

Rules

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 select the option Add Facet “country” from the input dropdown. {facet:country} should then be displayed in the input.
In the Consequence(s) section:
- Click the Add consequence button and select Add Query Parameter.
- In the input field that appears, add the JSON parameters you want to apply when the user’s query matches the Rule: { "aroundLatLngViaIP": false }
Don’t forget to save your changes.
Click the New Rule button again and then Manual Editor.
In the Condition(s) section, keep Query toggled on, select Contains in the dropdown, and select the option Add Facet “city” from the input dropdown. {facet:city} should then be displayed in the input.
In the Consequence(s) section:
- Click the Add consequence button again and select Add Query Parameter.
- In the input field that appears, add the JSON parameters you want to apply when the user’s query matches the Rule: { "aroundLatLngViaIP": false }
Don’t forget to save your changes.

Query time

Once your Rule is ready, you can search for airports, cities, and countries. When the query exactly matches a city or a country from your dataset, the Rule sets aroundLatLngViaIP to false regardless of the parameters you set in the query.

Therefore, when a user searches for “paris” or “china”, matching airports are ranked by nb_airline_liaisons. When not searching for either a city or a country, airports are ranked by distance to the user’s current location.

Copy

1
2
3
$results = $index->search('query', [
  'aroundLatLngViaIP' => true
]);

1
2
3
4
5
6
7
8
9
let query = Query()
  .set(\.query, to: "query")
  .set(\.aroundLatLngViaIP, to: true)

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

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

Adding Search Parameters Dynamically

On this page

Dataset Example

Using the API

Using the Dashboard

Custom ranking

Rules

Query time

Did you find this page helpful?

On this page