iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
In Whoosh’s default query language, "machine learning"~2 is a quoted phrase query with a proximity-slop value of 2. The suffix allows a positional gap between the phrase terms; it is not the fuzzy edit-distance syntax used with a single unquoted term such as machine~2. Phrase matching also depends on the parser and on the indexed field storing term positions.
How Whoosh reads "machine learning"~2
The quotation marks make machine learning a phrase, and the trailing ~2 sets the phrase slop. Whoosh’s query-language documentation illustrates the syntax with "whoosh library"~5, describing it as matching when “library” is within five words after “whoosh.” The number is therefore a phrase-proximity parameter, not a synonym for fuzzy matching or an edit-distance allowance. See the Whoosh query-language guide.
| # | Preview | Product | Price | |
|---|---|---|---|---|
| 1 |
|
The Little Engine That Could | Buy on Amazon | |
| 2 |
|
The Hidden Monster: A Find-One-on-Every-Page Word Search Book | $9.99 | Buy on Amazon |
The documented example does not establish the exact boundary behavior for every slop value or token sequence. If a particular edge case matters to your search, check it against your installed Whoosh version and parser configuration rather than assuming a more general rule from the example.
How this differs from fuzzy-term syntax
Whoosh’s parser can also support fuzzy-term syntax on an individual unquoted term. For example, machine~2 may be interpreted by the configured fuzzy-term plugin as an edit-distance query. That is different from "machine learning"~2: the latter applies slop to a quoted phrase. Which syntax is accepted depends on the parser instance and its plugins.
#1 Best Overall
What must be configured for phrase matching
Phrase queries need term positions in the field’s index. Whoosh’s schema guide says TEXT fields store positions by default, but other field types or customized configurations may not. If the target field lacks positions, phrase searching cannot work as expected. Check the field definition and schema documentation: Whoosh schema guide.
The query text and indexed content must also be analyzed compatibly. If their tokenization or other analysis differs, the terms and positions used for comparison may not line up.
Why the query may fail or behave differently
- The parser does not handle quoted phrases. The default
PhrasePluginhandles quoted phrase syntax, but a customized parser may remove or replace plugins. - The field does not store positions. Confirm the schema and field type used when the index was created.
- The query and indexed text are analyzed differently. Check the parser and field analysis so both sides produce compatible terms.
- You need a more expressive proximity query. The parser guide describes replacing the normal
PhrasePluginwithSequencePluginfor more complex proximity syntax.
Whoosh’s parser guide explains the modular parser and its plugins: Whoosh parsing guide. It identifies the documented material as version 2.7.4; that documentation alone does not establish whether the project is currently maintained or whether this is the latest release.
Query-string syntax or Python query objects?
| Approach | Best suited to | Key consideration |
|---|---|---|
Query string: "machine learning"~2 |
User-entered searches and compact query syntax | Requires a parser configured to accept the phrase syntax. |
| Programmatic query objects | Queries assembled explicitly in application code | Still requires an index and field setup that supports positional matching. |
The API documents Phrase and span-query classes for constructing queries directly. For new code using near-span queries, the API recommends SpanNear2 rather than SpanNear. Consult the Whoosh query API reference for the relevant constructors and details.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
