Whoosh Reloaded

https://github.com/sygil-dev/whoosh-reloaded
Admin
A fast, pure-Python full-text search library for indexing and searching documents with customizable...
Tokens:226,244
Snippets:1,905
Trust Score:8.6
License:BSD-2-Clause
Update:1 month ago
Show doc for...
Tokens:
Raw
### Open a Searcher with searcher()

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/searching.rst

Call searcher() on an Index object to get a Searcher instance. This is the basic way to start searching.

```default
searcher = myindex.searcher()
```

--------------------------------

### Get search results and print title

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/highlight.rst

Basic search loop that prints the title of each hit. This is the starting point for highlighting examples.

```default
results = mysearcher.search(myquery)
for hit in results:
    print(hit["title"])
```

--------------------------------

### Query.docs example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/query.rst

Shows how to get a list of document numbers matching a query using the docs method within a searcher context.

```python
>>> with my_index.searcher() as searcher:
...     list(my_query.docs(searcher))
[10, 34, 78, 103]
```

--------------------------------

### Prefix query example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/query.rst

Creates a Prefix query to match documents containing words starting with 'comp'.

```pycon
>>> # Match documents containing words starting with 'comp'
>>> Prefix("content", u"comp")
```

--------------------------------

### Install whoosh-reloaded with pip

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/README.md

Install the stable release from PyPI or the latest development version directly from the GitHub repository using pip.

```bash
# Install the stable version from Pypi
$ pip install whoosh-reloaded

# Install the development version from GitHub.
$ pip install git+https://github.com/Sygil-Dev/whoosh-reloaded.git
```

--------------------------------

### Install Whoosh with easy_install or pip

Source: https://github.com/sygil-dev/whoosh-reloaded/wiki/Home

Install Whoosh using easy_install or pip for the PyPI release, or install the development version directly from the GitHub repository. Use when setting up the library for the first time.

```shell
# install the old version from Pypi
$ easy_install Whoosh

or

$ pip install Whoosh


# Install the development version from Github.
$ pip install git+https://github.com/Sygil-Dev/whoosh.git
```

--------------------------------

### matched_terms() example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/searching.rst

Shows how to get the set of terms that matched in the top N documents. Requires terms=True in the search call, otherwise it raises an exception. The example parses a query, searches with terms=True, and compares the matched terms to the query's terms.

```pycon
>>> q = myparser.parse("alfa OR bravo OR charlie")
>>> results = searcher.search(q, terms=True)
>>> results.terms()
set([("content", "alfa"), ("content", "charlie")])
>>> q.all_terms() - results.terms()
set([("content", "bravo")])
```

--------------------------------

### Example documents with priority numbers

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/facets.rst

Example data showing documents with a custom priority number for sorting.

```text
name=Big Wheel
price=100
priority=1

name=Toss Across
price=40
priority=3

name=Slinky
price=25
priority=2
...
```

--------------------------------

### Set up pre-commit for development

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/README.md

Install pre-commit and set up the git hooks to format code and run checks before committing.

```bash
$ pip install pre-commit
$ pre-commit install
```

--------------------------------

### more_like() example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/searching.rst

Returns a Results object containing documents similar to the given document, based on "key terms" in the given field. The example shows how to get the document number, call more_like(), and print the titles of similar documents.

```default
# Get the ID for the document you're interested in
docnum = search.document_number(path=u"/a/b/c")

r = searcher.more_like(docnum)

print("Documents like", searcher.stored_fields(docnum)["title"])
for hit in r:
    print(hit["title"])
```

--------------------------------

### make_binary_tree example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/util.rst

Example usage of whoosh.util.make_binary_tree, showing how it builds a binary tree from a list of arguments using a function or class that takes two positional arguments. The output demonstrates the resulting nested structure.

```pycon
>>> make_binary_tree(UnionMatcher, [matcher1, matcher2, matcher3])
UnionMatcher(matcher1, UnionMatcher(matcher2, matcher3))
```

--------------------------------

### GtLtPlugin range syntax example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/releases/1_0.rst

Example of the greater-than/less-than syntax enabled by the GtLtPlugin for range queries.

```python
count:>100 tag:<=zebra date:>='29 march 2001'
```

--------------------------------

### StemmingAnalyzer schema example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/stemming.rst

Shows how to create a schema using the pre-packaged StemmingAnalyzer for TEXT fields.

```python
from whoosh import fields
from whoosh.analysis import StemmingAnalyzer

stem_ana = StemmingAnalyzer()
schema = fields.Schema(title=TEXT(analyzer=stem_ana, stored=True),
                       content=TEXT(analyzer=stem_ana))
```

--------------------------------

### Create FileStorage and directory

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/filedb/filestore.rst

Use to instantiate a FileStorage and create its backing directory. The create() method performs implementation-specific setup.

```default
# Create a storage object
st = FileStorage("indexdir")
# Create the directory if it doesn't already exist
st.create()
```

--------------------------------

### DateRangeFacet example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/facets.rst

Creates a DateRangeFacet for DATETIME fields. The start and end must be datetime objects, and the gap must be a timedelta. Supports lists of gaps and the hardend keyword argument like RangeFacet.

