Wednesday, June 1, 2011

The Life and Times of a SharePoint Search Results Click Event

Technorati Tags: ,,

In my previous posting I wrote about how to customize your own ranking models. Ranking models are used to sort search results according to their relevance. The higher the rank of the document the higher it is listed in the search results.  SharePoint Search 2010 implements the BM25 ranking model. This model uses field weighting (managed properties) for dynamic ranking. For instance, some properties are more important than others, like title or social rating.  For static ranking calculations, SharePoint search ranks a document higher  if a document in a search results set was visited (click through) from a search results page.  In this post I will explain how SharePoint Search implements the tracking of click through events by users from the search results page. Also, I will show how custom search applications can leverage a SharePoint web service and the object model to log click through events.


Enable Query Logging

The first step of making sure search result click through events are used in ranking calculations is to enable query logging in the Search Service Application associated with the web application.  This can be enabled by navigating to the Search Service Application in Central Administration and clicking the Enable link next to Query Logging.



The Life of a Search Results Click Event

The flow diagram below illustrates the steps taken to process a search result click through in order for it to affect the relevance ranking of the document.


The first step of this process is initiated by the Core Search Results Web Part using JavaScript. The web part emits JavaScript to call the Search web service’s RecordClick method when a user clicks on the title or the URL of the result item. You can easily verify this using Fiddler. In the second step the Search web service calls the associated Search Service Application’s RecordClick method. The service application then calls the internal QueryLogger’s RecordClick method which in turn then calls the internal QueryLogQueue. This object caches the information sent and periodically flushes the data to the MSSQLogUnprocessed table contained in the Search Service Application’s database. These unprocessed URLs are processed and used in the next ranking calculation.

In addition to tracking click through events from search result items the web part will also track click through events for Best Bets. Best Bets are suggested links set up by search administrators that represent the most relevant documents for given keyword terms. Best Bet click through events are used to help manage Best Bet using the Best Bet Usage page in the Search Keywords section of Site Collection Administration. The search administrator can use this information to determine if Best Bets are being used.


Enable Custom Search Applications Click Through

SharePoint Search only records the search result click through event if query logging is enabled and if the search results are hosted in the Core Search Results Web Part. Custom search applications that do not use this web part must implement it. There are two methods to track search result  click through events, one using the Search web service’s RecordClick method or the SearchServiceApplication class’s  RecordClick method.


Search Web Service RecordClick Method

Custom search applications running remotely should use the Search web service to record a click through event. The important task is to create and populate the xml that is sent to this method. The xml represents a serialized Microsoft.Office.Server.Search.Query.QueryInfo class. If you reflect the QueryInfo class you will see custom xml serialization attributes and elements defined for each property. The attributes are cryptic. Below is an example of an xml serialized QueryInfo object:

The “c” element represents the URL that was clicked. The “g” attribute represents the guid ID for the SPSite that the search was executed from and is required. The “qi”  element is required and represents the id of the query. In the case of custom search applications you can create your own guid for the query id. Finally, the “t” attribute represents the time that the search was executed and is required. You must also send it in UTC format. Below is sample code for recording a click through event using the Search web service.

public static void RecordSearchClick()
    string xmlTemplate = "<i  ";
    xmlTemplate += "g=\"e1c43a36-4dcf-4fd9-9287-30e7773c4159\" ";
    xmlTemplate += "t=\"2011-05-31T21:49:28.0642745-05:00\" ";
    xmlTemplate += "xmlns=\"urn:Microsoft.Search\"> ";
    xmlTemplate += "<qi>" + Guid.NewGuid().ToString() + "</qi>";
    xmlTemplate += "<c>http://basesmc2008/tester/pdfimg.pdf</c> "; 
    xmlTemplate += "</i>";

    search.QueryService queryService = new search.QueryService();
    queryService.Url = "http://basesmc2008/_vti_bin/search.asmx";
    queryService.UseDefaultCredentials = true;



Search Service Application RecordClick Method

Custom search applications that can access the SharePoint object model should use the Microsoft.Office.Server.Search.Administration.SearchServiceApplication object associated with the web application it is running in.  This class exposes a RecordClick method using a QueryInfo object as an argument.  The Search web service RecordClick method calls this same method by de-serializing the xml sent to it into a QueryInfo object, then passing it as an argument. The code below shows you an example.

SPFarm farm = SPFarm.Local;
SearchServiceApplication searchApp = (SearchServiceApplication)farm.Services.
    Applications.GetValue<SearchServiceApplication>("Search Service Application");

using(SPSite site = new SPSite("http://basesmc2008"))
    QueryInfo qi = new QueryInfo();
    qi.QueryGuid = Guid.NewGuid().ToString();
    qi.ClickedUrl = "http://basesmc2008/tester/pdfimg.pdf";
    qi.SearchTime = DateTime.Now;
    qi.ClickTime = DateTime.Now;
    qi.SiteGuid = site.ID.ToString();


Relevant Clicking

Search result click through events influence the relevance of a document. The action is important enough for Microsoft to integrate the tracking of this action directly into the Core Search Results Web Part. If your custom search applications do not extend this web part, then you can enable the same type of tracking using one of these two methods. The QueryInfo class is the structure used to hold this information. I recommend looking at this class further. The class has many properties and is also used for logging queries for search administration reporting. Other properties may play a role in influencing relevance, for example, the NonClickedUrls property can hold a string array of URLs that were not clicked. So it appears that not clicking on search result items can lower their relevance.

1 comment:

Anonymous said...

Very interesting article! Thank you!

Post a Comment