Expanding the Refiners

SharePoint 2010 Search has many new features but one of which will be most evident to users will be the inclusion of a new WebPart called the Refinement Panel. This WebPart allows the user to refine the search results returned from a query even further by viewing a list of refiners (categories). The user may choose to reissue the query with the refinement to filter the results further. For example, lets say your query returned 100 documents which were authored by 5 different people within your organization. The out of the box (OOTB) the Refinement Panel has an Author refiner and it would show you the 5 Author’s names, which in itself is very interesting, but in addition you could select an author and get a list of just those documents authored by that particular author.

OOTB SharePoint has six refiners or “Categories” including Author, Result Type, Site, Modified Date, Managed Metadata columns, and Tags. Each is used in much the same way, as I explained previously in my Author example, however each differ in what data they look at to determine a grouping to refine upon as well as how the query is reformatted to refine the results.

In this post I would like to show you how to add your own Category without having to write any code (this assumes you don’t consider XML code). In our scenario we want to add a Category which allows us to refine the search results based on the size of the document. That is, we want to filter or refine our search results based on the size of the documents as returned from issuing a query. For this to work I need to create a classification system for my documents based on their size. The table below is what I am using to group my documents; obviously the name and value ranges are of my choosing and you can choose any which make since to your scenario but this is what we will use in this example.


Name Min value Max value
Tiny 0 10,000
Small 10,001 100,000
Medium 100,001 1,000,000
Large 1,000,001 5,000,000
Huge 5,000,000 Infinite


The easiest way to get started is by creating a new web based on the Search Center template provided by SharePoint 2010. Once created, navigate to the results page (results.aspx) and put the page into edit mode. On the left side of the page you will find the Refinement Panel Web Part which we need to edit. Once the Editor Panel open navigate to the “Refinement” section and expand. There are 3 items we want to change. The first change we need to make is to the Filter Category Definition; this is a XML document the Refinement Panel Web Part uses to define the categories which represent the various refinements. The second is the Number of Categories to Display. This option allows you to choose the max number of categories which will be displayed when a Refiner is available. Categories are only displayed when there are items found which can be refined further. For example, the Tag refiner will only be displayed if there are documents, within the search results, which have been tagged. Since this example adds a 7th category its important we change this value to 7. The last configuration change we need to make is to uncheck the Use Default Configuration checkbox. With this selected any changes to the Filter Category Definition will not be persisted. Its unfortunate this checkbox did not just disable the Filter Category Definition configuration UI but let me just save you some time and tell you that if you plan on editing the Filter Category Definition you will need this checkbox unchecked.



So lets take a look at the Filter Category Definition XML document. The document has a root element of FilterCategories with Category sub elements which each represent the refiner categories. Reading through the document’s default content offers a great way to learn the syntax and provides examples. The nodes and attributes are actually pretty well named such that you can get an idea pretty quickly what is going on. The Type attribute is very important and points to a class which implements the filter called the filter generator. OOTB there are three including ManagedPropertyFilterGenerator (which we use here), TaxonomyFilterGenerator, and RankingModelFilterGenerator (digging into each of these filter generators is beyond the scope of this blog post). If none of these filters are what you want you can write your own by deriving from RefinementFilterGenerator and adding your own implementation. If I can think of a scenario where this might be needed I may do another blog post on this later.

In this example I am going to add a new category named “File Size” for which I have included the definition below. Since this is based on the managed property filter generator its important that we define the MappedProperty, in this case, “Size”, which represents the file size of the document. I include a CustomFilters element and set the DataType to Numeric (String and Date are acceptable here too) which properly represents the type coming from the managed property stored in Search. Next I implement the size ranges/groups, which I detailed earlier in the table above, using the format “A..B” where A and B are optional but one is always required. The formatting rules are, A must be less than B when B is included, and B must be greater than A when A is included. So for my first filter I called it “Tiny” and gave it no lower bound but an upper bound of 10,000. For “Small” I used similar syntax and defined the range from 10,0001 to 100,000.

<Category Title="File Size"
            Description="The size of each document"
            MoreLinkText="show more"
            LessLinkText="show fewer">
    <CustomFilters MappingType="RangeMapping" DataType="Numeric" ValueReference="Absolute" ShowAllInMore="False">
      <CustomFilter CustomValue="Tiny">
      <CustomFilter CustomValue="Small">
      <CustomFilter CustomValue="Medium">
      <CustomFilter CustomValue="Large">
      <CustomFilter CustomValue="Larger">
      <CustomFilter CustomValue="Huge">

With the new XML created we can edit the Filter Category Definition and append our XML fragment into the document ensuring the XML is still well-formed (if we fail to format the XML properly the Web Part will tell us before we exit edit mode, so be on the lookout for that message).

After leaving edit mode submit a query to search and see the results. Below is a screenshot of what we just created with the new category highlighted in yellow. Note that if I click on any of the filters such as Tiny, Small, or Medium I will see search results based on those filters. In addition you will note we do not have filters for “Large” and “Huge” as we defined earlier, this is because our results set does not include any documents which have sizes which fall into these ranges.

Search refiners are a powerful way to allow uses to dig deeper into the query results and find what they are looking for. Couple that with the ability to customize the refiners on your site and you have a powerful feature which I am sure your users will find very useful.

4 thoughts on “Expanding the Refiners

  1. Terrific write up and sample code – it was easy to follow and implement the new refinement category detailed above.

    Thank you…

    Side questoin: In case you know, why aren’t the meta-properties from Office (e.g. Word, Excel, etc…) persisted up to the SharePoint libraries? For instance, categories, tags, comments…? Is there some additional configuration I need to do to enable, persist these properties to my SP environment?

    Please advise…


  2. Good example.. But how can we group refiners for example ..
    let mananged property be “animals”
    values for this refiners is a lion tiger cat dog wolves
    how can i group lion tiger and cat into cat family
    and rest 2 dog family…


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s