LucyX:...:Filter(3pm)

💖 LucyX::Search::Filter 💖

okay bestie, so this is a page from the User Contributed Perl Documentation for LucyX::Search::Filter — it's a Perl 3pm manual page and it's literally the blueprint for building a caching filter out of a Query. come sit with me, we're gonna get you fluent in this. 🫶

---

✨ NAME ✨

LucyX::Search::Filter — bestie, this builds a caching filter based on the results of a Query. that's the whole vibe. it's giving "filter, but make it remembered." 👑

---

✨ SYNOPSIS ✨

okay so here's how you'd actually use it — pre-building one filter per category so you can reuse them, then ANDing the user's query with whichever filter matches:

my %category_filters;
for my $category (qw( sweet sour salty bitter )) {
    my $cat_query = Lucy::Search::TermQuery->new(
        field => 'category',
        term  => $category,
    );
    $category_filters{$category} = LucyX::Search::Filter->new(
        query => $cat_query,
    );
}

while ( my $cgi = CGI::Fast->new ) {
    my $user_query = $cgi->param('q');
    my $filter     = $category_filters{ $cgi->param('category') };
    my $and_query  = Lucy::Search::ANDQuery->new;
    $and_query->add_child($user_query);
    $and_query->add_child($filter);
    my $hits = $searcher->hits( query => $and_query );
    ...
}

see how the filters are built once outside the loop? that's the whole point, that's the slay. 💅

---

✨ DESCRIPTION ✨

so a Filter is a Lucy::Search::Query subclass (yes, it's in the family 🌈) and you use it to filter the results of another Query.

the effect? very similar to just using the wrapped inner query directly — BUT. and this is the important part, bestie. there are two important differences:

• a Filter does not contribute to the score of the documents it matches. zero. nada. it's not here for points, it's here to filter. 💀
• a Filter caches its results, so it's way more efficient if you're gonna use it more than once. reusing it? iconic. not reusing it? why would you. 😭

and if you want the logically equivalent results to the Filter but you wanna skip the caching? okay so — substitute the wrapped query, but use set_boost() to set its "boost" to 0. that's the swap. no cap. ⭐

---

✨ METHODS ✨

🌸 new

my $filter = LucyX::Search::Filter->new(
    query => $query;
);

Constructor, bestie. it takes one hash-style parameter, "query", and that has to be an object belonging to a subclass of Lucy::Search::Query. that's the whole rule. 🎀

---

💀 BUGS 💀

okay so this is the one that hurts: Filters do not cache when they're used in a search cluster with LucyX::Remote's SearchServer and SearchClient. 🥲

like. the caching? gone. in that specific setup. tragic, honestly, but at least you know now. 🙈

---

and that's the page, bestie! this one shipped as perl v5.42.0, dated 2025-07-25 — go forth and filter, you absolute main character. 🦋✨💜