NAME
Lucy::Search::Compiler - Query-to-Matcher compiler.
SYNOPSIS
# (Compiler is an abstract base class.)
package MyCompiler;
use base qw( Lucy::Search::Compiler );
sub make_matcher {
my $self = shift;
return MyMatcher->new( @_, compiler => $self );
}DESCRIPTION
The purpose of the Compiler class is to take a specification in the form of a Query object and compile a Matcher object that can do real work.
The simplest Compiler subclasses – such as those associated with constant-scoring Query types – might simply implement a make_matcher() method which passes along information verbatim from the Query to the Matcher’s constructor.
However it is common for the Compiler to perform some calculations which affect it’s “weight” – a floating point multiplier that the Matcher will factor into each document’s score. If that is the case, then the Compiler subclass may wish to override get_weight(), sum_of_squared_weights(), and apply_norm_factor().
Compiling a Matcher is a two stage process.
The first stage takes place during the Compiler’s construction, which is where the Query object meets a Searcher object for the first time. Searchers operate on a specific document collection and they can tell you certain statistical information about the collection – such as how many total documents are in the collection, or how many documents in the collection a particular term is present in. Lucy’s core Compiler classes plug this information into the classic TF/IDF weighting algorithm to adjust the Compiler’s weight; custom subclasses might do something similar.
The second stage of compilation is make_matcher(), method, which is where the Compiler meets a SegReader object. SegReaders are associated with a single segment within a single index on a single machine, and are thus lower-level than Searchers, which may represent a document collection spread out over a search cluster (comprising several indexes and many segments). The Compiler object can use new information supplied by the SegReader – such as whether a term is missing from the local index even though it is present within the larger collection represented by the Searcher – when figuring out what to feed to the Matchers’s constructor, or whether make_matcher() should return a Matcher at all.
CONSTRUCTORS
new
my $compiler = MyCompiler->SUPER::new(
parent => $my_query,
searcher => $searcher,
similarity => $sim, # default: undef
boost => undef, # default: see below
);Abstract constructor.
parent - The parent Query.
searcher - A Lucy::Search::Searcher, such as an IndexSearcher.
similarity - A Similarity.
boost - An arbitrary scoring multiplier. Defaults to the boost of the parent Query.
ABSTRACT METHODS
make_matcher
my $matcher = $compiler->make_matcher(
reader => $reader, # required
need_score => $need_score, # required
);Factory method returning a Matcher.
reader - A SegReader.
need_score - Indicate whether the Matcher must implement score().
Returns: a Matcher, or undef if the Matcher would have matched no documents.
METHODS
get_weight
my $float = $compiler->get_weight();Return the Compiler’s numerical weight, a scoring multiplier. By default, returns the object’s boost.
get_similarity
my $similarity = $compiler->get_similarity();Accessor for the Compiler’s Similarity object.
get_parent
my $query = $compiler->get_parent();Accessor for the Compiler’s parent Query object.
sum_of_squared_weights
my $float = $compiler->sum_of_squared_weights();Compute and return a raw weighting factor. (This quantity is used by normalize()). By default, simply returns 1.0.
apply_norm_factor
$compiler->apply_norm_factor($factor);Apply a floating point normalization multiplier. For a TermCompiler, this involves multiplying its own weight by the supplied factor; combining classes such as ORCompiler would apply the factor recursively to their children.
The default implementation is a no-op; subclasses may wish to multiply their internal weight by the supplied factor.
factor - The multiplier.
normalize
$compiler->normalize();Take a newly minted Compiler object and apply query-specific normalization factors. Should be invoked by Query subclasses during make_compiler() for top-level nodes.
For a TermQuery, the scoring formula is approximately:
(tf_d * idf_t / norm_d) * (tf_q * idf_t / norm_q)normalize() is theoretically concerned with applying the second half of that formula to a the Compiler’s weight. What actually happens depends on how the Compiler and Similarity methods called internally are implemented.
INHERITANCE
Lucy::Search::Compiler isa Lucy::Search::Query isa Clownfish::Obj.