NAME

       Lucy::Search::QueryParser - Transform a string into a Query object.

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

       QueryParser accepts search strings as input and produces Lucy::Search::Query objects, suitable for
       feeding into IndexSearcher and other Searcher subclasses.

       The following syntactical constructs are recognized by QueryParser:

           * Boolean operators 'AND', 'OR', and 'AND NOT'.
           * Prepented +plus and -minus, indicating that the labeled entity
             should be either required or forbidden -- be it a single word, a
             phrase, or a parenthetical group.
           * Logical groups, delimited by parentheses.
           * Phrases, delimited by double quotes.

       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).

CONSTRUCTORS

   new( [labeled params] )
           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.

       •   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.

       •   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(query_string)
       Build  a Query object from the contents of a query string.  At present, implemented internally by calling
       tree(), expand(), and prune().

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

       Returns: a Query.

   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.

       •   query_string - The string to be parsed.

       Returns: a Query.

   expand(query)
       Walk the hierarchy of a Query tree, descending through all PolyQuery nodes and calling  expand_leaf()  on
       any LeafQuery nodes encountered.

       •   query - A Query object.

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

   expand_leaf(query)
       Convert  a  LeafQuery  into  either  a  TermQuery,  a  PhraseQuery,  or  an  ORQuery   joining   multiple
       TermQueries/PhraseQueries  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.

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

       Returns: A Query.

   prune(query)
       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.

            '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().

       •   query - A Query.

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

   set_heed_colons(heed_colons)
       Enable/disable parsing of "fieldname:foo" constructs.

   make_term_query( [labeled params] )
       Factory method creating a TermQuery.

       •   field - Field name.

       •   term - Term text.

       Returns: A Query.

   make_phrase_query( [labeled params] )
       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_and_query(children)
       Factory method creating an ANDQuery.

       •   children - Array of child Queries.

       Returns: A Query.

   make_or_query(children)
       Factory method creating an ORQuery.

       •   children - Array of child Queries.

       Returns: A Query.

   make_not_query(negated_query)
       Factory method creating a NOTQuery.

       •   negated_query - Query to be inverted.

       Returns: A Query.

   make_req_opt_query( [labeled params] )
       Factory method creating a RequiredOptionalQuery.

       •   required_query - Query must must match.

       •   optional_query - Query which should match.

       Returns: A Query.

INHERITANCE

       Lucy::Search::QueryParser isa Lucy::Object::Obj.

perl v5.26.0                                       2017-08-02                     Lucy::Search::QueryParser(3pm)