Using Refiners in the Query Web Service

Learn how you can use FAST Search Server 2010 for SharePoint query refinement in the Query Web service.

This article describes how you can use FAST Search Server 2010 for SharePoint query refinement in the Query Web service, as follows:

In this article
Specifying Refiners in the Query XML
Refinement Data in the Query Result
Creating a Refined Query
Query Refinement Visual Studio Example

Applies to: SharePoint Server 2010

Specifying Refiners in the Query XML

The Query Web service uses the Refiner Element in Microsoft.Search.Query Schema to specify which refiners to return in the query result.

This element contains the name of the refiner, but you can also use an advanced syntax to apply non-default configuration values for the named refiner. For more information about the advanced syntax for the Refiner element, see Refiner Specification in the Query Web Service and Query Object Model.

The following example shows the query XML that requests three refiners.

<IncludeRefinementResults>
  <Refiners>
    <Refiner>author</Refiner>
    <Refiner>write(discretize=manual/2010-01-01/2010-08-22/2010-09-15/2010-09-21/2010-09-22)</Refiner>
    <Refiner>companies</Refiner>
  </Refiners>
</IncludeRefinementResults> 

The write refiner represents the last modified date for the item, and uses the advanced syntax to return fixed size date/time bins.

Refinement Data in the Query Result

If you have enabled query refinement for a managed property in your query, the query result contains refinement bin data. One refinement bin represents a specific value or value range for the managed property. In a search UI you will typically present the refinement bins as Refine your query choices.

When using the QueryEx Query Web service method, the dataset returned contains a table named RefinementResults. The table contains one row per refinement bin, and contains the columns as specified in Table 1.

Table 1. Data returned for refinement bins

Parameter

Description

RefinerName

The name of the query refiner. This is a lowercased representation of the managed property name.

RefinementName

A displayable string representation of the refinement represented by this refinement bin. This string is typically used when presenting the refinement options to the users on a query result page.

RefinementValue

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

RefinementToken

A base-64 encoded string that represents this refinement bin when you perform a refined query. This is the value that is passed to the FAST Search Server 2010 for SharePoint farm when performing a refined query.

RefinementCount

The result count for this refinement bin. This represents the number of items in the query result that has a value for the given managed property that falls into this refinement bin.

Creating a Refined Query

A refined query is a query that is created based on a refinement option selected by the user, for example, to limit the query to a specific date range.

A query result typically presents refinement options in the form of string values or value ranges. Each string value or numeric value range is known as a refinement bin. For each refinement bin, there is an associated RefinementToken value. You use this value in the refined query.

The following example shows the query XML representing a refinement.

<RefinementFilters>
  <RefinementFilter>AQVmaXhlZA90ZWxzdHJha2V5d29yZHMBAV4BJA==</RefinementFilter>
</RefinementFilters>

The RefinementFilter element represents one refinement bin. The resulting query is limited to items where the associated managed property has a value within the refinement bin.

You can add multiple refinement bins in the RefinementFilters element. In this case, the resulting query will be limited to items where the associated managed property has a value within all refinement bins. This enables you to apply refinement on multi-valued properties. For instance, 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.

The following example shows the query XML representing a refinement that contains two refinement bins.

<RefinementFilters>
  <RefinementFilter>AQVmaXhlZA90ZWxzdHJha2V5d29yZHMBAV4BJA==</RefinementFilter>
  <RefinementFilter>AQZidW5kbGUPdGVsc3RyYWtleXdvcmRzAQFeASQ=</RefinementFilter>
</RefinementFilters>

Query Refinement Visual Studio Example

The following steps are an extension of Walkthrough: Querying FAST Search Server From a Client Application. Follow the steps in that article, and extend the code as described below.

The code extensions are as follows:

  • Request three refiners in the query result (author, write and company). This is the same as the example in Specifying Refiners in the Query XML.

  • Print the query refinement data in the second DataGridView control.

To extend the code for the Visual Studio client application

  1. Replace the definition of the queryXML2 string, to add three query refiners in the result set:

       // queryXML2 is the part of the XML after the query string.
       string queryXML2 = @"
             </QueryText>
          </Context>
          <ResultProvider>FASTSearch</ResultProvider>
          <Range>
             <Count>10</Count>
          </Range>
          <IncludeRefinementResults>
            <Refiners>
              <Refiner>author</Refiner>
              <Refiner>write(discretize=manual/2010-01-01/2010-08-22/2010-09-15/2010-09-21/2010-09-22)</Refiner>
              <Refiner>companies</Refiner>
            </Refiners>
          </IncludeRefinementResults>
       </Query>
    </QueryPacket>";
    
  2. Add the following code line to the queryButton_Click event:

       // Set the second DataGridView data source to the RefinementResults table in the DataSet object:
       secondGrid.DataSource = queryResults.Tables["RefinementResults"];
    

See Also

Reference

Refiner Element in Microsoft.Search.Query Schema

Concepts

Index Schema (FAST Search Server 2010 for SharePoint)

Walkthrough: Querying FAST Search Server From a Client Application