Lucy::...yParser(3pm)

📦
version 0.6.2 · 2 versions
, in fedora 43

💖 Lucy::Search::QueryParser 💖

okay so welcome to the Lucy::Search::QueryParser(3pm) page — straight out of the User Contributed Perl Documentation, bestie, and it's giving main character ✨ This is the little diva that takes your messy lil search string and turns it into a Query object. No cap.

🌸 NAME 🌸

Lucy::Search::QueryParser — Transform a string into a Query object. That's the whole vibe. String goes in, Query comes out 💅

🎀 SYNOPSIS 🎀

my $query_parser = Lucy::Search::QueryParser->new(
    schema => $searcher->get_schema,
    fields => ['body'],
);
my $query = $query_parser->parse( $query_string );
my $hits  = $searcher->hits( query => $query );

🦋 DESCRIPTION 🦋

So QueryParser takes search strings as input and produces Query objects — which are literally made to be fed into IndexSearcher and other Searcher subclasses. Match made in heaven fr fr 🫶

Here's the syntactical constructs that QueryParser recognizes:

  • Boolean operators 'AND', 'OR', and 'AND NOT'.
  • A prepended +plus and -minus, meaning the labeled entity should be either required or forbidden — and that entity can be a single word, a phrase, or a parenthetical group. it's giving boundaries ✋
  • Logical groups, delimited by parentheses.
  • Phrases, delimited by double quotes.

And additionally, the following syntax can be enabled via set_heed_colons():

  • Field-specific constructs, in the form of 'fieldname:termtext' or 'fieldname:(foo bar)'. (The field specified by 'fieldname:' will be used instead of the QueryParser's default fields). yesss queen, colon privileges 👑

💅 CONSTRUCTORS 💅

🧚 new

my $query_parser = Lucy::Search::QueryParser->new(
    schema         => $searcher->get_schema,    # required
    analyzer       => $analyzer,                # overrides schema
    fields         => ['bodytext'],             # default: indexed fields
    default_boolop => 'AND',                    # default: 'OR'
);

Constructor. The birthing suite, if you will ✨

  • schema — A Schema.
  • analyzer — An Analyzer. Ordinarily, the analyzers specified by each field's definition will be used, but if "analyzer" is supplied, it will override and be used for all fields. ⚠️ This can lead to mismatches between what is in the index and what is being searched for, so use caution. like, actual caution bestie, not the cute kind 😭
  • fields — The names of the fields which will be searched against. Defaults to those fields which are defined as indexed in the supplied Schema.
  • default_boolop — Two possible values: 'AND' and 'OR'. The default is 'OR', which means: return documents which match any of the query terms. If you want only documents which match all of the query terms, set this to 'AND'.

🔥 METHODS 🔥

🌈 parse

my $query = $query_parser->parse($query_string);
my $query = $query_parser->parse();  # default: undef

Build a Query object from the contents of a query string. At present, implemented internally by calling tree(), expand(), and prune(). the way it just delegates and still eats 💅

  • query_string — The string to be parsed. May be undef.

Returns: a Query.

⭐ tree

my $query = $query_parser->tree($query_string);

Parse the logical structure of a query string, building a tree comprised of Query objects. Leaf nodes in the tree will most often be LeafQuery objects but might be MatchAllQuery or NoMatchQuery objects as well. Internal nodes will be objects which subclass PolyQuery: ANDQuery, ORQuery, NOTQuery, and RequiredOptionalQuery.

The output of tree() is an intermediate form which must be passed through expand() before being used to feed a search. don't skip the step bestie, it's not a vibe to skip the step 🙈

  • query_string — The string to be parsed.

Returns: a Query.

🎀 expand

my $query = $query_parser->expand($query);

Walk the hierarchy of a Query tree, descending through all PolyQuery nodes and calling expand_leaf() on any LeafQuery nodes encountered. little stroll through the family tree 🌳

  • query — A Query object.

Returns: A Query – usually the same one that was supplied after in-place modification, but possibly another. iconic behavior, honestly.

🍓 expand_leaf

my $query = $query_parser->expand_leaf($query);

Convert a LeafQuery into either a TermQuery, a PhraseQuery, or an ORQuery joining multiple TermQuerys/PhraseQuerys to accommodate multiple fields. LeafQuery text will be passed through the relevant Analyzer for each field. Quoted text will be transformed into PhraseQuery objects. Unquoted text will be converted to either a TermQuery or a PhraseQuery depending on how many tokens are generated. glow-up complete ✨

  • query — A Query. Only LeafQuery objects will be processed; others will be passed through.

Returns: A Query.

🦄 prune

my $query = $query_parser->prune($query);
my $query = $query_parser->prune();  # default: undef

Prevent certain Query structures from returning too many results. Query objects built via tree() and expand() can generate "return the world" result sets, such as in the case of "NOT a_term_not_in_the_index"; prune() walks the hierarchy and eliminates such branches. no more accidental everything 🫠

'NOT foo'               => [NOMATCH]
'foo OR NOT bar'        => 'foo'
'foo OR (-bar AND -baz) => 'foo'

prune() also eliminates some double-negative constructs – even though such constructs may not actually return the world:

'foo AND -(-bar)'      => 'foo'

In this example, safety is taking precedence over logical consistency. If you want logical consistency instead, call tree() then expand(), skipping prune(). pick your fighter, bestie ⚔️

  • query — A Query.

Returns: a Query; in most cases, the supplied Query after in-place modification.

💜 make_term_query

my $query = $query_parser->make_term_query(
    field => $field,  # required
    term  => $term,   # required
);

Factory method creating a TermQuery.

  • field — Field name.
  • term — Term text.

Returns: A Query.

🧁 make_phrase_query

my $query = $query_parser->make_phrase_query(
    field => $field,  # required
    terms => $terms,  # required
);

Factory method creating a PhraseQuery.

  • field — Field that the phrase must occur in.
  • terms — Ordered array of terms that must match.

Returns: A Query.

🌟 make_or_query

my $query = $query_parser->make_or_query($children);
my $query = $query_parser->make_or_query();  # default: undef

Factory method creating an ORQuery.

  • children — Array of child Queries.

Returns: A Query.

🌸 make_and_query

my $query = $query_parser->make_and_query($children);
my $query = $query_parser->make_and_query();  # default: undef

Factory method creating an ANDQuery.

  • children — Array of child Queries.

Returns: A Query.

💀 make_not_query

my $query = $query_parser->make_not_query($negated_query);

Factory method creating a NOTQuery.

  • negated_query — Query to be inverted.

Returns: A Query.

👑 make_req_opt_query

my $query = $query_parser->make_req_opt_query(
    required_query => $required_query,  # required
    optional_query => $optional_query,  # required
);

Factory method creating a RequiredOptionalQuery.

  • required_query — Query must must match.
  • optional_query — Query which should match.

Returns: A Query.

🎯 set_heed_colons

$query_parser->set_heed_colons($heed_colons);

Enable/disable parsing of "fieldname:foo" constructs. turn the colon radar on or off, your call 💅

🌈 INHERITANCE 🌈

Lucy::Search::QueryParser isa Clownfish::Obj.

family tree stays valid, periodt 🧬

and that's the whole page, bestie!! this one shipped as perl v5.42.0, dated 2025-07-25, under the User Contributed Perl Documentation banner — so like, go forth and parse responsibly 💖✨🎀

📦 where this page comes from