Custom Search Refiners

Will Holland is an Software Engineer at ThreeWill. Will has proven to be adept at understanding a client's needs and matching them with the appropriate solution. Recently he's developed a passion on working with .NET, MVC, and cloud-based solutions such as Microsoft Azure and Office 365.

Default refiners are great….if you have some pre-existing knowledge of the document.

Out of the box, SharePoint’s search feature makes finding documents, videos, and other items much easier when the user doesn’t know where to begin looking. Sometimes, however, it’s just not enough. If your site collection contains a large number of documents, as was the case with a recent project I was on, a user’s search may return hundreds of results. The only methods the user has at their immediate disposal for narrowing those results down is to either search again with more keywords or use some crummy filters provided by the Search Refinement Panel. The default refiners, such as author, require that the searching user know details of the document prior to searching for it. Great if you just published a document and immediately had a brain fart; not so useful for the rest of us though.

Fortunately, it’s not all that difficult to create your own custom refiners that will provide your users with the experience they have been searching for. All puns aside, adding custom refiners will allow your user to narrow their search results down by more meaningful filters, thereby reducing the amount of time spent searching and, hopefully, increase productivity.


  • You have an existing site collection with the Search feature active and configured.
  • You have sufficient permissions to access and modify Central Administration.
  • You have permissions to edit pages and web parts.


For the sake of consistency, I’ll be using the “Productivity Hub” as my example site collection. The Productivity Hub is a SharePoint 2010 site collection that contains a plethora of content for users making the migration from Office 2007 to Office 2010. It’s a free download, available at

The content for the Productivity Hub is stored in a document library, aptly named “Content Library”. The content library contains a “Product” column which indicates what Office product the document is intended for. This is the column that I will use during this tutorial.

In the beginning…

To start things off, the first thing we must do is determine what data we have that could be useful to searching users. Something that helps them define what they’re looking for. If your site collection contains a large number of documents that relate to specific clients, it would probably be useful if the user could narrow their search by documents that only pertained to a chosen customer. In my case, my documents all pertain to various products in Microsoft Office 2010, so I’ll use the “Product” column so that my users can narrow their search results down based on specific Office products.

As a best practice, the best columns to use for metadata are those that are indicative of the document contents, which is why I’m not a huge fan of the OOB search refiners. It’s also best if the data stored in the column is NOT a multi-value choice or multi-line text.

If your library doesn’t contain a particularly useful column…create one!

If you must walk before you run, before you walk you must have crawled.

Unless you created a new column for your library, the chances are that your desired column has already been indexed when the last scheduled site crawl ran. Regardless, we still need to verify that it was crawled. You know what they say happens when you assume something.

The Crawled Properties Page of Central Administration

  • Open up Central Administration and navigate to Application Management | Manage Service Applications
  • From list of Service Applications click Search Service Application
  • From the Queries and Results section, click the Metadata Properties link.
  • Finally, click the Crawled Properties link.

This page contains a list of every column captured during a crawl and, hopefully, your column will be in this list somewhere. To find out, type the name of the column in the search bar towards the top of the page and let’er rip. With any luck, you’ll receive a few results. My search for “Product” resulted in quite a few, but the one I’m interested in is ows_Product(Text). If given the choice, the crawled property that contains the ows_ prefix is usually the one you want.

If you created your own column or your search results didn’t include an ows_{YourColumnName}({YourColumnType}) type result, then I’m sorry to say that before you can continue, you’re going to have to do a full or incremental crawl. This may or may not be an issue for you depending on how long a crawl takes to complete.

Once you have verified that your column has been crawled, click the Managed Properties link followed by the New Managed Property link.

The “New Managed Property” window.

  • Fill out this new window by giving your property a useful name.
    • Try keeping the name to one word, but if you need to use multiple words be sure to use Pascal casing.
  • Give your property a useful description.
  • Select the appropriate type.
  • In the second section, select Include values from a single crawled property based on the order specified.
  • Click the Add Mapping button.
  • Type the name of your crawled property and click the Find button.
  • Select your crawled property from the list and click the OK button.
  • Everything else can be left at its default values, so click the OK button.

