Lucy::...archer(3pm)

💖 Lucy::Search::Searcher — the whole vibe 💖

ok so bestie, we're in the User Contributed Perl Documentation and this page is literally called Lucy::...archer(3pm) (yes the title got its lil ellipsis glow-up, we love that for it). anyway. sit down, grab a strawberry 🍓, because this one's the blueprint.

---

✨ NAME ✨

Lucy::Search::Searcher — the base class for searching collections of documents. it's giving founder energy 👑

---

🦋 SYNOPSIS 🦋

# Abstract base class.

that's it. that's the whole synopsis. she's abstract, she doesn't do the work herself, she just sets the standard 💅

---

🌸 DESCRIPTION 🌸

okay so. Lucy::Search::Searcher is the abstract base class for objects which search. no cap. the core subclasses are IndexSearcher and PolySearcher — those are the main characters that actually show up and do stuff 🔥

---

🎀 CONSTRUCTORS 🎀

💜 new

package MySearcher;
use base qw( Lucy::Search::Searcher );
sub new {
    my $self = shift->SUPER::new;
    ...
    return $self;
}

it's an abstract constructor — meaning you don't call this one directly, you subclass it and do your own thing, iykyk.

• schema — a Schema.

---

🧚 ABSTRACT METHODS 🧚

these are the methods you have to implement yourself in your subclass. no skipping, bestie, it's mandatory 🌈

⭐ doc_max

my $int = $searcher->doc_max();

returns the max number of docs in the collection the Searcher represents — which is also the highest possible internal doc id. and heads up: documents that got marked as deleted but haven't been purged yet are still counted in this number. they're in the count even though they're ghosted 👻

🦋 doc_freq

my $int = $searcher->doc_freq(
    field => $field,  # required
    term  => $term,   # required
);

tells you how many documents contain that term in that given field. very "who's talking about this" energy.

• field — Field name.
• term — The term to look up.

💖 collect

$searcher->collect(
    query     => $query,      # required
    collector => $collector,  # required
);

iterates over hits and feeds them into a Collector. like a lil conveyor belt of results feeding your collector 🍓

• query — A Query.
• collector — A Collector.

👑 fetch_doc

my $hit_doc = $searcher->fetch_doc($doc_id);

retrieves a document. throws an error if the doc id is out of range — so don't come at it with a bogus id, she will not be chill about it 😭

• doc_id — A document id.

---

🌈 METHODS 🌈

💅 glean_query

my $query = $searcher->glean_query($query);
my $query = $searcher->glean_query();  # default: undef

if the object you hand over is a Query, she just hands it right back to you. but if it's a query string, she creates a QueryParser and parses it to produce a query against all indexed fields. versatile queen ✨

🫶 hits

my $hits = $searcher->hits(
    query      => $query,       # required
    offset     => $offset,      # default: 0
    num_wanted => $num_wanted,  # default: 10
    sort_spec  => $sort_spec,   # default: undef
);

returns a Hits object containing the top results. this is the one everyone actually came here for, fr fr.

• query — either a Query object or a query string.
• offset — the number of most-relevant hits to discard, typically used when "paging" through hits N at a time. setting offset to 20 and num_wanted to 10 retrieves hits 21-30, assuming that 30 hits can be found. so good for scrolling through results 10 at a time, iconic pager behaviour 🎀
• num_wanted — the number of hits you would like to see after offset is taken into account.
• sort_spec — a SortSpec, which will affect how results are ranked and returned. this one changes the whole ranking vibe, so use it with intention 💜

💖 get_schema

my $schema = $searcher->get_schema();

accessor for the object's schema member. just a lil getter, doing her lil job 🦋

---

⭐ INHERITANCE ⭐

Lucy::Search::Searcher isa Clownfish::Obj. family tree goes crazy, we respect the lineage 👑

---

and that's the whole page, bestie!! perl v5.42.0, dated 2025-07-25 — shoutout to the User Contributed Perl Documentation for hosting this absolute legend, mwah 💋 no notes, ate and left zero crumbs 💖✨