Lucy::...mpiler(3pm)

✨ Lucy::Search::Compiler — the query-to-Matcher glow-up machine ✨

okay bestie, this page is Lucy::...mpiler(3pm) from the User Contributed Perl Documentation, and it's genuinely one of the most important little classes in Lucy, so let's get into it 💖

---

🌸 NAME 🌸

Lucy::Search::Compiler — the Query-to-Matcher compiler. it takes your cute abstract specification and turns it into something that can actually do stuff. iconic behaviour fr.

---

🎀 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 );
}

heads up: Compiler is an abstract base class, so you're not supposed to instantiate it directly, you subclass it. no cap.

---

💅 DESCRIPTION 💅

so the whole purpose of the Compiler class is: you hand it a specification in the form of a Query object, and it compiles a Matcher object that can do real work. that's the vibe check. that's the job. ✨

the simplest Compiler subclasses — think the ones that go with constant-scoring Query types — might just implement a make_matcher() method that passes information along verbatim from the Query to the Matcher's constructor. low effort, high reward.

but it's super common for the Compiler to do some calculations that affect its "weight" — that's a floating point multiplier that the Matcher will factor into each document's score. so if that's your situation, your Compiler subclass may wish to override get_weight(), sum_of_squared_weights(), and apply_norm_factor(). slay.

---

🦋 compiling a Matcher is a TWO stage process 🦋

stage one happens during the Compiler's construction, which is where the Query object meets a Searcher object for the very first time. Searchers operate on a specific document collection, and they can tell you certain statistical information about that collection — like how many total documents are in it, or how many documents in the collection a particular term is present in. Lucy's core Compiler classes plug this info into the classic TF/IDF weighting algorithm to adjust the Compiler's weight; custom subclasses might do something similar. 👑

stage two of compilation is make_matcher(), which is where the Compiler meets a SegReader object. SegReaders are associated with a single segment within a single index on a single machine, so they're lower-level than Searchers — and Searchers 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 — like 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 Matcher's constructor, or whether make_matcher() should return a Matcher at all. 😭 the drama of it.

---

🌈 CONSTRUCTORS 🌈

💜 new 💜

my $compiler = MyCompiler->SUPER::new(
    parent     => $my_query,
    searcher   => $searcher,
    similarity => $sim,        # default: undef
    boost      => undef,       # default: see below
);

Abstract constructor. (yes, abstract. don't come for me.)

• 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, it just returns 1.0. simple. elegant. minimal effort.

---

🌸 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 the Compiler's weight. what actually happens depends on how the Compiler and Similarity methods called internally are implemented. 👀 (iykyk)

---

👑 INHERITANCE 👑

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

---

and that's the whole page bestie, every last detail, periodt 💅 this was perl v5.42.0, dated 2025-07-25, and filed under Lucy::...mpiler(3pm) in the User Contributed Perl Documentation — go forth and compile those Matchers, you absolute icon 🦋💖