Using In-place Search for Graph

When preserving an Office 365 or Microsoft consumer mailbox (e.g., Hotmail, Outlook.com, etc.) using Microsoft Graph API, it is possible to perform in-place searches to narrow down the data set. You can launch the in-place search interface for Graph by clicking the "Perform Pre-Acquisition Search" link as shown below:

Graph API supports two mechanisms for in-place search: the filter query parameter and the search query parameter. Starting in version 3.52.5.0, FEC uses the filter query parameter by default in order to work around the API cap associated with the search query parameter. You can control this behavior via the "Use Search instead of Filter for In-place Searches" option in Graph API settings as in the screenshot below.

1. Filtering

The filter query parameter supports the following search operators:

equals eq / not equals ne
less than lt / greater than gt
less than or equal to le / greater than or equal to ge
and and / or or
in in
Negation not
lambda operator any any
lambda operator all all
Starts with startsWith
Ends with endsWith

For a list of properties that can be filtered (with some caveats), please refer to Microsoft's documentation below:

https://docs.microsoft.com/en-us/graph/api/resources/message?view=graph-rest-1.0

Example Searches:

Example 1—Items with sent or received dates between January 1, 2019 and December 31, 2019:

	(receivedDateTime ge 2019-01-01 AND receivedDateTime le 2019-12-31) OR (sentDateTime ge 2019-01-01 AND sentDateTime le 2019-12-31)

Example 2—Emails from a specific address:

	from/emailAddress/address eq 'jdoe@example.com'

Example 3—Emails with a specific Internet Message-ID:

	internetMessageId eq '<2011203292@example.com>'

You can use the Unified Query Builder to construct participant and date restrictions using the filter query parameter.

Limitations: As of this writing, the filter query parameter in Microsoft Graph API does not support the "contains" operator. So, it is not possible to search for items that contain a certain string within a metadata field. It is possible to partially work around this by using the startsWith or endsWith operators. Additionally, it is currently not possible to filter the recipient email fields (i.e., toRecipients, ccRecipients, and bccRecipients). Therefore, Unified Query Builder does not show those participant types as an option when using Graph API with the filter query parameter.

2. Searching

If you select the Use Search instead of Filter for In-place Searches option in Graph API settings, FEC will use the search query parameter instead of the filter query parameter. The search query parameter is much more flexible, but it has the following important limitation:

Warning: When using the search query parameter, Microsoft Graph API currently limits search results to 275 items per search. If your search query returns more than 275 results per folder, Microsoft will cap the results and return only 275 responsive items per folder. If you are running into this limitation, you can perform your in-place search via filtering as described above, or perform your acquisition and in-place search via EWS or IMAP instead depending on if you are targeting O365 or Microsoft consumer accounts. We are watching Microsoft's handling of this issue closely and will update our documentation if/when they remove this limitation. For clarity, this is not a limitation specific to FEC and applies to Microsoft Graph API in general.

Graph API in-place searches via the search query parameter use Keyword Query Language (KQL) syntax. You can find the details in Microsoft's documentation below:

Keyword Query Language (KQL) syntax reference

Important Note: KQL syntax looks very similar to the Advanced Query Syntax used with EWS. Please note that date searches in KQL should appear without colons, as in the example below:
received>=2016-01-01 OR sent>=2016-01-01

3. Saving the Search Query

Once you have finalized your search query, you can save it by using the SAVE button. This will close the in-place search window and activate your query. You will see a notice as in the screenshot below:

4. Clearing the Search Query

If you would like to clear the search query, you can click on the small (x) symbol next to the "Search Query Activated" text as shown in the figure above.

Limitations of Graph Search

The search functionality built into Graph API and utilized by FEC is limited to the documents that Microsoft's servers are able to recognize and index. For instance, a proprietary CAD file unrecognized by the server, or files inside an encrypted file archive would not be indexed or searched. Similarly, if a file has no extractable text (e.g., a scanned TIFF image of a document), the server would not be able to extract text from it or index it.

Given the above limitations, it may be appropriate to use the Graph API search functionality in FEC to filter messages by top-level message characteristics such as sender, recipient, and subject content. Keep these limitations in mind if you plan to use this functionality to perform a blanket search intended to search all documents and their attachments recursively.