1Lucy::Search::Compiler(U3spemr)Contributed Perl DocumentLautciyo:n:Search::Compiler(3pm)
2
3
4

NAME

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

SYNOPSIS

9           # (Compiler is an abstract base class.)
10           package MyCompiler;
11           use base qw( Lucy::Search::Compiler );
12
13           sub make_matcher {
14               my $self = shift;
15               return MyMatcher->new( @_, compiler => $self );
16           }
17

DESCRIPTION

19       The purpose of the Compiler class is to take a specification in the
20       form of a Query object and compile a Matcher object that can do real
21       work.
22
23       The simplest Compiler subclasses – such as those associated with
24       constant-scoring Query types – might simply implement a make_matcher()
25       method which passes along information verbatim from the Query to the
26       Matcher’s constructor.
27
28       However it is common for the Compiler to perform some calculations
29       which affect it’s “weight” – a floating point multiplier that the
30       Matcher will factor into each document’s score.  If that is the case,
31       then the Compiler subclass may wish to override get_weight(),
32       sum_of_squared_weights(), and apply_norm_factor().
33
34       Compiling a Matcher is a two stage process.
35
36       The first stage takes place during the Compiler’s construction, which
37       is where the Query object meets a Searcher object for the first time.
38       Searchers operate on a specific document collection and they can tell
39       you certain statistical information about the collection – such as how
40       many total documents are in the collection, or how many documents in
41       the collection a particular term is present in.  Lucy’s core Compiler
42       classes plug this information into the classic TF/IDF weighting
43       algorithm to adjust the Compiler’s weight; custom subclasses might do
44       something similar.
45
46       The second stage of compilation is make_matcher(), method, which is
47       where the Compiler meets a SegReader object.  SegReaders are associated
48       with a single segment within a single index on a single machine, and
49       are thus lower-level than Searchers, which may represent a document
50       collection spread out over a search cluster (comprising several indexes
51       and many segments).  The Compiler object can use new information
52       supplied by the SegReader – such as whether a term is missing from the
53       local index even though it is present within the larger collection
54       represented by the Searcher – when figuring out what to feed to the
55       Matchers’s constructor, or whether make_matcher() should return a
56       Matcher at all.
57

CONSTRUCTORS

59   new
60           my $compiler = MyCompiler->SUPER::new(
61               parent     => $my_query,
62               searcher   => $searcher,
63               similarity => $sim,        # default: undef
64               boost      => undef,       # default: see below
65           );
66
67       Abstract constructor.
68
69       •   parent - The parent Query.
70
71       •   searcher - A Lucy::Search::Searcher, such as an IndexSearcher.
72
73       •   similarity - A Similarity.
74
75       •   boost - An arbitrary scoring multiplier.  Defaults to the boost of
76           the parent Query.
77

ABSTRACT METHODS

79   make_matcher
80           my $matcher = $compiler->make_matcher(
81               reader     => $reader,      # required
82               need_score => $need_score,  # required
83           );
84
85       Factory method returning a Matcher.
86
87       •   reader - A SegReader.
88
89       •   need_score - Indicate whether the Matcher must implement score().
90
91       Returns: a Matcher, or undef if the Matcher would have matched no
92       documents.
93

METHODS

95   get_weight
96           my $float = $compiler->get_weight();
97
98       Return the Compiler’s numerical weight, a scoring multiplier.  By
99       default, returns the object’s boost.
100
101   get_similarity
102           my $similarity = $compiler->get_similarity();
103
104       Accessor for the Compiler’s Similarity object.
105
106   get_parent
107           my $query = $compiler->get_parent();
108
109       Accessor for the Compiler’s parent Query object.
110
111   sum_of_squared_weights
112           my $float = $compiler->sum_of_squared_weights();
113
114       Compute and return a raw weighting factor.  (This quantity is used by
115       normalize()).  By default, simply returns 1.0.
116
117   apply_norm_factor
118           $compiler->apply_norm_factor($factor);
119
120       Apply a floating point normalization multiplier.  For a TermCompiler,
121       this involves multiplying its own weight by the supplied factor;
122       combining classes such as ORCompiler would apply the factor recursively
123       to their children.
124
125       The default implementation is a no-op; subclasses may wish to multiply
126       their internal weight by the supplied factor.
127
128       •   factor - The multiplier.
129
130   normalize
131           $compiler->normalize();
132
133       Take a newly minted Compiler object and apply query-specific
134       normalization factors.  Should be invoked by Query subclasses during
135       make_compiler() for top-level nodes.
136
137       For a TermQuery, the scoring formula is approximately:
138
139           (tf_d * idf_t / norm_d) * (tf_q * idf_t / norm_q)
140
141       normalize() is theoretically concerned with applying the second half of
142       that formula to a the Compiler’s weight. What actually happens depends
143       on how the Compiler and Similarity methods called internally are
144       implemented.
145

INHERITANCE

147       Lucy::Search::Compiler isa Lucy::Search::Query isa Clownfish::Obj.
148
149
150
151perl v5.38.0                      2023-07-20       Lucy::Search::Compiler(3pm)