This project has retired. For details please refer to its Attic page.
Lucy::Search::Compiler – Apache Lucy Documentation
Apache Lucy™


Lucy::Search::Compiler - Query-to-Matcher compiler.


# (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 );


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.



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.



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.



my $float = $compiler->get_weight();

Return the Compiler’s numerical weight, a scoring multiplier. By default, returns the object’s boost.


my $similarity = $compiler->get_similarity();

Accessor for the Compiler’s Similarity object.


my $query = $compiler->get_parent();

Accessor for the Compiler’s parent Query object.


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 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.



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.


Lucy::Search::Compiler isa Lucy::Search::Query isa Clownfish::Obj.