Struct tantivy::collector::FacetCollector

pub struct FacetCollector { /* private fields */ }

Collector for faceting

The collector collects all facets. You need to configure it beforehand with the facet you want to extract.

This is done by calling .add_facet(...) with the root of the facet you want to extract as argument.

Facet counts will only be computed for the facet that are direct children of such a root facet.

For instance, if your index represents books, your hierarchy of facets may contain category, language.

The category facet may include subcategories. For instance, a book could belong to /category/fiction/fantasy.

If you request the facet counts for /category, the result will be the breakdown of counts for the direct children of /category (e.g. /category/fiction, /category/biography, /category/personal_development).

Once collection is finished, you can harvest its results in the form of a FacetCounts object, and extract your facet counts from it.

This implementation assumes you are working with a number of facets that is many hundreds of times smaller than your number of documents.

use tantivy::collector::FacetCollector;
use tantivy::query::AllQuery;
use tantivy::schema::{Facet, Schema, FacetOptions, TEXT};
use tantivy::{doc, Index};

fn example() -> tantivy::Result<()> {
    let mut schema_builder = Schema::builder();

    // Facet have their own specific type.
    // It is not a bad practise to put all of your
    // facet information in the same field.
    let facet = schema_builder.add_facet_field("facet", FacetOptions::default());
    let title = schema_builder.add_text_field("title", TEXT);
    let schema = schema_builder.build();
    let index = Index::create_in_ram(schema);
    {
        let mut index_writer = index.writer(15_000_000)?;
        // a document can be associated with any number of facets
        index_writer.add_document(doc!(
            title => "The Name of the Wind",
            facet => Facet::from("/lang/en"),
            facet => Facet::from("/category/fiction/fantasy")
        ))?;
        index_writer.add_document(doc!(
            title => "Dune",
            facet => Facet::from("/lang/en"),
            facet => Facet::from("/category/fiction/sci-fi")
        ))?;
        index_writer.add_document(doc!(
            title => "La Vénus d'Ille",
            facet => Facet::from("/lang/fr"),
            facet => Facet::from("/category/fiction/fantasy"),
            facet => Facet::from("/category/fiction/horror")
        ))?;
        index_writer.add_document(doc!(
            title => "The Diary of a Young Girl",
            facet => Facet::from("/lang/en"),
            facet => Facet::from("/category/biography")
        ))?;
        index_writer.commit()?;
    }
    let reader = index.reader()?;
    let searcher = reader.searcher();

    {
        let mut facet_collector = FacetCollector::for_field("facet");
        facet_collector.add_facet("/lang");
        facet_collector.add_facet("/category");
        let facet_counts = searcher.search(&AllQuery, &facet_collector)?;

        // This lists all of the facet counts
        let facets: Vec<(&Facet, u64)> = facet_counts
            .get("/category")
            .collect();
        assert_eq!(facets, vec![
            (&Facet::from("/category/biography"), 1),
            (&Facet::from("/category/fiction"), 3)
        ]);
    }

    {
        let mut facet_collector = FacetCollector::for_field("facet");
        facet_collector.add_facet("/category/fiction");
        let facet_counts = searcher.search(&AllQuery, &facet_collector)?;

        // This lists all of the facet counts
        let facets: Vec<(&Facet, u64)> = facet_counts
            .get("/category/fiction")
            .collect();
        assert_eq!(facets, vec![
            (&Facet::from("/category/fiction/fantasy"), 2),
            (&Facet::from("/category/fiction/horror"), 1),
            (&Facet::from("/category/fiction/sci-fi"), 1)
        ]);
    }

    {
        let mut facet_collector = FacetCollector::for_field("facet");
        facet_collector.add_facet("/category/fiction");
        let facet_counts = searcher.search(&AllQuery, &facet_collector)?;

        // This lists all of the facet counts
        let facets: Vec<(&Facet, u64)> = facet_counts.top_k("/category/fiction", 1);
        assert_eq!(facets, vec![
            (&Facet::from("/category/fiction/fantasy"), 2)
        ]);
    }

    {
        let mut facet_collector = FacetCollector::for_field("facet");
        facet_collector.add_facet("/");
        let facet_counts = searcher.search(&AllQuery, &facet_collector)?;

        // This lists all of the facet counts
        let facets: Vec<(&Facet, u64)> = facet_counts
            .get("/")
            .collect();
        assert_eq!(facets, vec![
            (&Facet::from("/category"), 4),
            (&Facet::from("/lang"), 4)
        ]);
    }

    Ok(())
}

Implementations

impl FacetCollector

pub fn for_field(field_name: impl ToString) -> FacetCollector

Create a facet collector to collect the facets from a specific facet Field.

This function does not check whether the field is of the proper type.

pub fn add_facet<T>(&mut self, facet_from: T)

where Facet: From<T>,

Adds a facet that we want to record counts

Adding facet Facet::from("/country") for instance, will record the counts of all of the direct children of the facet country (e.g. /country/FR, /country/UK).

Adding two facets within which one is the prefix of the other is forbidden. If you need the correct number of unique documents for two such facets, just add them in a separate FacetCollector.

Trait Implementations

impl Collector for FacetCollector

type Fruit = FacetCounts

Fruit is the type for the result of our collection. e.g. usize for the Count collector.

type Child = FacetSegmentCollector

Type of the SegmentCollector associated with this collector.

fn for_segment( &self, _: SegmentOrdinal, reader: &SegmentReader ) -> Result<FacetSegmentCollector>

set_segment is called before beginning to enumerate on this segment.

fn requires_scoring(&self) -> bool

Returns true iff the collector requires to compute scores for documents.

fn merge_fruits( &self, segments_facet_counts: Vec<FacetCounts> ) -> Result<FacetCounts>

Combines the fruit associated with the collection of each segments into one fruit.

fn collect_segment( &self, weight: &dyn Weight, segment_ord: u32, reader: &SegmentReader ) -> Result<<Self::Child as SegmentCollector>::Fruit>

Created a segment collector and