Sorting Results Within an App Search

How to Sort Results
Sorting by Multiple Values
Sorting by Relevancy and Another Value
Sorting by Geo Location

If you are searching within an app you can control the order that results are returned. By default search results are returned in order of relevance with the most relevant result first.

For example, you could choose to return results ordered by the item name or by their published date.

Note that sorting does not work with full site search as that will always return results ordered by relevance. This feature only works when you are using the search forms provided by an individual app, like the General App for example.

How to Sort Results

To change the sorting of the search results you need to include at least field in the app search form that sets how to sort. This will often be a hidden field but you could use another field type if you want to give the user choice over sorting.

There are three formats that are accepted: Simple, Advanced Multiple Fields, Advanced Single Field.

The Simple format is the most common one used and it can be used to set one or more fields to sort by and the sort order.

The Advanced Multiple Fields format allows you to set the sort mode in addition to the field to sort by and it's sort order. You can do this for one or more fields.

The Advanced Single Field format allows you to set the sort mode in addition to one field to sort by and it's sort order.

Sort Mode

The sort mode is usually not needed unless you are sorting by a field that may have one or more values, like a set of checkboxes or multi-select field. The sort mode essentially tells the search engine how to combine the multiple values to sort the field.

Sort modes are: 'min', 'max', 'avg' (for average), or 'sum'. 'min' is the default for multi-value fields.

Simple Format

Here is an example of the simple sort format.

You would replace "APP_ATTRIBUTE_LAYOUT_KEY" with the layout key of the app item attribute that you want to sort by. And you would replace "SORT_ORDER" with the appropriate sort order value. For example, to sort by publish date in descending order you would have a tag like this.

Allowed field values are 'desc' for descending sort order and 'asc' for ascending sort order.

With this format you can specify multiple fields to sort by with different orders. For example, say we were searching in the General App. For each item we have an attribute called 'Favorite Color' with a layout key of 'favoriteColor' and another attribute called 'Gender' with a layout key of 'gender'. We want to return results ordered first by color in descending order and then by gender is ascending order. This will return results ordered by color and within each color grouped by gender.

Advanced Multiple Fields Format

The advanced multiple fields format is really only useful if you need to specify the sort mode in addition to the field to sort by. You can set the sort order and sort mode for multiple fields with this format.

You would replace "APP_ATTRIBUTE_LAYOUT_KEY" with the layout key of the app item attribute that you want to sort by. You would replace "SORT_ORDER" with the appropriate sort order value and replace "SORT_MODE" with the appropriate sort mode value.

For example, if you had a checkbox field for favorite ice cream with a layout key of "favoriteIceCream" and you wanted to sort in descending order using the maximum value you would have tags like this.

Advanced Single Field Format

The advanced single field format requires two fields. One to specify the field to sort by and the other to specify the direction to sort by. You can also optionally set the sort mode.

For example, to sort by publish date in descending order you would have a tag like this.

Note that if you didn't include the "sort[_order]" field that sorting would default to 'asc'.

Sorting by Multiple Values

With some of the formats listed above you can specify multiple fields to sort by with different orders. For example, say we were searching in the General App. For each item we have an attribute called 'Favorite Color' with a layout key of 'favoriteColor' and another attribute called 'Gender' with a layout key of 'gender'. We want to return results ordered first by color in descending order and then by gender is ascending order. This will return results ordered by color and within each color grouped by gender.

If you are sorting by multiple fields the order that the sort data is submitted is important. Sorting will be done in the order that the sort fields are submitted.

Using the Simple format your fields would be:

Using the Advanced Multiple Fields format your fields would be:

Sorting by Relevancy and Another Value

By default if no sort values are specified then search results will be returned in order of relevancy with the most relevant first.

Sometimes you might want to maintain that relevancy sorting but also sort by another value within items that have the same relevancy.

To do that you would need to pass a sort value to use relevancy. You would want the relevancy to be the first sort value passed as the order of sort values does matter.

For a full example say that we wanted to sort by relevancy and then by a field called "Town" that has a layout key of "town". Using the Simple format your fields would be:

Sorting by Geo Location

