SharePoint makes great use of its Search engine and it is pervasive throughout most SharePoint solutions today. Whether you are building Content Search WebParts leveraging Display Templates or creating a custom Search center you will be making use of SharePoint’s powerful and mature Search engine. However, what happens when things behave unexpectedly? How can you troubleshoot Search? This article will focus mainly on SharePoint Online (O365) but could also be applied to Search on premises.
Search is not magic!
When supporting others in their troubleshooting of Search issues I usually start by explaining that Search is not a black art. I would agree there are nuances but, for the most part, figuring out issues can follow simple scientific process. After all, SharePoint Search is just a collection of properties stored for query and retrieval by the Search engine.
The perception that Search is a black art often extends to users and their expectations. When search does not yield the results a user expects we should always investigate what they expect and why they expect it. Work directly with end users and try to help them understand why they are not getting what they expect.
Approach to Troubleshooting
Generally speaking it is advisable to try and make small but smart moves when changing configuration. It can sometimes take days or weeks to test the results of your configuration changes if long re-crawls are required. Above all, be scientific! Use the same test cases before and after changes and measure your results by tracking search results before and after.
The two sides of Search
There are two sides to Search, Crawl and Query. Potentially either side could be failing or not working as expected so it is important to investigate both.
SharePoint Online in O365 does not currently offer too much control nor insight into the Crawl side (this may change in future). SharePoint 2013 on premises offers lots of opportunity to troubleshoot the crawl. On premises we can:
- Inspect the crawl log
- Turn on verbose logging during crawls
- Attach crawls to Fiddler
The Query side can be inspected almost equally online as it can be on premises. It’s important to understand that Search queries are transformed as they are passed to the search engine. The user can type a query into a search box but there are number of places the query could be transformed or results influenced by search configuration:
- Search Results WebPart e.g. in a Search Center
- Content by Search WebPart
- Results Source
- Query Rules
- Synonyms
Inspect the Query using the Query Builder
There are at least two great ways to inspect the Query side of Search.
One, use the OOTB Query Builder to help you. From a Content by Search or Search Results WebPart you can open the Query Builder. Switch to Advanced Mode (you are most definitely Advanced now!) and then head over to the TEST tab. Once on the TEST tab click ‘Show more’ to see the full transformation of the query in the bottom text box (highlighted).
Seeing the full transformation of the query is important because there may well be transformations impacting results you had not thought of. In addition if any part of the query is using dynamic property values based upon the Page or User (e.g. {User.ProfileProperty}) these values will be expanded and displayed for inspection.
Inspect the Query using the 2013 Search Tool
The SharePoint 2013 Search Query Tool is now an essential part of my day-to-day work with SharePoint Search. It uses the REST API to retrieve results from SharePoint Search and can be used with SharePoint Online (O365) and On Premises SharePoint 2013.
http://sp2013searchtool.codeplex.com
The tool provides a fast, convenient and repeatable way to inspect Search results. A few tips for using this tool most effectively:
- Be scientific! Use fixed queries, analyze results before and after configuration changes.
- Turn off Trim Duplicates, it will be ON by default. Trimming duplicates can be really confusing when analyzing results, especially when you have repetitive test data in a system.
- Ensure you are using the correct Results Source. By default this will be set to Local SharePoint Results. However, if custom Result Sources are in play be sure to set them in the tool. You will need the GUID identifying the Results Source, this can be obtained easily by browsing to the Results Source in SharePoint and grabbing the ID from the querystring.
- Inspect the Rank values returned. The rank values will determine which results appear first. If any parts of the transformation use XRANK to boost results then this should be evident in the Rank value.
Check the basics
Are you writing valid Keyword Query Language (KQL)? SharePoint Search can only understand KQL and not syntax from other search engines such as Google, Solr, Westlaw, Lexis etc.
http://msdn.microsoft.com/en-us/library/office/ee558911.aspx
If the user is expecting a specific document to be returned has that document actually been indexed? This can be verified by performing a Path search e.g.:
Path:http://contoso.sharepoint.com/documents/document.docx
On Premises you could also check the crawl log to see if the item hit an error during indexing.
If the search query is expecting to hit document body content you should also check that the source text is readable by the search engine. In the case of PDF documents, they will need to be OCR’d.
Managed Properties
It’s likely that Search is not behaving the way users expect due to Managed Property configuration. Managed Properties are really the backbone of the search engine and our greatest opportunity for customization. They are also our greatest opportunity to make mistakes in configuration. We need to check the Managed Property settings. This article does not fully explore Managed Property configuration but here are the basic settings we should consider when troubleshooting:
- Searchable – Enables us to query against the content of the property, the content is stored in the full-text index. On premises we can also set the ‘Context’ of the property which will allow different weighting to be applied.
- Queryable – Enables us to query directly against the property e.g. Title:Hines . Note that this is different to simply being included in the full text index.
- Retrieveable – Enables us to retrieve the value of the property in search results. If a property is not retrievable it can sometimes be confusing when trying to inspect it using the search tool. The value may be Queryable and used in queries but not retrieveable so that we can inspect it.
- Refinable – Means that it can be used in a search by refinement. Note that this is different to querying properties.
- Sortable – Means that results could be sorted by this property.
- Mappings – Managed Properties will be mapped to one or more Crawled Properties. This relationship is worth reading more about and the necessity to re-crawl after changing these values in important to consider. When more than one Crawled Property is selected be sure that the configuration is resulting
It’s really important during any Search project to have consistent and well-understood Managed Property configuration. At Perficient we often build a Managed Properties Specification which allows us to collaborate on how properties will be configured. In addition it is highly recommended to script Managed Property configuration so that Development, QA and Production environments are the same. It’s very easy to let this slip and have misconfigurations confuse you when testing across multiple environments. More on script deployment to O365:
https://blogs.perficient.com/microsoft/2014/09/powershell-deployment-to-sharepoint-online
OOTB Title Managed Property
The ‘Title’ Managed Property is probably the single greatest point of confusion I see in SharePoint Search projects. Looking at the Mapping configuration it is already apparent that it’s complicated.
Unfortunately the MetadataExtractorTitle has, in my opinion, only added to this confusion. If your users are relaxed about seeing an interpreted Title in search results then you will most likely not get feedback. However, it appears most users get confused about this and require us to troubleshoot exactly why their Title is not displaying as expected in Search results. In response to this, you can of course look at the Crawled Property ordering and try to determine exactly why the Title Managed Property is populated as such. However, if it transpires this is a major problem for users I would look into creating your own separate Managed Property for handling Title.
Low level Debugging
Detailed debugging during a crawl or query is reserved for SharePoint on premises. During a crawl we can turn on VerboseEx logging and analyze the detail of what’s happening during acquisition. This could point to a number of problems including communication with the source during a crawl or an issue with security trimming when querying.
If you need to pursue a Search support incidents with Microsoft it is most likely Microsoft will ask for VerboseEx log. The only caution with this is that VerboseEx will grow the logs very quickly so it’s recommended you ensure it is only enabled for a short period of time.
Good luck!
SharePoint Search does have its challenges but it is also extremely powerful and offers great patterns for surfacing content. We see it making its way into new areas and services in Office 365 all the time. Embrace it! I think it’s here to stay.