```default
from datetime import datetime, timedelta

start = datetime(2000, 1, 1)
end = datetime.now()
gap = timedelta(days=365)
bdayfacet = sorting.DateRangeFacet("birthday", start, end, gap)
```

--------------------------------

### Determine required queries with requires()

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/query.rst

Shows how to use Query.requires() to get a set of queries that are known to be required for the entire query to match. The example demonstrates results for And, Or, AndMaybe, and a single Term.

```pycon
>>> a = Term("f", u"a")
>>> b = Term("f", u"b")
>>> And([a, b]).requires()
set([Term("f", u"a"), Term("f", u"b")])
>>> Or([a, b]).requires()
set([])
>>> AndMaybe(a, b).requires()
set([Term("f", u"a")])
>>> a.requires()
set([Term("f", u"a")])
```

--------------------------------

### Example date queries supported by DateParserPlugin

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/dates.rst

Lists example date query strings that the DateParserPlugin can parse, including absolute dates, relative dates, and ranges. Users must quote queries containing spaces unless free mode is enabled.

```text
20050912
2005 sept 12th
june 23 1978
23 mar 2005
july 1985
sep 12
today
yesterday
tomorrow
now
next friday
last tuesday
5am
10:25:54
23:12
8 PM
4:46 am oct 31 2010
last tuesday to today
today to next friday
jan 2005 to feb 2008
-1 week to now
now to +2h
-1y6mo to +2 yrs 23d
```

--------------------------------

### NgramTokenizer example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/ngrams.rst

Tokenizes the entire field into N-grams. Useful for CJK languages. The example uses minsize=2 and maxsize=4.

```python
>>> ngt = NgramTokenizer(minsize=2, maxsize=4)
>>> [token.text for token in ngt(u"hi there")]
[u'hi', u'hi ', u'hi t',u'i ', u'i t', u'i th', u' t', u' th', u' the', u'th',
u'the', u'ther', u'he', u'her', u'here', u'er', u'ere', u're']
```

--------------------------------

### Dynamic field example with documents and query

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/schema.rst

Complete example of using a dynamic field: schema with a glob pattern for fields ending in '_id', creating an index, adding documents with dynamic fields, and searching with a query parser.

```python
schema = fields.Schema(path=fields.ID)
schema.add("*_id", fields.ID, glob=True)

ix = index.create_in("myindex", schema)

w = ix.writer()
w.add_document(path=u"/a", test_id=u"alfa")
w.add_document(path=u"/b", class_id=u"MyClass")
# ...
w.commit()

qp = qparser.QueryParser("path", schema=schema)
q = qp.parse(u"test_id:alfa")
with ix.searcher() as s:
    results = s.search(q)
```

--------------------------------

### NgramTokenizer example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/analysis.rst

Splits input text into N-grams instead of words. The example uses a minimum size of 4 and shows that grams may contain whitespace and punctuation.

```pycon
>>> ngt = NgramTokenizer(4)
>>> [token.text for token in ngt("hi there")]
["hi t", "i th", " the", "ther", "here"]
```

--------------------------------

### And query examples

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/query.rst

Shows two ways to create an And query: using the And class with a list of subqueries, and using the & operator.

```pycon
>>> And([Term("content", u"render"),
...      Term("content", u"shade"),
...      Not(Term("content", u"texture"))])
>>> # You can also do this
>>> Term("content", u"render") & Term("content", u"shade")
```

--------------------------------

### Inefficient Every query example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/query.rst

This example shows the inefficient way to match all documents with a field using Every. It is slow because it requires reading the full posting list of every term in the field.

```default
# Match all documents that have something in the "path" field
q = Every("path")
```

--------------------------------

### Thesaurus.from_file example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/lang/wordnet.rst

Parses the WordNet file from a file-like object and retrieves synonyms.

```pycon
>>> f = open("wn_s.pl")
>>> t = Thesaurus.from_file(f)
>>> t.synonyms("hail")
['acclaim', 'come', 'herald']

```

--------------------------------

### Or query examples

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/query.rst

Shows two ways to create an Or query: using the Or class with a list of subqueries, and using the | operator.

```pycon
>>> Or([Term("content", u"render"),
...     And([Term("content", u"shade"), Term("content", u"texture")]),
...     Not(Term("content", u"network"))])
>>> # You can also do this
>>> Term("content", u"render") | Term("content", u"shade")
```

--------------------------------

### LanguageAnalyzer example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/analysis.rst

Configures a simple analyzer for the given language, with a LowercaseFilter, StopFilter, and StemFilter. The example uses Spanish ('es') and shows the stemmed tokens for a sample sentence.

```pycon
>>> ana = LanguageAnalyzer("es")
>>> [token.text for token in ana("Por el mar corren las liebres")]
['mar', 'corr', 'liebr']
```

--------------------------------

### RegexTokenizer example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/analysis.rst

Uses a regular expression to extract tokens from text. The example shows how it splits a string with numbers, punctuation, and underscores.

```pycon
>>> rex = RegexTokenizer()
>>> [token.text for token in rex(u("hi there 3.141 big-time under_score"))]
["hi", "there", "3.141", "big", "time", "under_score"]
```

--------------------------------

### KeywordAnalyzer usage example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/analysis.rst

