Edit

Share via

searchRequest resource type

  • Article

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Caution

Resources used in a Microsoft Search API request and response have had properties renamed or removed, or are being deprecated. Find more details about the deprecation. Update search API queries in any earlier apps accordingly.

A search request formatted in a JSON blob.

The JSON blob contains the types of resources expected in the response, the underlying sources, paging parameters, sort options, requested aggregations and fields, and actual search query. See examples of search requests on various resources.

Note

Be aware of known limitations on searching specific combinations of entity types, and sorting or aggregating search results.

Properties

Property Type Description
aggregations aggregationOption collection Specifies aggregations (also known as refiners) to be returned alongside search results. Optional.
aggregationFilters String collection Contains one or more filters to obtain search results aggregated and filtered to a specific value of a field. Optional.
Build this filter based on a prior search that aggregates by the same field. From the response of the prior search, identify the searchBucket that filters results to the specific value of the field, use the string in its aggregationFilterToken property, and build an aggregation filter string in the format "{field}:\"{aggregationFilterToken}\"".
If multiple values for the same field need to be provided, use the strings in its aggregationFilterToken property and build an aggregation filter string in the format "{field}:or(\"{aggregationFilterToken1}\",\"{aggregationFilterToken2}\")".
For example, searching and aggregating drive items by file type returns a searchBucket for the file type docx in the response. You can conveniently use the aggregationFilterToken returned for this searchBucket in a subsequent search query and filter matches down to drive items of the docx file type. Example 1 and example 2 show the actual requests and responses.
collapseProperties collapseProperty collection Contains the ordered collection of fields and limit to collapse results. Optional.
contentSources String collection Contains the connection to be targeted.
Respects the following format : /external/connections/connectionid where connectionid is the ConnectionId defined in the Connectors Administration.
Note: contentSource is only applicable when entityType=externalItem. Optional.
enableTopResults Boolean This triggers hybrid sort for messages: the first 3 messages are the most relevant. This property is only applicable to entityType=message. Optional.
entityTypes entityType collection One or more types of resources expected in the response. Possible values are: list, site, listItem, message, event, drive, driveItem, person, externalItem, acronym, bookmark, chatMessage. For details about combinations of two or more entity types that are supported in the same search request, see known limitations. Required.
fields String collection Contains the fields to be returned for each resource object specified in entityTypes, allowing customization of the fields returned by default otherwise, including additional fields such as custom managed properties from SharePoint and OneDrive, or custom fields in externalItem from content that Microsoft Graph connectors bring in.
The fields property can be using the semantic labels applied to properties. For example, if a property is label as title, you can retrieve it using the following syntax : label_title.
Optional.
from Int32 Specifies the offset for the search results. Offset 0 returns the very first result. Optional.
query searchQuery Contains the query terms. Required.
queryAlterationOptions searchAlterationOptions Provides query alteration options formatted as a JSON blob that contains two optional flags related to spelling correction. Optional.
region string Required for searches that use application permissions. Represents the geographic location for the search. For details, see Get the region value.
resultTemplateOptions resultTemplateOption collection Provides the search result templates options for rendering connectors search results.
sharePointOneDriveOptions sharePointOneDriveOptions Indicates the kind of contents to be searched when a search is performed using application permissions. Optional.
size Int32 The size of the page to be retrieved. The maximum value is 500. Optional.
sortProperties sortProperty collection Contains the ordered collection of fields and direction to sort results. There can be at most 5 sort properties in the collection. Optional.
trimDuplicates Boolean Indicates whether to trim away the duplicate SharePoint files from search results. Default value is false. Optional.
stored_fields (deprecated) String collection This is now replaced by the fields property.

JSON representation

The following JSON representation shows the resource type.

{
  "aggregationFilters": ["String"],
  "aggregations": [{"@odata.type": "microsoft.graph.aggregationOption"}],
  "contentSources": ["String"],
  "enableTopResults": true,
  "entityTypes": ["String"],
  "fields": ["String"],
  "from": 1024,
  "query": {"@odata.type": "microsoft.graph.searchQuery"},
  "queryAlterationOptions": {"@odata.type": "microsoft.graph.searchAlterationOptions"},
  "region": "63128164-cbbf-4db4-896c-a7038417019c",
  "resultTemplateOptions": [{"@odata.type": "microsoft.graph.resultTemplateOption"}],
  "sharePointOneDriveOptions": {"@odata.type": "microsoft.graph.sharePointOneDriveOptions"},
  "size": 1024,
  "sortProperties": [{"@odata.type": "microsoft.graph.sortProperty"}],
  "collapseProperties": [{"@odata.type": "microsoft.graph.collapseProperty"}],
  "trimDuplicates": false
}

Related content