Use the $search query parameter

In addition to other OData query parameters, Microsoft Graph supports the $search query parameter to restrict the results of a request to match a search criterion.

The support for the $search query parameter varies by entity, with some, such as Azure AD resources that derive from directoryObject, supporting $search only in advanced queries.

Note

The $search query parameter is currently not available in Azure AD B2C tenants.

Using $search on message collections

You can search messages based on a value in specific message properties. The results of the search are sorted by the date and time that the message was sent. A $search request returns up to 1000 results.

If you do a search on messages and specify only a value without specific message properties, the search is carried out on the default search properties of from, subject, and body.

The following example returns all messages in the signed-in user's Inbox that contains "pizza" in any of the three default search properties:

HTTP

GET https://graph.microsoft.com/v1.0/me/messages?$search="pizza"

C#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var queryOptions = new List<QueryOption>()
{
	new QueryOption("$search", "\"pizza\"")
};

var messages = await graphClient.Me.Messages
	.Request( queryOptions )
	.GetAsync();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/messages')
	.search('pizza')
	.get();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new QueryOption("$search", "\"pizza\""));

MessageCollectionPage messages = graphClient.me().messages()
	.buildRequest( requestOptions )
	.get();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Go

//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)


requestSearch := "\"pizza\""

requestParameters := &graphconfig.MeMessagesRequestBuilderGetQueryParameters{
	Search: &requestSearch,
}
configuration := &graphconfig.MeMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Me().Messages().Get(context.Background(), configuration)

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

PowerShell

Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Search "pizza" 

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

PHP

<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();

$queryParameters = new MessagesRequestBuilderGetQueryParameters();
$queryParameters->search = "\"pizza\"";

$requestConfiguration->queryParameters = $queryParameters;


$requestResult = $graphServiceClient->me()->messages()->get($requestConfiguration);

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

This looks for all groups with display names that has one and video tokens, or mail starting with onevideo.

$search can be used together with $filter:

HTTP

GET https://graph.microsoft.com/v1.0/groups/?$filter=mailEnabled eq true&$search="displayName:OneVideo"

C#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var queryOptions = new List<QueryOption>()
{
	new QueryOption("$search", "\"displayName:OneVideo\"")
};

var groups = await graphClient.Groups
	.Request( queryOptions )
	.Filter("mailEnabled eq true")
	.GetAsync();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let groups = await client.api('/groups/')
	.filter('mailEnabled eq true')
	.search('displayName:OneVideo')
	.get();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new QueryOption("$search", "\"displayName:OneVideo\""));

GroupCollectionPage groups = graphClient.groups()
	.buildRequest( requestOptions )
	.filter("mailEnabled eq true")
	.get();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Go

//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)


requestFilter := "mailEnabled eq true"
requestSearch := "\"displayName:OneVideo\""

requestParameters := &graphconfig.GroupsRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
	Search: &requestSearch,
}
configuration := &graphconfig.GroupsRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Groups().Get(context.Background(), configuration)

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

PowerShell

Import-Module Microsoft.Graph.Groups

Get-MgGroup -Filter "mailEnabled eq true" -Search "displayName:OneVideo" 

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

PHP

<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new GroupsRequestBuilderGetRequestConfiguration();

$queryParameters = new GroupsRequestBuilderGetQueryParameters();
$queryParameters->filter = "mailEnabled eq true";
$queryParameters->search = "\"displayName:OneVideo\"";

$requestConfiguration->queryParameters = $queryParameters;


$requestResult = $graphServiceClient->groups()->get($requestConfiguration);

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

This looks for all mail-enabled groups with display names that look like "OneVideo". The results are restricted based on a logical conjunction (an "AND") of the $filter and the entire query in the $search.

The syntax of search follows these rules:

• Generic format: $search="clause1" [AND | OR] "[clauseX]".
• Any number of clauses is supported. Parentheses for precedence is also supported.
• The syntax for each clause is: "<property>:<text to search>".
• The property name must be specified in the clause. Any property that can be used in $filter can also be used inside $search. Depending on the property, the search behavior is either "search" or "startsWith" if search is not supported on the property.
• The whole clause must be declared inside double quotes. If it contains double quotes or backslash, it should be escaped with a backslash. All the other special characters must be URL encoded.
• Logical AND and OR operators must be put outside double quotes and they must be in upper case.

The following table shows some examples.

Object class	Description	Example
User	Address book display name of the user.	GET ../users?$search="displayName:Guthr"
User	Address book display name or mail of the user.	GET ../users?$search="displayName:Guthr" OR "mail:Guthr"
Group	Address book display name or description of the group.	GET ../groups?$search="description:One" AND ("displayName:Video" OR "displayName:Drive"
Group	Address book display name on a mail-enabled group.	GET ../groups?$filter=mailEnabled eq true&$search="displayName:OneVideo"

Both the string inputs you provide in $search, as well as the searchable properties, are split up into parts by spaces, different casing, and character types (numbers and special characters).

See also

• Use query parameters to customize responses
• Advanced query capabilities on Azure AD directory objects
• Query parameter limitations