Parses whitespace- or comma-separated tokens. The example shows the default behavior without lowercasing or comma splitting, preserving punctuation like commas in tokens.

```pycon
>>> ana = KeywordAnalyzer()
>>> [token.text for token in ana("Hello there, this is a TEST")]
["Hello", "there,", "this", "is", "a", "TEST"]
```

--------------------------------

### Wildcard query example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/query.rst

Creates a Wildcard query using a glob pattern.

```pycon
>>> Wildcard("content", u"in*f?x")
```

--------------------------------

### Using highlights() to get highlighted snippets

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/searching.rst

Shows how to iterate over search results and print highlighted snippets from a field.

```default
r = searcher.search(myquery)
for hit in r:
    print(hit["title"])
    print(hit.highlights("content"))
```

--------------------------------

### DateRange example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/query.rst

Creates a DateRange query with datetime objects for the 'date' field.

```pycon
>>> DateRange("date", datetime(2010, 11, 3, 3, 0),
...           datetime(2010, 11, 3, 17, 59))
```

--------------------------------

### Porter stemmer example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/stemming.rst

Demonstrates using the Porter stemmer from whoosh.lang.porter to reduce a word to its base form.

```python
>>> from whoosh.lang.porter import stem
>>> stem("rendering")
'render'
```

--------------------------------

### Using searcher.vector_as() to get term vector as list

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/reading.rst

Shows the shortcut method vector_as() to get term vector data as a list of (term, value) pairs. The example uses the 'frequency' format.

```pycon
>>> docnum = searcher.document_number(path=u'/a/b/c')
>>> searcher.vector_as("frequency", docnum, "content")
[(u"apple", 3), (u"bear", 2), (u"cab", 2)]
```

--------------------------------

### Create index with FileStorage and create_index

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/filedb/filestore.rst

Shows creating a schema and using FileStorage.create (class method) to set up storage, then creating an index with create_index().

```pycon
>>> from whoosh import fields
>>> from whoosh.filedb.filestore import FileStorage
>>> schema = fields.Schema(content=fields.TEXT)
>>> # Create the storage directory
>>> st = FileStorage.create("indexdir")
>>> # Create an index in the storage
>>> ix = st.create_index(schema)
```

--------------------------------

### Open an index with FileStorage.open_index()

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/filedb/filestore.rst

Shows how to create a FileStorage instance and open an existing index. The example uses the 'indexdir' directory and calls st.open_index() without arguments.

```pycon
>>> from whoosh.filedb.filestore import FileStorage
>>> st = FileStorage("indexdir")
>>> # Open an index in the storage
>>> ix = st.open_index()
```

--------------------------------

### Get lexicon from Searcher

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/searching.rst

Use the lexicon() method to list terms in a field. The example shows the output for the 'content' field.

```default
>>> list(searcher.lexicon("content"))
[u"document", u"index", u" whoosh"]
```

--------------------------------

### OnDiskBitSet usage with RamStorage

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/idsets.rst

Interactive console example that demonstrates creating a BitSet, writing it to disk, reading it back as an OnDiskBitSet, and iterating over it. Output is shown: [1, 2, 7, 10, 15]. The script uses RamStorage to create and open a file.

```pycon
>>> st = RamStorage()
>>> f = st.create_file("test.bin")
>>> bs = BitSet([1, 10, 15, 7, 2])
>>> bytecount = bs.to_disk(f)
>>> f.close()
>>> # ...
>>> f = st.open_file("test.bin")
>>> odbs = OnDiskBitSet(f, bytecount)
>>> list(odbs)
[1, 2, 7, 10, 15]
```

--------------------------------

### Thesaurus.from_filename example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/lang/wordnet.rst

Loads a Thesaurus from the WordNet wn_s.pl file.

```pycon
>>> t = Thesaurus.from_filename("wn_s.pl")

```

--------------------------------

### Thesaurus.from_storage example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/lang/wordnet.rst

Loads a Thesaurus from an existing Whoosh index.

```pycon
>>> t = Thesaurus.from_storage(fs)

```

--------------------------------

### Not query examples

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/query.rst

Shows how to exclude documents using the Not class and the - operator.

```pycon
>>> # Match documents that contain 'render' but not 'texture'
>>> And([Term("content", u"render"),
...      Not(Term("content", u"texture"))])
>>> # You can also do this
>>> Term("content", u"render") - Term("content", u"texture")
```

--------------------------------

### reset()

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/matching.rst

Returns to the start of the posting list.

```APIDOC
## Matcher.reset()

### Description
Returns to the start of the posting list. Note that reset() may not do what you expect after calling replace(), since this can mean calling reset() on an optimized replacement.

### Method
reset()

### Parameters
None

### Returns
None

```

--------------------------------

### Collector.prepare(top_searcher, q, context)

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/collectors.rst

Called before a search. Subclasses can override this to perform set-up work, but they should still call the superclass's method because it sets several necessary attributes on the collector object: self.top_searcher, self.q, and self.context.

