Sorting search results in SharePoint

Sort search results programmatically—by ran k, by managed property value, by a formula expression, or in random order—by using the Query object model in SharePoint.

You can sort the search results for SharePoint in four ways:

• Sort search results by rank: Enables you to sort the search result by relevance rank.

• Sort search results by managed property value: Enables you to sort the search result based on the value of one or more managed properties.

• Sort search results by a formula expression: Enables you to sort the search result by a formula specified in the query request.

• Sort search results in random order: Enables you to sort the query result in random order, or add a random component to the sort order.

This article focuses on sorting search results programmatically. To learn how to sort search results using SharePoint query rules, see the following articles:

• Change ranked search results in Manage query rules

• Change ranked search results in Create query rules for web content management

How to specify sorting in a query request

When you use the Query object model, you can choose the sort criteria by providing a sort specification through the SortList property of the KeywordQuery class. The SortList property is of type SortCollection, which represents a collection of Sort objects.

A Sort object defines a way to sort search results; it consists of a value you want to order search results on (Property) and a direction in which you want to order the results (Direction). The direction is of type SortDirection() and can be ascending or descending.

If you have multiple values in SortList, the sorting is performed based on the sequence in which the values appear. This means that every Sort object represents a sort order level. Any succeeding level does not change the ordering of results that were differentiated by previous ones, but it may affect the internal ordering of results that have the same sort values for the previous levels.

Apart from the Query object model, SharePoint also provides a Search REST service that you can use to query the search index with your client or mobile applications. The Search REST service supports both HTTP POST and HTTP GET requests. For more information on how to construct URIs for these requests, see Querying with the Search REST service.

Sort search results by rank

By default, search results are sorted by relevance rank. This means that SharePoint places the most relevant results on top in the search result set. If you sort by rank, the results are always sorted in descending order. But you can change the sort order to ascending by using SortDirection().

You can also influence the rank calculation in the query string, in one of two ways:

• By using the XRANK operator available in Keyword Query Language (KQL) syntax reference and FAST Query Language (FQL) syntax reference. You can use XRANK to apply a conditional rank boosting if a specific query condition is met.

• By choosing a relevance weight for dynamic ranking. When using FQL, you can specify an individual relevance weight for each STRING operator.

Sort search results by managed property value

You can specify search result sorting based on the value of one or more managed properties. This means that SharePoint performs the sorting based on all results that match the query.

You can sort based on text and numeric properties. For text properties, the sorting is based on standard text string sorting. In contrast, for numeric properties (including managed properties of type DateTime), the sorting is based on numeric value.

Example

The following example shows how to sort search results by using the Size managed property.

using (var context = new ClientContext("http://localhost"))
{
    var query = new KeywordQuery(context)
    {
        QueryText = "home"
    };
    query.SortList.Add("Size", SortDirection.Descending);

    var executor = new SearchExecutor(context);
    var results = executor.ExecuteQuery(query);

    context.ExecuteQuery();

    foreach (var result in results.Value[0].ResultRows)
    { 
        Console.WriteLine(result["Title"] + " Size:" + result["Size"]);
    }
}

Alternatively, you could use the Search REST API to sort search results by using the Size property with the following call.

http://localhost/_api/search/query?querytext='home'&sortlist='size:descending'

Sort search results by a formula expression

You can specify search result sorting based on a sort specification that uses a mathematical formula to create the sorting value.

The sort by formula feature is an extension of the single-level and multilevel sorting functionality for search results. The feature enables you to specify a formula instead of a managed property as sorting criteria.

By using the sort by formula feature, you can apply mathematical operations on the value of one or more managed properties for each item in the query result.

The following are examples that can be implemented by using a formula to specify search result sorting:

• K-nearest neighbor algorithm to classify documents.

• Euclidean distance or Manhattan distance to calculate geographical distances.

• Preferred value, for example, to sort documents based on how far a given managed property value is from a preferred value.

The sort by formula feature does not include control of statistical dynamic rank parameters, such as term frequency and proximity.

The formula is evaluated left to right and uses standard mathematical-operator precedence. That is, functions and parenthetical groups are evaluated first, multiplication and division operations are performed next, and addition and subtraction operations are performed last.

Specifying the sort formula in a query

You specify a sort formula instead of a managed property in the sort specification of the query request.

The sort specification has the following format: [formula:<sort-formula>]

In the format, <sort-formula> is the sort formula expression.

The default sort direction is descending. You may also use a formula that sorts by ascending value, for example, if the formula specifies a geographical distance.

The following code example shows how to specify sort by formula with ascending sort order by using the Query object model.

using (var context = new ClientContext("http://localhost"))
{
    var query = new KeywordQuery(context)
    {
        QueryText = "home"
    };
    query.SortList.Add("[formula:abs(2000-size)]", SortDirection.Ascending);

    var executor = new SearchExecutor(context);
    var results = executor.ExecuteQuery(query);

    context.ExecuteQuery();

    foreach (var result in results.Value[0].ResultRows)
    { 
        Console.WriteLine(result["Title"]);
    }
}

Alternatively, you could use the Search REST API to sort search results by using the Size property with the following call.

http://localhost/_api/search/query?querytext='home'&sortlist='[formula:abs(2000-size)]:ascending'

Using managed properties in the sort formula

You can apply a sort formula on the value of managed properties of type Integer, Decimal, and Datetime(). You must enable sorting for the specified managed property in the search schema.

For more managed properties of type Decimal, the value is multiplied by 10^(decimal digits) before being used in the formula evaluation.

