In this article

Query Refinement in SharePoint

In this article

Learn how to use SharePoint query refinement features programmatically when you are working with search queries and results.
You can use query refinement features to provide end users with refinement options that are relevant for their queries. These features let the end user drill down into search results by using refinement data computed for the results. Refinement data is calculated by the index component, based on the aggregation of managed property statistics for all of the results of a search query.

Typically, query refinement is used for metadata associated with the indexed items, such as creation date, author, or file types that appear in the item. By using the refinement options, you can refine your query to display only items created during a certain time period, or display only items of a specific file type.

Using refiners in the Query Object Model

There are two queries involved in query refinement:

You can request for a set of refiners to be returned in the search results by adding a refiner spec to the end user's query. A refiner spec is the input for the Refiners property. This query is run against the search index. The search results will consist of relevant results and refinement data.

You can use the refinement data to drill down into the search results by, creating a refined query. Add the RefinementFilters property to the query so that the final search results will meet the requirements of both the original query text from the end user and the selected refinement option from the refinement data.

The following sections describe these steps in detail, and provide code examples.

Adding refiners to the end-user's query by using refiner specs

You can specify the requested query refiners by using the Refiners property of the KeywordQuery class. Use the following syntax to specify the requested query refiners:

<refiner>[,<refiner>]*

Each refiner has the following format:

<refiner-name>[(parameter=value[,parameter=value]*)]?

Where:

<refiner-name> is the name of the managed property associated with the refiner. This managed property must be set to Refinable or Sortable in the search schema.

The optional list of parameter=value pairs specifies non-default configuration values for the named refiner. If a parameter for a refiner is not listed inside the parentheses, the search schema configuration gives you the default setting. Table 1 lists possible values for the parameter=value pairs.

Note

When you specify refiners, the minimum requirement is to specify a refiner-name, which is a managed property.

Example

Refiners = "FileType"

Or, you can also use the advanced syntax to adjust the refiner settings.

Overrides the default number of hits that is used as the basis for refinement computation. When refiners are produced, all results for the query will be evaluated. Normally, using this parameter will improve search performance. Syntaxdeephits=<integer value>Exampleprice(deephits=1000)Note: This limit applies within each index partition. The actual number of hits that are evaluated will be larger than this value due to the aggregation across search partitions.

discretize

Specifies custom intervals (refinement bins) for numeric refiners. Syntaxdiscretize=manual/<threshold>/<threshold>[/<threshold>]*Examplewrite(discretize=manual/2013-01-01/2013-08-22/2013-09-15/2013-09-21/2013-09-22)The <threshold> attribute specifies the threshold for each refinement bin. There is one interval for everything below the first threshold specified, one interval between each consecutive threshold, and one interval for everything above the last threshold. For a refiner of type DateTime, specify the threshold according to one of the following ISO 8601-compatible formats:

Important: All date/time values must be specified according to the Coordinated Universal Time (UTC), also known as Greenwich Mean Time (GMT) zone. The UTC zone identifier (a trailing "Z" character) is optional.

sort

Defines how to sort the bins within a string refiner. Syntaxsort=<property>/<direction>The attributes perform the following:

number - Treats the strings as numeric and uses numeric sorting. This value can be useful to specify discrete values, for example, to perform numeric sorting of a value that is contained in a managed property of type String.

Defines how bins within a refiner of type String are filtered before they are returned to the client. Syntaxfilter=<bins>/<freq>/<prefix>[<levels>]The attributes perform the following:

<bins> - Specifies the maximum number of returned bins. After sorting the bins within the refiner, use this attribute to truncate any trailing bins. For example, if bins=10, only the first 10 bins are returned, according to the specified sorting algorithm.

<freq> - Limits the number of returned bins. Use this attribute to remove bins that have low frequency counts. For example, freq=2 indicates that only the bins with 2 or more members are returned.