```APIDOC
## Collector.prepare(top_searcher, q, context)

### Description
This method is called before a search. Subclasses can override this to perform set-up work, but they should still call the superclass's method because it sets several necessary attributes on the collector object: self.top_searcher (the top-level Searcher), self.q (the query object), and self.context (a SearchContext object).

### Method
prepare(top_searcher, q, context)

### Parameters
- **top_searcher** (whoosh.searching.Searcher) - Required - The top-level Searcher object.
- **q** (whoosh.query.Query) - Required - The query object being searched for.
- **context** (whoosh.searching.SearchContext) - Required - A SearchContext object containing information about the search.
```

--------------------------------

### key_terms() terms extraction example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/searching.rst

To just get the terms themselves from the key_terms() method, you can use a list comprehension to extract the first element of each tuple.

```pycon
>>> kws = [kw for kw, score in searcher.key_terms([docnum], "content")]
```

--------------------------------

### Whoosh quick start: create index, add documents, and search

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/quickstart.rst

Interactive Python session showing the complete Whoosh workflow: create an index with a schema, add documents, commit, and search. The output shows the first result for the query "first".

```python
>>> from whoosh.index import create_in
>>> from whoosh.fields import Schema, TEXT, ID
>>> schema = Schema(title=TEXT(stored=True), path=ID(stored=True), content=TEXT)
>>> ix = create_in("indexdir", schema)
>>> writer = ix.writer()
>>> writer.add_document(title=u"First document", path=u"/a",
...                     content=u"This is the first document we've added!")
>>> writer.add_document(title=u"Second document", path=u"/b",
...                     content=u"The second one is even more interesting!")
>>> writer.commit()
>>> from whoosh.qparser import QueryParser
>>> with ix.searcher() as searcher:
...     query = QueryParser("content", ix.schema).parse("first")
...     results = searcher.search(query)
...     results[0]
...
{"title": u"First document", "path": u"/a"}
```

--------------------------------

### Perform a basic search with search()

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/searching.rst

Parse a query with QueryParser and search the index. The example shows the typical pattern: create a parser, parse a query string, open a searcher, and call search().

```default
from whoosh.qparser import QueryParser

qp = QueryParser("content", schema=myindex.schema)
q = qp.parse(u"hello world")

with myindex.searcher() as s:
    results = s.search(q)
```

--------------------------------

### document() and documents() convenience methods

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/searching.rst

Shows how to retrieve stored fields using keyword arguments. The first example lists documents matching a date, the second retrieves a single document by path.

```python
>>> list(searcher.documents(indexeddate=u"20051225"))
[{"title": u"Christmas presents"}, {"title": u"Turkey dinner report"}]
>>> print searcher.document(path=u"/a/b/c")
{"title": "Document C"}
```

--------------------------------

### Using searcher.vector() to get term vector

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/reading.rst

Demonstrates retrieving a Matcher for a term vector and converting it to a frequency list. The example shows the output for a document with path '/a/b/c'.

```pycon
>>> docnum = searcher.document_number(path=u'/a/b/c')
>>> v = searcher.vector(docnum, "content")
>>> v.all_as("frequency")
[(u"apple", 3), (u"bear", 2), (u"cab", 2)]
```

--------------------------------

### Thesaurus.from_storage with synonyms example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/lang/wordnet.rst

Loads a Thesaurus from storage and retrieves synonyms for a word.

```pycon
>>> from whoosh.filedb.filestore import FileStorage
>>> fs = FileStorage("index")
>>> t = Thesaurus.from_storage(fs)
>>> t.synonyms("hail")
['acclaim', 'come', 'herald']

```

--------------------------------

### Example user query and parsed query objects

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/parsing.rst

Shows the user query string and the query objects it might be parsed into by the default parser.

```none
rendering shading
```

```default
And([Term("content", u"rendering"), Term("content", u"shading")])
```

--------------------------------

### Thesaurus.from_filename with synonyms example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/lang/wordnet.rst

Loads a Thesaurus from a filename and looks up synonyms for a word.

```pycon
>>> t = Thesaurus.from_filename("wn_s.pl")
>>> t.synonyms("hail")
['acclaim', 'come', 'herald']

```

--------------------------------

### QueryParser initialization with schema

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/releases/1_0.rst

Shows the new required schema argument for QueryParser initialization.

```python
qp = qparser.QueryParser("content", myindex.schema)
```

--------------------------------

### Get highlighted snippets with Hit.highlights

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/releases/1_0.rst

Retrieve highlighted snippets for each hit automatically using the Hit.highlights method. The example searches with a limit of 20 and prints the title and highlighted content for each hit.

```default
results = searcher.search(myquery, limit=20)
for hit in results:
    print hit["title"]
    print hit.highlights("content")
```

--------------------------------

### Thesaurus.to_storage with from_filename example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/lang/wordnet.rst

Creates an index in the given storage from a loaded Thesaurus.

```pycon
>>> from whoosh.filedb.filestore import FileStorage
>>> fs = FileStorage("index")
>>> t = Thesaurus.from_filename("wn_s.pl")
>>> t.to_storage(fs)

```

--------------------------------

### Using reader.postings() to iterate postings

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/reading.rst

Shows how to get a Matcher for a term's postings and skip to a specific document ID. The example prints the document ID after skipping to document 10.

```pycon
>>> pr = reader.postings("content", "render")
>>> pr.skip_to(10)
>>> pr.id
12
```

--------------------------------

### Get spelling suggestions with Searcher.suggest()

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/searching.rst

