Quick start

This guide will help you get setup quickly using Examine with minimal configuration options. Umbraco ships Examine with 2 internal indexes which should not be used for searching when returning results on a public website because it indexes content that has not been published yet. It also ships with an external index that you can use to get up and running.

Create an index

To create a searchable index we need to create 3 components: an Indexer a Searcher and an Index Set. Umbraco 7 ships with these three components ready to go, but you can use the below as a reference as you walk through your implementation.

1. Open ~/Config/ExamineSettings.config and add an indexer under the 'ExamineIndexProviders/providers' section (in this example it is named ExternalIndexer):

<add name="ExternalIndexer" type="UmbracoExamine.UmbracoContentIndexer, UmbracoExamine" />

1. In the same file (~/Config/ExamineSettings.config) add a searcher under the 'ExamineSearchProviders/providers' section (in this example it is named ExternalSearcher):

<add name="ExternalSearcher" type="UmbracoExamine.UmbracoExamineSearcher, UmbracoExamine" />

1. In the same file we'll change the default search provider to the one we've created, set defaultProvider="ExternalSearcher"

2. Open ~/Config/ExamineIndex.config and add an index set (in this example it is named ExternalIndexSet):

<IndexSet SetName="ExternalIndexSet" IndexPath="~/App_Data/TEMP/ExamineIndexes/External/" />

That's it, now we have a searchable index configured using Examine. Examine will detect that the index doesn't exist on the file system yet so the index will be rebuilt during application startup. Once that happens the index will automatically stay up to date with the data in Umbraco.

Naming conventions

It is important to note the naming conventions above. Your Indexer, Searcher and associated Index Set must all be named according to convention so that they match. With the above examples the naming conventions are:

ExternalIndexer
ExternalSearcher
ExternalIndexSet

Notice that the prefix is all the same, this is a requirement. The suffixes must also match so that the indexer name is suffixed with Indexer, the searcher is suffixed with Searcher and the index set is suffixed with IndexSet.

Searching

In all of these examples we assume that the page that is being loaded has a query string in the Url called 'query'. For example the URL might be: https://mysite.com/search?query=Hello which means we are searching for the term Hello.

MVC

In MVC we have a method called TypedSearch on the UmbracoHelper which will return a list of IPublishedContent objects.

@if (!string.IsNullOrEmpty(Request.QueryString["query"]))
{
    <ul>
        @foreach (var result in Umbraco.TypedSearch(Request.QueryString["query"]))
        {
            <li>
                <a href="@result.Url">@result.Name</a>
            </li>
        }
    </ul>
}

ExamineManager

To complete more complex searches, we can use the ExamineManager and our custom search provider to expose further functionality, such as being able to handle misspellings, for example. There is an example using this available on the ExamineManager page.

Fluent API

Examine offers a fluent search API which aims to make constructing complex searches straight-forward. The underlying API is determined by the provider implementation, with Examine exposing the appropriate methods. With the fluent API, we can introduce fuzzy-text search and boosting, which allows us to favour a search result if our search term is found in particular fields, including custom fields added to document types.

using Examine.LuceneEngine.SearchCriteria;

var query = Request.QueryString["query"];
var searcher = Examine.ExamineManager.Instance.SearchProviderCollection["ExternalSearcher"];

var searchCriteria = searcher.CreateSearchCriteria(Examine.SearchCriteria.BooleanOperation.Or);
var searchQuery = searchCriteria.Field("nodeName", query.Boost(5)).Or().Field("nodeName", query.Fuzzy()).And().Field("__IndexType", "content").And().OrderByDescending("createDate");
var searchResults = searcher.Search(searchQuery.Compile());
if(searchResults.Any())
{
<ul>
    @foreach (var result in searchResults)
    {
        var node = Umbraco.TypedContent(result.Id);
        <li>
        <a href="@node.Url">@node.Name</a>
        </li>
    }
</ul>
}

XSLT

The XSLT implementation of Examine has a few specific steps that you'll need to follow. They can be found as part of an XSLT Example.

Recommended resources

For more detailed examples of implementing search with Examine, the following resources can be extremely helpful

• Examining Examine by Peter Gregory.
• The worlds friendliest post on getting started with Examine (24 Days in Umbraco)