🔍 Code Extractor

A class representing a search request formatted as a JSON blob for Microsoft Graph API search operations, encapsulating query parameters and search configuration.

Purpose

SearchRequest is a data transfer object that structures search queries for Microsoft 365 services (SharePoint, OneDrive, Exchange, etc.). It inherits from ClientValue to enable JSON serialization for API communication. The class aggregates all necessary parameters for executing a search including query terms, entity types to search, field selection, pagination, sorting, and content source filtering. It's designed to be instantiated with search criteria and then serialized for transmission to Microsoft Graph search endpoints.

Source Code

class SearchRequest(ClientValue):
    """A search request formatted in a JSON blob."""

    def __init__(
        self,
        query,
        entity_types=None,
        fields=None,
        search_from=None,
        sort_properties=None,
        content_sources=None,
        sharepoint_onedrive_options=SharePointOneDriveOptions(),
    ):
        """
        :param office365.search.query.SearchQuery query: Contains the query terms.
        :param list[str] entity_types: One or more types of resources expected in the response.
            Possible values are: list, site, listItem, message, event, drive, driveItem, externalItem.
            See known limitations for those combinations of two or more entity types that are supported in the
            same search request.
        :param list[str] fields: 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 the
            content that Microsoft Graph connectors bring in. The fields property can use the semantic labels
            applied to properties. For example, if a property is labeled as title, you can retrieve it using
            the following syntax: label_title.
        :param int search_from: Specifies the offset for the search results. Offset 0 returns the very first result.
        :param list[SortProperty] sort_properties: Contains the ordered collection of fields and direction to
            sort results. There can be at most 5 sort properties in the collection.
        :param list[str] content_sources: Contains the connection to be targeted.
        """
        super(SearchRequest, self).__init__()
        self.query = query
        self.entityTypes = entity_types
        self.fields = fields
        self.search_from = search_from
        self.sortProperties = ClientValueCollection(SortProperty, sort_properties)
        self.contentSources = StringCollection(content_sources)
        self.sharePointOneDriveOptions = sharepoint_onedrive_options

Parameters

Name	Type	Default	Kind
bases	ClientValue	-

Parameter Details

query: A SearchQuery object containing the actual search terms and query logic. This is the core search criteria that defines what to search for.

entity_types: Optional list of strings specifying resource types to search. Valid values include 'list', 'site', 'listItem', 'message', 'event', 'drive', 'driveItem', 'externalItem'. Some combinations of multiple entity types have known limitations. Defaults to None.

fields: Optional list of strings specifying which fields to return for each resource. Can include default fields, custom managed properties from SharePoint/OneDrive, or custom fields from external items. Supports semantic labels (e.g., 'label_title'). Defaults to None.

search_from: Optional integer specifying the offset for pagination of search results. Value of 0 returns the first result. Used for implementing pagination. Defaults to None.

sort_properties: Optional list of SortProperty objects defining the sort order for results. Maximum of 5 sort properties allowed. Each property specifies a field and direction (ascending/descending). Defaults to None.

content_sources: Optional list of strings identifying specific connections to target for the search. Used to filter search scope to particular content sources. Defaults to None.

sharepoint_onedrive_options: Optional SharePointOneDriveOptions object containing specific configuration for SharePoint and OneDrive searches. Defaults to a new empty SharePointOneDriveOptions instance.

Return Value

Instantiation returns a SearchRequest object that encapsulates all search parameters. The object inherits from ClientValue, making it serializable to JSON for API requests. The instance maintains all provided search criteria as attributes and can be used directly with Microsoft Graph API client methods.

Class Interface

Methods

Attributes

Name	Type	Description	Scope
query	SearchQuery	The search query object containing query terms and logic	instance
entityTypes	list[str] or None	List of resource types to include in search results	instance
fields	list[str] or None	List of field names to return for each resource object	instance
search_from	int or None	Offset value for pagination of search results	instance
sortProperties	ClientValueCollection[SortProperty]	Collection of sort properties defining result ordering (max 5)	instance
contentSources	StringCollection	Collection of content source identifiers to target for search	instance
sharePointOneDriveOptions	SharePointOneDriveOptions	Configuration options specific to SharePoint and OneDrive searches	instance

Dependencies

• office365

Required Imports