Shows the Searcher.suggest() method returning a sorted list of suggested corrections for a mis-typed word based on the contents of a field. The example shows the input and the returned list.

```default
>>> searcher.suggest("content", "specail")
["special"]
```

--------------------------------

### Open index and create writer

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/indexing.rst

Shows how to open an index directory and obtain an IndexWriter. Creating a writer locks the index for writing, so only one thread/process can have a writer open at a time.

```default
ix = index.open_dir("index")
writer = ix.writer()
```

--------------------------------

### Term query example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/query.rst

Creates a Term query for the field 'content' and the text 'render'.

```pycon
>>> Term("content", u"render")
```

--------------------------------

### Accessing document numbers from groups()

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/searching.rst

Shows how to retrieve the list of document numbers for a specific category from the groups() result. The example searches with groupedby="tag" and then accesses the 'new' key to get the document numbers.

```pycon
>>> results = mysearcher.search(myquery, groupedby="tag")
>>> docnums = results.groups()
>>> docnums['new']
[12, 1, 4]
```

--------------------------------

### Boost all fields and specific fields

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/writing.rst

Shows how to boost all fields at once with _boost and override for specific fields with _<fieldname>_boost.

```default
writer.add_document(a="alfa", b="bravo", c="charlie",
                    _boost=2.0, _c_boost=3.0)
```

--------------------------------

### Every query usage examples

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/query.rst

Shows how to create an Every query for a specific field or for all documents. The unfielded form is efficient, while the fielded form can be slow on large indexes.

```pycon
>>> # Match any documents with something in the "path" field
>>> q = Every("path")
>>> # Matcher every document
>>> q = Every()
```

--------------------------------

### key_terms() example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/searching.rst

Returns the 'numterms' most important terms from the documents listed (by number) in 'docnums'. You can get document numbers for the documents your interested in with the document_number() and document_numbers() methods. This method returns a list of ("term", score) tuples.

```pycon
>>> docnum = searcher.document_number(path=u"/a/b")
>>> keywords_and_scores = searcher.key_terms([docnum], "content")
```

--------------------------------

### StemFilter example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/stemming.rst

Shows how to apply the StemFilter to a token stream from a RegexTokenizer, producing stemmed tokens.

```python
>>> rext = RegexTokenizer()
>>> stream = rext(u"fundamentally willows")
>>> stemmer = StemFilter()
>>> [token.text for token in stemmer(stream)]
[u"fundament", u"willow"]
```

--------------------------------

### Create an index with index.create_in

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/indexing.rst

Creates a new index in a directory using the convenience function index.create_in. The directory must exist before calling this function, so the example checks and creates it with os.mkdir. The schema must be defined beforehand.

```default
import os, os.path
from whoosh import index

if not os.path.exists("indexdir"):
    os.mkdir("indexdir")

ix = index.create_in("indexdir", schema)
```

--------------------------------

### FilterCollector usage example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/collectors.rst

Use FilterCollector to allow or restrict document numbers in search results. The allow and restrict parameters can be queries, Results objects, or set-like objects. Documents not in the allow set or in the restrict set are discarded; if a document is in both sets, it is discarded. Access filtered_count on the collector to get the number of filtered documents.

```python
uc = collectors.UnlimitedCollector()

ins = query.Term("chapter", "rendering")
outs = query.Term("status", "restricted")
fc = FilterCollector(uc, allow=ins, restrict=outs)

mysearcher.search_with_collector(myquery, fc)
print(fc.results())
```

--------------------------------

### Get term frequency and document frequency

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/recipes.rst

Use searcher.frequency() to get the total term frequency and searcher.doc_frequency() to get the document frequency for a term in a field.

```default
# Number of times content:wobble appears in all documents
freq = searcher.frequency("content", "wobble")

# Number of documents containing content:wobble
docfreq = searcher.doc_frequency("content", "wobble")
```

--------------------------------

### Create and open an index with FileStorage

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/indexing.rst

Shows the underlying FileStorage methods that the convenience functions index.create_in and index.open_dir wrap. Use this when you need direct access to the storage object. The schema is required for create_index.

```default
from whoosh.filedb.filestore import FileStorage
storage = FileStorage("indexdir")

# Create an index
ix = storage.create_index(schema)

# Open an existing index
storage.open_index()
```

--------------------------------

### Get spelling suggestions from an index field

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/spelling.rst

Use a Searcher.corrector() to get a corrector for a field and call suggest() to get spelling suggestions for mistyped words. The limit argument controls the maximum number of suggestions returned.

```python
with ix.searcher() as s:
    corrector = s.corrector("text")
    for mistyped_word in mistyped_words:
        print corrector.suggest(mistyped_word, limit=3)
```

--------------------------------

### Query.accept example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/query.rst

Defines a function to boost Phrase queries and applies it to a query using the accept method. The method copies nodes before applying the function, so the original tree is not modified.

```python
def boost_phrases(q):
    if isintance(q, Phrase):
        q.boost *= 2.0
    return q

myquery = myquery.accept(boost_phrases)
```

--------------------------------

### SpaceSeparatedTokenizer example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/analysis.rst

Returns a RegexTokenizer that splits tokens by whitespace. The example shows how it handles punctuation and hyphens.

