A Primer on the Graph Query Language and SharePoint Online

So, you may or may not have heard of the Graph Query Language (GQL) for SharePoint Online. For those new to the language, here’s a primer on what it is, where it came from, and how it can be of value to your organization. 

Microsoft released a framework called Office Graph as part of the Office 365 core stack. This framework provides data based on user content, identity and activity. It is referred to as an Intelligent Framework for Office 365. This framework is built on very complex machine learning code allowing for relationships to be created among email, social conversations, meetings and documents in SharePoint and OneDrive. The goal of Office Graph is to allow richer applications and experiences that are more relevant and personalized. Everything that makes Office Graph work is related to the individual and the assumed relationships it defines automatically.

For example, Office Graph might determine a relationship based on a document and the users who modify and share it. Each of those users have done something to the content, so a relationship would be defined within the Office Graph.

Office Graph contains data that represents objects, such as people, files, and the relationships and interactions among the objects. These objects are referred to as “edges,” and can be single or multiple interactions. Each edge in the Office Graph contains a source and target node: The source is called the actor, and target is called the object. The edge represents the relationship between the actor and object. The edge itself has property descriptions and types that can be used within code and represent various identifiers and values that are needed for querying.

Office Graph currently retrieves information from SharePoint Online, OneDrive for Business, Exchange Online, Azure Active Directory and Delve. 

When querying the Office Graph, you typically want to find items that are related to other items, as well as the core information about them and their relationships.

As an example, you might want find “everything related to James Brown” or “all items created by Bruce Lee.”

The Graph Query Language has one core operator, ACTOR. This operator will find all actions of the chosen actor that matches the filter applied, then return all objects for the action types. In this example of “everything related to me,” we would use the following syntax.

ACTOR(ME)

This would return objects related to me. However, if I wanted to perform the same query but for “James Brown,” we would first need to know his ID—which, for this example, will be 123--then we would use the following syntax.

ACTOR(123)

If we wanted to retrieve both objects related to “me” and “James Brown” at the same time, we would use the following syntax.

AND(ACTOR(ME), ACTOR(123))

Combining ACTORS with ACTIONS brings even greater power for retrieving content. If we wanted to retrieve objects recently viewed by both myself and “James Brown,” then we would use a syntax similar to the above. However, this time we would add an ACTION number that tells the Office Graph to return only “recently viewed” items.

AND(ACTOR(ME, action:1001), ACTOR(123, action:1001))'

As you can see, the syntax is fairly straight-forward for any type of query, as it is based on passing an ACTOR and then a FILTER of some description.

The current documented list of ACTION types and descriptions can be found online here.

A simplified list is shown below:

The standard way of interacting with the Office Graph using the Graph Query Language is through the SharePoint REST APIs that are available within an Office 365 tenant.

Taking the example we used earlier of retrieving objects recently viewed by both myself and “James Brown,” we would use the following REST API syntax:

/_api/search/query?Querytext='*'&Properties='GraphQuery:AND(ACTOR(ME, action:1001), ACTOR(123, action:1001))'

This would return JSON that could then be further queried and presented within standard SharePoint or regular .NET controls.

As you can see, this process provides a fantastic way to build more personal user experiences within applications you build on Office 365.out

Hopefully this gives you an idea of where to start with the Office Graph and also the Graph Query Language. At this year’s IT/Dev Connections conference at the ARIA Resort Hotel in Las Vegas, Scot Hillier will talk in greater detail about how this can power applications built within SharePoint.

IT/Dev Connections promises to be a valuable show for anyone who wants actionable insight and content, as well as the opportunity to collaborate with IT peers. Click here for more details on IT/Dev Connections and to register. Use the code ITDCCLEARY15 for $100 off.

Liam began his career as a trainer of all things computer-related. He quickly realized that programming, breaking and hacking was a lot more fun. He spent the next few years working within core infrastructure and security services, until he found SharePoint. He now works as a Solution Architect for Protiviti in Virginia. His core focus is to ensure that SharePoint can either natively or with minimal customization meet business requirements. He is also a nine-time SharePoint MVP focusing on architecture, but also crosses the boundary into development. His specialty over the past few years has been security in SharePoint and its surrounding platforms.

What questions do you have about Graph Query Language? Please provide your comments and questions in the space below.