Microsoft Search | Add a Retention Label filter

Reading Time: 4 minutes

For organizations starting to apply Purview retention labels to content across their SharePoint sites, there may come a time when you want to be able to filter Microsoft Search results by the retention label applied to each item. With Microsoft Search, it’s simple to do!

What does this look like for an end-user searching for content? In this image, I’ve added a new filter called Retention Label under the built-in Files search vertical.

What’s a search vertical and how do you add a filter to one? Here’s the official link on Microsoft docs:

To show how to do this for a retention label, read on…

Good thing to know about filters is they’re smart. 🙂 Only the filter values that are in the search results will appear as a filter value.

For this post, I’ve added the filter on the Files vertical since retention labels are added to files. I’m also defining it at the organization-level so it appears on the Files vertical when searching from the SharePoint start page, Microsoft Office and Microsoft Search in Bing. Other great places to add a Retention Label filter would be:

  • a Record Archive SharePoint site you may have on your tenant
  • any site on your tenant where you may want to filter on retention label

To add a filter on a specific site rather than at the organization-level, you would add the filter at the site level instead. The steps to add the custom filter are the same whether adding it on the site level or organization level.


To add at organization-level: Navigate to the Microsoft 365 Admin Center and select Settings… Search & intelligence and click CustomizationsVerticals… Files:

(To add at a site-level: Navigate to the site and then Site Settings… Microsoft Search… Configure search settings)

The above list of verticals are the built-in; however you can also add your own custom vertical to target specific content in your tenant/site. Whether the vertical is built-in or custom, the process to add a filter on the vertical is the same.

Edit the Files vertical

Click the 3 dots to Edit the Files vertical and you’ll see the default Filters included. In this case, File type and Last modified. This is where I’ll add a custom filter for retention label. Click Edit.

You will be taken thru 3 settings for the Files search vertical. I am ONLY adding a new filter and will not be changing any of the default settings for Vertical name and Query. Click next until you get to the Filters tab to add your custom filter:

The retention label is stored in the search index under managed property name ComplianceTag. Search for Compliance to find it and select it from the available list of properties:

Provide a display name for the filter to appear on the search results page (in my case, “Retention Label”) and whether you will allow multi-selections:

Select Done and you will see the custom Retention Label filter added alongside the built-in filters:

Select Update Vertical for your changes to take effect. There is a small delay before the filter will appear for end-users executing searches from the Microsoft Search bar. When the change has been propagated to end-users, they will see the filter appear if any of the content returned has a retention label applied:

Tip: If you wanted labeled content to appear differently (E.g., anything labeled with a Contract label to also include some of its metadata in the search results for example), you would use a custom result type to further customize the search results. That’s for another post. 🙂

Thanks for reading.




  1. Awesome Joanne, thanks for the heads up. So I’m guessing for each Label it would need its own custom result type as it’s effectively a single entity, so would an approach be to gather the organisational labels that are the most important or is there a way to programmatically create these through PowerShell and .xml/.csv?

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.