Refiner Specification in the Query Web Service and Query Object Model

Learn about specifying refiners in the Query Web service or Query object model.

When querying FAST Search Server 2010 for SharePoint, you can specify which refiners and what type of refinement data to return in the query result.

Applies to: SharePoint Server 2010

Specifying Refiners Using the Query Web Service or Query Object Model

If you use the Query Web service, you specify the requested query refiners by using the Refiner Element in Microsoft.Search.Query Schema. For more information, see Using Refiners in the Query Web Service.

If you use the Query object model, you specify the requested query refiners by using the Refiners property of the KeywordQuery class. You use the following syntax to specify the requested query refiners:

<refiner>[,<refiner>]*

In both cases each individual refiner specification has the following format:

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

Where:

  • <refiner-name> is the name of the managed property associated with the refiner.

  • 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 index schema configuration gives you the default setting. For more information, see Index Schema (FAST Search Server 2010 for SharePoint).

Table 1 lists the valid parameters for the refiners.

Table 1. Valid parameters for refiners (FAST Search Server 2010 for SharePoint)

Parameter

Description

deephits

Overrides the default number of hits that is used as the basis for deep refinement computation. This will impact the search performance.

Syntax

deephits=<integer value>

Example

price(deephits=1000)

Note

This limit applies within each search partition inside the search rows or columns. The actual number of hits that are evaluated will be larger than this value due to the result aggregation across search partitions.

discretize

Specifies custom intervals (refinement bins) for numeric refiners.

Syntax

discretize=manual/<threshold>/<threshold>[/<threshold>]*

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 the following ISO 8601-compatible formats:

  • YYYY-MM-DD

  • YYYY-MM-DDThh:mm:ss

  • YYYY-MM-DDThh:mm:ssZ

The format values specify the following:

  • YYYY  Four-digit year. Only four-digit years are supported.

  • MM  Two-digit month. 01 = January.

  • DD  Two-digit day of month (01 through 31).

  • T  The letter "T".

  • hh  Two-digit hour (00 through 23). A.M. or P.M. indication is not allowed.

  • mm  Two-digit minute (00 through 59).

  • ss  Two-digit second (00 through 59).

Important

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

sort

Defines how to sort the bins within a string refiner.

Syntax

sort=<property>/<direction>

The attributes do the following:

  • <property>  Specifies the sorting algorithm. Valid values are as follows (values must be in lowercase letters):

    • frequency  Orders by occurrence within the bins.

    • name Orders by label name.

    • 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 string managed property.

  • <direction>  Specifies the sorting direction. Valid values are as follows:

    • descending

    • ascending

Example

sort=frequency/descending

Default: frequency/descending.

filter

Defines how bins within a refiner of type String are filtered before they are returned to the client.

Syntax

filter=<bins>/<freq>/<prefix>[<levels>]

The attributes do the following:

  • <bins>  Specifies the maximum number of returned bins.

    After sorting the bins within the refiner, use this attribute to cut off 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 starts with this prefix are returned.

    The wildcard asterisk character "*" will match all names.

    Example

    filter=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 containing 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 very large taxonomy navigator. The filtering is performed as part of the result processing.

    Note

    This parameter applies application-specific result-side filtering. This is different from the cutoff parameter, which applies limitations in each individual query matching node for performance optimization.

cutoff

Limits the amount of data that must be transferred and processed for deep string refiners. The refiners can be configured to return only the most relevant values (bins).

Note

This cutoff filtering is performed within each query matching server. This is different from the filter parameter, which performs result-side filtering only. You can combine the two parameters.

Syntax

cutoff=<frequency>/<minbins>/<maxbins>

The attributes do 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 enhance search performance when string refiners with large number of bins are returned.

    "0" implies that the default value specified in the index 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 index 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 done, 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 number of occurrences. The default value of this attribute is "0", meaning that frequency cutoff is done 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 using only <maxbins>.

The following example specifies a query refiner for the last modified date:

write(discretize=manual/2010-01-01/2010-08-22/2010-09-15/2010-09-21/2010-09-22)

The write refiner is associated with the managed property that contains the last modified date for the items. This refiner specifies fixed size date/time bins, where the last bin (2010-09-22) should represent the current date when the query is issued. The specified bins can then be used as a basis to represent refinement bins for today, yesterday, last week, last month, last year and older.

If you want to adapt to the user's time zone, you can specify the bins with full date/time representation.

Note

The refiner names must be in lowercase letters in the specification.

See Also

Concepts

Using Refiners in the Query Web Service

Adding a Refiner to the Refinement Panel Web Part

Query Refinement (FAST Search Server 2010 for SharePoint)