Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsA Whoosh index is not one file: in Whoosh 2.7.4, a versioned .toc master file tracks one or more segment mini-indexes, each made up of files for postings, stored fields, and other data. Which files appear—and what they contain—depends on the schema and on how the index has been built and merged.
Start with the master file: .toc
In the Whoosh 2.7.4 documented layout, the file named <revision_number>.toc is the index’s master file. It holds information about the index and its segments, so it is the starting point for understanding which segment files belong to the index. The filename’s revision number is part of the documented naming scheme; it is not a promise that every Whoosh release uses an identical on-disk format. Whoosh 2.7.4 file database documentation
As an Amazon Associate I earn from qualifying purchases.
Segments are mini-indexes
Whoosh organizes indexed documents into segments. Adding documents creates a new segment; a search combines results across the segments, and Whoosh may merge segments later. As a result, two directories built with the same schema can have different segment counts because their indexing and merge histories differ. The directory is not guaranteed to contain a fixed number of files or segments.
Recommended Free Tools
What the common segment files do
Segment filenames begin with a segment number, followed by an extension that identifies the data file’s role. The 2.7.4 documentation describes these files:
#1 Best Overall
| File pattern | Role |
|---|---|
<segment_number>.dci |
Per-document information, such as field lengths. Field-length data relates to fields that support scoring; it should not be assumed to be present in the same way for every field. |
<segment_number>.dcz |
Stored field values for documents. These support retrieving document data and are distinct from the terms and postings used for search. |
<segment_number>.tiz |
Per-term information. Its size varies with the unique terms represented; the documentation does not establish a fixed size or record layout. |
<segment_number>.pst |
Per-term postings. Size depends on the collection and field formats, including whether term positions are stored. |
<segment_number>.fvz |
Term vectors, also called forward indexes. This file is created only if at least one schema field stores term vectors; it is not a required part of every index. |
These extensions identify broad responsibilities, not a basis for inferring exact binary encodings. The documented file sizes and presence depend on what was indexed and how fields were configured. Whoosh 2.7.4 file database documentation
How schema choices shape the contents
The schema declares document fields and their types. A field can be indexed, stored, or both. Those are separate choices: indexing makes values searchable, while storing retains values so they can be retrieved later.
Rank #2
Indexed terms and postings
Whoosh’s main index is inverted: terms map to the documents containing them. A field’s posting format controls what is retained for a term: existence alone, frequency, or frequency plus positions. Positional data supports phrase queries; it takes more information to record than frequency-only postings. In Whoosh 2.7.4, TEXT uses positional information by default, while disabling phrase support allows frequency-only storage.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchStored values are not the same as searchable terms
A TEXT field is not stored by default. To retain its original value as document data, configure it as TEXT(stored=True). A STORED field retains a value without indexing it, so its contents are available for retrieval but do not become searchable terms through that field. Whoosh 2.7.4 schema documentation
Rank #3
Forward term vectors are optional
Inverted postings answer the question “which documents contain this term?” A forward index, or term vector, reverses that relationship by mapping a document to its terms. Whoosh does not store term vectors by default; field configuration can request them. That is why an .fvz file is conditional rather than universal. Whoosh 2.7.4 schema documentation
Other field types change how values are interpreted
An ID field treats a whole value, such as a path, as one term. A KEYWORD field is intended for delimited keywords. The schema documentation describes the field types and their behavior; the index files reflect those configuration choices rather than a single universal representation. Whoosh 2.7.4 schema documentation
Why two Whoosh index directories can look different
- Different schemas: stored fields affect whether stored document values are retained; phrase and posting settings affect whether positions are recorded; vector settings affect whether
.fvzfiles are created. - Different document collections: postings and per-term data vary with the indexed collection and its terms.
- Different indexing and merge histories: adding documents creates segments, and later merges can change how many segments remain.
So a directory listing is evidence about one index’s configuration and history, not a template every Whoosh index must match.
Version limits matter when inspecting an index
The file descriptions above are documented for Whoosh 2.7.4. Whoosh’s index API exposes a version tuple that identifies both the release that created an index and its on-disk format version. For forensic inspection or migration, check the actual index version and consult documentation or source matching that release. The cited documentation does not establish a byte-level compatibility guarantee across releases. Whoosh index API documentation
A useful mental model
Read a Whoosh index from the outside in: the .toc identifies index and segment information; each segment divides search and document data among specialized files; and the schema determines which information is recorded. Postings are the inverted search structure, stored fields preserve retrievable values, and forward vectors are optional. The exact directory is therefore shaped by both field configuration and the index’s lifecycle.
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.