```pycon
>>> sst = SpaceSeparatedTokenizer()
>>> [token.text for token in sst("hi there big-time, what's up")]
["hi", "there", "big-time,", "what's", "up"]
```

--------------------------------

### variations() example in Python console

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/lang/morph_en.rst

Shows how to call variations() with the word 'pull' and the resulting set of variations, which may include non-words.

```pycon
>>> variations("pull")
set(['pull', 'pullings', 'pullnesses', 'pullful', 'pullment', 'puller', ... ])
```

--------------------------------

### Enable PrefixPlugin for prefix queries

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/qparser.rst

Shows how to enable prefix queries by removing the WildcardPlugin and adding the PrefixPlugin. The example parses the query "pre*" to produce a prefix query.

```pycon
>>> qp = qparser.QueryParser("content", myschema)
>>> qp.remove_plugin_class(qparser.WildcardPlugin)
>>> qp.add_plugin(qparser.PrefixPlugin())
>>> q = qp.parse("pre*")
```

--------------------------------

### SimpleAnalyzer usage example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/analysis.rst

Composes a RegexTokenizer with a LowercaseFilter. The example shows tokens being lowercased and punctuation removed.

```pycon
>>> ana = SimpleAnalyzer()
>>> [token.text for token in ana("Hello there, this is a TEST")]
["hello", "there", "this", "is", "a", "test"]
```

--------------------------------

### NgramAnalyzer usage example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/analysis.rst

Composes an NgramTokenizer and a LowercaseFilter. The example shows generating 4-character n-grams from the input string.

```pycon
>>> ana = NgramAnalyzer(4)
>>> [token.text for token in ana("hi there")]
["hi t", "i th", " the", "ther", "here"]
```

--------------------------------

### Equivalent range query syntax

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/qparser.rst

Equivalent range query syntax using the standard range notation, corresponding to the GtLtPlugin example above.

```default
a:{100 to] b:[to z] c:[-1.4 to] d:[to mz}
```

--------------------------------

### Search page example with find_page

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/searching.rst

Shows how to use Searcher.find_page() to retrieve a page of results, print page information, iterate over the page's fields, and close the searcher.

```pycon
>>> mysearcher = myindex.searcher()
>>> pagenum = 2
>>> page = mysearcher.find_page(pagenum, myquery)
>>> print("Page %s of %s, results %s to %s of %s" %
...       (pagenum, page.pagecount, page.offset+1,
...        page.offset+page.pagelen, page.total))
>>> for i, fields in enumerate(page):
...   print("%s. %r" % (page.offset + i + 1, fields))
>>> mysearcher.close()
```

--------------------------------

### CommaSeparatedTokenizer example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/analysis.rst

Splits tokens by commas and calls unicode.strip() on each match. The example shows how it handles spaces around commas.

```pycon
>>> cst = CommaSeparatedTokenizer()
>>> [token.text for token in cst("hi there, what's , up")]
["hi there", "what's", "up"]
```

--------------------------------

### iTunes-style search-as-you-type with NgramWordAnalyzer

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/recipes.rst

Sets up a field with NgramWordAnalyzer for search-as-you-type. Disable positions with phrase=False to save space, as phrase searching on N-gram fields is usually not useful.

```python
# For example, to search the "title" field as the user types
analyzer = analysis.NgramWordAnalyzer()
title_field = fields.TEXT(analyzer=analyzer, phrase=False)
schema = fields.Schema(title=title_field)
```

--------------------------------

### Query parser examples with output

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/quickstart.rst

Demonstrates the default query language: terms are joined with AND by default, OR and parentheses group clauses, and prefix queries use an asterisk. The output shows the parsed query structures.

```python
>>> print(parser.parse(u"render shade animate"))
And([Term("content", "render"), Term("content", "shade"), Term("content", "animate")])

>>> print(parser.parse(u"render OR (title:shade keyword:animate)"))
Or([Term("content", "render"), And([Term("title", "shade"), Term("keyword", "animate")])])

>>> print(parser.parse(u"rend*"))
Prefix("content", "rend")
```

--------------------------------

### Get a corrector for a field with Searcher.corrector()

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/spelling.rst

Get a corrector for a specific field using the Searcher.corrector() method. The corrector can then be used to suggest corrections based on the index contents.

```python
corrector = searcher.corrector("content")
```

--------------------------------

### FileStorage.__init__

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/filedb/filestore.rst

Constructor for the FileStorage class, which stores the index as files in a directory on disk.

```APIDOC
## FileStorage(path, supports_mmap=True, readonly=False, debug=False)

### Description
Storage object that stores the index as files in a directory on disk. Prior to version 3, the initializer would raise an IOError if the directory did not exist. As of version 3, the object does not check if the directory exists at initialization. This change is to support using the `FileStorage.create()` method.

### Parameters
- **path** (str) - Required - A path to a directory.
- **supports_mmap** (bool) - Optional - If True (the default), use the `mmap` module to open memory mapped files. You can open the storage object with `supports_mmap=False` to force Whoosh to open files normally instead of with `mmap`.
- **readonly** (bool) - Optional - If `True`, the object will raise an exception if you attempt to create or rename a file.
- **debug** (bool) - Optional - Debug flag.
```

