Lucy::...ndexer(3pm)

💖 Lucy::Index::Indexer — bestie's guide to building inverted indexes 💖

okay so this is Lucy::Index::Indexer(3pm), straight out of the User Contributed Perl Documentation, and it's literally the class that builds your inverted indexes. sit down, grab a boba, we're doing this 🧋✨

---

✨ NAME ✨

Lucy::Index::Indexer — Build inverted indexes. that's it, that's the whole job, and she does it gorgeously 💅

---

✨ SYNOPSIS ✨

my $indexer = Lucy::Index::Indexer->new(
    schema => $schema,
    index  => '/path/to/index',
    create => 1,
);
while ( my ( $title, $content ) = each %source_docs ) {
    $indexer->add_doc({
        title   => $title,
        content => $content,
    });
}
$indexer->commit;

see how clean that is?? make an indexer, yeet your docs in one by one, commit at the end and boom 💥 you have an index. no cap.

---

✨ DESCRIPTION ✨

The Indexer class is Apache Lucy's main character when it comes to managing the content of inverted indexes — the ones you can later search with IndexSearcher. she's the primary tool, periodt. 👑

okay so important vibe check: in general, only one Indexer at a time may write to an index safely. if a write lock can't be secured, new() will throw an exception. no lock, no entry, sorry bestie 😭

if your index lives on a shared volume, then every single writer application has to identify itself by giving an IndexManager a unique "host" id, passed to Indexer's constructor. skip that and index corruption will occur. that's not a drill, that's actual corruption 💀 see FileLocking for the whole detailed discussion, iykyk.

Note: at present, delete_by_term() and delete_by_query() only affect documents which had been previously committed to the index — and not any documents added this indexing session but not yet committed. this may change in a future update, so don't @ me 🙈

---

✨ CONSTRUCTORS ✨

🌸 new 🌸

my $indexer = Lucy::Index::Indexer->new(
    schema   => $schema,             # required at index creation
    index    => '/path/to/index',    # required
    create   => 1,                   # default: 0
    truncate => 1,                   # default: 0
    manager  => $manager             # default: created internally
);

• schema — a Schema. required when the index is being created; if you don't supply it, it'll be extracted from the index folder. so like, she can figure it out, but only if there's something to figure out from 🎀
• index — either a filepath to an index or a Folder.
• create — if true and the index directory does not exist, attempt to create it. default 0.
• truncate — if true, proceed with the intention of discarding all previous indexing data. the old data will remain intact and visible until commit() succeeds. so it's giving "we're about to wipe this" but it's not actually gone-gone until the commit lands 🦋
• manager — an IndexManager.

---

✨ METHODS ✨

💅 add_doc 💅

$indexer->add_doc($doc);
$indexer->add_doc( { field_name => $field_value } );
$indexer->add_doc(
    doc   => { field_name => $field_value },
    boost => 2.5,         # default: 1.0
);

add a document to the index. she accepts either a single argument or labeled params. flexible queen 🌈

• doc — either a Lucy::Document::Doc object, or a hashref (which will be attached to a Lucy::Document::Doc object internally, behind the scenes, no extra work for you).
• boost — a floating point weight which affects how this document scores. default 1.0. bump it up if you want her to hit different in the rankings 🔥

---

🌟 add_index 🌟

$indexer->add_index($index);

absorb an existing index into this one. the two indexes must have matching Schemas — they have to be compatible, bestie, no forcing it 💜

• index — either an index path name or a Folder.

---

🎀 delete_by_term 🎀

$indexer->delete_by_term(
    field => $field,  # required
    term  => $term,   # required
);

mark documents which contain the supplied term as deleted, so that they'll be excluded from search results and eventually removed altogether. the change is not apparent to search apps until after commit() succeeds. so like, it's a soft launch until commit 👀

• field — the name of an indexed field. (if it is not spec'd as "indexed", an error will occur. so double check that, fr fr.)
• term — the term which identifies docs to be marked as deleted. if "field" is associated with an Analyzer, "term" will be processed automatically — so don't pre-process it yourself, she's got it 🙅‍♀️

---

🦋 delete_by_query 🦋

$indexer->delete_by_query($query);

mark documents which match the supplied Query as deleted. whole query, whole vibe, gone ✨

• query — a Query.

---

⭐ delete_by_doc_id ⭐

$indexer->delete_by_doc_id($doc_id);

mark the document identified by the supplied document ID as deleted. targeted deletion, we love a precision moment 🎯

• doc_id — a document id.

---

👑 optimize 👑

$indexer->optimize();

optimize the index for search-time performance. this may take a while, as it can involve rewriting large amounts of data. so like, maybe grab a snack while this runs 🍓

every Indexer session which changes index content and ends in a commit() creates a new segment. once written, segments are never modified. however, they are periodically recycled by feeding their content into the segment currently being written. cute little ecosystem, honestly 🌈

the optimize() method causes all existing index content to be fed back into the Indexer. when commit() completes after an optimize(), the index will consist of one segment. so optimize() must be called before commit(). also, optimizing a fresh index created from scratch has no effect — nothing to collapse, she's already brand new 💫

historically, there was a significant search-time performance benefit to collapsing down to a single segment versus even two segments. now the effect of collapsing is much less significant, and calling optimize() is rarely justified. so like, she's a legacy baddie, not a necessity 🫶

---

💖 commit 💖

$indexer->commit();

commit any changes made to the index. until this is called, none of the changes made during an indexing session are permanent. this is the moment everything becomes real, no takebacks 🔥

calling commit() invalidates the Indexer, so if you want to make more changes you'll need a new one. she's done after this, she said goodbye, make a new bestie 😭

---

🌸 prepare_commit 🌸

$indexer->prepare_commit();

perform the expensive setup for commit() in advance, so that commit() completes quickly. it's giving pre-gaming the hard part so the finale is snappy ✨ (if prepare_commit() is not called explicitly by the user, commit() will call it internally — she's self-sufficient like that.)

---

💜 get_schema 💜

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

accessor for schema. simple, iconic, does exactly what it says 💅

---

✨ INHERITANCE ✨

Lucy::Index::Indexer isa Clownfish::Obj. family tree confirmed 🌳

---

and that's the whole page bestie — every option, every default, every warning, all of it, kept exactly as she is 💖

this was Lucy::Index::Indexer(3pm) from the User Contributed Perl Documentation, running on perl v5.42.0, dated 2025-07-25. go forth and index, you absolute legend 👑✨🦋