from office365.runtime.client_value import ClientValue
from office365.runtime.client_value_collection import ClientValueCollection
from office365.runtime.types.collections import StringCollection
from office365.search.sharepoint_onedrive_options import SharePointOneDriveOptions
from office365.search.sort_property import SortProperty
from office365.search.query import SearchQuery

Usage Example

from office365.search.search_request import SearchRequest
from office365.search.query import SearchQuery
from office365.search.sort_property import SortProperty
from office365.search.sharepoint_onedrive_options import SharePointOneDriveOptions

# Create a search query
query = SearchQuery(query_string="project report")

# Define sort properties
sort_props = [SortProperty(name="lastModifiedDateTime", is_descending=True)]

# Create SharePoint/OneDrive specific options
sp_options = SharePointOneDriveOptions()

# Instantiate the search request
search_request = SearchRequest(
    query=query,
    entity_types=["driveItem", "listItem"],
    fields=["title", "lastModifiedDateTime", "createdBy"],
    search_from=0,
    sort_properties=sort_props,
    content_sources=None,
    sharepoint_onedrive_options=sp_options
)

# The search_request object can now be passed to a Microsoft Graph API client
# for execution, typically through a search endpoint method

Best Practices

• Always provide a valid SearchQuery object as the query parameter - this is the only required parameter
• When specifying entity_types, be aware of known limitations with certain combinations of multiple entity types
• Limit sort_properties to a maximum of 5 items as enforced by the Microsoft Graph API
• Use search_from parameter for pagination, incrementing by the page size for subsequent requests
• When using custom fields, ensure they are properly indexed and available in the target content sources
• The sharepoint_onedrive_options parameter defaults to an empty instance, so only provide it if you need specific SharePoint/OneDrive configurations
• This class is immutable after instantiation - create a new instance if you need to modify search parameters
• The class inherits from ClientValue which handles JSON serialization automatically for API communication

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class SearchRequest 75.8% similar

  SearchRequest is a data structure class that represents the HTTP POST body for SharePoint search queries, designed to overcome URL length limitations of HTTP GET operations.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/search/request.py

• class SearchQuery 71.2% similar

  Represents a search query object that encapsulates search terms and optional query templates for SharePoint/Office365 search operations.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/search/query.py

• class SearchResponse 70.7% similar

  A data class that encapsulates search query results and the search terms used to generate those results, inheriting from ClientValue for Office 365 API integration.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/search/response.py

• class GraphRequest 67.5% similar

  GraphRequest is a specialized OData request class configured for Microsoft Graph API interactions using V4 JSON format.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/graph_request.py

• class SearchEntity 66.6% similar

  A wrapper class for the Microsoft Graph Search API endpoint that provides methods to query various Microsoft 365 resources including messages, events, drive items, and other entity types.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/search/entity.py

class SearchRequest(ClientValue):
    """A search request formatted in a JSON blob."""

    def __init__(
        self,
        query,
        entity_types=None,
        fields=None,
        search_from=None,
        sort_properties=None,
        content_sources=None,
        sharepoint_onedrive_options=SharePointOneDriveOptions(),
    ):
        """
        :param office365.search.query.SearchQuery query: Contains the query terms.
        :param list[str] entity_types: One or more types of resources expected in the response.
            Possible values are: list, site, listItem, message, event, drive, driveItem, externalItem.
            See known limitations for those combinations of two or more entity types that are supported in the
            same search request.
        :param list[str] fields: 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 the
            content that Microsoft Graph connectors bring in. The fields property can use the semantic labels
            applied to properties. For example, if a property is labeled as title, you can retrieve it using
            the following syntax: label_title.
        :param int search_from: Specifies the offset for the search results. Offset 0 returns the very first result.
        :param list[SortProperty] sort_properties: Contains the ordered collection of fields and direction to
            sort results. There can be at most 5 sort properties in the collection.
        :param list[str] content_sources: Contains the connection to be targeted.
        """
        super(SearchRequest, self).__init__()
        self.query = query
        self.entityTypes = entity_types
        self.fields = fields
        self.search_from = search_from
        self.sortProperties = ClientValueCollection(SortProperty, sort_properties)
        self.contentSources = StringCollection(content_sources)
        self.sharePointOneDriveOptions = sharepoint_onedrive_options