Repository navigation
Facets
A facet query counts how many matching objects carry each value of a property: how many notes per tag, how many products per brand, how many orders per month. The counts come from the same Lucene search that returns the results, so a results page and its filter sidebar cost one query.
Facets need LottaDB 5.3.0 or later.
Facets are opt-in. Mark the properties you want to count:
Attribute-based:
public class Product
{
[Key]
public string Id { get; set; } = "";
[Queryable(QueryableMode.NotAnalyzed, Facet = true)]
public string Category { get; set; } = "";
[Queryable(Facet = true)] // still full-text searchable
public string Brand { get; set; } = "";
[Queryable(Facet = true)] // string collections work
public List<string> Tags { get; set; } = new();
[Queryable(Facet = true)] // numbers and dates also get range counts
public double Price { get; set; }
[Queryable(Facet = true)]
public DateTime Released { get; set; }
}Fluent:
config.Store<Product>(s =>
{
s.AddQueryable(p => p.Category).NotAnalyzed().Facet();
s.AddField(p => p.Brand).Facet();
});The fluent call configures a property only when it has no [Queryable] or [Field] attribute; an attribute wins.
Facet works on strings, string collections, int, long, double, bool, Guid, DateTime and DateTimeOffset. It can't be combined with Vector = true on the same property. Lucene.Net.Linq's own [Field(Facet = true)] is honoured too.
Declaring a facet changes the schema, so LottaDB rebuilds the search index the next time the database is opened (see Schema Migration). Objects saved earlier are counted after that rebuild; there is nothing to re-save.
.Facets(...) is an extension method from Lucene.Net.Linq. Add it to any Search<T>() query:
using Lucene.Net.Linq;
var page = db.Search<Product>()
.Where(p => p.Category == "phone")
.Facets(out var facets, f => f
.Count(p => p.Tags) // every value
.Count(p => p.Brand, top: 10)) // the 10 most common
.OrderBy(p => p.Price)
.Take(20)
.ToList();
foreach (var value in facets.For(p => p.Tags))
Console.WriteLine($"{value.Label}: {value.Count}");-
Counts cover every match, not just the page:
TakeandSkipdon't change them. -
Counts are filled when the query runs (
ToList(),Count(), aforeach...). Readingfacetsbefore that throws. - Values come back by count, highest first, then by value.
-
Labels are the values as you stored them.
"Berlin"and"berlin"are two values, even on an analyzed property that searches case-insensitively. Null and empty values are skipped. - Call
.Facets(...)before anySelect. -
Counts follow the query. A
Where, a predicate, or a query string (db.Search<Product>("zen")) narrows the counts the same way it narrows the results. -
Base types include derived types. Counts on
Search<Vehicle>()include every storedTruck.
Numbers and dates can be counted in buckets:
db.Search<Product>()
.Facets(out var facets, f => f
.Ranges(p => p.Price, new[]
{
new FacetRange("under 100", null, 100.0), // null = unbounded
new FacetRange("100 to 1000", 100.0, 1000.0),
new FacetRange("1000 and up", 1000.0, null),
})
.Ranges(p => p.Released, FacetRange.Yearly(from, to)))
.ToList();
foreach (var bucket in facets.For(p => p.Price))
Console.WriteLine($"{bucket.Label}: {bucket.Count}");- Ranges include their lower bound and exclude their upper bound.
- Buckets come back in the order you gave them. A value is counted in every range that contains it.
-
FacetRange.Daily,MonthlyandYearlybuild date buckets. - Use
Rangesfor dates.Counton a date gives one value per distinct instant, labelled in LottaDB's index format. - String collections have value counts only.
-
Search<object>()returns a plain list, not a Lucene query, so it has no facets. Use a typedSearch<T>(). - Asking for counts on a property that isn't declared as a facet throws.
- With a
join, counts cover the objects that join only when the join runs inside Lucene (see Search and LINQ). A join done in memory does not narrow the search, so its counts cover every object the query matched before the join. - The first facet query after the index changes builds a lookup table for the new index state, so it is slower than the ones after it.