Lucy::...DocIDs(3pm)

💖 Lucy::...DocIDs 💖

okay bestie, so this is the tea on Lucy::Docs::DocIDs — literally the whole vibe of Apache Lucy document ids. what they are, what they are not, and why you should not get attached. 🦋

---

✨ DESCRIPTION ✨

🔢 Document ids are signed 32-bit integers

so like, first thing: document ids in Apache Lucy start at 1. not 0. never 0. 🫶

and because 0 is literally never a valid doc id, we get to use it as a sentinel value — it's giving "nobody's home" energy:

while ( my $doc_id = $posting_list->next ) {
    ...
}

see how that works? when next hands you a 0, the loop just stops. iconic. 💅

🍓 Document ids are ephemeral

bestie. hear me. these ids are not forever. 😭

the document ids Lucy uses are tied to a single index snapshot. the moment an index gets updated, the mapping of document ids to documents is subject to change. like, gone. shifted. different.

now here's the part that saves you: since IndexReader objects represent a point-in-time view of an index, document ids are guaranteed to remain static for the life of the reader. so inside one reader? stable. slay. ✨

but because they're not permanent, Lucy document ids cannot be used as foreign keys to locate records in external data sources. periodt. so if you truly need a primary key field, you have to define it and populate it yourself. no shortcuts, babes. 💀

and one more thing, highkey important: the order of document ids does not tell you anything about the sequence in which documents were added to the index. so don't go reading meaning into it. it's not a timeline, it's just numbers. 🌈

---

that's the whole page, bestie — go forth and index responsibly 🧚💜

this was perl v5.42.0, dated 2025-07-25, and it's the Lucy::...DocIDs(3pm) page from the User Contributed Perl Documentation. mwah. 💖