Lucy::...Reader(3pm)

💖 Lucy::Index::IndexReader — read from an inverted index, bestie 💖

okay so this is Lucy::Index::IndexReader from the Perl docs (user contributed, we love that for us). it's giving the way to peek inside an index. let's get into it 🦋

---

✨ NAME ✨

Lucy::Index::IndexReader — read from an inverted index. that's it. that's the whole vibe. 📖✨

---

🌸 SYNOPSIS 🌸

here's the lil taste test, no cap:

my $reader = Lucy::Index::IndexReader->open(
    index => '/path/to/index',
);
my $seg_readers = $reader->seg_readers;
for my $seg_reader (@$seg_readers) {
    my $seg_name = $seg_reader->get_segment->get_name;
    my $num_docs = $seg_reader->doc_max;
    print "Segment $seg_name ($num_docs documents):\n";
    my $doc_reader = $seg_reader->obtain("Lucy::Index::DocReader");
    for my $doc_id ( 1 .. $num_docs ) {
        my $doc = $doc_reader->fetch_doc($doc_id);
        print "  $doc_id: $doc->{title}\n";
    }
}

like… look at her go 💅

---

💜 DESCRIPTION 💜

so IndexReader is the interface through which IndexSearcher objects access the content of an index. that's the whole job. it's the plug, the gateway, the main character 🔑

and here's the thing you HAVE to remember bestie: IndexReader objects always represent a point-in-time view of an index, like, as it existed at the exact moment the reader was created. frozen. a lil time capsule 🕰️. so if you want your search results to reflect modifications to an index, you must create a new IndexReader after the update process completes. no shortcuts, no vibes-based hoping. periodt.

also IndexReaders are composites — most of the work is done by individual DataReader sub-components, which you can get at via fetch() and obtain(). but lowkey the most efficient and powerful access to index data happens at the segment level, via SegReader's sub-components. iykyk 🫶

---

🎀 CONSTRUCTORS 🎀

open

my $reader = Lucy::Index::IndexReader->open(
    index    => '/path/to/index', # required
    snapshot => $snapshot,
    manager  => $index_manager,
);

plot twist: IndexReader is an abstract base class — so open() returns the IndexReader subclass PolyReader, which channels the output of 0 or more SegReaders. zero!! or more!! the range is wild fr fr.

• index — either a string filepath or a Folder. you gotta give her something to read 📂
• snapshot — a Snapshot. if you don't supply it, the most recent snapshot file gets used. no thoughts, just the freshest one ✨
• manager — an IndexManager. heads up: read-locking is off by default, and supplying this argument turns it on. so that's the switch bestie 🔒

---

🦋 ABSTRACT METHODS 🦋

doc_max

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

return the maximum number of documents available to the reader — which is also the highest possible internal document id. and yes, documents that have been marked as deleted but not yet purged from the index are included in this count. they're still on the roster, they just don't get playtime 💀

doc_count

my $int = $index_reader->doc_count();

return the number of documents available to the reader, subtracting any that are marked as deleted. so this one's the honest count, the "minus the ghosts" number 👻

del_count

my $int = $index_reader->del_count();

return the number of documents that have been marked as deleted but not yet purged from the index. the graveyard tally 🪦

offsets

my $i32_array = $index_reader->offsets();

return an array with one entry for each segment, corresponding to segment doc_id start offset. one per segment, no skipping 🧮

seg_readers

my $arrayref = $index_reader->seg_readers();

return an array of all the SegReaders represented within the IndexReader. the whole squad, assembled 🌈

---

💅 METHODS 💅

obtain

my $data_reader = $index_reader->obtain($api);

fetch a component — or throw an error if the component can't be found. she does not do silence, she does not do ambiguity. dramatic? yes. useful? also yes 😭

• api — the name of the DataReader subclass that the desired component must implement.

fetch

my $data_reader = $index_reader->fetch($api);

fetch a component — or return undef if the component can't be found. the chill version of obtain. no drama, just undef 🙈

• api — the name of the DataReader subclass that the desired component must implement.

---

👑 INHERITANCE 👑

Lucy::Index::IndexReader isa Lucy::Index::DataReader isa Clownfish::Obj.

a whole family tree, and she's got main character energy at every level 💖

---

that's the page bestie!! this manual came from perl v5.42.0, dated 2025-07-25, and it's filed under Lucy::...Reader(3pm) 🎀✨ go forth and read your index, you've got this 🫶💜