Sorting

Sorting can be achieved by using a ranking expression to update the ranking of results based on the field you want to sort on. See below for common examples.

Note about ranking expressions
Ranking expressions can significantly change the search results. We recommend experimenting with very small values, and testing the results across many queries to ensure they're having the desired affect. In cases where there are very few relevant results, ranking expressions may not be effective. If you are having issues with ranking expressions, contact support.

Read more about ranking expressions here: Ranking expressions

Sort by relevance score

Sorting by relevance score is the default behavior of the search API. No changes are required to sort results by relevance.

Behind the scenes
This is achieved by setting the ranking expression to the following, which is the default value:

ranking_expr=uncalibrated_relevance

Exhaustive vs Relevance sorting

Exhaustive sorting refers to sorting all of the results strictly by the field you're sorting on. Relevance sorting refers to combining relevance with the sorted field, to ensure that the results remain relevant while applying the sort.

When should I use Exhaustive vs Relevance sorting?
Using exhaustive sort risks harming relevance, push results to the top that are irrelevant, even though they match the sorting criteria. To avoid this, we recommend using ranking signals to rank the results by the sorted field, but also factoring in relevance, called Relevance sorting. This typically leads to better results for users.

Exhaustive sorting

Exhaustive sorting is achieved by overriding the ranking expression to contain only the field you want to sort by.

Examples

Sort by rating

Assume the index contains objects like:

# Common e-commerce data structure
{
  "title": "YUEDGE 5 Pairs Men's Moisture Control Cushioned Dry Fit Casual Athletic Crew Socks for Men (Blue, Size 9-12)",
  "average_rating": 4.6,
  "images": [...],
  ...other fields
}

Sort highest to lowest

We can sort the results by the average_rating field by setting the ranking expression to:

ranking_expr=object.average_rating

$ curl --request GET \
  --url 'https://api.objective.inc/v1/indexes/.../search?query=shoes&object_fields=title%2Caverage_rating&ranking_expr=object.average_rating' \
  --header 'Authorization: Bearer ...' \

