<!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>sorting 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="spelling module" href="spelling.html" />
<link rel="prev" title="searching module" href="searching.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="spelling.html" title="spelling module"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="searching.html" title="searching 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.sorting">
<span id="sorting-module"></span><h1><tt class="docutils literal"><span class="pre">sorting</span></tt> module<a class="headerlink" href="#module-whoosh.sorting" title="Permalink to this headline">¶</a></h1>
<div class="section" id="base-types">
<h2>Base types<a class="headerlink" href="#base-types" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="whoosh.sorting.FacetType">
<em class="property">class </em><tt class="descclassname">whoosh.sorting.</tt><tt class="descname">FacetType</tt><a class="headerlink" href="#whoosh.sorting.FacetType" title="Permalink to this definition">¶</a></dt>
<dd><p>Base class for “facets”, aspects that can be sorted/faceted.</p>
<dl class="method">
<dt id="whoosh.sorting.FacetType.categorizer">
<tt class="descname">categorizer</tt><big>(</big><em>global_searcher</em><big>)</big><a class="headerlink" href="#whoosh.sorting.FacetType.categorizer" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a <a class="reference internal" href="#whoosh.sorting.Categorizer" title="whoosh.sorting.Categorizer"><tt class="xref py py-class docutils literal"><span class="pre">Categorizer</span></tt></a> corresponding to this facet.</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>global_searcher</strong> – A parent searcher. You can use this searcher if
you need global document ID references.</td>
</tr>
</tbody>
</table>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="whoosh.sorting.Categorizer">
<em class="property">class </em><tt class="descclassname">whoosh.sorting.</tt><tt class="descname">Categorizer</tt><a class="headerlink" href="#whoosh.sorting.Categorizer" title="Permalink to this definition">¶</a></dt>
<dd><p>Base class for categorizer objects which compute a key value for a
document based on certain criteria, for use in sorting/faceting.</p>
<p>Categorizers are created by FacetType objects through the
<a class="reference internal" href="#whoosh.sorting.FacetType.categorizer" title="whoosh.sorting.FacetType.categorizer"><tt class="xref py py-meth docutils literal"><span class="pre">FacetType.categorizer()</span></tt></a> method. The
<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 passed to the <tt class="docutils literal"><span class="pre">categorizer</span></tt>
method may be a composite searcher (that is, wrapping a multi-reader), but
categorizers are always run <strong>per-segment</strong>, with segment-relative document
numbers.</p>
<p>The collector will call a categorizer’s <tt class="docutils literal"><span class="pre">set_searcher</span></tt> method as it
searches each segment to let the cateogorizer set up whatever segment-
specific data it needs.</p>
<p><tt class="docutils literal"><span class="pre">Collector.allow_overlap</span></tt> should be <tt class="docutils literal"><span class="pre">True</span></tt> if the caller can use the
<tt class="docutils literal"><span class="pre">keys_for</span></tt> method instead of <tt class="docutils literal"><span class="pre">key_for</span></tt> to group documents into
potentially overlapping groups. The default is <tt class="docutils literal"><span class="pre">False</span></tt>.</p>
<p>If a categorizer subclass can categorize the document using only the
document number, it should set <tt class="docutils literal"><span class="pre">Collector.needs_current</span></tt> to <tt class="docutils literal"><span class="pre">False</span></tt>
(this is the default) and NOT USE the given matcher in the <tt class="docutils literal"><span class="pre">key_for</span></tt> or
<tt class="docutils literal"><span class="pre">keys_for</span></tt> methods, since in that case <tt class="docutils literal"><span class="pre">segment_docnum</span></tt> is not
guaranteed to be consistent with the given matcher. If a categorizer
subclass needs to access information on the matcher, it should set
<tt class="docutils literal"><span class="pre">needs_current</span></tt> to <tt class="docutils literal"><span class="pre">True</span></tt>. This will prevent the caller from using
optimizations that might leave the matcher in an inconsistent state.</p>
<dl class="method">
<dt id="whoosh.sorting.Categorizer.key_for">
<tt class="descname">key_for</tt><big>(</big><em>matcher</em>, <em>segment_docnum</em><big>)</big><a class="headerlink" href="#whoosh.sorting.Categorizer.key_for" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a key for the current match.</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>matcher</strong> – 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. If
<tt class="docutils literal"><span class="pre">self.needs_current</span></tt> is <tt class="docutils literal"><span class="pre">False</span></tt>, DO NOT use this object,
since it may be inconsistent. Use the given <tt class="docutils literal"><span class="pre">segment_docnum</span></tt>
instead.</li>
<li><strong>segment_docnum</strong> – the segment-relative document number of the
current match.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="whoosh.sorting.Categorizer.key_to_name">
<tt class="descname">key_to_name</tt><big>(</big><em>key</em><big>)</big><a class="headerlink" href="#whoosh.sorting.Categorizer.key_to_name" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a representation of the key to be used as a dictionary key
in faceting. For example, the sorting key for date fields is a large
integer; this method translates it into a <tt class="docutils literal"><span class="pre">datetime</span></tt> object to make
the groupings clearer.</p>
</dd></dl>
<dl class="method">
<dt id="whoosh.sorting.Categorizer.keys_for">
<tt class="descname">keys_for</tt><big>(</big><em>matcher</em>, <em>segment_docnum</em><big>)</big><a class="headerlink" href="#whoosh.sorting.Categorizer.keys_for" title="Permalink to this definition">¶</a></dt>
<dd><p>Yields a series of keys for the current match.</p>
<p>This method will be called instead of <tt class="docutils literal"><span class="pre">key_for</span></tt> if
<tt class="docutils literal"><span class="pre">self.allow_overlap</span></tt> is <tt class="docutils literal"><span class="pre">True</span></tt>.</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>matcher</strong> – 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. If
<tt class="docutils literal"><span class="pre">self.needs_current</span></tt> is <tt class="docutils literal"><span class="pre">False</span></tt>, DO NOT use this object,
since it may be inconsistent. Use the given <tt class="docutils literal"><span class="pre">segment_docnum</span></tt>
instead.</li>
<li><strong>segment_docnum</strong> – the segment-relative document number of the
current match.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="whoosh.sorting.Categorizer.set_searcher">
<tt class="descname">set_searcher</tt><big>(</big><em>segment_searcher</em>, <em>docoffset</em><big>)</big><a class="headerlink" href="#whoosh.sorting.Categorizer.set_searcher" title="Permalink to this definition">¶</a></dt>
<dd><p>Called by the collector when the collector moves to a new segment.
The <tt class="docutils literal"><span class="pre">segment_searcher</span></tt> will be atomic. The <tt class="docutils literal"><span class="pre">docoffset</span></tt> is the
offset of the segment’s document numbers relative to the entire index.
You can use the offset to get absolute index docnums by adding the
offset to segment-relative docnums.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="facet-types">
<h2>Facet types<a class="headerlink" href="#facet-types" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="whoosh.sorting.FieldFacet">
<em class="property">class </em><tt class="descclassname">whoosh.sorting.</tt><tt class="descname">FieldFacet</tt><big>(</big><em>fieldname</em>, <em>reverse=False</em>, <em>allow_overlap=False</em>, <em>maptype=None</em><big>)</big><a class="headerlink" href="#whoosh.sorting.FieldFacet" title="Permalink to this definition">¶</a></dt>
<dd><p>Sorts/facest by the contents of a field.</p>
<p>For example, to sort by the contents of the “path” field in reverse order,
and facet by the contents of the “tag” field:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">paths</span> <span class="o">=</span> <span class="n">FieldFacet</span><span class="p">(</span><span class="s">"path"</span><span class="p">,</span> <span class="n">reverse</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="n">tags</span> <span class="o">=</span> <span class="n">FieldFacet</span><span class="p">(</span><span class="s">"tag"</span><span class="p">)</span>
<span class="n">results</span> <span class="o">=</span> <span class="n">searcher</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="n">myquery</span><span class="p">,</span> <span class="n">sortedby</span><span class="o">=</span><span class="n">paths</span><span class="p">,</span> <span class="n">groupedby</span><span class="o">=</span><span class="n">tags</span><span class="p">)</span>
</pre></div>
</div>
<p>This facet returns different categorizers based on the field type.</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>fieldname</strong> – the name of the field to sort/facet on.</li>
<li><strong>reverse</strong> – if True, when sorting, reverse the sort order of this
facet.</li>
<li><strong>allow_overlap</strong> – if True, when grouping, allow documents to appear
in multiple groups when they have multiple terms in the field.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="class">
<dt id="whoosh.sorting.QueryFacet">
<em class="property">class </em><tt class="descclassname">whoosh.sorting.</tt><tt class="descname">QueryFacet</tt><big>(</big><em>querydict</em>, <em>other=None</em>, <em>allow_overlap=False</em>, <em>maptype=None</em><big>)</big><a class="headerlink" href="#whoosh.sorting.QueryFacet" title="Permalink to this definition">¶</a></dt>
<dd><p>Sorts/facets based on the results of a series of queries.</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>querydict</strong> – a dictionary mapping keys to
<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> objects.</li>
<li><strong>other</strong> – the key to use for documents that don’t match any of the
queries.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="class">
<dt id="whoosh.sorting.RangeFacet">
<em class="property">class </em><tt class="descclassname">whoosh.sorting.</tt><tt class="descname">RangeFacet</tt><big>(</big><em>fieldname</em>, <em>start</em>, <em>end</em>, <em>gap</em>, <em>hardend=False</em>, <em>maptype=None</em><big>)</big><a class="headerlink" href="#whoosh.sorting.RangeFacet" title="Permalink to this definition">¶</a></dt>
<dd><p>Sorts/facets based on numeric ranges. For textual ranges, use
<a class="reference internal" href="#whoosh.sorting.QueryFacet" title="whoosh.sorting.QueryFacet"><tt class="xref py py-class docutils literal"><span class="pre">QueryFacet</span></tt></a>.</p>
<p>For example, to facet the “price” field into $100 buckets, up to $1000:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">prices</span> <span class="o">=</span> <span class="n">RangeFacet</span><span class="p">(</span><span class="s">"price"</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1000</span><span class="p">,</span> <span class="mi">100</span><span class="p">)</span>
<span class="n">results</span> <span class="o">=</span> <span class="n">searcher</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="n">myquery</span><span class="p">,</span> <span class="n">groupedby</span><span class="o">=</span><span class="n">prices</span><span class="p">)</span>
</pre></div>
</div>
<p>The ranges/buckets are always <strong>inclusive</strong> at the start and <strong>exclusive</strong>
at the end.</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>fieldname</strong> – the numeric field to sort/facet on.</li>
<li><strong>start</strong> – the start of the entire range.</li>
<li><strong>end</strong> – the end of the entire range.</li>
<li><strong>gap</strong> – the size of each “bucket” in the range. This can be a
sequence of sizes. For example, <tt class="docutils literal"><span class="pre">gap=[1,5,10]</span></tt> will use 1 as the
size of the first bucket, 5 as the size of the second bucket, and
10 as the size of all subsequent buckets.</li>
<li><strong>hardend</strong> – if True, the end of the last bucket is clamped to the
value of <tt class="docutils literal"><span class="pre">end</span></tt>. If False (the default), the last bucket is always
<tt class="docutils literal"><span class="pre">gap</span></tt> sized, even if that means the end of the last bucket is
after <tt class="docutils literal"><span class="pre">end</span></tt>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="class">
<dt id="whoosh.sorting.DateRangeFacet">
<em class="property">class </em><tt class="descclassname">whoosh.sorting.</tt><tt class="descname">DateRangeFacet</tt><big>(</big><em>fieldname</em>, <em>start</em>, <em>end</em>, <em>gap</em>, <em>hardend=False</em>, <em>maptype=None</em><big>)</big><a class="headerlink" href="#whoosh.sorting.DateRangeFacet" title="Permalink to this definition">¶</a></dt>
<dd><p>Sorts/facets based on date ranges. This is the same as RangeFacet
except you are expected to use <tt class="docutils literal"><span class="pre">daterange</span></tt> objects as the start and end
of the range, and <tt class="docutils literal"><span class="pre">timedelta</span></tt> or <tt class="docutils literal"><span class="pre">relativedelta</span></tt> objects as the gap(s),
and it generates <a class="reference internal" href="query.html#whoosh.query.DateRange" title="whoosh.query.DateRange"><tt class="xref py py-class docutils literal"><span class="pre">DateRange</span></tt></a> queries instead of
<a class="reference internal" href="query.html#whoosh.query.TermRange" title="whoosh.query.TermRange"><tt class="xref py py-class docutils literal"><span class="pre">TermRange</span></tt></a> queries.</p>
<p>For example, to facet a “birthday” range into 5 year buckets:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">datetime</span> <span class="kn">import</span> <span class="n">datetime</span>
<span class="kn">from</span> <span class="nn">whoosh.support.relativedelta</span> <span class="kn">import</span> <span class="n">relativedelta</span>
<span class="n">startdate</span> <span class="o">=</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">1920</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
<span class="n">enddate</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span>
<span class="n">gap</span> <span class="o">=</span> <span class="n">relativedelta</span><span class="p">(</span><span class="n">years</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span>
<span class="n">bdays</span> <span class="o">=</span> <span class="n">DateRangeFacet</span><span class="p">(</span><span class="s">"birthday"</span><span class="p">,</span> <span class="n">startdate</span><span class="p">,</span> <span class="n">enddate</span><span class="p">,</span> <span class="n">gap</span><span class="p">)</span>
<span class="n">results</span> <span class="o">=</span> <span class="n">searcher</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="n">myquery</span><span class="p">,</span> <span class="n">groupedby</span><span class="o">=</span><span class="n">bdays</span><span class="p">)</span>
</pre></div>
</div>
<p>The ranges/buckets are always <strong>inclusive</strong> at the start and <strong>exclusive</strong>
at the end.</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>fieldname</strong> – the numeric field to sort/facet on.</li>
<li><strong>start</strong> – the start of the entire range.</li>
<li><strong>end</strong> – the end of the entire range.</li>
<li><strong>gap</strong> – the size of each “bucket” in the range. This can be a
sequence of sizes. For example, <tt class="docutils literal"><span class="pre">gap=[1,5,10]</span></tt> will use 1 as the
size of the first bucket, 5 as the size of the second bucket, and
10 as the size of all subsequent buckets.</li>
<li><strong>hardend</strong> – if True, the end of the last bucket is clamped to the
value of <tt class="docutils literal"><span class="pre">end</span></tt>. If False (the default), the last bucket is always
<tt class="docutils literal"><span class="pre">gap</span></tt> sized, even if that means the end of the last bucket is
after <tt class="docutils literal"><span class="pre">end</span></tt>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="class">
<dt id="whoosh.sorting.ScoreFacet">
<em class="property">class </em><tt class="descclassname">whoosh.sorting.</tt><tt class="descname">ScoreFacet</tt><a class="headerlink" href="#whoosh.sorting.ScoreFacet" title="Permalink to this definition">¶</a></dt>
<dd><p>Uses a document’s score as a sorting criterion.</p>
<p>For example, to sort by the <tt class="docutils literal"><span class="pre">tag</span></tt> field, and then within that by relative
score:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">tag_score</span> <span class="o">=</span> <span class="n">MultiFacet</span><span class="p">([</span><span class="s">"tag"</span><span class="p">,</span> <span class="n">ScoreFacet</span><span class="p">()])</span>
<span class="n">results</span> <span class="o">=</span> <span class="n">searcher</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="n">myquery</span><span class="p">,</span> <span class="n">sortedby</span><span class="o">=</span><span class="n">tag_score</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
<dl class="class">
<dt id="whoosh.sorting.FunctionFacet">
<em class="property">class </em><tt class="descclassname">whoosh.sorting.</tt><tt class="descname">FunctionFacet</tt><big>(</big><em>fn</em>, <em>maptype=None</em><big>)</big><a class="headerlink" href="#whoosh.sorting.FunctionFacet" title="Permalink to this definition">¶</a></dt>
<dd><p>This facet type is low-level. In most cases you should use
<tt class="xref py py-class docutils literal"><span class="pre">TranslateFacet</span></tt> instead.</p>
<p>This facet type ets you pass an arbitrary function that will compute the
key. This may be easier than subclassing FacetType and Categorizer to set up
the desired behavior.</p>
<p>The function is called with the arguments <tt class="docutils literal"><span class="pre">(searcher,</span> <span class="pre">docid)</span></tt>, where the
<tt class="docutils literal"><span class="pre">searcher</span></tt> may be a composite searcher, and the <tt class="docutils literal"><span class="pre">docid</span></tt> is an absolute
index document number (not segment-relative).</p>
<p>For example, to use the number of words in the document’s “content” field
as the sorting/faceting key:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">fn</span> <span class="o">=</span> <span class="k">lambda</span> <span class="n">s</span><span class="p">,</span> <span class="n">docid</span><span class="p">:</span> <span class="n">s</span><span class="o">.</span><span class="n">doc_field_length</span><span class="p">(</span><span class="n">docid</span><span class="p">,</span> <span class="s">"content"</span><span class="p">)</span>
<span class="n">lengths</span> <span class="o">=</span> <span class="n">FunctionFacet</span><span class="p">(</span><span class="n">fn</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
<dl class="class">
<dt id="whoosh.sorting.MultiFacet">
<em class="property">class </em><tt class="descclassname">whoosh.sorting.</tt><tt class="descname">MultiFacet</tt><big>(</big><em>items=None</em>, <em>maptype=None</em><big>)</big><a class="headerlink" href="#whoosh.sorting.MultiFacet" title="Permalink to this definition">¶</a></dt>
<dd><p>Sorts/facets by the combination of multiple “sub-facets”.</p>
<p>For example, to sort by the value of the “tag” field, and then (for
documents where the tag is the same) by the value of the “path” field:</p>
<div class="highlight-python"><pre>facet = MultiFacet(FieldFacet("tag"), FieldFacet("path")
results = searcher.search(myquery, sortedby=facet)</pre>
</div>
<p>As a shortcut, you can use strings to refer to field names, and they will
be assumed to be field names and turned into FieldFacet objects:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">facet</span> <span class="o">=</span> <span class="n">MultiFacet</span><span class="p">(</span><span class="s">"tag"</span><span class="p">,</span> <span class="s">"path"</span><span class="p">)</span>
</pre></div>
</div>
<p>You can also use the <tt class="docutils literal"><span class="pre">add_*</span></tt> methods to add criteria to the multifacet:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">facet</span> <span class="o">=</span> <span class="n">MultiFacet</span><span class="p">()</span>
<span class="n">facet</span><span class="o">.</span><span class="n">add_field</span><span class="p">(</span><span class="s">"tag"</span><span class="p">)</span>
<span class="n">facet</span><span class="o">.</span><span class="n">add_field</span><span class="p">(</span><span class="s">"path"</span><span class="p">,</span> <span class="n">reverse</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="n">facet</span><span class="o">.</span><span class="n">add_query</span><span class="p">({</span><span class="s">"a-m"</span><span class="p">:</span> <span class="n">TermRange</span><span class="p">(</span><span class="s">"name"</span><span class="p">,</span> <span class="s">"a"</span><span class="p">,</span> <span class="s">"m"</span><span class="p">),</span>
<span class="s">"n-z"</span><span class="p">:</span> <span class="n">TermRange</span><span class="p">(</span><span class="s">"name"</span><span class="p">,</span> <span class="s">"n"</span><span class="p">,</span> <span class="s">"z"</span><span class="p">)})</span>
</pre></div>
</div>
</dd></dl>
<dl class="class">
<dt id="whoosh.sorting.StoredFieldFacet">
<em class="property">class </em><tt class="descclassname">whoosh.sorting.</tt><tt class="descname">StoredFieldFacet</tt><big>(</big><em>fieldname</em>, <em>allow_overlap=False</em>, <em>split_fn=None</em>, <em>maptype=None</em><big>)</big><a class="headerlink" href="#whoosh.sorting.StoredFieldFacet" title="Permalink to this definition">¶</a></dt>
<dd><p>Lets you sort/group using the value in an unindexed, stored field (e.g.
<a class="reference internal" href="fields.html#whoosh.fields.STORED" title="whoosh.fields.STORED"><tt class="xref py py-class docutils literal"><span class="pre">whoosh.fields.STORED</span></tt></a>). This is usually slower than using an indexed
field.</p>
<p>For fields where the stored value is a space-separated list of keywords,
(e.g. <tt class="docutils literal"><span class="pre">"tag1</span> <span class="pre">tag2</span> <span class="pre">tag3"</span></tt>), you can use the <tt class="docutils literal"><span class="pre">allow_overlap</span></tt> keyword
argument to allow overlapped faceting on the result of calling the
<tt class="docutils literal"><span class="pre">split()</span></tt> method on the field value (or calling a custom split function
if one is supplied).</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>fieldname</strong> – the name of the stored field.</li>
<li><strong>allow_overlap</strong> – if True, when grouping, allow documents to appear
in multiple groups when they have multiple terms in the field. The
categorizer uses <tt class="docutils literal"><span class="pre">string.split()</span></tt> or the custom <tt class="docutils literal"><span class="pre">split_fn</span></tt> to
convert the stored value into a list of facet values.</li>
<li><strong>split_fn</strong> – a custom function to split a stored field value into
multiple facet values when <tt class="docutils literal"><span class="pre">allow_overlap</span></tt> is True. If not
supplied, the categorizer simply calls the value’s <tt class="docutils literal"><span class="pre">split()</span></tt>
method.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
</div>
<div class="section" id="facets-object">
<h2>Facets object<a class="headerlink" href="#facets-object" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="whoosh.sorting.Facets">
<em class="property">class </em><tt class="descclassname">whoosh.sorting.</tt><tt class="descname">Facets</tt><big>(</big><em>x=None</em><big>)</big><a class="headerlink" href="#whoosh.sorting.Facets" title="Permalink to this definition">¶</a></dt>
<dd><p>Maps facet names to <a class="reference internal" href="#whoosh.sorting.FacetType" title="whoosh.sorting.FacetType"><tt class="xref py py-class docutils literal"><span class="pre">FacetType</span></tt></a> objects, for creating multiple
groupings of documents.</p>
<p>For example, to group by tag, and <strong>also</strong> group by price range:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">facets</span> <span class="o">=</span> <span class="n">Facets</span><span class="p">()</span>
<span class="n">facets</span><span class="o">.</span><span class="n">add_field</span><span class="p">(</span><span class="s">"tag"</span><span class="p">)</span>
<span class="n">facets</span><span class="o">.</span><span class="n">add_facet</span><span class="p">(</span><span class="s">"price"</span><span class="p">,</span> <span class="n">RangeFacet</span><span class="p">(</span><span class="s">"price"</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1000</span><span class="p">,</span> <span class="mi">100</span><span class="p">))</span>
<span class="n">results</span> <span class="o">=</span> <span class="n">searcher</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="n">myquery</span><span class="p">,</span> <span class="n">groupedby</span><span class="o">=</span><span class="n">facets</span><span class="p">)</span>
<span class="n">tag_groups</span> <span class="o">=</span> <span class="n">results</span><span class="o">.</span><span class="n">groups</span><span class="p">(</span><span class="s">"tag"</span><span class="p">)</span>
<span class="n">price_groups</span> <span class="o">=</span> <span class="n">results</span><span class="o">.</span><span class="n">groups</span><span class="p">(</span><span class="s">"price"</span><span class="p">)</span>
</pre></div>
</div>
<p>(To group by the combination of multiple facets, use <a class="reference internal" href="#whoosh.sorting.MultiFacet" title="whoosh.sorting.MultiFacet"><tt class="xref py py-class docutils literal"><span class="pre">MultiFacet</span></tt></a>.)</p>
<dl class="method">
<dt id="whoosh.sorting.Facets.add_facet">
<tt class="descname">add_facet</tt><big>(</big><em>name</em>, <em>facet</em><big>)</big><a class="headerlink" href="#whoosh.sorting.Facets.add_facet" title="Permalink to this definition">¶</a></dt>
<dd><p>Adds a <a class="reference internal" href="#whoosh.sorting.FacetType" title="whoosh.sorting.FacetType"><tt class="xref py py-class docutils literal"><span class="pre">FacetType</span></tt></a> object under the given <tt class="docutils literal"><span class="pre">name</span></tt>.</p>
</dd></dl>
<dl class="method">
<dt id="whoosh.sorting.Facets.add_facets">
<tt class="descname">add_facets</tt><big>(</big><em>facets</em>, <em>replace=True</em><big>)</big><a class="headerlink" href="#whoosh.sorting.Facets.add_facets" title="Permalink to this definition">¶</a></dt>
<dd><p>Adds the contents of the given <tt class="docutils literal"><span class="pre">Facets</span></tt> or <tt class="docutils literal"><span class="pre">dict</span></tt> object to this
object.</p>
</dd></dl>
<dl class="method">
<dt id="whoosh.sorting.Facets.add_field">
<tt class="descname">add_field</tt><big>(</big><em>fieldname</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#whoosh.sorting.Facets.add_field" title="Permalink to this definition">¶</a></dt>
<dd><p>Adds a <a class="reference internal" href="#whoosh.sorting.FieldFacet" title="whoosh.sorting.FieldFacet"><tt class="xref py py-class docutils literal"><span class="pre">FieldFacet</span></tt></a> for the given field name (the field name
is automatically used as the facet name).</p>
</dd></dl>
<dl class="method">
<dt id="whoosh.sorting.Facets.add_query">
<tt class="descname">add_query</tt><big>(</big><em>name</em>, <em>querydict</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#whoosh.sorting.Facets.add_query" title="Permalink to this definition">¶</a></dt>
<dd><p>Adds a <a class="reference internal" href="#whoosh.sorting.QueryFacet" title="whoosh.sorting.QueryFacet"><tt class="xref py py-class docutils literal"><span class="pre">QueryFacet</span></tt></a> under the given <tt class="docutils literal"><span class="pre">name</span></tt>.</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>name</strong> – a name for the facet.</li>
<li><strong>querydict</strong> – a dictionary mapping keys to
<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> objects.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="whoosh.sorting.Facets.items">
<tt class="descname">items</tt><big>(</big><big>)</big><a class="headerlink" href="#whoosh.sorting.Facets.items" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a list of (facetname, facetobject) tuples for the facets in
this object.</p>
</dd></dl>
<dl class="method">
<dt id="whoosh.sorting.Facets.names">
<tt class="descname">names</tt><big>(</big><big>)</big><a class="headerlink" href="#whoosh.sorting.Facets.names" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns an iterator of the facet names in this object.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="facettype-objects">
<h2>FacetType objects<a class="headerlink" href="#facettype-objects" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="whoosh.sorting.FacetMap">
<em class="property">class </em><tt class="descclassname">whoosh.sorting.</tt><tt class="descname">FacetMap</tt><a class="headerlink" href="#whoosh.sorting.FacetMap" title="Permalink to this definition">¶</a></dt>
<dd><p>Base class for objects holding the results of grouping search results by
a Facet. Use an object’s <tt class="docutils literal"><span class="pre">as_dict()</span></tt> method to access the results.</p>
<p>You can pass a subclass of this to the <tt class="docutils literal"><span class="pre">maptype</span></tt> keyword argument when
creating a <tt class="docutils literal"><span class="pre">FacetType</span></tt> object to specify what information the facet
should record about the group. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># Record each document in each group in its sorted order</span>
<span class="n">myfacet</span> <span class="o">=</span> <span class="n">FieldFacet</span><span class="p">(</span><span class="s">"size"</span><span class="p">,</span> <span class="n">maptype</span><span class="o">=</span><span class="n">OrderedList</span><span class="p">)</span>
<span class="c"># Record only the count of documents in each group</span>
<span class="n">myfacet</span> <span class="o">=</span> <span class="n">FieldFacet</span><span class="p">(</span><span class="s">"size"</span><span class="p">,</span> <span class="n">maptype</span><span class="o">=</span><span class="n">Count</span><span class="p">)</span>
</pre></div>
</div>
<dl class="method">
<dt id="whoosh.sorting.FacetMap.add">
<tt class="descname">add</tt><big>(</big><em>groupname</em>, <em>docid</em>, <em>sortkey</em><big>)</big><a class="headerlink" href="#whoosh.sorting.FacetMap.add" title="Permalink to this definition">¶</a></dt>
<dd><p>Adds a document to the facet 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>groupname</strong> – the name of the group to add this document to.</li>
<li><strong>docid</strong> – the document number of the document to add.</li>
<li><strong>sortkey</strong> – a value representing the sort position of the document
in the full results.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="whoosh.sorting.FacetMap.as_dict">
<tt class="descname">as_dict</tt><big>(</big><big>)</big><a class="headerlink" href="#whoosh.sorting.FacetMap.as_dict" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a dictionary object mapping group names to
implementation-specific values. For example, the value might be a list
of document numbers, or a integer representing the number of documents
in the group.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="whoosh.sorting.OrderedList">
<em class="property">class </em><tt class="descclassname">whoosh.sorting.</tt><tt class="descname">OrderedList</tt><a class="headerlink" href="#whoosh.sorting.OrderedList" title="Permalink to this definition">¶</a></dt>
<dd><p>Stores a list of document numbers for each group, in the same order as
they appear in the search results.</p>
<p>The <tt class="docutils literal"><span class="pre">as_dict</span></tt> method returns a dictionary mapping group names to lists
of document numbers.</p>
</dd></dl>
<dl class="class">
<dt id="whoosh.sorting.UnorderedList">
<em class="property">class </em><tt class="descclassname">whoosh.sorting.</tt><tt class="descname">UnorderedList</tt><a class="headerlink" href="#whoosh.sorting.UnorderedList" title="Permalink to this definition">¶</a></dt>
<dd><p>Stores a list of document numbers for each group, in arbitrary order.
This is slightly faster and uses less memory than
<tt class="xref py py-class docutils literal"><span class="pre">OrderedListResult</span></tt> if you don’t care about the ordering of the
documents within groups.</p>
<p>The <tt class="docutils literal"><span class="pre">as_dict</span></tt> method returns a dictionary mapping group names to lists
of document numbers.</p>
</dd></dl>
<dl class="class">
<dt id="whoosh.sorting.Count">
<em class="property">class </em><tt class="descclassname">whoosh.sorting.</tt><tt class="descname">Count</tt><a class="headerlink" href="#whoosh.sorting.Count" title="Permalink to this definition">¶</a></dt>
<dd><p>Stores the number of documents in each group.</p>
<p>The <tt class="docutils literal"><span class="pre">as_dict</span></tt> method returns a dictionary mapping group names to
integers.</p>
</dd></dl>
<dl class="class">
<dt id="whoosh.sorting.Best">
<em class="property">class </em><tt class="descclassname">whoosh.sorting.</tt><tt class="descname">Best</tt><a class="headerlink" href="#whoosh.sorting.Best" title="Permalink to this definition">¶</a></dt>
<dd><p>Stores the “best” document in each group (that is, the one with the
highest sort key).</p>
<p>The <tt class="docutils literal"><span class="pre">as_dict</span></tt> method returns a dictionary mapping group names to
docnument numbers.</p>
</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">sorting</span></tt> module</a><ul>
<li><a class="reference internal" href="#base-types">Base types</a></li>
<li><a class="reference internal" href="#facet-types">Facet types</a></li>
<li><a class="reference internal" href="#facets-object">Facets object</a></li>
<li><a class="reference internal" href="#facettype-objects">FacetType objects</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="searching.html"
title="previous chapter"><tt class="docutils literal"><span class="pre">searching</span></tt> module</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="spelling.html"
title="next chapter"><tt class="docutils literal"><span class="pre">spelling</span></tt> module</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/api/sorting.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="spelling.html" title="spelling module"
>next</a> |</li>
<li class="right" >
<a href="searching.html" title="searching 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>
