Lucy::Search::QueryParser

Name

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

Description

QueryParser accepts search strings as input and produces 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).

Functions

new

lucy_QueryParser* // incremented
lucy_QParser_new(
    lucy_Schema *schema,
    lucy_Analyzer *analyzer,
    cfish_String *default_boolop,
    cfish_Vector *fields
);

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

init

lucy_QueryParser*
lucy_QParser_init(
    lucy_QueryParser *self,
    lucy_Schema *schema,
    lucy_Analyzer *analyzer,
    cfish_String *default_boolop,
    cfish_Vector *fields
);

Initialize a QueryParser.

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

lucy_Query* // incremented
lucy_QParser_Parse(
    lucy_QueryParser *self,
    cfish_String *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 NULL.

Returns: a Query.

Tree

lucy_Query* // incremented
lucy_QParser_Tree(
    lucy_QueryParser *self,
    cfish_String *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

lucy_Query* // incremented
lucy_QParser_Expand(
    lucy_QueryParser *self,
    lucy_Query *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

lucy_Query* // incremented
lucy_QParser_Expand_Leaf(
    lucy_QueryParser *self,
    lucy_Query *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

lucy_Query* // incremented
lucy_QParser_Prune(
    lucy_QueryParser *self,
    lucy_Query *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.

Make_Term_Query

lucy_Query* // incremented
lucy_QParser_Make_Term_Query(
    lucy_QueryParser *self,
    cfish_String *field,
    cfish_Obj *term
);

Factory method creating a TermQuery.

field

Field name.

term

Term text.

Returns: A Query.

Make_Phrase_Query

lucy_Query* // incremented
lucy_QParser_Make_Phrase_Query(
    lucy_QueryParser *self,
    cfish_String *field,
    cfish_Vector *terms
);

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

lucy_Query* // incremented
lucy_QParser_Make_OR_Query(
    lucy_QueryParser *self,
    cfish_Vector *children
);

Factory method creating an ORQuery.

children

Array of child Queries.

Returns: A Query.

Make_AND_Query

lucy_Query* // incremented
lucy_QParser_Make_AND_Query(
    lucy_QueryParser *self,
    cfish_Vector *children
);

Factory method creating an ANDQuery.

children

Array of child Queries.

Returns: A Query.

Make_NOT_Query

lucy_Query* // incremented
lucy_QParser_Make_NOT_Query(
    lucy_QueryParser *self,
    lucy_Query *negated_query
);

Factory method creating a NOTQuery.

negated_query

Query to be inverted.

Returns: A Query.

Make_Req_Opt_Query

lucy_Query* // incremented
lucy_QParser_Make_Req_Opt_Query(
    lucy_QueryParser *self,
    lucy_Query *required_query,
    lucy_Query *optional_query
);

Factory method creating a RequiredOptionalQuery.

required_query

Query must must match.

optional_query

Query which should match.

Returns: A Query.

Set_Heed_Colons

void
lucy_QParser_Set_Heed_Colons(
    lucy_QueryParser *self,
    bool heed_colons
);

Enable/disable parsing of fieldname:foo constructs.

Inheritance

Lucy::Search::QueryParser is a Clownfish::Obj.