<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>collectors module — Whoosh 2.5.7 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '2.5.7',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="top" title="Whoosh 2.5.7 documentation" href="../index.html" />
<link rel="up" title="Whoosh API" href="api.html" />
<link rel="next" title="columns module" href="columns.html" />
<link rel="prev" title="codec.base module" href="codec/base.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="columns.html" title="columns module"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="codec/base.html" title="codec.base module"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Whoosh 2.5.7 documentation</a> »</li>
<li><a href="api.html" accesskey="U">Whoosh API</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="module-whoosh.collectors">
<span id="collectors-module"></span><h1><tt class="docutils literal"><span class="pre">collectors</span></tt> module<a class="headerlink" href="#module-whoosh.collectors" title="Permalink to this headline">¶</a></h1>
<p>This module contains “collector” objects. Collectors provide a way to gather
“raw” results from a <a class="reference internal" href="matching.html#whoosh.matching.Matcher" title="whoosh.matching.Matcher"><tt class="xref py py-class docutils literal"><span class="pre">whoosh.matching.Matcher</span></tt></a> object, implement
sorting, filtering, collation, etc., and produce a
<a class="reference internal" href="searching.html#whoosh.searching.Results" title="whoosh.searching.Results"><tt class="xref py py-class docutils literal"><span class="pre">whoosh.searching.Results</span></tt></a> object.</p>
<p>The basic collectors are:</p>
<dl class="docutils">
<dt>TopCollector</dt>
<dd>Returns the top N matching results sorted by score, using block-quality
optimizations to skip blocks of documents that can’t contribute to the top
N. The <a class="reference internal" href="searching.html#whoosh.searching.Searcher.search" title="whoosh.searching.Searcher.search"><tt class="xref py py-meth docutils literal"><span class="pre">whoosh.searching.Searcher.search()</span></tt></a> method uses this type of
collector by default or when you specify a <tt class="docutils literal"><span class="pre">limit</span></tt>.</dd>
<dt>UnlimitedCollector</dt>
<dd>Returns all matching results sorted by score. The
<a class="reference internal" href="searching.html#whoosh.searching.Searcher.search" title="whoosh.searching.Searcher.search"><tt class="xref py py-meth docutils literal"><span class="pre">whoosh.searching.Searcher.search()</span></tt></a> method uses this type of collector
when you specify <tt class="docutils literal"><span class="pre">limit=None</span></tt> or you specify a limit equal to or greater
than the number of documents in the searcher.</dd>
<dt>SortingCollector</dt>
<dd>Returns all matching results sorted by a <tt class="xref py py-class docutils literal"><span class="pre">whoosh.sorting.Facet</span></tt>
object. The <a class="reference internal" href="searching.html#whoosh.searching.Searcher.search" title="whoosh.searching.Searcher.search"><tt class="xref py py-meth docutils literal"><span class="pre">whoosh.searching.Searcher.search()</span></tt></a> method uses this type
of collector when you use the <tt class="docutils literal"><span class="pre">sortedby</span></tt> parameter.</dd>
</dl>
<p>Here’s an example of a simple collector that instead of remembering the matched
documents just counts up the number of matches:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">CountingCollector</span><span class="p">(</span><span class="n">Collector</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">prepare</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">top_searcher</span><span class="p">,</span> <span class="n">q</span><span class="p">,</span> <span class="n">context</span><span class="p">):</span>
<span class="c"># Always call super method in prepare</span>
<span class="n">Collector</span><span class="o">.</span><span class="n">prepare</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">top_searcher</span><span class="p">,</span> <span class="n">q</span><span class="p">,</span> <span class="n">context</span><span class="p">)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">count</span> <span class="o">=</span> <span class="mi">0</span>
<span class="k">def</span> <span class="nf">collect</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">sub_docnum</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">count</span> <span class="o">+=</span> <span class="mi">1</span>
<span class="n">c</span> <span class="o">=</span> <span class="n">CountingCollector</span><span class="p">()</span>
<span class="n">mysearcher</span><span class="o">.</span><span class="n">search_with_collector</span><span class="p">(</span><span class="n">myquery</span><span class="p">,</span> <span class="n">c</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="n">c</span><span class="o">.</span><span class="n">count</span><span class="p">)</span>
</pre></div>
</div>
<p>There are also several wrapping collectors that extend or modify the
functionality of other collectors. The meth:<cite>whoosh.searching.Searcher.search</cite>
method uses many of these when you specify various parameters.</p>
<p>NOTE: collectors are not designed to be reentrant or thread-safe. It is
generally a good idea to create a new collector for each search.</p>
<div class="section" id="base-classes">
<h2>Base classes<a class="headerlink" href="#base-classes" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="whoosh.collectors.Collector">
<em class="property">class </em><tt class="descclassname">whoosh.collectors.</tt><tt class="descname">Collector</tt><a class="headerlink" href="#whoosh.collectors.Collector" title="Permalink to this definition">¶</a></dt>
<dd><p>Base class for collectors.</p>
<dl class="method">
<dt id="whoosh.collectors.Collector.all_ids">
<tt class="descname">all_ids</tt><big>(</big><big>)</big><a class="headerlink" href="#whoosh.collectors.Collector.all_ids" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a sequence of docnums matched in this collector. (Only valid
after the collector is run.)</p>
<p>The default implementation is based on the docset. If a collector does
not maintain the docset, it will need to override this method.</p>
</dd></dl>
<dl class="method">
<dt id="whoosh.collectors.Collector.collect">
<tt class="descname">collect</tt><big>(</big><em>sub_docnum</em><big>)</big><a class="headerlink" href="#whoosh.collectors.Collector.collect" title="Permalink to this definition">¶</a></dt>
<dd><p>This method is called for every matched document. It should do the
work of adding a matched document to the results, and it should return
an object to use as a “sorting key” for the given document (such as the
document’s score, a key generated by a facet, or just None). Subclasses
must implement this method.</p>
<p>If you want the score for the current document, use
<tt class="docutils literal"><span class="pre">self.matcher.score()</span></tt>.</p>
<p>Overriding methods should add the current document offset
(<tt class="docutils literal"><span class="pre">self.offset</span></tt>) to the <tt class="docutils literal"><span class="pre">sub_docnum</span></tt> to get the top-level document
number for the matching document to add to results.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>sub_docnum</strong> – the document number of the current match within the
current sub-searcher. You must add <tt class="docutils literal"><span class="pre">self.offset</span></tt> to this number
to get the document’s top-level document number.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="whoosh.collectors.Collector.collect_matches">
<tt class="descname">collect_matches</tt><big>(</big><big>)</big><a class="headerlink" href="#whoosh.collectors.Collector.collect_matches" title="Permalink to this definition">¶</a></dt>
<dd><p>This method calls <a class="reference internal" href="#whoosh.collectors.Collector.matches" title="whoosh.collectors.Collector.matches"><tt class="xref py py-meth docutils literal"><span class="pre">Collector.matches()</span></tt></a> and then for each
matched document calls <a class="reference internal" href="#whoosh.collectors.Collector.collect" title="whoosh.collectors.Collector.collect"><tt class="xref py py-meth docutils literal"><span class="pre">Collector.collect()</span></tt></a>. Sub-classes that
want to intervene between finding matches and adding them to the
collection (for example, to filter out certain documents) can override
this method.</p>
</dd></dl>
<dl class="method">
<dt id="whoosh.collectors.Collector.computes_count">
<tt class="descname">computes_count</tt><big>(</big><big>)</big><a class="headerlink" href="#whoosh.collectors.Collector.computes_count" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns True if the collector naturally computes the exact number of
matching documents. Collectors that use block optimizations will return
False since they might skip blocks containing matching documents.</p>
<p>Note that if this method returns False you can still call <a class="reference internal" href="#whoosh.collectors.Collector.count" title="whoosh.collectors.Collector.count"><tt class="xref py py-meth docutils literal"><span class="pre">count()</span></tt></a>,
but it means that method might have to do more work to calculate the
number of matching documents.</p>
</dd></dl>
<dl class="method">
<dt id="whoosh.collectors.Collector.count">
<tt class="descname">count</tt><big>(</big><big>)</big><a class="headerlink" href="#whoosh.collectors.Collector.count" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the total number of documents matched in this collector.
(Only valid after the collector is run.)</p>
<p>The default implementation is based on the docset. If a collector does
not maintain the docset, it will need to override this method.</p>
</dd></dl>
<dl class="method">
<dt id="whoosh.collectors.Collector.finish">
<tt class="descname">finish</tt><big>(</big><big>)</big><a class="headerlink" href="#whoosh.collectors.Collector.finish" title="Permalink to this definition">¶</a></dt>
<dd><p>This method is called after a search.</p>
<p>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:</p>
<dl class="docutils">
<dt>self.runtime</dt>
<dd>The time (in seconds) the search took.</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="whoosh.collectors.Collector.matches">
<tt class="descname">matches</tt><big>(</big><big>)</big><a class="headerlink" href="#whoosh.collectors.Collector.matches" title="Permalink to this definition">¶</a></dt>
<dd><p>Yields a series of relative document numbers for matches
in the current subsearcher.</p>
</dd></dl>
<dl class="method">
<dt id="whoosh.collectors.Collector.prepare">
<tt class="descname">prepare</tt><big>(</big><em>top_searcher</em>, <em>q</em>, <em>context</em><big>)</big><a class="headerlink" href="#whoosh.collectors.Collector.prepare" title="Permalink to this definition">¶</a></dt>
<dd><p>This method is called before a search.</p>
<p>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:</p>
<dl class="docutils">
<dt>self.top_searcher</dt>
<dd>The top-level searcher.</dd>
<dt>self.q</dt>
<dd>The query object</dd>
<dt>self.context</dt>
<dd><tt class="docutils literal"><span class="pre">context.needs_current</span></tt> controls whether a wrapping collector
requires that this collector’s matcher be in a valid state at every
call to <tt class="docutils literal"><span class="pre">collect()</span></tt>. If this is <tt class="docutils literal"><span class="pre">False</span></tt>, the collector is free
to use faster methods that don’t necessarily keep the matcher
updated, such as <tt class="docutils literal"><span class="pre">matcher.all_ids()</span></tt>.</dd>
</dl>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>top_searcher</strong> – the top-level <a class="reference internal" href="searching.html#whoosh.searching.Searcher" title="whoosh.searching.Searcher"><tt class="xref py py-class docutils literal"><span class="pre">whoosh.searching.Searcher</span></tt></a>
object.</li>
<li><strong>q</strong> – the <a class="reference internal" href="query.html#whoosh.query.Query" title="whoosh.query.Query"><tt class="xref py py-class docutils literal"><span class="pre">whoosh.query.Query</span></tt></a> object being searched for.</li>
<li><strong>context</strong> – a <tt class="xref py py-class docutils literal"><span class="pre">whoosh.searching.SearchContext</span></tt> object
containing information about the search.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="whoosh.collectors.Collector.remove">
<tt class="descname">remove</tt><big>(</big><em>global_docnum</em><big>)</big><a class="headerlink" href="#whoosh.collectors.Collector.remove" title="Permalink to this definition">¶</a></dt>
<dd><p>Removes a document from the collector. Not that this method uses the
global document number as opposed to <a class="reference internal" href="#whoosh.collectors.Collector.collect" title="whoosh.collectors.Collector.collect"><tt class="xref py py-meth docutils literal"><span class="pre">Collector.collect()</span></tt></a> which
takes a segment-relative docnum.</p>
</dd></dl>
<dl class="method">
<dt id="whoosh.collectors.Collector.results">
<tt class="descname">results</tt><big>(</big><big>)</big><a class="headerlink" href="#whoosh.collectors.Collector.results" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a <a class="reference internal" href="searching.html#whoosh.searching.Results" title="whoosh.searching.Results"><tt class="xref py py-class docutils literal"><span class="pre">Results</span></tt></a> object containing the
results of the search. Subclasses must implement this method</p>
</dd></dl>
<dl class="method">
<dt id="whoosh.collectors.Collector.set_subsearcher">
<tt class="descname">set_subsearcher</tt><big>(</big><em>subsearcher</em>, <em>offset</em><big>)</big><a class="headerlink" href="#whoosh.collectors.Collector.set_subsearcher" title="Permalink to this definition">¶</a></dt>
<dd><p>This method is called each time the collector starts on a new
sub-searcher.</p>
<p>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:</p>
<dl class="docutils">
<dt>self.subsearcher</dt>
<dd>The current sub-searcher. If the top-level searcher is atomic, this
is the same as the top-level searcher.</dd>
<dt>self.offset</dt>
<dd>The document number offset of the current searcher. You must add
this number to the document number passed to
<a class="reference internal" href="#whoosh.collectors.Collector.collect" title="whoosh.collectors.Collector.collect"><tt class="xref py py-meth docutils literal"><span class="pre">Collector.collect()</span></tt></a> to get the top-level document number
for use in results.</dd>
<dt>self.matcher</dt>
<dd>A <a class="reference internal" href="matching.html#whoosh.matching.Matcher" title="whoosh.matching.Matcher"><tt class="xref py py-class docutils literal"><span class="pre">whoosh.matching.Matcher</span></tt></a> object representing the matches
for the query in the current sub-searcher.</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="whoosh.collectors.Collector.sort_key">
<tt class="descname">sort_key</tt><big>(</big><em>sub_docnum</em><big>)</big><a class="headerlink" href="#whoosh.collectors.Collector.sort_key" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a sorting key for the current match. This should return the
same value returned by <a class="reference internal" href="#whoosh.collectors.Collector.collect" title="whoosh.collectors.Collector.collect"><tt class="xref py py-meth docutils literal"><span class="pre">Collector.collect()</span></tt></a>, but without the side
effect of adding the current document to the results.</p>
<p>If the collector has been prepared with <tt class="docutils literal"><span class="pre">context.needs_current=True</span></tt>,
this method can use <tt class="docutils literal"><span class="pre">self.matcher</span></tt> to get information, for example
the score. Otherwise, it should only use the provided <tt class="docutils literal"><span class="pre">sub_docnum</span></tt>,
since the matcher may be in an inconsistent state.</p>
<p>Subclasses must implement this method.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="whoosh.collectors.ScoredCollector">
<em class="property">class </em><tt class="descclassname">whoosh.collectors.</tt><tt class="descname">ScoredCollector</tt><big>(</big><em>replace=10</em><big>)</big><a class="headerlink" href="#whoosh.collectors.ScoredCollector" title="Permalink to this definition">¶</a></dt>
<dd><p>Base class for collectors that sort the results based on document score.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>replace</strong> – Number of matches between attempts to replace the
matcher with a more efficient version.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="class">
<dt id="whoosh.collectors.WrappingCollector">
<em class="property">class </em><tt class="descclassname">whoosh.collectors.</tt><tt class="descname">WrappingCollector</tt><big>(</big><em>child</em><big>)</big><a class="headerlink" href="#whoosh.collectors.WrappingCollector" title="Permalink to this definition">¶</a></dt>
<dd><p>Base class for collectors that wrap other collectors.</p>
</dd></dl>
</div>
<div class="section" id="basic-collectors">
<h2>Basic collectors<a class="headerlink" href="#basic-collectors" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="whoosh.collectors.TopCollector">
<em class="property">class </em><tt class="descclassname">whoosh.collectors.</tt><tt class="descname">TopCollector</tt><big>(</big><em>limit=10</em>, <em>usequality=True</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#whoosh.collectors.TopCollector" title="Permalink to this definition">¶</a></dt>
<dd><p>A collector that only returns the top “N” scored results.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>limit</strong> – the maximum number of results to return.</li>
<li><strong>usequality</strong> – whether to use block-quality optimizations. This may
be useful for debugging.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="class">
<dt id="whoosh.collectors.UnlimitedCollector">
<em class="property">class </em><tt class="descclassname">whoosh.collectors.</tt><tt class="descname">UnlimitedCollector</tt><big>(</big><em>reverse=False</em><big>)</big><a class="headerlink" href="#whoosh.collectors.UnlimitedCollector" title="Permalink to this definition">¶</a></dt>
<dd><p>A collector that returns <strong>all</strong> scored results.</p>
</dd></dl>
<dl class="class">
<dt id="whoosh.collectors.SortingCollector">
<em class="property">class </em><tt class="descclassname">whoosh.collectors.</tt><tt class="descname">SortingCollector</tt><big>(</big><em>sortedby</em>, <em>limit=10</em>, <em>reverse=False</em><big>)</big><a class="headerlink" href="#whoosh.collectors.SortingCollector" title="Permalink to this definition">¶</a></dt>
<dd><p>A collector that returns results sorted by a given
<tt class="xref py py-class docutils literal"><span class="pre">whoosh.sorting.Facet</span></tt> object. See <a class="reference internal" href="../facets.html"><em>Sorting and faceting</em></a> for more
information.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>sortedby</strong> – see <a class="reference internal" href="../facets.html"><em>Sorting and faceting</em></a>.</li>
<li><strong>reverse</strong> – If True, reverse the overall results. Note that you
can reverse individual facets in a multi-facet sort key as well.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
</div>
<div class="section" id="wrappers">
<h2>Wrappers<a class="headerlink" href="#wrappers" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="whoosh.collectors.FilterCollector">
<em class="property">class </em><tt class="descclassname">whoosh.collectors.</tt><tt class="descname">FilterCollector</tt><big>(</big><em>child</em>, <em>allow=None</em>, <em>restrict=None</em><big>)</big><a class="headerlink" href="#whoosh.collectors.FilterCollector" title="Permalink to this definition">¶</a></dt>
<dd><p>A collector that lets you allow and/or restrict certain document numbers
in the results:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">uc</span> <span class="o">=</span> <span class="n">collectors</span><span class="o">.</span><span class="n">UnlimitedCollector</span><span class="p">()</span>
<span class="n">ins</span> <span class="o">=</span> <span class="n">query</span><span class="o">.</span><span class="n">Term</span><span class="p">(</span><span class="s">"chapter"</span><span class="p">,</span> <span class="s">"rendering"</span><span class="p">)</span>
<span class="n">outs</span> <span class="o">=</span> <span class="n">query</span><span class="o">.</span><span class="n">Term</span><span class="p">(</span><span class="s">"status"</span><span class="p">,</span> <span class="s">"restricted"</span><span class="p">)</span>
<span class="n">fc</span> <span class="o">=</span> <span class="n">FilterCollector</span><span class="p">(</span><span class="n">uc</span><span class="p">,</span> <span class="n">allow</span><span class="o">=</span><span class="n">ins</span><span class="p">,</span> <span class="n">restrict</span><span class="o">=</span><span class="n">outs</span><span class="p">)</span>
<span class="n">mysearcher</span><span class="o">.</span><span class="n">search_with_collector</span><span class="p">(</span><span class="n">myquery</span><span class="p">,</span> <span class="n">fc</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="n">fc</span><span class="o">.</span><span class="n">results</span><span class="p">())</span>
</pre></div>
</div>
<p>This collector discards a document if:</p>
<ul class="simple">
<li>The allowed set is not None and a document number is not in the set, or</li>
<li>The restrict set is not None and a document number is in the set.</li>
</ul>
<p>(So, if the same document number is in both sets, that document will be
discarded.)</p>
<p>If you have a reference to the collector, you can use
<tt class="docutils literal"><span class="pre">FilterCollector.filtered_count</span></tt> to get the number of matching documents
filtered out of the results by the collector.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>child</strong> – the collector to wrap.</li>
<li><strong>allow</strong> – a query, Results object, or set-like object containing
docnument numbers that are allowed in the results, or None (meaning
everything is allowed).</li>
<li><strong>restrict</strong> – a query, Results object, or set-like object containing
document numbers to disallow from the results, or None (meaning
nothing is disallowed).</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="class">
<dt id="whoosh.collectors.FacetCollector">
<em class="property">class </em><tt class="descclassname">whoosh.collectors.</tt><tt class="descname">FacetCollector</tt><big>(</big><em>child</em>, <em>groupedby</em>, <em>maptype=None</em><big>)</big><a class="headerlink" href="#whoosh.collectors.FacetCollector" title="Permalink to this definition">¶</a></dt>
<dd><p>A collector that creates groups of documents based on
<tt class="xref py py-class docutils literal"><span class="pre">whoosh.sorting.Facet</span></tt> objects. See <a class="reference internal" href="../facets.html"><em>Sorting and faceting</em></a> for more
information.</p>
<p>This collector is used if you specify a <tt class="docutils literal"><span class="pre">groupedby</span></tt> parameter in the
<a class="reference internal" href="searching.html#whoosh.searching.Searcher.search" title="whoosh.searching.Searcher.search"><tt class="xref py py-meth docutils literal"><span class="pre">whoosh.searching.Searcher.search()</span></tt></a> method. You can use the
<a class="reference internal" href="searching.html#whoosh.searching.Results.groups" title="whoosh.searching.Results.groups"><tt class="xref py py-meth docutils literal"><span class="pre">whoosh.searching.Results.groups()</span></tt></a> method to access the facet groups.</p>
<p>If you have a reference to the collector can also use
<tt class="docutils literal"><span class="pre">FacetedCollector.facetmaps</span></tt> to access the groups directly:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">uc</span> <span class="o">=</span> <span class="n">collectors</span><span class="o">.</span><span class="n">UnlimitedCollector</span><span class="p">()</span>
<span class="n">fc</span> <span class="o">=</span> <span class="n">FacetedCollector</span><span class="p">(</span><span class="n">uc</span><span class="p">,</span> <span class="n">sorting</span><span class="o">.</span><span class="n">FieldFacet</span><span class="p">(</span><span class="s">"category"</span><span class="p">))</span>
<span class="n">mysearcher</span><span class="o">.</span><span class="n">search_with_collector</span><span class="p">(</span><span class="n">myquery</span><span class="p">,</span> <span class="n">fc</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="n">fc</span><span class="o">.</span><span class="n">facetmaps</span><span class="p">)</span>
</pre></div>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>groupedby</strong> – see <a class="reference internal" href="../facets.html"><em>Sorting and faceting</em></a>.</li>
<li><strong>maptype</strong> – a <a class="reference internal" href="sorting.html#whoosh.sorting.FacetMap" title="whoosh.sorting.FacetMap"><tt class="xref py py-class docutils literal"><span class="pre">whoosh.sorting.FacetMap</span></tt></a> type to use for any
facets that don’t specify their own.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="class">
<dt id="whoosh.collectors.CollapseCollector">
<em class="property">class </em><tt class="descclassname">whoosh.collectors.</tt><tt class="descname">CollapseCollector</tt><big>(</big><em>child</em>, <em>keyfacet</em>, <em>limit=1</em>, <em>order=None</em><big>)</big><a class="headerlink" href="#whoosh.collectors.CollapseCollector" title="Permalink to this definition">¶</a></dt>
<dd><p>A collector that collapses results based on a facet. That is, it
eliminates all but the top N results that share the same facet key.
Documents with an empty key for the facet are never eliminated.</p>
<p>The “top” results within each group is determined by the result ordering
(e.g. highest score in a scored search) or an optional second “ordering”
facet.</p>
<p>If you have a reference to the collector you can use
<tt class="docutils literal"><span class="pre">CollapseCollector.collapsed_counts</span></tt> to access the number of documents
eliminated based on each key:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">tc</span> <span class="o">=</span> <span class="n">TopCollector</span><span class="p">(</span><span class="n">limit</span><span class="o">=</span><span class="mi">20</span><span class="p">)</span>
<span class="n">cc</span> <span class="o">=</span> <span class="n">CollapseCollector</span><span class="p">(</span><span class="n">tc</span><span class="p">,</span> <span class="s">"group"</span><span class="p">,</span> <span class="n">limit</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
<span class="n">mysearcher</span><span class="o">.</span><span class="n">search_with_collector</span><span class="p">(</span><span class="n">myquery</span><span class="p">,</span> <span class="n">cc</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="n">cc</span><span class="o">.</span><span class="n">collapsed_counts</span><span class="p">)</span>
</pre></div>
</div>
<p>See <a class="reference internal" href="../searching.html#collapsing"><em>Collapsing results</em></a> for more information.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>child</strong> – the collector to wrap.</li>
<li><strong>keyfacet</strong> – a <tt class="xref py py-class docutils literal"><span class="pre">whoosh.sorting.Facet</span></tt> to use for collapsing.
All but the top N documents that share a key will be eliminated
from the results.</li>
<li><strong>limit</strong> – the maximum number of documents to keep for each key.</li>
<li><strong>order</strong> – an optional <tt class="xref py py-class docutils literal"><span class="pre">whoosh.sorting.Facet</span></tt> to use
to determine the “top” document(s) to keep when collapsing. The
default (<tt class="docutils literal"><span class="pre">orderfaceet=None</span></tt>) uses the results order (e.g. the
highest score in a scored search).</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="class">
<dt id="whoosh.collectors.TimeLimitCollector">
<em class="property">class </em><tt class="descclassname">whoosh.collectors.</tt><tt class="descname">TimeLimitCollector</tt><big>(</big><em>child</em>, <em>timelimit</em>, <em>greedy=False</em>, <em>use_alarm=True</em><big>)</big><a class="headerlink" href="#whoosh.collectors.TimeLimitCollector" title="Permalink to this definition">¶</a></dt>
<dd><p>A collector that raises a <tt class="xref py py-class docutils literal"><span class="pre">TimeLimit</span></tt> exception if the search
does not complete within a certain number of seconds:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">uc</span> <span class="o">=</span> <span class="n">collectors</span><span class="o">.</span><span class="n">UnlimitedCollector</span><span class="p">()</span>
<span class="n">tlc</span> <span class="o">=</span> <span class="n">TimeLimitedCollector</span><span class="p">(</span><span class="n">uc</span><span class="p">,</span> <span class="n">timelimit</span><span class="o">=</span><span class="mf">5.8</span><span class="p">)</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">mysearcher</span><span class="o">.</span><span class="n">search_with_collector</span><span class="p">(</span><span class="n">myquery</span><span class="p">,</span> <span class="n">tlc</span><span class="p">)</span>
<span class="k">except</span> <span class="n">collectors</span><span class="o">.</span><span class="n">TimeLimit</span><span class="p">:</span>
<span class="k">print</span><span class="p">(</span><span class="s">"The search ran out of time!"</span><span class="p">)</span>
<span class="c"># We can still get partial results from the collector</span>
<span class="k">print</span><span class="p">(</span><span class="n">tlc</span><span class="o">.</span><span class="n">results</span><span class="p">())</span>
</pre></div>
</div>
<p>IMPORTANT: On Unix systems (systems where signal.SIGALRM is defined), the
code uses signals to stop searching immediately when the time limit is
reached. On Windows, the OS does not support this functionality, so the
search only checks the time between each found document, so if a matcher
is slow the search could exceed the time limit.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>child</strong> – the collector to wrap.</li>
<li><strong>timelimit</strong> – the maximum amount of time (in seconds) to
allow for searching. If the search takes longer than this, it will
raise a <tt class="docutils literal"><span class="pre">TimeLimit</span></tt> exception.</li>
<li><strong>greedy</strong> – if <tt class="docutils literal"><span class="pre">True</span></tt>, the collector will finish adding the most
recent hit before raising the <tt class="docutils literal"><span class="pre">TimeLimit</span></tt> exception.</li>
<li><strong>use_alarm</strong> – if <tt class="docutils literal"><span class="pre">True</span></tt> (the default), the collector will try to
use signal.SIGALRM (on UNIX).</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="class">
<dt id="whoosh.collectors.TermsCollector">
<em class="property">class </em><tt class="descclassname">whoosh.collectors.</tt><tt class="descname">TermsCollector</tt><big>(</big><em>child</em>, <em>settype=<type 'set'></em><big>)</big><a class="headerlink" href="#whoosh.collectors.TermsCollector" title="Permalink to this definition">¶</a></dt>
<dd><p>A collector that remembers which terms appeared in which terms appeared
in each matched document.</p>
<p>This collector is used if you specify <tt class="docutils literal"><span class="pre">terms=True</span></tt> in the
<a class="reference internal" href="searching.html#whoosh.searching.Searcher.search" title="whoosh.searching.Searcher.search"><tt class="xref py py-meth docutils literal"><span class="pre">whoosh.searching.Searcher.search()</span></tt></a> method.</p>
<p>If you have a reference to the collector can also use
<tt class="docutils literal"><span class="pre">TermsCollector.termslist</span></tt> to access the term lists directly:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">uc</span> <span class="o">=</span> <span class="n">collectors</span><span class="o">.</span><span class="n">UnlimitedCollector</span><span class="p">()</span>
<span class="n">tc</span> <span class="o">=</span> <span class="n">TermsCollector</span><span class="p">(</span><span class="n">uc</span><span class="p">)</span>
<span class="n">mysearcher</span><span class="o">.</span><span class="n">search_with_collector</span><span class="p">(</span><span class="n">myquery</span><span class="p">,</span> <span class="n">tc</span><span class="p">)</span>
<span class="c"># tc.termdocs is a dictionary mapping (fieldname, text) tuples to</span>
<span class="c"># sets of document numbers</span>
<span class="k">print</span><span class="p">(</span><span class="n">tc</span><span class="o">.</span><span class="n">termdocs</span><span class="p">)</span>
<span class="c"># tc.docterms is a dictionary mapping docnums to lists of</span>
<span class="c"># (fieldname, text) tuples</span>
<span class="k">print</span><span class="p">(</span><span class="n">tc</span><span class="o">.</span><span class="n">docterms</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#"><tt class="docutils literal"><span class="pre">collectors</span></tt> module</a><ul>
<li><a class="reference internal" href="#base-classes">Base classes</a></li>
<li><a class="reference internal" href="#basic-collectors">Basic collectors</a></li>
<li><a class="reference internal" href="#wrappers">Wrappers</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="codec/base.html"
title="previous chapter"><tt class="docutils literal"><span class="pre">codec.base</span></tt> module</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="columns.html"
title="next chapter"><tt class="docutils literal"><span class="pre">columns</span></tt> module</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/api/collectors.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="columns.html" title="columns module"
>next</a> |</li>
<li class="right" >
<a href="codec/base.html" title="codec.base module"
>previous</a> |</li>
<li><a href="../index.html">Whoosh 2.5.7 documentation</a> »</li>
<li><a href="api.html" >Whoosh API</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2007-2012 Matt Chaput.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