--------------------------------

### FancyAnalyzer usage example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/analysis.rst

Composes a RegexTokenizer with an IntraWordFilter, LowercaseFilter, and StopFilter. The example shows splitting of compound words like 'getInt' and 'get_real' into separate tokens.

```pycon
>>> ana = FancyAnalyzer()
>>> [token.text for token in ana("Should I call getInt or get_real?")]
["should", "call", "getInt", "get", "int", "get_real", "get", "real"]
```

--------------------------------

### Storage.create()

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/filedb/filestore.rst

Creates implementation-specific resources (e.g., a directory for filesystem storage). Returns self to allow chaining.

```APIDOC
## Storage.create()

### Description
Creates any required implementation-specific resources, such as a directory or database tables. Returns `self` to allow chaining.

### Method
create()

### Signature
`Storage.create()`

### Parameters
None

### Returns
Returns `self` (a Storage instance).

```

--------------------------------

### HtmlFormatter usage example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/highlight.rst

Shows how to instantiate HtmlFormatter with custom tag and class names, then call it on text and fragments to produce an HTML excerpt with per-term classes.

```pycon
>>> hf = HtmlFormatter(tagname="span", classname="match", termclass="term")
>>> hf(mytext, myfragments)
"The <span class="match term0">template</span> <span class="match term1">geometry</span> is..."
```

--------------------------------

### StandardAnalyzer usage example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/analysis.rst

Composes a RegexTokenizer with a LowercaseFilter and optional StopFilter. The example shows stop words and short words being removed, leaving only repeated 'testing' tokens.

```pycon
>>> ana = StandardAnalyzer()
>>> [token.text for token in ana("Testing is testing and testing")]
["testing", "testing", "testing"]
```

--------------------------------

### Configure QueryParser plugins and parse a query

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/qparser.rst

Shows how to create a QueryParser with a custom plugin configuration: remove the WildcardPlugin and add a PrefixPlugin, then parse a query. The output is an And group of Term objects.

```pycon
>>> from whoosh import qparser
>>> parser = qparser.QueryParser("content", schema)
>>> parser.remove_plugin_class(qparser.WildcardPlugin)
>>> parser.add_plugin(qparser.PrefixPlugin())
>>> parser.parse(u"hello there")
And([Term("content", u"hello"), Term("content", u"there")])
```

--------------------------------

### NgramFilter example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/ngrams.rst

Breaks individual tokens into N-grams as part of an analysis pipeline. Useful for languages with word separation. The example uses StandardAnalyzer with NgramFilter(minsize=2, maxsize=4).

```python
>>> my_analyzer = StandardAnalyzer() | NgramFilter(minsize=2, maxsize=4)
>>> [token.text for token in my_analyzer(u"rendering shaders")]
[u'ren', u'rend', u'end', u'ende', u'nde', u'nder', u'der', u'deri', u'eri',
u'erin', u'rin', u'ring', u'ing', u'sha', u'shad', u'had', u'hade', u'ade',
u'ader', u'der', u'ders', u'ers']
```

--------------------------------

### Get spelling suggestions with searcher.suggest

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/releases/2_0.rst

Gets spelling suggestions for an individual word using the searcher's suggest method. The limit parameter controls the maximum number of suggestions returned.

```python
suglist = searcher.suggest("content", "werd", limit=3)
```

--------------------------------

### Efficient indexing alternative to Every

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/query.rst

This example shows the recommended approach: add an extra field to the schema and set it during indexing to indicate whether a document has the field. This is more efficient than using Every.

```default
# Add an extra field that indicates whether a document has a path
schema = fields.Schema(path=fields.ID, has_path=fields.ID)

# When indexing, set the "has_path" field based on whether the document
# has anything in the "path" field
writer.add_document(text=text_value1)
writer.add_document(text=text_value2, path=path_value2, has_path="t")
```

--------------------------------

### StemmingAnalyzer usage example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/analysis.rst

Composes a RegexTokenizer with a lower case filter, an optional stop filter, and a stemming filter. The example shows stop words removed and 'testing' stemmed to 'test'.

```pycon
>>> ana = StemmingAnalyzer()
>>> [token.text for token in ana("Testing is testing and testing")]
["test", "test", "test"]
```

--------------------------------

### Configure parser to use Variations

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/stemming.rst

Shows how to initialize a QueryParser with termclass=query.Variations so that individual terms are parsed as Variations queries instead of Term queries.

```python
from whoosh import qparser, query

qp = qparser.QueryParser("content", termclass=query.Variations)
```

--------------------------------

### Create FileStorage with import and chained create

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/filedb/filestore.rst

Creates a FileStorage with an explicit import, then shows the chained alternative that returns the storage instance. The create() method is safe to call multiple times.

```default
from whoosh.filedb.filestore import FileStorage
# Create a storage object
st = FileStorage("indexdir")
# Create any necessary resources
st.create()
```

```default
st = FileStorage("indexdir").create()
```

--------------------------------

### scored_length() example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/searching.rst

Shows that scored_length() returns the number of scored documents, which is equal to or less than the limit keyword argument. The example searches with limit=20 and shows that len(r) may be larger than scored_length().

