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 sent to Azure AI Search as a facet expression on the same request as the query.
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 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.
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 Azure’s default number of terms (10). UseMaxCountto change that, e.g..FacetString("Location", c => c.MaxCount(5)).- Passing values to
FacetStringfilters the search results to those values (usingsearch.in), e.g..FacetString("Location", null, "Sydney")only returns documents in Sydney and the facet counts reflect that filter.
Range boundaries
Section titled “Range boundaries”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.