Dot Net Mafia

Group site for developer blogs dealing with (usually) Ionic, .NET, SharePoint, Office 365, Mobile Development, and other Microsoft products, as well as some discussion of general programming related concepts.

This Blog



Corey Roth [MVP]

A SharePoint MVP bringing you the latest time saving tips for Ionic, SharePoint, and Office 365.

Get to know the Refinement Web Part in SharePoint 2010 Enterprise Search

In MOSS 2007, people often extending the search results experience by using the Faceted Search Web Parts.  People really liked these so it looks like Microsoft decided to implement their own version called the RefinementWebPart (also known as the Refinement Panel).  If you are familiar with the Faceted Search Web Parts at all, you will notice there are a lot of similarities in the way things are implemented.  If you’re not familiar with what I’m talking about, it’s this web part that allows users to drill down into a set of search results based upon managed properties and other criteria.  Let’s take a look at a quick example.


On the left there, you will see a set of refinements that we get out of the box.  I didn’t have to do anything to configure these at all.  There are a number of refinements built in including file type, site, author, modified date, and taxonomy.  You can also easily create your own based on managed property which we will see here shortly. 

Let’s take a look at some of the options on this web part.  If we edit the page and then edit the web part, we will be able to see the options.  If you’re on a small screen (or a small window in the case of a  VM), you will have to scroll right to see the web part properties.


Since this is a search web part, you will see the familiar Cross-Web Part query ID.  This should be synced up to whatever else you are using on the page.  Usually it is set to User query.  The next section is where we can configure the refinement.  Make note of the Use Default Configuration checkbox.  If you don’t uncheck this, anything you customize will not be saved.  Each thing that you can filter on is called a category by the RefinementWebPart.  The Filter Category Definition property is an XML field where each category is specified.  We’ll also look at that later in the post.  Other properties to note here.  The Accuracy Index is the number of results it looks at to determine things to refine.  I assume this it mainly there to keep things performing well.  What this does mean is that if there is something unique to refine on but it doesn’t occur until result number 51, then it will not be included.  You can also configure how many categories to display. This is set to 6 by default.  The last thing I will point out is that you can configure how the web part displays its information using XSLT (not shown in the screenshot above).

Now let’s look at how we can add our own managed property to the category list.  You should of course confirm the managed property works and that you can query on it first (do a full crawl if necessary).  We then, just need to take a look at the XML for the Filter Category Definition.

