How to use New-ComplianceSearch in PowerShell

How to use New-ComplianceSearch in PowerShell

We all understand the importance of complying with data protection laws and internal policies, which is why Microsoft offers powerful tools like the Start-ComplianceSearch cmdlet.

The Start-ComplianceSearch cmdlet helps us proactively manage and audit our data, ensuring it meets legal and regulatory requirements. Whether you're searching for specific content across mailboxes and SharePoint sites, responding to legal inquiries, or maintaining data governance standards, this cmdlet lets you initiate, manage, and retrieve data for compliance purposes.

In this blog post, we'll explore how to effectively use the Start-ComplianceSearch cmdlet in 3 quick steps.

What is the New-ComplianceSearch Cmdlet?

The New-ComplianceSearch is a cmdlet in Exchange Server 2016 or later and the Microsoft Purview compliance portal that is used to create compliance searches to define search criteria for mailboxes, SharePoint sites, and other locations.

It supports parameters to specify search conditions, including Exchange and SharePoint locations, content match queries, and inclusion or exclusion settings. This cmdlet is available in both on-premises Exchange and cloud-based services, with certain parameters potentially exclusive to specific environments.

This is the syntax of New-ComplianceSearch in PowerShell:


[-Name] <String>

[-AllowNotFoundExchangeLocationsEnabled <Boolean>]

[-Case <String>]


[-ContentMatchQuery <String>]

[-Description <String>]

[-ExchangeLocation <String[]>]

[-ExchangeLocationExclusion <String[]>]


[-HoldNames <String[]>]

[-IncludeOrgContent <Boolean>]

[-IncludeUserAppContent <Boolean>]

[-Language <CultureInfo>]

[-LogLevel <ComplianceJobLogLevel>]

[-PublicFolderLocation <String[]>]

[-RefinerNames <String[]>]

[-SharePointLocation <String[]>]

[-SharePointLocationExclusion <String[]>]

[-StatusMailRecipients <String[]>]



Here is a quick list explaining the meaning of each of these parameters:

  • Name: Specifies the name of the compliance search.
  • AllowNotFoundExchangeLocationsEnabled: Indicates whether to allow the search to run even if some specified Exchange locations are not found.
  • Case: Associates the compliance search with a specific case.
  • Confirm: Prompts for confirmation before executing the cmdlet.
  • ContentMatchQuery: Defines the query to match content based on specified criteria.
  • Description: Provides a description for the compliance search.
  • ExchangeLocation: Specifies the mailboxes or other Exchange locations to include in the search.
  • ExchangeLocationExclusion: Specifies the mailboxes or other Exchange locations to exclude from the search.
  • Force: Forces the command to run without asking for user confirmation.
  • HoldNames: Lists the names of holds associated with the search.
  • IncludeOrgContent: Indicates whether to include organizational content in the search.
  • IncludeUserAppContent: Indicates whether to include content from user apps in the search.
  • Language: Sets the language for the search.
  • LogLevel: Specifies the level of detail for logging the search.
  • PublicFolderLocation: Specifies the public folders to include in the search.
  • RefinerNames: Lists the refiner properties to include in the search results.
  • SharePointLocation: Specifies the SharePoint sites to include in the search.
  • SharePointLocationExclusion: Specifies the SharePoint sites to exclude from the search.
  • StatusMailRecipients: Lists the email addresses to receive status updates about the search.

What Can You Use the New-ComplianceSearch PowerShell Cmdlet For?

The New-ComplianceSearch cmdlet can be used for many things, including the following:

  • Defining Search Criteria: It allows you to create and specify detailed search criteria for compliance searches across mailboxes, SharePoint sites, and other locations in Exchange Server and the Microsoft Purview compliance portal.
  • Conducting Content Searches: You can use it to search for specific content based on keywords, phrases, or other criteria within the specified locations, aiding in regulatory compliance and data management.
  • Associating Searches with Cases: It can link compliance searches to specific legal or regulatory cases, making it easier to manage and organize search results related to ongoing investigations or compliance audits.

Prerequisites to Run the New-ComplianceSearch Command

There are three prerequisites for using the New-ComplianceSearch cmdlet efficiently that you should take into account:

  1. Appropriate Permissions: You must have the necessary permissions to run this cmdlet. In on-premises Exchange, this typically involves being assigned to the Discovery Management role group, which includes the Mailbox Search role.
  2. Exchange Server Version: The cmdlet is available in Exchange Server 2016 or later. Therefore, you need to ensure you are running a compatible version of Exchange Server or using the cloud-based service provided by Microsoft 365.
  3. Assigned Roles: For on-premises Exchange, the Mailbox Search role must be explicitly assigned to you, which is by default part of the Discovery Management role group. In the Microsoft Purview compliance portal, you need to be assigned roles that provide the necessary permissions to create and manage compliance searches, ensuring you have the capability to perform these searches.

How to Use New-ComplianceSearch in PowerShell in 3 Steps

To use New-ComplianceSearch in PowerShell, we'll follow three easy steps.

Step 1: Connect to the Exchange Online

First, connect to your Exchange server or the Microsoft Purview compliance portal. This step is crucial because it establishes a session with the service where you will run the compliance search.

Use the Connect-ExchangeOnline cmdlet to connect to the server with your credentials:

Connect-ExchangeOnline -UserPrincipalName $UserCredential.UserName -Password $UserCredential.GetNetworkCredential().Password

Now that you are connected to the service, you can create and run a compliance search.

First, we’ll use the New-ComplianceSearch cmdlet to define the search criteria. For example, to create a search named "MeetingRoom" that looks for emails containing the word "room" in all mailboxes, run:

New-ComplianceSearch -Name "MeetingRoom" -ExchangeLocation All -ContentMatchQuery "room"

This command creates a compliance search named "MeetingRoom" that searches all Exchange locations (mailboxes) for content matching the query “room.”

However, after creating the search, you need to start it using the Start-ComplianceSearch cmdlet like this:

Start-ComplianceSearch -Identity "MeetingRoom"

This command initiates the search process based on the criteria defined in the previous step, and it’s necessary to start your search.

After starting the compliance search, you can monitor its progress and retrieve the search results.

Use the Get-ComplianceSearch cmdlet to check the status of your compliance search.

This cmdlet provides information about the search progress and completion status. So, for example, you would need to run it like this:

Get-ComplianceSearch -Identity "MeetingRoom"

Mastering Compliance Searches with New-ComplianceSearch

The Start-ComplianceSearch cmdlet is a powerful tool essential for ensuring compliance and data governance in Microsoft Exchange and SharePoint environments.

By enabling administrators to initiate and manage compliance searches effectively, organizations can address legal and regulatory requirements, mitigate risks, and safeguard sensitive information.

This helps streamline compliance efforts, enhance data protection strategies, and maintain organizational integrity.