In Whoosh’s default query language, "machine learning"~2 is a phrase query with a proximity-slop suffix. The ~2 sets phrase slop; it is not the fuzzy-edit-distance syntax used with a single unquoted term. Whether it works depends on the parser and the indexed field’s support for term positions.
How Whoosh interprets "machine learning"~2
Whoosh’s default phrase parser treats the text inside quotation marks as a phrase and tokenizes it into terms. The trailing positive integer ~N sets the phrase slop. Whoosh’s query-language guide illustrates this with "whoosh library"~5, which matches when “library” is within five words after “whoosh.”
| # | Preview | Product | Price | |
|---|---|---|---|---|
| 1 |
|
The Hidden Monster: A Find-One-on-Every-Page Word Search Book | $9.99 | Buy on Amazon |
As an Amazon Associate I earn from qualifying purchases.
So the query asks Whoosh to find the phrase terms in positional proximity, allowing slop of 2. Do not read that suffix as a synonym rule or as a general guarantee about every possible arrangement of intervening words. The documentation’s example establishes the intended proximity behavior, but does not spell out every boundary case for every tokenizer or parser configuration. If an exact edge case matters, verify it against the application’s installed Whoosh version and parser.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesHow this differs from a fuzzy term query
Quotation marks matter. "machine learning"~2 is a phrase query with slop. By contrast, a suffix on a single unquoted term, such as machine~2, can be interpreted by the parser’s fuzzy-term plugin as an edit-distance setting. The two forms use similar punctuation but express different query behavior.
#1 Best Overall
What must be true for the phrase query to match
- The parser must accept phrase syntax. Whoosh’s default
PhrasePluginhandles quoted phrases. Parser plugins can be removed, replaced, or extended, so a customized parser may not accept the same syntax. - The field must store term positions. Phrase searching relies on positions in the indexed field. Whoosh’s schema guide says
TEXTfields store positions by default, but a field type or configuration without positions cannot support phrase matching. - Indexing and query analysis must be compatible. The text in the index and the text in the query are analyzed into terms. If their analysis differs, the expected phrase may not be represented as the query assumes.
What to check if the query returns no matches
- Confirm the parser instance and plugins. Check that the application uses a parser with the default phrase handling, or another parser that supports the syntax. Whoosh’s parser guide describes
SequencePluginfor more complex proximity queries. - Check the target field’s schema. Confirm that the indexed field stores term positions. A field without positions cannot satisfy phrase queries.
- Compare the analyzers. Verify that indexing and query parsing produce compatible terms for the field, especially if the application uses custom analysis.
- Test the boundary behavior you need. Documentation examples explain the general slop syntax, but do not establish every tokenizer- and configuration-specific edge case. Run a focused test with the installed version and the real parser and schema.
Query-string syntax or programmatic query objects?
| Approach | Best suited to | Considerations |
|---|---|---|
Query string, such as "machine learning"~2 |
User-entered or compact query syntax | Depends on the parser and its phrase-related plugins. |
| Programmatic query objects | Queries assembled explicitly in application code | The API provides Phrase and span-query types. For new code using near-span queries, the API reference recommends SpanNear2 rather than SpanNear. |
Both approaches still require an index and field configuration that support positional matching. The relevant documentation identifies itself as Whoosh 2.7.4; these syntax notes should not be taken as a claim about current maintenance or the latest release.
Quick Recap
Whoosh documentation
- Whoosh query language — phrase and slop syntax.
- Whoosh parser guide — parser plugins, including phrase and sequence parsing.
- Whoosh query API reference — phrase and span query objects.
- Whoosh schema guide — field configuration and term positions.
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.