<?xml version="1.0" encoding="utf-8"?>


  <Category    Title="Result Type"    Description="The file extension of the item"    Type="Microsoft.Office.Server.Search.WebControls.ManagedPropertyFilterGenerator"    MetadataThreshold="5"    NumberOfFiltersToDisplay="4"    MaxNumberOfFilters="0"    SortBy="Frequency"    SortDirection="Descending"    SortByForMoreFilters="Name"    SortDirectionForMoreFilters="Ascending"    ShowMoreLink="True"    MappedProperty="FileExtension"    MoreLinkText="show more"    LessLinkText="show fewer">

    <CustomFilters MappingType="ValueMapping" DataType="String" ValueReference="Absolute" ShowAllInMore="False">

      <CustomFilter CustomValue="Adobe PDF">



      <CustomFilter CustomValue="Email">





      <CustomFilter CustomValue="Excel">








      <CustomFilter CustomValue="Image">




      <CustomFilter CustomValue="Lotus Notes">



      <CustomFilter CustomValue="One Note">



      <CustomFilter CustomValue="PowerPoint">






      <CustomFilter CustomValue="Publisher">



      <CustomFilter CustomValue="Text">






      <CustomFilter CustomValue="Visio">









      <CustomFilter CustomValue="Webpage">














      <CustomFilter CustomValue="XML">



      <CustomFilter CustomValue="Word">







      <CustomFilter CustomValue="Zip">





  <Category    Title="Site"    Description="Which site this document is from"    Type="Microsoft.Office.Server.Search.WebControls.ManagedPropertyFilterGenerator"    MetadataThreshold="5"    NumberOfFiltersToDisplay="4"    MaxNumberOfFilters="20"    SortBy="Frequency"    SortByForMoreFilters="Name"    SortDirection="Descending"    SortDirectionForMoreFilters="Ascending"    ShowMoreLink="True"    MappedProperty="SiteName"    MoreLinkText="show more"    LessLinkText="show fewer" />

  <Category    Title="Author"    Description="Use this filter to restrict results authored by a specific author"    Type="Microsoft.Office.Server.Search.WebControls.ManagedPropertyFilterGenerator"    MetadataThreshold="5"    NumberOfFiltersToDisplay="4"    MaxNumberOfFilters="20"    SortBy="Frequency"    SortByForMoreFilters="Name"    SortDirection="Descending"    SortDirectionForMoreFilters="Ascending"    ShowMoreLink="True"    MappedProperty="Author"    MoreLinkText="show more"    LessLinkText="show fewer"    />

  <Category    Title="Modified Date"    Description="When the item was last updated"    Type="Microsoft.Office.Server.Search.WebControls.ManagedPropertyFilterGenerator"    MetadataThreshold="5"    NumberOfFiltersToDisplay="6"    MaxNumberOfFilters="0"    SortBy="Custom"    ShowMoreLink="True"    MappedProperty="Write"    MoreLinkText="show more"    LessLinkText="show fewer" >

    <CustomFilters MappingType="RangeMapping" DataType="Date" ValueReference="Relative" ShowAllInMore="False">

      <CustomFilter CustomValue="Past 24 Hours">



      <CustomFilter CustomValue="Past Week">



      <CustomFilter CustomValue="Past Month">



      <CustomFilter CustomValue="Past Six Months">



      <CustomFilter CustomValue="Past Year">



      <CustomFilter CustomValue="Earlier">





  <Category    Title="Managed Metadata Columns"    Description="Managed metadata of the documents"    Type="Microsoft.Office.Server.Search.WebControls.TaxonomyFilterGenerator"    MetadataThreshold="3"    NumberOfFiltersToDisplay="3"    MaxNumberOfFilters="20"    ShowMoreLink="True"    MappedProperty="ows_MetadataFacetInfo"    MoreLinkText="show more"    LessLinkText="show fewer" />

  <Category    Title="Tags"    Description="All managed metadata of the documents and social tags"    Type="Microsoft.Office.Server.Search.WebControls.TaxonomyFilterGenerator"    MetadataThreshold="3"    NumberOfFiltersToDisplay="3"    MaxNumberOfFilters="20"    ShowMoreLink="True"    MappedProperty="ows_MetadataFacetInfo,popularsocialtags"    MoreLinkText="show more"    LessLinkText="show fewer" />


I went ahead and posted the entire XML because it’s worth seeing.  For the most part the schema is pretty easy to follow.  The Category element defines each thing to refine and then it has some basic configuration items such as the number of filters to display.  You specify the name of the managed property to use in the MappedProperty attribute.  The MetadataThreshold property is the number of results that have to be returned with that property in order to do refinement.  If you are familiar with the schema used by Faceted Search, you will see a similar concept with the CustomFilter elements.  These allow you map a value into something more readable.  For example instead of display xlsx, it displays Excel. 

One more thing I will point out is that the Category element has a Type attribute.  So far I have seen ManagedPropertyFilterGenerator and TaxonomyFilterGenerator.  These both inherit from RefinementFilterGenerator.  None of its sealed surprisingly which means you could actually write your own custom filter for the refinement web part.  That’s pretty cool.  I’m not sure why I would need to yet, but you never know what you might want to be able to customize.

I want to add my own managed property, so I just add a category to the end like this.

<Category    Title="Color"    Description="Use this filter to restrict results by color" Type="Microsoft.Office.Server.Search.WebControls.ManagedPropertyFilterGenerator"    MetadataThreshold="5"    NumberOfFiltersToDisplay="4"    MaxNumberOfFilters="20"    SortBy="Frequency"    SortByForMoreFilters="Name"    SortDirection="Descending"    SortDirectionForMoreFilters="Ascending"    ShowMoreLink="True"    MappedProperty="Color"    MoreLinkText="show more"    LessLinkText="show fewer"    />

All I did was copy the category that was used for author and it works great.  You can tweak the individual settings if you like.  Here is what my custom managed property looks like.