<prefix> - Specifies that only bins with a name that begins with this prefix are returned. The wildcard character "*" will match all names. Examplefilter=30/2/*

<levels> - Specifies the levels of taxonomy. Use this attribute to filter hierarchical refiner output based on taxonomy levels. The attribute should be a positive integer n. The default value is n=0. If n>0, only refiner entries that contain less than n taxonomy path separator symbols ("/") will be returned. If n=0, no level filtering is performed. The level separator is the forward slash character ("/"). Be aware of the performance cost of using a large taxonomy navigator. The filtering is performed as part of the result processing.

Note: This parameter applies application-specific result-side filtering. This differs from the cutoff parameter, which applies limitations in every index partition for performance reasons.

cutoff

Limits the data that must be transferred and processed for deep string refiners. You can configure the refiners to return only the most relevant values (bins). Note: This cutoff filtering is performed within each index partition. This differs from the filter parameter, which performs result-side filtering only. You can combine the two parameters. Syntaxcutoff=<frequency>/<minbins>/<maxbins>The attributes perform the following:

<maxbins> - Limits the number of bins. This parameter limits the number of unique values (bins) that will be returned for a refiner. It is the preferred way to increase search performance when string refiners with large number of bins are returned. "0" implies that the default value specified in the search schema is used.

<frequency> - Limits the number of bins by frequency. If the number of occurrences of a refiner value in a result set is less than or equal to the frequency value, the refiner value is not returned. "0" implies that the default value according to the search schema is used.

<minbins> - Specifies the minimum value for frequency cutoff. If the number of unique refiner values for the query is less than this value, no frequency cutoff is performed, and all refiner values are returned from that search partition. When cutoff by frequency is used, this parameter can be used to specify a minimum number of unique refiner values that will be returned regardless of the number of occurrences. The default value of this attribute is "0", indicating that frequency cutoff is performed regardless of the number of unique navigator values. "0" implies that the default value specified in the index schema is used.

Note: Use <frequency> and <minbins> with care. We recommend that you use only <maxbins>.

Example: Adding refiners

The following CSOM example shows how to programmatically request three refiners: FileType, Write, and Companies. Write represents the last modified date for the item, and uses the advanced syntax to return fixed-size date/time bins.

Understanding the refinement data in the search result

If you have enabled query refinement for a managed property in your query, the query result contains refinement data split into refinement bins. This data is located in the RefinementResults table ( RefinementResults ) within the ResultTableCollection . One refinement bin represents a specific value or value range for the managed property.The RefinementResults table contains one row per refinement bin, and contains the columns, as specified in Table 2.

Table 2: Data returned for refinement bins

Parameter

Description

RefinerName

The name of the query refiner.

RefinementName

The string that represents the refinement bin. This string is typically used when presenting the refinement options to the users on a search result page.

RefinementValue

An implementation-specific formatted string that represents refinement. This data is returned for debugging and is typically not required for the client.

RefinementToken

A string that represents the refinement bin to use with RefinerName when you perform a refined query.

RefinementCount

The result count for this refinement bin. This data represents the number of items (including duplicates) in the search result with a value for the given managed property that falls into this refinement bin.

Example: Refinement data

Table 3 below contains two rows of refinement data. The first row holds refinement data for indexed items, where the file type is HTML. The second row holds refinement data for indexed items, where the last modified time is from 2013/09/21 until 2013/09/22.

Table 3: Format and contents of refinement data

RefinerName

RefinementName

RefinementValue

RefinementToken

RefinementCount

FileType

Html

Html

"????68746d6c"

50553

Write

From 2013-09-21T00:00:00Z up to 2013-09-22T00:00:00Z

From 2013-09-21T00:00:00Z up to 2013-09-22T00:00:00Z

range(2013-09-21T00:00:00Z, 2013-09-22T00:00:00Z)

37

Creating a refined query

A search result presents refinement options in the form of string values or value ranges. Each string value or numeric value range is called a refinement bin, and each refinement bin has an associated RefinementToken value. A refinement option is associated with a managed property, which is provided by the RefinerName value.

Both the RefinementToken and RefinerName values are concatenated to create a refinement filter string. This string represents a filter that can be used to limit search result items to include only items where a managed property has a value within a refinement bin. In short:

refinement filter = <RefinerName>:<RefinementToken>

You can provide one or more refinement filters for a refined query by adding refinement filters to the RefinementFilters property of the KeywordQuery class. Multiple refinement filters enable you to provide multilevel drill-down into the search results, and to apply refinement on multivalued properties. For example, you can refine the query to items that have two authors - each represented by a refinement bin - but exclude items that have only one of the authors.

Example 1: Creating a refined query for HTML file types

The following CSOM example shows how to programmatically perform a refinement, to limit the search results to those of HTML file type only. As mentioned in Example: Refinement data, refinement data related to this refinement option has RefinerName set to Filetype and RefinementToken set to "????68746d6c".

The following CSOM example shows how to run a query with a refiner spec to create refinement data which is subsequently used to perform refinement. This example simulates the process of an end user selecting the first refinement option.