Skip to main content

Searching API

Execute queries and retrieve results.

Searcher​

class whoosh.searching.Searcher

The Searcher is the primary interface for reading from the index.

Methods​

results = searcher.search(query, limit=10, **kwargs)

Execute a query and return Results.

Args:

  • query: The query to run.
  • limit (int): Maximum number of results. Use None for all results.

Returns:

  • Results: A Results object.

search_page()​

results = searcher.search_page(query, pagenum, pagelen=10)

Get a page of results.

search_with_collector()​

searcher.search_with_collector(query, collector)

Advanced search with custom collector.

find()​

results = searcher.find("field", "text")

Convenience method to search a single field.

documents()​

docs = list(searcher.documents(fieldname=value))

Get stored documents matching a term.

document()​

doc = searcher.document(fieldname=value)

Get a single stored document.

lexicon()​

terms = list(searcher.lexicon("fieldname"))

List all terms in a field.

all_stored_fields()​

for fields in searcher.all_stored_fields():
    print(fields)

Iterate over all stored fields.

all_features()​

with searcher.all_features() as features:
    facets = features.facet(facet)

Get facet counts across all documents.

Results​

class whoosh.searching.Results

List-like container for matched documents.

Methods​

__len__()​

total = len(results)

Total matching documents (may recount).

scored_length()​

scored = results.scored_length()

Number of scored/sorted documents in this results object.

__getitem__()​

hit = results[0]
hits = results[0:10]

Get a hit by index or slice.

has_matched_terms()​

if results.has_matched_terms():
    print(results.matched_terms())

Check if matched terms were collected.

iter_matched_terms()​

Iterate over (docnum, term) pairs.

upgrade()​

Move docs from another Results to top.

extend()​

Append docs from another Results.

upgrade_and_extend()​

Upgrade docs and append rest.

filtered_count​

Number of documents filtered out.

collapsed_counts​

Dict of collapse keys to filtered counts.

Hit​

class whoosh.searching.Hit

A single matched document.

Attributes​

  • hit["fieldname"]: Stored field value
  • hit.score: Relevance score
  • hit.docnum: Internal document number

Methods​

highlights()​

snippets = hit.highlights("content", top=3)

Get highlighted snippets.

matched_terms()​

terms = hit.matched_terms()

Get terms that matched (if terms=True).

Highlight​

from whoosh.highlight import highlight, Fragment

snippets = hit.highlights(
    "content",
    top=3,
    fragmenter=None,
    formatter=None
)

Collectors​

from whoosh.collectors import Collector, FacetCollector, TimeLimitCollector

Sorting and Facets​

from whoosh import sorting

facet = sorting.FieldFacet("category")
results = searcher.search(query, sortedby="date")