Skip to content
Tom Laird-McConnell edited this page Nov 13, 2026 · 2 revisions

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.

Declaring a facet

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.

Counting values

.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: Take and Skip don't change them.
  • Counts are filled when the query runs (ToList(), Count(), a foreach...). Reading facets before 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 any Select.
  • 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 stored Truck.

Counting ranges

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, Monthly and Yearly build date buckets.
  • Use Ranges for dates. Count on a date gives one value per distinct instant, labelled in LottaDB's index format.
  • String collections have value counts only.

Limits

  • Search<object>() returns a plain list, not a Lucene query, so it has no facets. Use a typed Search<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.

Clone this wiki locally