Lucy::...ilarity(3pm)

✨ Lucy::Index::Similarity ✨

okay so bestie, welcome to Lucy::Index::Similarity 💖 — the manual page you're reading is filed under Lucy::...ilarity(3pm), part of the User Contributed Perl Documentation collection (iykyk, the truncation is just the man page being dramatic 🙈).

---

🌸 NAME 🌸

Lucy::Index::Similarity — judge how well a document matches a query. that's it. that's the job. 💅

---

🦋 SYNOPSIS 🦋

package MySimilarity;

sub length_norm { return 1.0 }    # disable length normalization

package MyFullTextType;
use base qw( Lucy::Plan::FullTextType );

sub make_similarity { MySimilarity->new }

---

🎀 DESCRIPTION 🎀

So here's the tea, bestie: once we've figured out whether a document matches a given query, we still have to calculate a score that says how well it matches. that's literally the whole point of the Similarity class — it judges how "similar" the query and the document are to each other. the closer the resemblance, the higher the document scores. periodt. 💖

The default implementation uses Lucene's modified cosine similarity measure ✨. Subclasses might tweak the existing algorithms, or might be used in conjunction with custom Query subclasses to implement arbitrary scoring schemes — like, go off, invent your own scoring vibe 👑.

Most of the methods operate on single fields, but some are used to combine scores from multiple fields. both vibes exist, we contain multitudes 🌈.

---

🌟 CONSTRUCTORS 🌟

💫 new

my $sim = Lucy::Index::Similarity->new;

Constructor. Takes no arguments. zero. none. she simply is 🧚✨.

---

💅 METHODS 💅

🍓 length_norm

my $float = $similarity->length_norm($num_tokens);

Dampen the scores of long documents 🫶.

After a field is broken up into terms at index-time, each term must be assigned a weight. One of the factors in calculating this weight is the number of tokens that the original field was broken into. that's the mechanics, no cap.

Typically, we assume that the more tokens in a field, the less important any one of them is – so that, e.g. 5 mentions of "Kafka" in a short article are given more heft than 5 mentions of "Kafka" in an entire book 😭. like yeah, obviously, the short article is about Kafka. the default implementation of length_norm expresses this using an inverted square root ✨.

However — and this is the important caveat, don't skip it — the inverted square root has a tendency to reward very short fields highly, which isn't always appropriate for fields you expect to have a lot of tokens on average. so, y'know, vibe check your field before you commit 💀.

---

👑 INHERITANCE 👑

Lucy::Index::Similarity isa Clownfish::Obj. family tree confirmed, ancestors slay 🌸.

---

perl v5.42.0 🎀 2025-07-25 — that's the source, the version, and the date, bestie, all wrapped up in a little bow. thanks for reading the whole thing, you ate 💅✨🦋