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
When the document you expect to be first lands at the bottom of a Whoosh result list, the index is not reporting that the document is irrelevant. It is reporting that, under the current schema, scoring settings and query, other documents earned a higher score. Whoosh orders results by a score computed from the fields you index, the terms that match, and the weights you apply. That score is a model of relevance, not a measurement of it. The fix is to find which part of the score is pulling your target document down, change one control, and measure the effect on a fixed set of test queries.
How Whoosh decides the order of results
Whoosh sorts hits by score unless you explicitly sort by a field. Its scoring API documents BM25F as the default weighting model (the reference material used here is for Whoosh 2.7.4). BM25F combines three things for every matching term in every field: how often the term occurs, how long the field is, and how much weight the field carries through its boost.
Because of that arithmetic, a document can lose for reasons that have nothing to do with how useful it is to a person:
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →- Its matches sit in a body field, while competing documents match the same words in a short, boosted title.
- It is long, so its term counts are normalized downward against shorter documents.
- The query terms are spread across different fields, so no single field accumulates a strong score.
- A field that should hold exact values, such as an identifier or path, is analyzed as free text, so matches arrive for the wrong reasons.
- A query-time boost on one term quietly outweighs the term that actually describes your target document.
- The “best” document answers the question with different vocabulary from the query, which no weighting setting can bridge by itself.
Diagnose the ordering before changing anything
- Confirm the query parses as you intended. Print the parsed query object. If a term you care about is missing, is attached to the wrong field, or carries an unexpected boost, the problem is in parsing, not scoring.
from whoosh.qparser import QueryParser with ix.searcher() as searcher: parser = QueryParser("body", ix.schema) query = parser.parse(u"your query") print(query) - Print the scores and the fields of the top results. Hit fields are available only when they were indexed with
stored=True.with ix.searcher() as searcher: results = searcher.search(query, limit=10) for hit in results: print(round(hit.score, 3), hit["path"], hit["title"])Compare the top hit’s score with your target document’s score. A large gap usually points to a field or length effect; a small gap points to a term or vocabulary effect.
- Check the schema field types. Fields meant for searchable prose should be
TEXT, which is analyzed. Identifiers, paths and tags that must match exactly should useID, which is not analyzed. Confirm that each field you query is stored when you need to display it. - Locate the match. For your target document and the document ranked above it, note whether each matching term appears in the title, in headings, or only in the body. This tells you whether a field boost is the right lever.
- Record the baseline. Write down the current rank of your target document for each test query before you change anything (see the testing section below).
Control 1: field boosts in the schema
A field boost tells the index that matches in a particular field should count for more across all queries. Use it when titles, tags or headings are a stronger signal of relevance than body text throughout your collection. The Whoosh schema documentation illustrates the setting with a title field boost of 2.0 beside an unboosted body field:
#1 Best Overall
- Composition and permanence tables provide important information on the composition
- It remains our goal to earn your trust through the traditional way we do business
- Manufactured in united states
from whoosh.fields import Schema, TEXT, ID
schema = Schema(
path=ID(stored=True, unique=True),
title=TEXT(stored=True, field_boost=2.0),
body=TEXT(stored=True),
)The value 2.0 is the documentation’s example, not a recommended setting for your data. Because the boost is applied when documents are indexed, changing it means rebuilding the index; a schema edit alone does not re-weight documents already stored. An aggressive boost can also make titles dominate so strongly that a body-heavy document with a precise answer falls below generic title matches.
Control 2: BM25F parameters B and K1
BM25F exposes two tuning parameters on the scoring model:
Rank #2
- Skill-Building Fun: This book is not just about fun; it's a tool for growth. Children develop critical observation skills, boost attention to detail, and enhance their concentration ability as they search for hidden objects. It's a delightful way to build patience and focus, one find at a time.
- 30 Different Themes: The book contains 30 unique themes for preschoolers to explore, including the garden, ocean world, construction site, supermarket, clothing store, zoo, desert, and more. Each sheet unfolds a richly illustrated theme, from bustling city scenes to enchanting forest settings, encouraging children to dive into a world of engaging visual puzzles.
- Bright-colored & Eye-catching: Every page is a visual treat, filled with vibrant colors and detailed illustrations that capture kids' attention and spark their imagination. The adorable characters and diverse environments ensure that there's always something new to discover, keeping children engaged for hours.
- Premium, Reusable & Erasable: Crafted using high-quality materials, this search and find book is built to withstand the enthusiasm and energy of preschoolers. It features waterproof, sturdy pages and a durable cover, ensuring that it can withstand repeated use and provide long-lasting enjoyment.
- Value Pack: It comes with a large activity book, 8 dry-erase markers, and a storage bag, all of these are packaged in a reinforced protective box. It can be easily carried during travel, in restaurants, or at any other time when parents need an engaging activity to keep their preschoolers occupied.
- K1 controls how quickly repeated occurrences of a term stop adding to the score. Lower values saturate sooner, so a term repeated many times counts for less extra.
- B controls length normalization. Higher values penalize long fields more; lower values penalize them less.
The Whoosh BM25F documentation lists defaults of B=0.75 and K1=1.2. These are API defaults, not a measured recommendation for any index. BM25F also accepts a B value per field, so a long body field can be normalized differently from a short title. Correct BM25F results depend on field-length information being available, which Whoosh tracks for indexed fields. Check the BM25F class signature in your installed version for the exact keyword form of per-field B values.
Pass the model to a searcher:
from whoosh import scoring
with ix.searcher(weighting=scoring.BM25F(B=0.75, K1=1.2)) as searcher:
results = searcher.search(query, limit=10)Use this control when your target document is long and is losing to shorter documents that repeat the query term a few times, or when repeated terms in one long field are overwhelming the ranking.
Control 3: query-time boosts
Query syntax lets you boost a single term or a grouped element for one query. The documented forms include ninja^2 and (open sesame)^2.5. A query-time boost applies only to that query, which makes it the right choice when emphasis depends on what the user typed rather than on the document collection as a whole. For example, if a search for a product name should favor the name field, boost that term in the query rather than changing the schema for every search.
Boosts are fragile when hard-coded. If the application builds queries from user input, decide which terms receive a boost by rule, and test those rules with the same query set you use for other changes.
Rank #4
- Religion
- Spirituality
- Book
Control 4: a custom weighting model
Whoosh’s scoring API includes FunctionWeighting, and a weighting model can produce scorer instances, which lets you express a scoring rule in code. Reserve this for rules that the standard field boosts, BM25F parameters and query boosts cannot represent, such as a rule that depends on a value stored on each document. A custom model is the most code to maintain and the hardest to debug, so introduce it only after the simpler controls have been tested.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteComparing the controls
| Control | Where it applies | What it changes | Use it when | Main risk |
|---|---|---|---|---|
Schema field_boost |
Indexing; applies to every query | Weight of matches in that field | Titles, tags or headings are a stronger signal across the collection | Requires reindexing; an overlarge boost lets titles dominate |
BM25F B and K1 |
Scoring; set on the searcher | Term-frequency saturation and length normalization | Long documents are penalized, or repeated terms overwhelm the ranking | Effects depend on the corpus; defaults are not tuned for your data |
| Query-time boost | One query or query pattern | Weight of a term or grouped element | Emphasis depends on the user’s intent | Hard-coded boosts can mask underlying problems and need upkeep |
| Custom weighting model | Scoring code path | Any application-specific rule | No standard control can express the rule | Most code to maintain; harder to reason about and debug |
Test every change against a fixed query set
A ranking change that improves one query can damage several others, so judge changes on a stable set of representative queries rather than on the query that prompted the complaint.
Best Value
- The perfect product for busy offices, walk-in advising centers, call centers, and other high-traffic businesses
- Keep track of activities and follow-ups
- Includes columns for date, time, name of contact, phone number, subject, follow-up action required, initials of individual completing the log, and check box to signal completion
- Spiral bound at left
- 100 pages per book
- Assemble representative queries, ideally from real searches, and for each one write down the document or documents that should appear at the top.
- Record the current rank of each expected document using the score-printing loop above.
- Make one change: a field boost, a B or K1 value, a query boost, or a custom model.
- If the schema changed, rebuild the index. Then rerun every query in the set.
- Keep the change only if the expected documents rise and the queries that were already correct stay correct.
Nothing in the Whoosh documentation establishes a boost value or B and K1 pair that works across indexes, so the values that suit your collection can only be found this way.
Troubleshooting branches
- The expected document does not match the query at all. No weighting setting will rank it. Check that the query terms exist in the indexed field after analysis, and that the field is
TEXTrather thanIDwhere prose matching is needed. - It matches only in the body, while competitors match in the title. Consider a schema field boost on the title, or a query-time boost if the title emphasis only matters for certain searches.
- It is long and repeats the query terms less than shorter documents. Test a lower B for the body field, or review K1.
- It uses different vocabulary from the query. Add the missing terms to the indexed text, such as a summary or keyword field, rather than adjusting weights.
- Many documents have nearly identical scores. Scoring cannot separate them meaningfully. If a stored value such as a date or popularity count should decide the order, sort explicitly with a sort field, understanding that a field sort replaces score ordering for that search.
Version and currency
The reference documentation used for the examples above is for Whoosh 2.7.4. Confirm the version your application uses with pip show whoosh and check that the class names, keyword arguments and query syntax match that release before copying any example. The current maintenance status of the project is not established by these sources, so treat the examples as a starting point and verify them against the installed code.
No ranking outcome for your own index is promised here. Only the testing procedure above can show whether a given setting moves your target document up.
Free tools Windows power users keep installed
One-click scans. No signup required.
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.
