Skip to main content

Query API

Build and execute queries programmatically.

QueryParser​

class whoosh.qparser.QueryParser(
    fieldname: str,
    schema: Schema,
    group=AndGroup,
    **kwargs
)

Convert a query string into a Query object.

Methods​

parse()​

query = qp.parse(querystring)

Parse a query string.

tokenize()​

tokens = qp.tokenize(querystring)

Tokenize a query string without parsing.

MultifieldParser​

class whoosh.qparser.MultifieldParser(
    fieldnames: list,
    schema: Schema,
    fieldboosts: dict = None,
    group=OrGroup,
    **kwargs
)

Search multiple fields with different boosts.

Example:

from whoosh.qparser import MultifieldParser

qp = MultifieldParser(
    ["title", "content"],
    schema,
    fieldboosts={"title": 2.0}
)

Query Classes​

All queries inherit from Query:

class whoosh.query.Query

Methods​

matcher()​

matcher = query.matcher(searcher, context=None)

Return a matcher for executing the query.

__and__(), __or__(), __invert__()​

Combine queries with &, |, -.

Leaf Queries​

Term​

Term(fieldname: str, text: str, boost: float = 1.0)

Match a specific term.

Phrase​

Phrase(fieldname: str, words: list, boost: float = 1.0, slop: int = 1)

Match a phrase.

Prefix​

Prefix(fieldname: str, text: str, boost: float = 1.0)

Match terms starting with text.

Wildcard​

Wildcard(fieldname: str, text: str, boost: float = 1.0)

Match terms with ? and * wildcards.

FuzzyTerm​

FuzzyTerm(
    fieldname: str,
    text: str,
    maxdist: int = 2,
    prefix: int = 0,
    boost: float = 1.0
)

Fuzzy match with edit distance.

Range​

NumericRange(
    fieldname: str,
    start: Any,
    end: Any,
    startexact: bool = False,
    endexact: bool = False,
    boost: float = 1.0
)

Numeric range query.

DateRange(
    fieldname: str,
    start: datetime,
    end: datetime,
    startexact: bool = False,
    endexact: bool = False,
    boost: float = 1.0
)

Date range query.

Every​

Every(fieldname: str, boost: float = 1.0)

Match every document with any term in this field.

Boolean Queries​

And​

And(children: list, boost: float = 1.0)

All children must match.

Or​

Or(children: list, boost: float = 1.0)

Any child must match.

Not​

Not(query, exclude)

Match docs matching query but not exclude.

DisjunctionMax​

DisjunctionMax(
    children: list,
    tiebreak: float = 0.0,
    boost: float = 1.0
)

OR-like with scoring tiebreaker.

Special Queries​

Require​

Require(match, requires)

Match must have match, and at least one of requires.

AndMaybe​

AndMaybe(must, should)

Must match must, optionally boosting with should.

Boost​

Boost(q, factor)

Multiply score by factor.

ConstantScore​

ConstantScore(q, score=1.0)

Assign constant score.

Query Operators​

q1 & q2      # And
q1 | q2      # Or
~q1          # Not
q1 ^ q2      # DisjunctionMax

Plugins​

from whoosh.qparser import QueryParserPlugin

class RangePlugin(QueryParserPlugin):
    def __init__(self):
        pass

    def evaluate(self, env, signode):
        # Return a query node
        return query.Range(signode.fieldname, ...)

Exceptions​

class whoosh.qparser.QueryParserError(Exception)

Raised on parse errors.