```pycon
>>> r = mysearcher.search(myquery, limit=20)
>>> len(r)
1246
>>> r.scored_length()
20
```

--------------------------------

### open_file(name, *args, **kwargs)

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/filedb/filestore.rst

Opens a file with the given name in this storage and returns a StructFile instance.

```APIDOC
## open_file(name, *args, **kwargs)

### Description
Opens a file with the given name in this storage.

### Method
open_file

### Parameters
#### Parameters
- **name** (string) - Required - The name for the new file.
- **\*args** - Optional - Additional positional arguments.
- **\*\*kwargs** - Optional - Additional keyword arguments.

### Returns
A `whoosh.filedb.structfile.StructFile` instance.
```

--------------------------------

### SpanCondition: Get spans for 'alfa' in documents containing 'bravo'

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/query.rst

Creates a SpanCondition query to get spans for the term 'alfa' but only in documents that also contain the term 'bravo'. The spans returned are from the first query only.

```default
SpanCondition(Term("text", u"alfa"), Term("text", u"bravo"))
```

--------------------------------

### CharsetTokenizer example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/analysis.rst

Tokenizes and translates text according to a character mapping object, useful for case and accent folding. The example uses the default charset table to convert 'Straße ABC' to lowercase and accent-folded tokens.

```pycon
>>> from whoosh.support.charset import charset_table_to_dict
>>> from whoosh.support.charset import default_charset
>>> charmap = charset_table_to_dict(default_charset)
>>> chtokenizer = CharsetTokenizer(charmap)
>>> [t.text for t in chtokenizer(u'Stra\xdfe ABC')]
[u'strase', u'abc']
```

--------------------------------

### Equivalent explicit AND query

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/querylang.rst

The same as 'render shading modeling' when the default operator is AND.

```none
render AND shading AND modeling
```

--------------------------------

### ReverseTextFilter example

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/analysis.rst

Reverses the text of each token.

```pycon
>>> ana = RegexTokenizer() | ReverseTextFilter()
>>> [token.text for token in ana("hello there")]
["olleh", "ereht"]
```

--------------------------------

### suggest

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/searching.rst

Method to get spelling suggestions for a word.

```APIDOC
## suggest(fieldname, text, limit=5, maxdist=2, prefix=0)

### Description
Returns a sorted list of suggested corrections for a mis-typed word based on the contents of a given field. This is a convenience method; for multiple words, it is more efficient to use a `Corrector` object directly.

### Method
suggest

### Parameters
- **fieldname** (str) - Required - The name of the field to search for suggestions.
- **text** (str) - Required - The mis-typed word to correct.
- **limit** (int) - Optional - Only return up to this many suggestions. Default is 5.
- **maxdist** (int) - Optional - The largest edit distance from the given word to look at. Default is 2.
- **prefix** (int) - Optional - Require suggestions to share a prefix of this length with the given word. Default is 0.

### Returns
A sorted list of suggested corrections.

### Example
```default
>>> searcher.suggest("content", "specail")
["special"]
```
```

--------------------------------

### Open searcher with context manager

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/quickstart.rst

Opens a searcher using a `with` statement to ensure it is automatically closed when done. This is the recommended way to manage searcher resources.

```python
with ix.searcher() as searcher:
    ...
```

--------------------------------

### whoosh.spelling.Corrector.suggest

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/spelling.rst

Method to get spelling suggestions for a word.

```APIDOC
## whoosh.spelling.Corrector.suggest

### Description
Suggests spelling corrections for a given word based on the corrector's word graph. The original word is not included in the suggestions.

### Method
suggest(text, limit=5, maxdist=2, prefix=0)

### Parameters
- **text** (str) - Required - The text to check. This word will not be added to the suggestions, even if it appears in the word graph.
- **limit** (int) - Optional - Only return up to this many suggestions. If there are not enough terms in the field within `maxdist` of the given word, the returned list will be shorter than this number. Default: 5.
- **maxdist** (int) - Optional - The largest edit distance from the given word to look at. Values higher than 2 are not very effective or efficient. Default: 2.
- **prefix** (int) - Optional - Require suggestions to share a prefix of this length with the given word. This is often justifiable since most misspellings do not involve the first letter of the word. Using a prefix dramatically decreases the time it takes to generate the list of words. Default: 0.

### Returns
A list of suggested words (strings).
```

--------------------------------

### Get total and scored hit counts

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/searching.rst

Shows how to get the total number of matching documents in the index with len(results) and the number of scored hits in the Results object with results.scored_length(). The default search limit is 20, so scored_length() is often less than len().

```default
>>> # How many documents in the entire index would have matched?
>>> len(results)
27
>>> # How many scored and sorted documents in this Results object?
>>> # This will often be less than len() if the number of hits was limited
>>> # (the default).
>>> results.scored_length()
10
```

--------------------------------

### leaves()

Source: https://github.com/sygil-dev/whoosh-reloaded/blob/main/docs/source/api/query.rst

Method to get all leaf queries in the query tree.

```APIDOC
## leaves()

### Description
Returns an iterator of all the leaf queries in this query tree as a flat series.

### Method
leaves

### Parameters
None

### Returns
- **iterator** - An iterator of leaf query objects.

```
Tokens:
Raw