Lucy::...egment(3pm)

💖 Lucy::Index::Segment — the whole vibe 💖

okay so bestie, we're reading the manual page for Lucy::Index::Segment, straight out of the User Contributed Perl Documentation collection. pull up a chair, grab a strawberry 🍓, and let's get into it.

---

✨ NAME ✨

Lucy::Index::Segment — the warehouse where all the info about one segment of an inverted index lives. it's giving storage-unit-for-metadata energy. 🏬

---

🌈 SYNOPSIS 🌈

first up, index-time — this is where you, a DataWriter, stash your stuff:

# Index-time.
package MyDataWriter;
use base qw( Lucy::Index::DataWriter );

sub finish {
    my $self     = shift;
    my $segment  = $self->get_segment;
    my $metadata = $self->SUPER::metadata();
    $metadata->{foo} = $self->get_foo;
    $segment->store_metadata(
        key       => 'my_component',
        metadata  => $metadata
    );
}

then search-time, where a DataReader comes back for its little treasures:

# Search-time.
package MyDataReader;
use base qw( Lucy::Index::DataReader );

sub new {
    my $self     = shift->SUPER::new(@_);
    my $segment  = $self->get_segment;
    my $metadata = $segment->fetch_metadata('my_component');
    if ($metadata) {
        $self->set_foo( $metadata->{foo} );
        ...
    }
    return $self;
}

---

🦋 DESCRIPTION 🦋

so, Apache Lucy's indexes? they're made up of individual “segments”, and every single one of those is its own independent inverted index. yes, they're all out here with main character energy. 👑

on the file system, each segment is a directory sitting inside the main index directory, and its name starts with “seg_” — think “seg_2”, “seg_5a”, etc. 💅

every Segment object keeps track of info about one index segment: its fields, its document count, and so on. the Segment object itself writes exactly one file, segmeta.json. and honestly? besides storing the info Segment itself needs, that “segmeta” file is a whole central repository for metadata generated by other index components too — which lowkey relieves them of the burden of storing metadata themselves. iconic teamwork fr fr. 🫶

---

🎀 METHODS 🎀

🌸 add_field

my $int = $segment->add_field($field);

register a brand new field and hand it a field number. and if the field was already known? nothing happens. no drama, no fuss. 💅

• field — the field name.

Returns: the field's field number, which is a positive integer.

🌸 store_metadata

$segment->store_metadata(
    key      => $key,       # required
    metadata => $metadata,  # required
);

stash arbitrary info in the segment's metadata hash so it can get serialized later. ⚠️ heads up bestie: it throws an error if key is used twice. no double-dipping. 🙈

• key — a string identifying an index component.
• metadata — a JSON-izable data structure.

🌸 fetch_metadata

my $obj = $segment->fetch_metadata($key);

grab a value back out of the Segment's metadata hash. the lil reunion moment. 🥹

🌸 field_num

my $int = $segment->field_num($field);

give it a field name, it gives you back that field's number for this segment — and yes, that number can absolutely differ from its number in other segments, because every segment has its own thing going on. if the field name can't be found, you get 0 back, which is an invalid field number. 😭

• field — the field name.

🌸 field_name

my $string = $segment->field_name($field_num);

hand it a field number, get the name of its field back. if the field name can't be found, it's undef. that's it, that's the method. 🧚

🌸 get_name

my $string = $segment->get_name();

getter for the object's seg name. simple, clean, slays. ✨

🌸 get_number

my $int = $segment->get_number();

getter for the segment number.

🌸 set_count

$segment->set_count($count);

setter for the object's document count.

🌸 get_count

my $int = $segment->get_count();

getter for the object's document count. yes we do love a matching pair. 💜

🌸 compare_to

my $int = $segment->compare_to($other);

compares by segment number. that's the whole thing, no notes. ⭐

---

👑 INHERITANCE 👑

Lucy::Index::Segment isa Clownfish::Obj. the bloodline is strong, the lineage is documented. 🌈

---

aaaand that's the whole page bestie, we ate and left no crumbs 💅✨ this little manual page came to you as part of perl v5.42.0, dated 2025-07-25, and it lives at Lucy::...egment(3pm). mwah, bye! 💖🦋🎀