For managed properties of type Datetime()](/previous-versions/office/developer/sharepoint-2010/ms500214(v%3Doffice.14)), the value is converted to the number of 100 nanoseconds since January 1 29000 BC before being used in the formula evaluation. There are 366 days in the year.

Sort formula expressions

Table 1 lists the functions you can use in the sort formula expression. The expression must not contain spaces.

Table 1. Functions for sort formula expressions

Performance characteristics for sort by formula

Using a sort formula implies that the formula calculations are applied to all matching items in the result set. This means that the query performance impact depends on the number of items that match the query.

Long formulas with many operators require more processing time than short formulas.

Using sort by formula for geographical distance

You can use sort by formula to apply a ranking based on distance. This requires that you include managed properties that represent the latitude and longitude of each item.

For example, you can use one of the following standard formulas:

• Manhattan distance

• Euclidian distance (see example 2)

• Haversine formula

Examples

The following examples show how to specify the sort formula using the Query object model.

Example 1. Place the items that have the height managed property closest to 20 on top of the result list.

using (var context = new ClientContext("http://localhost"))
{
    var query = new KeywordQuery(context)
    {
        QueryText = "home"
    };
    query.SortList.Add("[formula:abs(20-height)]", SortDirection.Ascending);

    var executor = new SearchExecutor(context);
    var results = executor.ExecuteQuery(query);

    context.ExecuteQuery();

    foreach (var result in results.Value[0].ResultRows)
    { 
        Console.WriteLine(result["Title"]);
    }
}

Alternatively, you could use the Search REST API to place the items that have the height managed property closest to 20 on top of the result list, with the following call.

http://localhost/_api/search/query?querytext='home'&sortlist='[formula:abs(20-height)]:ascending

Example 2. Sort by true 3-D Euclidean distance from a given position (for example, user's position) based on position information that is provided in the managed properties latitude, longitude and height. The following formula provides the 3-D Euclidean distance, given that the base position is 50/100/200 (latitude/longitude/height).

sqrt(pow(50-latitude,2)+pow(100-longitude,2)+pow(200-height,2))

If you want to apply a distance-based sorting (not combining the distance with other parameters in a formula), you can remove the sqrt() component, as it does not change the sorting sequence; but it improves the query performance.

using (var context = new ClientContext("http://localhost"))
{
    var query = new KeywordQuery(context)
    {
        QueryText = "home"
    };
    query.SortList.Add("[formula:pow(50-latitude,2)+pow(100-longitude,2)+pow(200-height,2)]", SortDirection.Ascending);

    var executor = new SearchExecutor(context);
    var results = executor.ExecuteQuery(query);

    context.ExecuteQuery();

    foreach (var result in results.Value[0].ResultRows)
    { 
        Console.WriteLine(result["Title"]);
    }
}

Example 3. Round the values of size into buckets, rounding values down to one of the following: 0, 5, 15, 50, 100; sort with largest values first.

using (var context = new ClientContext("http://localhost"))
{
    var query = new KeywordQuery(context)
    {
        QueryText = "home"
    };
    query.SortList.Add("[formula:bucket(size,5,15,50,100)]", SortDirection.Ascending);

    var executor = new SearchExecutor(context);
    var results = executor.ExecuteQuery(query);

    context.ExecuteQuery();

    foreach (var result in results.Value[0].ResultRows)
    { 
        Console.WriteLine(result["Title"]);
    }
}

Sort search results in random order

You may apply random sorting of the query result, or add a random component to the result sorting.

The random sort specification has the following format: [random:seed=<seed>:hashfield=<managed property>]

Table 2 explains the parameters to the random sort specification.

Table 2. Parameters for the random sort specification

By providing the same seed for equal queries, items will be presented in the same order. This enables you to preserve the same random order when paging through search results. Use the hashfield parameter if you want to preserve the same random order when an index update accidentally occurs between the queries.

Examples

The following examples show how to specify random sorting by using the Query object model.

Example 1. Sort the entire result set in random order.

using (var context = new ClientContext("http://localhost"))
{
    var query = new KeywordQuery(context)
    {
        QueryText = "home"
    };
    query.SortList.Add("[random:seed=5432]", SortDirection.Ascending);

    var executor = new SearchExecutor(context);
    var results = executor.ExecuteQuery(query);

    context.ExecuteQuery();

    foreach (var result in results.Value[0].ResultRows)
    { 
        Console.WriteLine(result["Title"]);
    }
}

Alternatively, you could use the Search REST API to sort the entire result set in random order, with the following call.

http://localhost/_api/search/query?querytext='home'&sortlist='[random:seed=5432]:ascending

Example 2. Sort the entire result set in random order. Preserve the same random sequence for the same query with the same seed, even if an index switch occurs. A custom managed property named hashvalue must be available in the search schema, and populated with random or sequential numeric values for all indexed items.

using (var context = new ClientContext("http://localhost"))
{
    var query = new KeywordQuery(context)
    {
        QueryText = "home"
    };
    query.SortList.Add("[random:seed=6543:hashfield=hashvalue]", SortDirection.Ascending);

    var executor = new SearchExecutor(context);
    var results = executor.ExecuteQuery(query);

    context.ExecuteQuery();

    foreach (var result in results.Value[0].ResultRows)
    { 
        Console.WriteLine(result["Title"]);
    }
}

See also

• Search in SharePoint
• Keyword Query Language (KQL) syntax reference
• FAST Query Language (FQL) syntax reference
• SharePoint Search REST API overview
• Overview of crawled and managed properties in SharePoint