Faceting
Faceting
Section titled “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 executed as an Elastic Search aggregation in the same request as the query, so there’s no extra round trip.
Defining facet fields
Section titled “Defining facet fields”A field needs to be defined with one of Examine’s facet field types so that it’s mapped in Elastic Search with a type that can be aggregated:
| Examine field type | Elastic Search field type |
|---|---|
FieldDefinitionTypes.FacetFullText / FacetFullTextSortable |
keyword |
FieldDefinitionTypes.FacetLong / FacetTaxonomyLong |
long |
FieldDefinitionTypes.FacetFloat / FacetTaxonomyFloat |
float |
FieldDefinitionTypes.FacetDouble / FacetTaxonomyDouble |
double |
FieldDefinitionTypes.FacetDateTime / FacetTaxonomyDateTime |
date |
FieldDefinitionTypes.FacetDateYear, FacetDateMonth, FacetDateDay, FacetDateHour, FacetDateMinute (and the taxonomy versions) |
date (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. With FacetString the bucket labels are the rounded dates as Unix epoch milliseconds, since that’s how Elastic Search returns terms for a date field.
For example:
services.Configure<ElasticSearchIndexOptions>("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));});Changing the type of a field that already exists in your index means the mapping changes, so you’ll need to rebuild the index.
Querying facets
Section titled “Querying facets”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:
FacetDateTimeRangeis an ExamineX extension method (in theExamineX.Sharednamespace) since Examine itself doesn’t have aDateTimeOffsetrange facet.Facet("field")andFacetString("field")are the same thing, they both return the term counts for a field.FacetStringreturns the top 10 terms by default. UseMaxCountto change that, e.g..FacetString("Location", c => c.MaxCount(5)).- Passing values to
FacetStringfilters the search results to those values, e.g..FacetString("Location", null, "Sydney")only returns documents in Sydney and the facet counts reflect that filter. - Facets are populated once the search has executed, so either enumerate the results or read
TotalItemCountfirst. ReadingFacetswill also execute the search if it hasn’t been already.
Range boundaries
Section titled “Range boundaries”Elastic Search range buckets always include the from value and exclude the to value. ExamineX converts the inclusive/exclusive flags on Examine’s ranges to fit that. For long ranges this is 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. This matches how the Azure Search provider buckets values so you get the same counts from both.