If the items that you are searching have geo location attributes (i.e. Map Latitude & Longitude) you can sort search results by their distance from a specific latitude/longitude point. You would do this by using text or hidden form fields.

The fields for sorting by geo location are as follows:

sort[_geo][APP_ATTRIBUTE_LAYOUT_KEY][lat]
sort[_geo][APP_ATTRIBUTE_LAYOUT_KEY][lon]
sort[_geo][APP_ATTRIBUTE_LAYOUT_KEY][order]
sort[_geo][APP_ATTRIBUTE_LAYOUT_KEY][unit]

You would replace "APP_ATTRIBUTE_LAYOUT_KEY" with the layout key of the app item attribute that you want to sort by.

You can sort by multiple geo location attributes if you want.

In the examples below we're going to assume that we have a Map Latitude & Longitude attribute called "Map Point" with a layout key of "mapPoint".

sort[_geo][APP_ATTRIBUTE_LAYOUT_KEY][lat]

The sort[_geo][APP_ATTRIBUTE_LAYOUT_KEY][lat] field sets the latitude value to use in the sort searching. The latitude value is expressed in decimal degrees. Positive latitudes are north of the equator, negative latitudes are south of the equator.

For example, the latitude / longitude values for Lima, Peru are 12.0433° S, 77.0283° W. The latitude value is "South" so it's value would be "-12.0433". To sort by our "Map Point" attribute the latitude field would be:

The latitude / longitude values for Paris, France are 48.8567° N, 2.3508° E. The latitude value is "North" so it's value would be "48.8567". To sort by our "Map Point" attribute the latitude field would be:

sort[_geo][APP_ATTRIBUTE_LAYOUT_KEY][lon]

The sort[_geo][APP_ATTRIBUTE_LAYOUT_KEY][lon] field sets the longitude value to use in the sort searching. The longitude value is expressed in decimal degrees. Positive longitudes are east of prime meridian, negative longitudes are west of the prime meridian.

For example, the latitude / longitude values for Lima, Peru are 12.0433° S, 77.0283° W. The longitude value is "West" so it's value would be "-77.0283". To sort by our "Map Point" attribute the longitude field would be:

The latitude / longitude values for Paris, France are 48.8567° N, 2.3508° E. The longitude value is "East" so it's value would be 2.3508. To sort by our "Map Point" attribute the longitude field would be:

sort[_geo][APP_ATTRIBUTE_LAYOUT_KEY][order]

The optional sort[_geo][APP_ATTRIBUTE_LAYOUT_KEY][order] field holds the display order to sort the search results. The available values are "asc" or "desc". To sort results so that the closest items are returned first use "asc". Using "desc" will return results with the items furthest away from the submitted latitude/longitude values first.

If this field is not used then the display order will default to "asc".

To sort by our "Map Point" attribute the order field would be:

sort[_geo][APP_ATTRIBUTE_LAYOUT_KEY][unit]

The optional sort[_geo][APP_ATTRIBUTE_LAYOUT_KEY][unit] field holds the distance unit to return sort values in. If you are sorting by a geo location then for each search result an extra value will be included to give the distance from the submitted latitude and longitude. The value is 'sortData'. Here is an example:

[sortData] => Array (
'sort' => Array(
[mapPoint] => 308.83673260657
)
)

The 'sortData' array contains information about sorting for each attribute that you are sorting by. In this case we're sorting by the 'mapPoint' attribute so the value shows how far away this search result is from the submitted latitude/longitude values.

You can specify whether the sortData value should be in miles or kilometers. The default is "mi" for miles.

To specify miles use "mi". For example, sorting with our "Map Point" attribute the unit field would be:

To specify kilometers use "km". For example, sorting with our "Map Point" attribute the unit field would be:

Full Geo Sorting Examples

To put it all together, you might have the following fields to sort results in ascending kilometer distance from Paris, France using an attribute whose layout key is "mapPoint". Notice that "asc" is the default sort order so we don't need to specify the sort[_geo_distance][order] value.

You can combine the _score sort field to allow calculating geo distance sort values while maintaining the search results ordering by score.

Using the General App as an example, you can also order search results by item name, then by geo distance, and then by score, providing you with results that are ordered by item name and include distance and match score values.