Search Extensions

Extensions for performing searches in Umbraco.

v1.x supports Umbraco Umbraco 8.1+, v2.x supports Umbraco 9, and v3.x supports Umbraco versions 10 and beyond.

Querying

There are several short-hand extension methods for querying Umbraco content in an index – checking if an item is published, is visible, or has a template.

Querying only published content items can be done like this: query.And().IsPublished()

Similarly, querying all content where the umbracoNaviHide property is not set can be done like this: query.And().IsVisible()

It is possible to query content with a specific template ID set. If 0 or no value is passed to the method, the query will match content with any templatee ID set. query.And().HasTemplate(int templateId)

Finally, it is possible to query for content that has any one of the specified content type aliases. Out of the box Umbraco supports querying for a single content alias. query.And().NodeTypeAlias(string[] aliases)

Cultures

Umbraco properties that have been set to "vary by culture" are indexed with a specific alias: {culture}_{fieldName}. For example, if the "pageTitle" field varies by culture and has 2 languages, English and Spanish, the index would contain 2 fields: "en_pageTitle" and "es_pageTitle".

A culture can be passed to Field and NodeName queries like this:

query.And().Field(string field, string culture)

query.And().NodeName(string nodeName, string culture)

It even works with grouped queries such as GroupedAnd, GroupedOr, and GroupedNot, where multiple fields can be specified: query.And().GroupedOr(string[] fields, string culture)

Searching

The SearchHelper class contains logic for commonly performed actions when searching, particularly helpful for creating paged search functionality.

The Get<T> method gets all results for a query cast to a given type, including IPublishedContent.

var query = searcher.CreatePublishedQuery();

var results = searchHelper.Get<T>(query, out int totalResults);

The Page<T> method efficiently gets a given number of items (perPage) at a specific position (page) in the results for a query An optional type constraint can be added to also return paged results cast to IPublishedContent.

var query = searcher.CreatePublishedQuery();

var results = searchHelper.Page<T>(query, int page, int perPage, out int totalResults);

All helper methods provide the total number of results found as an out parameter.

Results

For more specific cases where the SearchHelper is not appropriate, the same features for accessing strongly typed results are available as extension methods.

An entire results collection can be cast to a type like this:

var results = query.Execute().GetResults<T>();

Specific fields from an individual search result can be accessed via the .Value<T>() extension method like this:

foreach (var result in query.Execute())
{
    var value = result.Value<T>(string field);
}

Advanced fields

Search Extensions introduces several new field types into Examine – JSON, list, UDI and picker – to ensure Umbraco data is correctly indexed and queryable. Defining which fields in the index use which types is done through the IExamineManager:

if (examineManager.TryGetIndex("ExternalIndex", out IIndex index))
{
    index.FieldDefinitionCollection.AddOrUpdate(new FieldDefinition("fieldName", "fieldType"));
}

The picker field type adds search-friendly aliases for the picked items into the index.

A picker with a selected a content item called "Example Page" can be queried like this:

query.Field("somePicker", "example-page");

Umbraco's "path" field is automatically indexed as a list and so a content item with the path "-1,1050,1100" can be queried like this:

query.Field("path", "1100");

Umbraco's "createDate" and "updateDate" fields are automatically indexed as date values, whereas they would be regularly indexed as string values.