Architecture & DesignCustomize SharePoint 2013 Searches

Customize SharePoint 2013 Searches content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.


Customizing search in SharePoint 2013 can be achieved in many ways. The most common way is to customize search display templates and apply them to the out of the box search results web part.

In this article, we will learn how to customize using code. Customization through code can be achieved in two different ways: by using CSOM (client-side object model) or by using REST. CSOM is available in three flavors: JavaScript, Silverlight, and C#. In this article, we will mainly focus on customizing search by using REST and a client-side object model using JavaScript.


Let’s understand search architecture briefly before we explore code. Figure 1 explains how the CSOM model operates. In SP2013, the functionality provided by the client object model has expanded, to include accessing the search engine and execute queries against it. The CSOM endpoint has been extended to include REST capabilities.

Figure 1: The CSOM model

The right side of Figure 1 displays the various flavors available with CSOM; OData represents the RESTful endpoint for accessing data. In SharePoint 2010, the web service was accessed by using ‘_vti_bin/client.svc’; with 2013, the services can be accessed by using ‘_api’.

Crawled and Managed Property

In SharePoint 2010, there were two kinds of search server available, FAST and Enterprise. With SP2013, it’s all merged into one Enterprise server. For search to return results, two types of properties plays an important role, crawled properties and managed properties. Users can search only on managed properties.

Metadata extracted from lists and documents forms the crawled property. Crawled property can be structured data such as list columns or unstructured like keywords extracted from documents. A crawled property can be added to multiple managed property and multiple crawled property can also be mapped to single managed property.

Note: Managed property is automatically created for site columns that contains data during the crawl.


Refiners are based on the aggregation of managed property and count is calculated based on all the result of a search query, through only a few may be retrieved. Refiners are used to drill down the search results.


Let’s understand how to use the REST APIs to perform a search. The basic parameters that can be used to fetch result set are:

The following code snippet uses the JQuery Ajax method to fetch search results using REST. In Line 3, ‘Url’ is the query parameter for search and Line 5 directs the result to be returned in JSON format.

 1. $.ajax(
 2.    {
 3.       url: "http://server/site/_api/search/query?querytext='query'",
 4.       method: "GET",
 5.       headers: {
 6.          "accept": "application/json;odata=verbose"
 7.       },
 8.       Success: onSuccess,
 9.       Error: onError
10.    }
11. );

Lines 8 & 9 has the success and error method definitions that are executed once the query is executed.

CSOM Using JavaScript

To use CSOM in JavaScript, a reference to ‘search.js’ need to be included; this is located at ‘_layouts/15/’. In this example, the result is fetched based on a criteria and also some refiners.

To begin with, register the SP.Search.js by using the following command:

RegisterSod("search.js", _spPageContextInfo.webAbsoluteUrl +

The next code snippet retrieves the result set based on the keyword ‘home’ and also gets refinement values for managed metadata named ‘FileType’; in other words, refiners.

 1. var ctx = SP.ClientContext.get_current();
 2. var kquery = new Microsoft.SharePoint.Client.
 3. kquery.set_queryText("home");
 4. kquery.set_refiners("FileType");
 5. var exec = new Microsoft.SharePoint.Client.
 6. var result = exec.executeQuery(kquery);
 7. ctx.executeQueryAsync(function ()
 8. {
 9.    var resultValues = result.m_value.ResultTables[0];
10.    var resultRefiner = result.m_value.ResultTables[1];
11.    $("#resultDiv").append('<table>');
12.    $.each(resultValues.ResultRows, function () {
13.       $("#resultDiv").append('<tr>');
14.       $("#resultDiv").append('<td>' + this.Title + '</td>');
15.       $("#resultDiv").append('<td>' + this.Path + '</td>');
16.       $("#resultDiv").append('</tr>');
17.    });
18.    $("#resultDiv").append('</table>');
19.    $("#refinerDiv").append('<table>');
20.    $.each(resultRefiner.ResultRows, function () {
21.       $("#refinerDiv").append('<tr>');
22.       $("#refinerDiv").append('<td>' + this.RefinementName +
23.       $(quot;#refinerDiv").append('<td>(' + this.RefinementCount +
24.       $("#refinerDiv").append('</tr>');
25.    });
26.    $("#refinerDiv").append('</table>');
27. }
28. function (sender, args)
29. { });

Let’s analyze the code in detail. Line 1 gets the current context object. To create an object of type KeywordQuery (Microsoft.SharePoint.Client.Search.Query.KeywordQuery), SP.Search.js files need to be referenced. The KeywordQuery object creation takes the current context as an input parameter (Line 2).

The KeywordQuery object has two properties, set_queryText and set_refiners. Use the set_queryText property (Lines 3 & 4) to set the keyword and/or the query condition, and use set_refiners to specify the refiners to be retrieved for the search criteria. These refiners can be used to further drill down the data.

Line 5 creates the search executor object and line 6 uses executequery method to execute the search. The search is still not executed at this stage; the search is executed by running ctx.executeQueryAsync (Line 7).

If the search is executed without any errors, an array of result tables is returned. ResultTables[0] is the search results returned and the refiners are populated in ResultTables[1]. In this example, Line 9 stores the search results and the same is looped through and displayed on the UI (Line 12-17). Line 10 stores the refiner values and the same is looped through and displayed on the UI (Lines 20-25).


In this article, we covered customizing a search using CSOM and REST. This gives the flexibility to develop search-based applications. We also covered how refiners can be retrieved and these can be further used to drill down the search. We can also use sourceId to restrict the search results from a particular result source.


Get the Free Newsletter!

Subscribe to Developer Insider for top news, trends & analysis

Latest Posts

Related Stories