Using Microsoft Graph search with SharePoint Online

SharePoint’s role as an enterprise content management system may be an old-fashioned one, but that doesn’t mean the platform is frozen in stone. Over time, Microsoft adds new features, and deprecates and removes old ones. The company has even begun to spin off what were SharePoint features into separate applications.

As SharePoint transitions from one way of working to another, these changes often require us to rewrite and rework our applications and extension code. SharePoint is currently beginning one such transition, moving away from its own search APIs to a new model based on the Microsoft Graph.

Fortunately, one of the main reasons for the success of SharePoint is its adaptability, backed by its own extensibility framework and an easy-to-learn programming model. 

Why use the Microsoft Graph?

While there’s no end-of-life date for the existing search APIs, new functionality will only be available through the Microsoft Graph. So it’s worth starting to rewrite code now, especially as the Microsoft Graph is key to providing grounding for the Microsoft Copilot AI assistants for Microsoft 365. These changes apply not only to SharePoint, but also to OneDrive.

As part of this change all searches will go through a single API. That means the code you write for SharePoint also will work with other Microsoft 365 services, including Outlook, wherever there’s a search index. Using a common search API for all your Microsoft 365 content makes sense, especially with Microsoft’s focus on AI, where that content will provide grounding for generative AI and large language models.

Establishing a common search API for all Microsoft 365 services starts a long-overdue move away from the aging folder metaphor. With good search capabilities and effective metadata tagging, there’s no real need for an artificial structure to help navigate files. Instead, information is delivered as needed from a single index, providing a transparent bridge across application silos.

Searching with the Microsoft Graph API

The Microsoft Graph API is a typical REST API, using POST with a JSON payload. Each JSON payload is made up of a set of requests, which run against entities, and which contain queries. Queries are strings, and they can be used to scope your requests. Thus you can include specific SharePoint sites in your tenant or exclude sections of your tenant that you don’t want searched.

There are some minor issues that need to be considered when building a query. For example, because a OneDrive for Business store is really a SharePoint entity, it must be queried differently from a personal OneDrive store.

Once you have built your basic query JSON, you can start to refine its operation. You can sort the results using familiar pagination techniques, or example, and you can apply additional filters, such as a specific time window.

Note you’re not limited to the hierarchical structure of graph queries, because you can use Microsoft’s Keyword Query Language (KQL) as part of your queries. Queries can then be aggregated, offering the ability to construct complex queries that work across different Microsoft 365 entities. This approach allows you to collect not only the documents related to a query, but also relevant emails and lists of people.

You’re not limited to searching only Microsoft Graph data either. If you use a Graph connector to link line-of-business systems into your Graph instance, Graph searches can extract all kinds of enterprise data—HR, ERP, CRM, and more. In addition to a library of prebuilt connectors, Microsoft provides tools you can use to build your own custom connectors for bespoke applications, or to work with legacy data in mainframes or minicomputers.

Think of the underlying Microsoft Graph as a dynamic, constantly updated index to your non-relational data. As new content is stored in Microsoft 365 and in platforms like SharePoint Online, that index automatically updates and makes your content available across your Microsoft 365 tenant and to all of your users.

Working with the KQL in Microsoft Graph

Once you’ve got basic queries under your belt, you’ll want to move to more advanced ways of working with the Microsoft Graph. This is where you can take advantage of existing skills using the Keyword Query Language (which is not to be confused with Microsoft’s other KQL, the large-scale data query language, Kusto).

KQL allows you to use free text as the basis of a query, looking for words or phrases in content, with support for simple wildcard completions. In addition to searching text, KQL allows you to use document metadata to restrict searches to specific files and authors. You can mix and match restrictions to build more complex queries, using parentheses to group search terms where you might have used an AND statement in SQL or similar query languages.

There are some KQL requirements that might seem confusing at first. For example, dates and times need to be expressed in ISO 8601 format, so you use the YYYY-MM-DD pattern for a date and YYYY-MM-DDThh:mm:ss for date and time (the T is used as the delimiter between data and time). There’s even the option of using relative times, so “today” and “this year” are valid query terms and will deliver different results when run on different days. Other useful options include Booleans, proximity operators, and the ONEAR operator, which uses the order of the terms to return results.

If you’re using KQL in Microsoft Graph queries, it’s a good idea to use KQL to build query templates. These give you a ready-made KQL query, so all you need do is pass in your specific search term. This can be especially useful if you’re programmatically constructing the JSON payload of a search, using a prebuilt query, and passing the search term as a query string.

One API to search them all

We’ve gotten used to treating SharePoint as a stand-alone tool, but it’s now one of the foundational technologies for Microsoft 365 and the Power Platform. Using the Microsoft Graph to query across the entire platform is an important change, one that aims to encapsulate the entire work output for a user or a team, across all the tools they use in their day-to-day work.

There’s yet another reason for using a single search API: It can help ensure that regulated data is being accessed by authorized users. Wrapping your Microsoft Graph queries in a role-based authentication scheme helps ensure that access to data is audited, and that users can access only the data permitted for their role or their group.

Again, there’s no end-of-life date for the old SharePoint search tools, so you’re free to keep using them. However, now that Microsoft’s development resources are focused on the Microsoft Graph, you might use this as an opportunity to start rewriting existing SharePoint applications and extensions, as well as experimenting with the cross-application capabilities of the Microsoft Graph.

After all, we have a lot of data stored in the Microsoft Graph, so we might as well use it. Searching across SharePoint, Outlook, and OneDrive gives you unified access to perhaps your company’s largest knowledge base, allowing you to extract information and insights you might not have found otherwise. That would be the best reason of all to make the shift.