Lucy::...alQuery(3pm)

💖 Lucy::Search::RequiredOptionalQuery — the manual, but make it make sense 💖

okay bestie, welcome to the Lucy::...alQuery(3pm) page, straight out of the User Contributed Perl Documentation collection. this is the whole thing, every flag and every method, just... with a personality. let's go 🫶

---

✨ NAME ✨

Lucy::Search::RequiredOptionalQuery — it joins the results for two Queries, one that's required and one that's optional. the way that it literally just vibes with two queries at once. iconic.

---

✨ SYNOPSIS ✨

my $foo_and_maybe_bar = Lucy::Search::RequiredOptionalQuery->new(
    required_query => $foo_query,
    optional_query => $bar_query,
);
my $hits = $searcher->hits( query => $foo_and_maybe_bar );
...

no cap, that's the whole setup. two queries in, hits out. slay. 💅

---

✨ DESCRIPTION ✨

okay so here's the tea. RequiredOptionalQuery joins the result sets of one Query which MUST match and one Query which SHOULD match. those are two very different energy levels and the class respects that. 🌸

• when only the required Query matches → its score is just passed along. no drama.
• when both match → the scores get summed. bestie behavior fr fr.

---

✨ CONSTRUCTORS ✨

🌈 new

my $reqopt_query = Lucy::Search::RequiredOptionalQuery->new(
    required_query => $foo_query,    # required
    optional_query => $bar_query,    # required
);

Create a new RequiredOptionalQuery. yes, both of those hash keys are marked required, look at the code, it said what it said. 💀

• required_query — the Query that must must match. (it really says "must must" in the original, so I'm keeping the double must, it's giving emphasis 💅)
• optional_query — the Query which should match. should, not must. different tier entirely.

---

✨ METHODS ✨

🎀 get_required_query

my $query = $required_optional_query->get_required_query();

Getter for the required Query. it gets. it returns. periodt.

🎀 set_required_query

$required_optional_query->set_required_query($required_query);

Setter for the required Query. give it a new one, it'll hold onto it.

🦋 get_optional_query

my $query = $required_optional_query->get_optional_query();

Getter for the optional Query. lowkey the same thing as above but for the chill one.

🦋 set_optional_query

$required_optional_query->set_optional_query($optional_query);

Setter for the optional Query. swap it out whenever, bestie.

👑 make_compiler

my $compiler = $required_optional_query->make_compiler(
    searcher    => $searcher,     # required
    boost       => $boost,        # required
    subordinate => $subordinate,  # default: false
);

an abstract factory method returning a Compiler derived from this Query. abstract meaning you don't get a fully cooked one handed to you here, iykyk.

• searcher — a Searcher. required, no skipping.
• boost — a scoring multiplier. also required. make it count 🔥
• subordinate — tells you whether the Query is a subquery (as opposed to a top-level query). defaults to false. and listen: if it's false, the implementation MUST invoke normalize() on the newly minted Compiler object before returning it. that's not a suggestion, that's the rule. don't skip it 🙈

---

✨ INHERITANCE ✨

the whole family tree, no branches skipped:

Lucy::Search::RequiredOptionalQuery isa Lucy::Search::PolyQuery isa Lucy::Search::Query isa Clownfish::Obj.

four generations deep and every one of them ate. 👑

---

and that's the page!! this was Lucy::...alQuery(3pm), served up by perl v5.42.0 on 2025-07-25, from the User Contributed Perl Documentation corner of the universe. go forth and join your queries responsibly 💖✨🎀🦋