Tuesday, May 24, 2016

Office Graph implementation with SharePoint Online Search REST APIs


Graph Query Language (GQL) is a preliminary query language designed to query the Office Graph via the SharePoint Online Search REST API. By using GQL, we can query the Office Graph to get items for an actor that satisfies a particular filter.The Office Graph contains information about enterprise objects, such as people and documents, as well as the relationships and interactions among these objects. The relationships and interactions are represented as edges.Some edges represent a single interaction:
  • Modified — User A modified a document.
  • Viewed — User B viewed a presentation.
Some edges are computed based on multiple interactions:
  • WorkingWith — People whom you frequently interact with.
  • TrendingAround — Items that are popular in your circle of colleagues.

The Office Graph data model and edge properties

As with any graph, each edge in the Office Graph has a source node and a target node. The source node is called the actor and the target node is called the object.

Figure 1. 










The relationship among actor, edge, and object

A typical graph query call via REST

A graph query can contain both a content part (Querytext) and a graph part (GraphQuery). We can use these to do a combined search on the contents of a whole item and the interactions people have had with this particular item. The Querytext property is mandatory. If we want to match all items without filtering any part of the content, you can use an asterisk (*).

GQL has one main operator: ACTOR. The ACTOR operator finds all actions of the given actor that satisfies a filter and then returns all the objects for these actions. For example, to return Items viewed by the actor in the last three months. (Assuming the ActorId = 12345 for User A) you can split this information into: User A is the ACTOR. View is the action with ID = 1001. Document is the object, which is returned in the result.Then, you can write the following query.ACTOR(ME, action:1001)The following is the syntax for the ACTOR operator.ACTOR(<ActorId> [, filter])

Example 1: View all items created by userExample 2: People whom the actor communicates with or works with frequently.  You can sort the result returned for graph queries in two ways: by the edge's Timestamp or the edge's Weight.
  • To sort based on the edge timestamp, set the GraphRankingModel property equal to {"features"\:[{"function"\:"EdgeTime"}]}.
  • To sort based on the edge weight, set the GraphRankingModel property equal to {"features"\:[{"function"\:"EdgeWeight"}]}.

In both cases, you must also set the RankingModelId property to '0c77ded8-c3ef-466d-929d-905670ea1d72'. If an item in the result is the object of more than one edge matching the graph query, the highest Timestamp or Weight is used.

Table 1. Edge property descriptions and their types


Property Type Description
ActorId Integer The ID of the actor.
ObjectId Integer The ID of the object.
Action type Integer An ID that identifies what action or relationship type the edge represents. Important action types are listed in Available action types.
Time String A timestamp of the edge; based on the ISO 8601 standard. The semantics of the time stamp depend on the type of the edge. See Available action types.
Weight Integer A number that indicates the importance of the edge. The semantics of the weight depend on the type of the edge. See Available action types.
Blob Blob For internal use only.
BlobContent String For internal use only.
ObjectSource Integer For internal use only.

Table 2. Action types and their descriptions


Action Type Description Visibility ID Weight Timestamp
PersonalFeed The actor's personal feed as shown on their Home view in Delve. Private 1021 A sequence number. When the item was added to the feed on the Home view in Delve.
Modified Items that the actor has modified in the last three months. Public 1003 The number of modifications. Last modified.
OrgColleague Everyone who reports to the same manager as the actor. Public 1015 Always 1. -
OrgDirect The actor's direct reports. Public 1014 Always 1. -
OrgManager The person whom the actor reports to. Public 1013 Always 1. -
OrgSkipLevelManager The actor's skip-level manager. Public 1016 Always 1. -
WorkingWith People whom the actor communicates with or works with frequently. Private 1019 A relevance score. -
TrendingAround Items popular with people whom the actor works with or communicates with frequently. Public 1020 A relevance score. -
Viewed Items viewed by the actor in the last three months. Private 1001 The number of views. Last viewed.
WorkingWithPublic A public version of theWorkingWith edge. Public 1033 A sequence number. -

Table 3. Result sources for SharePoint query


Result Source ID
Documents e7ec8cee-ded8-43c9-beb5-436b54b31e84
Items matching a content type 5dc9f503-801e-4ced-8a2c-5d1237132419
Items matching a tag e1327b9c-2b8c-4b23-99c9-3730cb29c3f7
Items related to current user 48fec42e-4a92-48ce-8363-c2703a40e67d
Items with same keyword as this item 5c069288-1d17-454a-8ac6-9c642a065f48
Local People Results b09a7990-05ea-4af9-81ef-edfab16c4e31
Local Reports And Data Results 203fba36-2763-4060-9931-911ac8c0583b
Local SharePoint Results 8413cd39-2156-4e00-b54d-11efd9abdb89
Local Video Results 78b793ce-7956-4669-aa3b-451fc5defebf
Pages 5e34578e-4d08-4edc-8bf3-002acf3cdbcc
Pictures 38403c8c-3975-41a8-826e-717f2d41568a
Popular 97c71db1-58ce-4891-8b64-585bc2326c12
Recently changed items ba63bbae-fa9c-42c0-b027-9a878f16557c
Recommended Items ec675252-14fa-4fbe-84dd-8d098ed74181
Wiki 9479bf85-e257-4318-b5a8-81a180f5faa1


References:Query the Office Graph using GQL and SharePoint Online Search REST APIsSharePoint Search REST API overview