How does this all work though.  Well it’s pretty simple.  Just copy any link that the web part displays and we’ll see that it makes use of the new r query string property.  It will be URL encoded but you can easily decode it and see the magic.  In this case if I want to view Red products, the query string has a r parameter of the following.


If I wanted to view files modified in the last 24 hours, it uses the new >= operator.


Don’t you just love that you can easily query against dates now using the keyword query syntax?  I think the r keyword is very interesting and I think it opens the door for some very interesting customizations of the search results page in the future.



Kevin said:


Very helpful.

March 30, 2010 4:32 AM

Dave said:

Hey there --

Really useful article. How would we do this, for instance, in conjunction with something like Content Type?



June 1, 2010 3:57 PM

CoreyRoth said:

@Dave - Content Type should be more than doable.  Try adding a Category and setting the Mapped Property to ContentType.  I'll try it when I get a chance, but if you happen to try it out, let me know if it works.  Thanks.

June 1, 2010 4:05 PM

Hervé said:


I've tried this feature myself and still facing the same old issue as with MOSS2007 with multi-valued columns.  When I add a managed property in the refinement panel it works fine as long as it's not multi-valued. If it is, the list of all the values appears as one element of the facets, all values being separated with ';'

June 3, 2010 12:55 AM

Gopalakrishnan said:

Hi Corey,

I have a set of document libraries which in turn have the same set of folders. Is it possible to display the available folders in the Refinement Web Part under a category?

June 18, 2010 4:37 AM

Gopalakrishnan said:


I am facing problems adding my new Metadata property into this. I created a site column called "Year", added this to a document lib, entered value for the column in each item and then did a full crawl (in fact did a Crawl index reset too before running the full crawl). Now, I added one more category titled "Year" and set its mapped property to "Year". I made sure that the "Use default.." checkbox is unchecked and set the no of categories to display to 10. I added this category before the "Managed Metadata Columns" category. After done all that, I don't see this category appearing in the Refinement Panel.

Any idea whether I have missed something?


June 21, 2010 4:40 AM

Veronique said:

I'm facing with the same issue as Herve; when i use a multi valued column in the refinement webpart,  the list of all the values appears as one element of the facets, all values being separated with ';'.

Do you have any idea to fix the problem ?

July 5, 2010 7:01 AM

Jason said:

Same problem as Hervé and Veronique, multichoice fields shows up as value1;value2;value2 in the refinement control.

If i look at the source from the core search webpart i see that my multichoice fields are returned in the xml, but i cant set the refinement control to the those fields fieldname_multivalue.

Anyone got any trix up their sleves?

July 6, 2010 6:33 AM

CoreyRoth said:

@Veronique @Jason @Herve Honestly, I haven't tried it with a multi-valued field yet.  I suspect it might be necessary to write a custom filter though.  I'll look into it when I get a chance.

July 6, 2010 12:36 PM

Hervé said:

@Veronique, Jason and Corey. I'm still stuck with this issue. I've tried to implement my own custom filter generator but without any success ... more details on

July 7, 2010 2:24 AM

Lorenzo said:

Hi folks,

thanks a lot for sharing this. Does anybody know if this webpart allows for the display, in brakets, of the total number of hits per faced value (e.g. Excel (50) )?


July 16, 2010 6:58 AM

CoreyRoth said:

@Lorenzo Only if you are using FAST.

July 16, 2010 9:13 AM

keren said:

i'm trying to add a custom property which is a managed metadata. it's named "Product" and in the central admin managed properties i see it as "owstaxIdProduct". what is the syntax to add in the refinement panel web part? i tried to set that name as you did with "Author". what's the difference between "Title" to "Mapped Property"?


August 2, 2010 6:00 AM

CoreyRoth said:

@keren.  I'm not sure if I am understanding your question right or not, but the Refinement Panel already has a managed metadata filter on it by default.  The field it uses is ows_MetadataFacetInfo

August 2, 2010 3:01 PM

Charlie Holland said:

Here's a how-to post on creating a custom RefinementFilterGenerator

August 20, 2010 10:24 AM

Marco said:

Do you know if it is possible to edit the web part in SharePoint Foundation? When I get to the search page there is no Edit Page option. Any ideas?


August 23, 2010 12:28 PM

CoreyRoth said:

