Edit

Using the SharePoint search Query APIs

  • Article

Learn about the query APIs available in SharePoint that enable you to add search functionality to custom solutions and applications.

SharePoint Query APIs

Search in SharePoint provides several query APIs, giving you lots of ways to access search results, so that you can return search results in a variety of custom solution types.

In addition to the server object model that was available in previous versions of SharePoint, Search in SharePoint also provides the following:

  • Client object model (CSOM)
  • JavaScript object model (JSOM)
  • Representational State Transfer (REST) service

Table 1 shows the APIs that you can use to program search queries and the path to the source file on the server.

Table 1. Search APIs

API name Class library or schema and path
.NET CSOM
Microsoft.SharePoint.Client.Search.dll
%ProgramFiles%\Common Files\Microsoft Shared\web server extensions\15\ISAPI
Silverlight CSOM
Microsoft.SharePoint.Client.Search.Silverlight.dll
%ProgramFiles%\Common Files\Microsoft Shared\web server extensions\15\TEMPLATE\LAYOUTS\ClientBin
JavaScript CSOM
SP.search.js
%ProgramFiles%\Common Files\Microsoft Shared\web server extensions\15\TEMPLATE\LAYOUTS
REST service endpoints
https://{site_url}/_api/search/query
https://{site_url}/_api/search/suggest
Server object model
Microsoft.Office.Server.Search.dll
%ProgramFiles%\Common Files\Microsoft Shared\web server extensions\15\ISAPI

As a best practice in SharePoint development, use client APIs when you can. Client APIs include the .NET, Silverlight, Phone, and JavaScript client object models, and the REST service. For more information about the APIs in SharePoint and when to use them, see Choose the right API set in SharePoint.

Query using the .NET client object model

Search in SharePoint includes a client object model that enables access to search results for online, on-premises, and mobile development. The Search in SharePoint CSOM is built on the SharePoint CSOM. Therefore, your client code first needs to access the SharePoint CSOM and then access the Search in SharePoint CSOM. For more information about the SharePoint CSOM and the ClientContext class, which is the entry point to the CSOM, see Complete basic operations using SharePoint client library code.

For the .NET managed CSOM, get a ClientContext instance (located in the Microsoft.SharePoint.Client namespace in the Microsoft.SharePoint.Client.dll). Then use the object model in the Microsoft.SharePoint.Client.Search.Query namespace in the Microsoft.SharePoint.Client.Search.dll.

Here's a basic example.

using (ClientContext clientContext = new ClientContext("http://<serverName>/sites/<siteCollectionPath>"))
{
  KeywordQuery keywordQuery = new KeywordQuery(clientContext);
  keywordQuery.QueryText = "SharePoint";
  SearchExecutor searchExecutor = new SearchExecutor(clientContext);
  ClientResult<ResultTableCollection> results = searchExecutor.ExecuteQuery(keywordQuery);
  clientContext.ExecuteQuery();
}

To download an example, see the following code sample posted by SharePoint MVP Corey Roth: SharePoint: Query Search with the Managed Client Object Model.

Query using the JavaScript client object model

For the JavaScript CSOM, get a ClientContext instance, and then use the object model in the SP.Search.js file.

Here's a basic example.

var clientContext = new SP.ClientContext("<serverRelativeUrl>");
var contextSite = clientContext.get_site();
var keywordQuery = new Microsoft.SharePoint.Client.Search.Query.KeywordQuery(clientContext);
keywordQuery.set_queryText("SharePoint");
var searchExecutor = new Microsoft.SharePoint.Client.Search.Query.SearchExecutor(clientContext);
var results = searchExecutor.executeQuery(keywordQuery);
context.executeQueryAsync(onQuerySuccess, onQueryError);

To download an example, see the following code sample posted by SharePoint MVP Corey Roth: SharePoint: Query Search with the Managed Client Object Model.

Query using the REST service

SharePoint includes a REST service that enables you to remotely execute queries against the SharePoint Search service from client applications by using any technology that supports REST web requests. The Search REST service exposes two endpoints, query and suggest, and will support both GET and POST operations. Results are returned in either XML or JavaScript Object Notation (JSON) format.

The following is the access point for the service: https://{site_url}/_api/search/ using the root site as the query entry point. You can also specify another site in the URL, as follows: https://{site_url}/site/_api/search/. The URL prefix before /_api/search/ will use the default result source defined at that site/scope and query rules will also be contextual to the URL used, unless parameters are used to override this behavior. Unless any specific search configuration is made at a site, the results are the the same for both ways to access the service.

See SharePoint Search REST API overview and Retrieving query suggestions using the Search REST service for more information.

Query using the .NET server object model

Applications that use the server object model must run directly on a server that is running SharePoint. The search Query server object model resides in the Microsoft.Office.Server.Search.Query namespace, which is located in Microsoft.Office.Server.Search.dll.

As in SharePoint Server 2010, you use the KeywordQuery class to define the query, and then called the Execute() method to submit the query. In SharePoint, the Execute method is obsolete, and while it will still work, you should use the SearchExecutor class instead. To submit the query, call the ExecuteQuery() method, passing the instance of the KeywordQuery class in the call.

Here's a basic example.

using (SPSite siteCollection = new SPSite("<serverRelativeUrl>"))
{
  KeywordQuery keywordQuery = new KeywordQuery(siteCollection);
  keywordQuery.QueryText = "SharePoint";
  SearchExecutor searchExecutor = new SearchExecutor();
  ResultTableCollection resultTableCollection = searchExecutor.ExecuteQuery(keywordQuery);
  resultTableCollection = resultTableCollection.Filter("TableType", KnownTableTypes.RelevantResults);
  ResultTable resultTable = resultTableCollection.FirstOrDefault();
  DataTable dataTable = resultTable.Table;
}

To download an example, see the following code sample posted by SharePoint MVP Corey Roth: SharePoint: Query Search with the Managed Client Object Model.

See also