# Results sorted by "average_rating"
{
	"results": [
		{
			"id": "B07MZK68W8",
			"object": {
				"title": "GAOAG Sport Shoes Lightweight Breathable Shoes Casual Shoes Unisex Cushioning Speed Quick Drying Easy Walking Black",
				"average_rating": 5
			},
		},
		{
			"id": "B01NBKRZ8R",
			"object": {
				"title": "QZbeita Net Surface Breathable Sneakers Male Leisure Running Shoes Low Sandals for Man,Orange,7.5 D(M) US",
				"average_rating": 5
			},
		},
	...

Sort lowest to highest

To invert the sort, update the ranking expression to subtract the value of the average_rating field from the field's largest value. In this case, the ratings can go from 1-5, so we subtract the value from 5. Updated expression:

ranking_expr=5 - object.average_rating

$ curl --request GET \
  --url 'https://api.objective.inc/v1/indexes/.../search?query=shoes&object_fields=title%2Caverage_rating&ranking_expr=5%20-%20object.average_rating' \
  --header 'Authorization: Bearer ...'

# Results sorted by "average_rating"
{
	"results": [
		{
			"id": "B08SGRW9ZD",
			"object": {
				"average_rating": 1,
				"title": "Akk Kids Shoes Boys Sneakers - Lightweight Walking Shoes Slip on Breathable Tennis Athletic Sports Shoes Grey Size 11"
			},
		},
		{
			"id": "B09BN511YJ",
			"object": {
				"average_rating": 1,
				"title": "UOVO Boys Shoes Boys Tennis Running Sneakers Waterproof Hiking Shoes Kids Outdoor Fashion Sneakers Slip Resistant (Big/Little Boys) Blue/Orange"
			},
		},
	...

Sort by price

Assume the index contains objects like:

# Common e-commerce data structure
{
  "title": "YUEDGE 5 Pairs Men's Moisture Control Cushioned Dry Fit Casual Athletic Crew Socks for Men (Blue, Size 9-12)",
  "price": 14.99,
  ...other fields
}

Sort highest to lowest

We can sort the results by the price field by setting the ranking expression to:

ranking_expr=object.price

Sort lowest to highest

To invert the sort, update the ranking expression to subtract the value of the price field from a value that is larger than the largest price will ever be. In this case, I'm using 1000. Updated expression:

ranking_expr=1000 - object.price

How does this work?
By subtracting the price from a large number, we invert the scores of the prices. For example, if the cheapest item is $1, and the most expensive is $100, then the values after the ranking expression will be:

1000 - 1 = $999
1000 - 100 = $900

Since $999 is higher than $900, the item with the price of $1 will rank higher than the one whose price is $100, sorting by lowest to highest.

Relevance sorting

Relevance sorting is achieved by using ranking signals in the ranking_expr= parameter to combine relevance with the field you want to sort by. See examples below.

Examples

Sort by rating

This example also applies to other integer or float based values such as price.

Assume the index contains objects like:

# Common e-commerce data structure
{
  "title": "YUEDGE 5 Pairs Men's Moisture Control Cushioned Dry Fit Casual Athletic Crew Socks for Men (Blue, Size 9-12)",
  "average_rating": 4.6,
  "images": [...],
  ...other fields
}

We can sort by rating by building a ranking expression that incorporates the field average_rating into the ranking. A naive ranking expression would be to add the rating to the relevance score:

ranking_expr=uncalibrated_relevance + object.average_rating

Results on the query "shoes"

Before:

$ curl --request GET \
  --url 'https://api.objective.inc/v1/indexes/.../search?query=shoes&object_fields=title%2Caverage_rating&ranking_expr=uncalibrated_relevance' \
  --header 'Authorization: Bearer ...' \
{
	"results": [
		{
			"id": "B07MZK68W8",
			"object": {
				"average_rating": 5,
				"title": "GAOAG Sport Shoes Lightweight Breathable Shoes Casual Shoes Unisex Cushioning Speed Quick Drying Easy Walking Black"
			},
		},
		{
			"id": "B07MDVKVXZ",
			"object": {
				"title": "HIITAVE Men/Womens Trail Running Barefoot Shoes Lightweight Gym Athletic Walking Shoes for Outdoor Sports Cross TrainerBlack/Gray/Yellow 10 Women/9 Men",
				"average_rating": 4.3  # <----- NOTE rating
			},
		},
		{
			"id": "B00IO23QTI",
			"object": {
				"title": "Dr. Comfort Cindee Dress Heels Diabetic Shoes for Women-Easy Off-Leather Therapeutic Shoes with Removable Insoles",
				"average_rating": 3.8  # <----- NOTE rating
			},
		},
    ...

After:

$ curl --request GET \
  --url 'https://api.objective.inc/v1/indexes/.../search?query=shoes&object_fields=title%2Caverage_rating&ranking_expr=uncalibrated_relevance%20%2B%20object.average_rating' \
  --header 'Authorization: Bearer ...' \
{
	"results": [
		{
			"id": "B07MZK68W8",
			"object": {
				"title": "GAOAG Sport Shoes Lightweight Breathable Shoes Casual Shoes Unisex Cushioning Speed Quick Drying Easy Walking Black",
				"average_rating": 5
			},
		},
		{
			"id": "B01NBKRZ8R",
			"object": {
				"average_rating": 5,  # <----- NOTE rated 5
				"title": "QZbeita Net Surface Breathable Sneakers Male Leisure Running Shoes Low Sandals for Man,Orange,7.5 D(M) US"
			},
		},
		{
			"id": "B01H9XVCZM",
			"object": {
				"title": "Women's Platform Suede Leather Trainers Breathable Height-increasing Fitness Work Out Sneaker Running Shoes (8 US 39EU, Grey)",
				"average_rating": 5  # <----- NOTE rated 5
			},
		},
    ...

Notice how all of the top results are rated "5" in the second set of results.

A safer approach

As noted at the top of this page, ranking expressions should be used carefully. It's safer to use small values when applying a ranking expression. In this example, we can normalize the ratings and take 1/10th of the value to reduce the score and still get the expected results. To do that, use this expression:

ranking_expr=uncalibrated_relevance + (0.1 * (object.average_rating / 5))

Doing so leads to the same results, but in a safer way:

$ curl --request GET \
  --url 'https://api.objective.inc/v1/indexes/.../search?query=shoes&object_fields=title%2Caverage_rating&ranking_expr=uncalibrated_relevance%20%2B%20(0.1%20*%20(object.average_rating%20%2F%205))' \
  --header 'Authorization: Bearer ...' \
{
	"results": [
		{
			"id": "B07MZK68W8",
			"object": {
				"average_rating": 5,
				"title": "GAOAG Sport Shoes Lightweight Breathable Shoes Casual Shoes Unisex Cushioning Speed Quick Drying Easy Walking Black"
			},
		},
		{
			"id": "B01NBKRZ8R",
			"object": {
				"title": "QZbeita Net Surface Breathable Sneakers Male Leisure Running Shoes Low Sandals for Man,Orange,7.5 D(M) US",
				"average_rating": 5
			},
		},
		{
			"id": "B01H9XVCZM",
			"object": {
				"title": "Women's Platform Suede Leather Trainers Breathable Height-increasing Fitness Work Out Sneaker Running Shoes (8 US 39EU, Grey)",
				"average_rating": 5
			},
		},
    ...