Skip to content
ExamineX
These docs are for ExamineX 11 · Umbraco 19 (pre-release). For the current release see ExamineX 6–10 · Umbraco 13–18.

Faceting

ExamineX supports the Examine 4 faceting APIs, so you get facet counts back with your search results using the same code you’d use with the Lucene provider. Under the hood each facet is sent to Azure AI Search as a facet expression on the same request as the query.

A field needs to be defined with one of Examine’s facet field types so that it’s created as facetable (and filterable) in Azure Search:

Examine field type Azure Search field type
FieldDefinitionTypes.FacetFullText / FacetFullTextSortable Edm.String
FieldDefinitionTypes.FacetLong / FacetTaxonomyLong Edm.Int64
FieldDefinitionTypes.FacetFloat / FacetDouble (and the taxonomy versions) Edm.Double
FieldDefinitionTypes.FacetDateTime / FacetTaxonomyDateTime Edm.DateTimeOffset
FieldDefinitionTypes.FacetDateYear, FacetDateMonth, FacetDateDay, FacetDateHour, FacetDateMinute (and the taxonomy versions) Edm.DateTimeOffset (rounded down to the resolution)

The date resolution types (FacetDateYear, FacetDateMonth, FacetDateDay, FacetDateHour and FacetDateMinute) are stored as dates, but each value is rounded down to that resolution when it’s indexed, the same as Examine’s Lucene provider. For example, with FacetDateMonth a value of 2024-03-17T14:25:00 is indexed as 2024-03-01T00:00:00, so FacetString on that field gives you one bucket per month.

Azure Search doesn’t have a single precision float field type (outside of vectors) so float facets are stored as doubles.

For example:

services.Configure<AzureSearchIndexOptions>("MyIndex", options =>
{
options.FieldDefinitions.AddOrUpdate(new FieldDefinition("Location", FieldDefinitionTypes.FacetFullText));
options.FieldDefinitions.AddOrUpdate(new FieldDefinition("IncomeBracket", FieldDefinitionTypes.FacetLong));
options.FieldDefinitions.AddOrUpdate(new FieldDefinition("AverageDailyHours", FieldDefinitionTypes.FacetFloat));
options.FieldDefinitions.AddOrUpdate(new FieldDefinition("HiringDate", FieldDefinitionTypes.FacetDateTime));
});

Azure Search doesn’t let you change the attributes of an existing field, so if a field already exists in your index without being facetable you’ll need to rebuild the index.

Use WithFacets on a query and then read the facets from the results:

var results = searcher.CreateQuery()
.All()
.WithFacets(facets => facets
.FacetString("Location")
.FacetLongRange("IncomeBracket",
new Int64Range("low", 1, true, 50_000, true),
new Int64Range("high", 50_001, true, 1_000_000, true))
.FacetFloatRange("AverageDailyHours",
new FloatRange("parttime", 0, true, 4.5F, true),
new FloatRange("fulltime", 4.5F, false, 14, true))
.FacetDateTimeRange("HiringDate",
new DateTimeRange("past", now.AddDays(-100), true, now, false),
new DateTimeRange("recent", now, true, now.AddDays(100), true)))
.Execute();
var location = results.GetFacet("Location");
foreach (var value in location)
{
Console.WriteLine($"{value.Label}: {value.Value}");
}
var redmondCount = location.Facet("Redmond").Value;

A few notes:

  • FacetDateTimeRange is an ExamineX extension method (in the ExamineX.Shared namespace) since Examine itself doesn’t have a DateTimeOffset range facet.
  • Facet("field") and FacetString("field") are the same thing, they both return the term counts for a field.
  • FacetString returns Azure’s default number of terms (10). Use MaxCount to change that, e.g. .FacetString("Location", c => c.MaxCount(5)).
  • Passing values to FacetString filters the search results to those values (using search.in), e.g. .FacetString("Location", null, "Sydney") only returns documents in Sydney and the facet counts reflect that filter.

Azure Search range facets are a list of cut points (values:a|b|c) and each bucket includes its lower value and excludes its upper value. ExamineX converts your ranges into those cut points and maps the buckets back to your labels, which has a couple of side effects:

  • Ranges can have gaps between them, but they can’t overlap. An overlapping range won’t line up with a bucket so it won’t be returned.
  • For long ranges the inclusive/exclusive flags are exact. For float, double and date ranges the adjustment is the smallest possible step (epsilon or a single tick), which means a value sitting exactly on a boundary between two adjacent ranges will normally land in the range that starts at that value.