What is the difference between the filter and search query parameters in Microsoft Graph Mail API?

Question

While I was looking at the documentation for query parameters here, I noticed that there were two query parameters that seemingly did the exact same thing: filter and search.

I'm just wondering what the difference is between them and when is one used over the other.

Answer 1

While they're similar, they operate a little differently.

$search uses Keyword Query Language (KQL) and is only supported by message and person collections (i.e. you can't use $search on most endpoints). By default, it searches multiple properties. Most importantly, $search is a "contains" search, meaning it will look for your search word/phrase anywhere within a string.

For example, /messages?$search="bacon" will search for the word "bacon" anywhere in the from, subject, or body properties.

Unlike $search, the $filter parameter only searches the specified property and does not support "contains" search. It also works with just about every endpoint. In most places, it supports the following operators: equals (eq), not equals (ne), greater than (gt), greater than or equals (ge), less than (lt), less than or equals (le), and (and), or (or), not (not), and (on some endpoints) starts with (startsWith).

For example, /messages?$filter=subject eq 'bacon' will return only messages where the subject is "bacon".

Answer 2

Both search and filter reduce the result set that you ultimately receive, however they operate in different ways.

• Search operates on the query against the entire graph and reduces the amount of information a search query returns. This is often optimized for queries that search is good at, e.g. performing searches for items that can be indexed.
• Filter operates on the much smaller result set returned by the search to provide more fine grain filtering. Separating this out allows filtering to perform tasks that would not be performant against the full collection.

This is indicated in Microsoft's documentation:

• Search: Returns results based on search criteria.
• Filter: Filters results (rows). (results that could be returned by search)

For performance purposes, it's good to use both if you can, search to narrow the results (e.g. using search indexes) and then do fine grain filtering on the returned results.