@Marco SharePoint Foundation uses an application page for search results so its not easily customizable.  However, if you install Search Server Express on top of foundation, you get a search center and you can edit it.

August 23, 2010 12:50 PM

jorge said:

do you know how is the 'r' query string parameter created? is it a hash of the property's value we are refining by? i tried urldecode to see what it is but i get a long set of chars, i guess these are guids. do you know more about this param?

August 31, 2010 9:26 AM

Norman said:

Is it possible to display Scopes in the refinement box ?

October 6, 2010 10:39 AM

CoreyRoth said:

@jorge I think it depends on what is being refined.  For simple managed properties it is the same syntax as the keyword query.  If you are seeing guids, I think that is how managed metadata shows up (and a few other things).

October 6, 2010 10:51 AM

CoreyRoth said:

@Norman There is nothing out of the box.  Once you execute a query, I don't think there is a way to tell from the results what scope each result came from when multiple scopes are returned.  You could always write a custom web part to allow the users to click on a scope and requery.

October 6, 2010 11:19 AM

Norman said:

Thanks Corey for the quick reply. Unfortunately I dont have the skill set to create a custom Webpart.

When the results comes in (All site includes all the scope , File server as well as Intranet ) . In the refinement box there is section Called Site. whic displays Any Site and the server name. I wanted to give them a user friendly name. Anyway thanks for your help.

October 6, 2010 12:00 PM

jorge said:

thanks, another question:

in my coreresults webpart, i have an 'append query string' (webpart property) that limits results to a specific spsiteurl, but the refiner seems to ignore this and i get refinments from other sites also, the search results work as expected. do i have to set this query in the refiner as well somewhere?


October 11, 2010 9:23 AM

rajesh said:

I have a managed metadata field which I use to tag the documents. The metadata field is hierarchical having categories and subcategories. for eg., Finance can be the main category and Tax, PayRoll can be the subcategory. Document can be tagged to Tax or Payroll.

I see that refinement panel provides a flat view of the metadata. Is it possible show all the categories and then the subcategories beneath those categories

April 20, 2011 11:18 AM

CoreyRoth said:

@Rajesh nothing out of the box I am afraid.  Although, you could always implement your own refiner.

April 20, 2011 4:52 PM

Yesh said:

Hi CoreyRoth,

Thanks for sharing this post. I guess we can create our own refining webpart to satisfy some of the criterias like allowing multivalue columns and others. I was wondering if there is any articles published on this regard.

April 25, 2011 7:24 AM

CoreyRoth said:

@Yesh there may be but I haven't stumbled upon any yet.

April 25, 2011 8:44 PM

Rocky said:

Can we have a OR condition in the refinement "r" parameter???

August 6, 2011 4:31 AM

CoreyRoth said:

@Rocky Hmm, good question.  I don't believe so.

August 10, 2011 2:57 PM

CoreyRoth said:

@Rocky Hmm, good question.  I don't believe so.

August 10, 2011 2:57 PM

Marc Saturnino said:

Great article Corey.  Thanks for the insight. :)

October 11, 2011 3:05 PM

SUSHD said:

How to get multiple sites in refinement panel under site category

December 15, 2011 11:27 AM

CoreyRoth said:

@SUSHD you don't have to do anything to get multiple sites to show up.  There does have to be enough results.  However, I have noticed peculiar behavior with this particular refiner before and sometimes other sites don't appear.

January 5, 2012 4:00 PM

The Case of the Case-Sensitive CustomFilter Refiner – Code Thug said:

Pingback from  The Case of the Case-Sensitive CustomFilter Refiner &ndash; Code Thug

September 14, 2012 7:07 AM

shaik said:

How can i add/modify refinement panel to my own custom search page(Am not using OOB search page)

October 18, 2012 7:33 AM

CoreyRoth said:

@Shaik assuming you have enabled the enterprise and search site collection features, you can add it to any page using the Refinement Panel web part.  As an alternative, you can get the schema you need for the web part by exporting that web part it from a search center.

October 19, 2012 3:37 PM

Leave a Comment


About CoreyRoth

Corey Roth is an independent SharePoint consultant specializing in ECM, Apps, and Search.
2018 dotnetmafia.
Powered by Community Server (Non-Commercial Edition), by Telligent Systems