Setup for Search Success

With our new managed property in place, we’re ready to begin adding our refiners.

Navigate your way to your search results page and put it in edit mode. The first thing we need to do is include our new metadata in the search results.

  • Locate the Search Core Results Web Part, located roughly in the middle of the page.
  • From the web part context menu, click Edit Web Part.
  • In the web part editor, expand the Display Properties section.
  • In the Fetched Properties text box, scroll towards the end until your cursor is directly in front of the </Columns> tag.
  • Add the following: <Column Name=”ProductName”/>, replace ProductName with whatever you named your managed property.
  • Click the Apply button.
  • Click the OK button.

Next, we need to define our actual refiner.

  • Locate the Search Refinement Panel web part, located on the left side of the page.
  • From the web part context menu, click Edit Web Part
  • In the web part editor, expand the Refinement section.

We need to add our refiner definition in the Filter Category Definition text box. This text box is quite a bit wordy, so it may be easier for you to copy the contents and paste them in an editor that will format it for you, such as NotePad++ or Visual Studio.

I do declare!

Once you have your code formatted, you can see that it’s an XML document that contains a series of <Category> definitions. These definitions are what define the refiners that appear on the refinement panel web part. You may also notice that they appear on the web part in the order that they are defined here, so a decision must be made on where you want your refiner to appear. I think the Product refiner is pretty useful, so I’ll simply insert my code before the other categories. Below is the definition I’ll use to declare my refiner.

Description="The Product associated with the item"
MetadataThreshold="1" NumberOfFiltersToDisplay="5"
MaxNumberOfFilters="0" SortBy="Name"
SortDirection="Ascending" SortByForMoreFilters="Name"
SortDirectionForMoreFilters="Descending" ShowMoreLink="True"
MappedProperty="ProductName" MoreLinkText="show more"
LessLinkText="show fewer">
ValueReference="Absolute" ShowAllInMore="False">








As you can see, the Category tag contains a large number of properties that you can configure. Here are a few that you’ll certainly want to understand.

  • Title – This is the display name for your refiner category.
  • MappedProperty – Extremely important. This should match the name of your managed property and the name specified when you added the column tag to the search core results web part. It is case sensitive!
  • MetadataThreshold – The number you specify is how many search results are required to be returned that match a filter before it will be presented to the user.
  • NumberOfFilterToDisplay – The number of filters to be displayed before the user has to click the “show more” link.
  • MaxNumberOfFilters – If the user clicks the “show more” link, how many filters do you want them to see. Set the value to zero if you want to show all filters.

For the complete list, please refer to this MSDN article: Refinement Panel XML Schema

The CustomFilters element has a few properties of its own, but for the most part, it will use the values shown above. The most common exception to that is when you’re refining by dates. The link above provides an explanation for each of these properties as well.

Finally, you have the CustomFilter and OriginalValue nodes. The “Name” property of CustomFilter is the text that will be displayed on the refinement panel, so keep it short and precise. The value between the OriginalValue tags is the value we expect for each custom filter. Again, this value is case sensitive. 

Once you’ve created your declaration, copy the contents of your editor and find your way back to that cluttered text box. Replace its contents with your code.

Click the Apply button and stop editing the page.

And you’re done! Well, almost. If you do a search, you notice that your refiners aren’t showing up.

I just learned to run, now you tell me to crawl again?

Yup. You’ll have to do another full crawl before your refiner will appear. Pretty much anytime you make a change to the search metadata, you’ll be forced to do this.

However, once that’s completed….

Ta-Da! My Custom Refiner LIVES!

Related Posts

William HollandCustom Search Refiners
  • Nice job with this Will…thanks for taking the time to do this.

  • jaasbaa

    Thanks Bill….

  • jaasbaa

    I have an issue displaying my custom metadata columns on left hand side refiners (sharepoint 2010). my
    search page is using /_layouts/OSSSearchResults.aspx where i cannot see / customize the Refinement Panel.
    Could you please help  me?
    I’m seeing my metadata column in Managed Properties as well as Crawled properties under Central Admin…