Search API

Searching content via SharePoint API

Search and search API is a huge and complex topic. In this article we're going mostly cover some basics in combination of Gosip plus REST API.

Basic search call

While executing search call there is no difference what web/site is used as a context, search API returns data due to search query object.

The simplest request looks this way:

// `res`ult here is a byte array with some helper methods as .Results()
res, err := sp.Search().PostQuery(&api.SearchQuery{
    QueryText: "*",
    RowLimit:  5,
})

if err != nil {
    log.Fatal(err)
}

fmt.Printf("%+v\n", res.Results())

Search query

Search query struct (api.SearchQuery) contains some, let's say, reasonable amount of options 🙈.

Option	Description
QueryText	A string that contains the text for the search query
QueryTemplate	A string that contains the text that replaces the query text, as part of a query transform
EnableInterleaving	A Boolean value that specifies whether the result tables that are returned for the result block are mixed with the result tables that are returned for the original query
EnableStemming	A Boolean value that specifies whether stemming is enabled
TrimDuplicates	A Boolean value that specifies whether duplicate items are removed from the results
EnableNicknames	A Boolean value that specifies whether the exact terms in the search query are used to find matches, or if nicknames are used also
EnableFQL	A Boolean value that specifies whether the query uses the FAST Query Language (FQL)
EnablePhonetic	A Boolean value that specifies whether the phonetic forms of the query terms are used to find matches
BypassResultTypes	A Boolean value that specifies whether to perform result type processing for the query
ProcessBestBets	A Boolean value that specifies whether to return best bet results for the query. This parameter is used only when EnableQueryRules is set to true, otherwise it is ignored.
EnableQueryRules	A Boolean value that specifies whether to enable query rules for the query
EnableSorting	A Boolean value that specifies whether to sort search results
GenerateBlockRankLog	Specifies whether to return block rank log information in the BlockRankLog property of the interleaved result table. A block rank log contains the textual information on the block score and the documents that were de-duplicated.
SourceID	The result source ID to use for executing the search query
RankingModelID	The ID of the ranking model to use for the query
StartRow	The first row that is included in the search results that are returned. You use this parameter when you want to implement paging for search results.
RowLimit	The maximum number of rows overall that are returned in the search results. Compared to RowsPerPage, RowLimit is the maximum number of rows returned overall.
RowsPerPage	The maximum number of rows to return per page. Compared to RowLimit, RowsPerPage refers to the maximum number of rows to return per page, and is used primarily when you want to implement paging for search results.
SelectProperties	The managed properties to return in the search results
Culture	The locale ID (LCID) for the query
RefinementFilters	The set of refinement filters used when issuing a refinement query (FQL)
Refiners	The set of refiners to return in a search result
HiddenConstraints	The additional query terms to append to the query
Timeout	The amount of time in milliseconds before the query request times out
HitHighlightedProperties	The properties to highlight in the search result summary when the property value matches the search terms entered by the user
ClientType	The type of the client that issued the query
PersonalizationData	The GUID for the user who submitted the search query
ResultsURL	The URL for the search results page
QueryTag	Custom tags that identify the query. You can specify multiple query tags
ProcessPersonalFavorites	A Boolean value that specifies whether to return personal favorites with the search results
QueryTemplatePropertiesURL	The location of the queryparametertemplate.xml file. This file is used to enable anonymous users to make Search REST queries
HitHighlightedMultivaluePropertyLimit	The number of properties to show hit highlighting for in the search results
EnableOrderingHitHighlightedProperty	A Boolean value that specifies whether the hit highlighted properties can be ordered
CollapseSpecification	The managed properties that are used to determine how to collapse individual search results. Results are collapsed into one or a specified number of results if they match any of the individual collapse specifications. In a collapse specification, results are collapsed if their properties match all individual properties in the collapse specification.
UIlanguage	The locale identifier (LCID) of the user interface
DesiredSnippetLength	The preferred number of characters to display in the hit-highlighted summary generated for a search result
MaxSnippetLength	The maximum number of characters to display in the hit-highlighted summary generated for a search result
SummaryLength	The number of characters to display in the result summary for a search result
SortList	The list of properties by which the search results are ordered
Properties	Properties to be used to configure the search query
ReorderingRules	Special rules for reordering search results. These rules can specify that documents matching certain conditions are ranked higher or lower in the results. This property applies only when search results are sorted based on rank.

But don't be afraid you use only a few of them and on demand and when know what you need.

User profiles search sample

res, err := sp.Search().PostQuery(&api.SearchQuery{
	QueryText:        "*",
	RowLimit:         5,
	SelectProperties: []string{"AccountName", "Title", "Department", "JobTitle"},
	StartRow:         10,
	TrimDuplicates:   false,
	SourceID:         "b09a7990-05ea-4af9-81ef-edfab16c4e31",
	SortList: []*api.SearchSort{
		&api.SearchSort{
			Property:  "Title",
			Direction: 0,
		},
	},
})

if err != nil {
	log.Fatal(err)
}

fmt.Printf("AccountName | Title | Department | JobTitle\n")
fmt.Printf("------------|-------|------------|---------\n")
for _, profile := range res.Results() {
	fmt.Printf(
		"%s | %s | %s | %s\n",
		profile["AccountName"],
		profile["Title"],
		profile["Department"],
		profile["JobTitle"],
	)
}

This search request searched only for user profiles (defined by SourceID), return five results per page, skips first ten records ignores trimming duplicates, retrieves specific managed properties and sorts by Title property.

Search response

Search response in Fluent API is sligtly bit adjusted with helper methods. Result itself is byte array, so you can process it in a custom way.

For lazy people (as I am) there are .Data() and .Results() helpers.

Results helper

Results helper retrieves PrimaryQueryResult.RelevantResults.Table.Rows and reduces search response results to the convenient array of string maps. So you can grasp results this way:

for _, profile := range res.Results() {
	fmt.Printf(
		"%s | %s | %s | %s\n",
		profile["AccountName"],
		profile["Title"],
		profile["Department"],
		profile["JobTitle"],
	)
}

Data helper

Data helper provides more options. It returns the following struct:

type SearchResults struct {
	ElapsedTime           int
	PrimaryQueryResult    *ResultTableCollection
	Properties            []*TypedKeyValue
	SecondaryQueryResults []*ResultTableCollection
	SpellingSuggestion    string
	TriggeredRules        []interface{}
}

type ResultTableCollection struct {
	QueryErrors        map[string]interface{}
	QueryID            string
	QueryRuleID        string
	CustomResults      *ResultTable
	RefinementResults  *ResultTable
	RelevantResults    *ResultTable
	SpecialTermResults *ResultTable
}

So you can have access to refiners and many more search goodies.