EVOLUTION-MANAGER

Edit File: facets.html

<?xml version="1.0" encoding="utf-8" ?>
<!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" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title>Xapian Faceting Support</title>
<style type="text/css">

/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 7056 2011-06-17 10:50:48Z milde $
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
  border: 0 }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 ! important }

.first {
  /* Override more specific margin styles with "! important". */
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
  overflow: hidden;
}

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em ;
  margin-right: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin: 0 0 0.5em 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left, .figure.align-left, object.align-left {
  clear: left ;
  float: left ;
  margin-right: 1em }

img.align-right, .figure.align-right, object.align-right {
  clear: right ;
  float: right ;
  margin-left: 1em }

img.align-center, .figure.align-center, object.align-center {
  display: block;
  margin-left: auto;
  margin-right: auto;
}

.align-left {
  text-align: left }

.align-center {
  clear: both ;
  text-align: center }

.align-right {
  text-align: right }

/* reset inner alignment in figures */
div.align-right {
  text-align: inherit }

/* div.align-center * { */
/*   text-align: left } */

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font: inherit }

pre.literal-block, pre.doctest-block, pre.math {
  margin-left: 2em ;
  margin-right: 2em }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid 1px gray;
  margin-left: 1px }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid 1px black;
  margin-left: 1px }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body>
<div class="document" id="xapian-faceting-support">
<h1 class="title">Xapian Faceting Support</h1>

<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of contents</p>
<ul class="simple">
<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
<li><a class="reference internal" href="#how-to-use-faceting" id="id2">How to use Faceting</a><ul>
<li><a class="reference internal" href="#indexing" id="id3">Indexing</a></li>
<li><a class="reference internal" href="#searching" id="id4">Searching</a><ul>
<li><a class="reference internal" href="#finding-facets" id="id5">Finding Facets</a></li>
<li><a class="reference internal" href="#restricting-by-facet-values" id="id6">Restricting by Facet Values</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="introduction">
<h1><a class="toc-backref" href="#id1">Introduction</a></h1>
<p>Xapian provides functionality which allows you to dynamically generate complete
lists of category values which feature in matching documents.  There are
numerous potential uses this can be put to, but a common one is to offer the
user the ability to narrow down their search by filtering it to only include
documents with a particular value of a particular category.  This is often
referred to as <tt class="docutils literal">faceted search</tt>.</p>
<p>You may have many multiple facets (for example colour, manufacturer, product
type) so Xapian allows you to handle multiple facets at once.</p>
</div>
<div class="section" id="how-to-use-faceting">
<h1><a class="toc-backref" href="#id2">How to use Faceting</a></h1>
<div class="section" id="indexing">
<h2><a class="toc-backref" href="#id3">Indexing</a></h2>
<p>When indexing a document, you need to add each facet in a different numbered
value slot.  As described elsewhere in the documentation, each Xapian document
has a set of &quot;value slots&quot;, each of which is addressed by a number, and can
contain a value which is an arbitrary string.</p>
<p>The <tt class="docutils literal"><span class="pre">Xapian::Document::add_value()</span></tt> method can be used to put values into a
particular slot.  So, if you had a database of books, you might put &quot;price&quot;
facet values in slot 0, say (serialised to strings using
<tt class="docutils literal"><span class="pre">Xapian::sortable_serialise</span></tt>, or some similar function), &quot;author&quot; facet
values in slot 1, &quot;publisher&quot; facet values in slot 2 and &quot;publication type&quot;
(eg, hardback, softback, etc) values in slot 3.</p>
</div>
<div class="section" id="searching">
<h2><a class="toc-backref" href="#id4">Searching</a></h2>
<div class="section" id="finding-facets">
<h3><a class="toc-backref" href="#id5">Finding Facets</a></h3>
<p>At search time, for each facet you want to consider, you need to get a count of
the number of times each facet value occurs in each slot; for the example
above, if you wanted to get facets for &quot;price&quot;, &quot;author&quot; and &quot;publication type&quot;
you'd want to get the counts from slots 0, 1 and 3.</p>
<p>This can be done by calling <tt class="docutils literal"><span class="pre">Xapian::Enquire::add_matchspy()</span></tt> with a pointer
to a <tt class="docutils literal"><span class="pre">Xapian::ValueCountMatchSpy</span></tt> object for each value slot you want to
get facet counts for, like so:</p>
<pre class="literal-block">
Xapian::ValueCountMatchSpy spy0(0);
Xapian::ValueCountMatchSpy spy1(1);
Xapian::ValueCountMatchSpy spy3(3);

Xapian::Enquire enq(db);
enq.add_matchspy(&amp;spy0);
enq.add_matchspy(&amp;spy1);
enq.add_matchspy(&amp;spy3);

enq.set_query(query);

Xapian::MSet mset = enq.get_mset(0, 10, 10000);
</pre>
<p>The <tt class="docutils literal">10000</tt> in the call to <tt class="docutils literal">get_mset()</tt> tells Xapian to check at least
10000 documents, so the MatchSpy objects will be passed at least 10000
documents to tally facet information from (unless fewer than 10000 documents
match the query, in which case they will see all of them).  Setting this to
<tt class="docutils literal">db.get_doccount()</tt> will make the facet counts exact, but Xapian will have to
do more work for most queries so searches will be slower.</p>
<p>The <tt class="docutils literal">spy</tt> objects now contain the facet information.  You can find out how
many documents they looked at by calling <tt class="docutils literal">spy0.get_total()</tt>.  (All the spies
will have looked at the same number of documents.)  You can read the values
from, say, <tt class="docutils literal">spy0</tt> like this:</p>
<pre class="literal-block">
Xapian::TermIterator i;
for (i = spy0.values_begin(); i != spy0.values_end(); ++i) {
    cout &lt;&lt; *i &lt;&lt; &quot;: &quot; &lt;&lt; i.get_termfreq() &lt;&lt; endl;
}
</pre>
</div>
<div class="section" id="restricting-by-facet-values">
<h3><a class="toc-backref" href="#id6">Restricting by Facet Values</a></h3>
<p>If you're using the facets to offer the user choices for narrowing down
their search results, you then need to be able to apply a suitable filter.</p>
<p>For a single value, you could use <tt class="docutils literal"><span class="pre">Xapian::Query::OP_VALUE_RANGE</span></tt> with the
same start and end, or <tt class="docutils literal"><span class="pre">Xapian::MatchDecider</span></tt>, but it's probably most
efficient to also index the categories as suitably prefixed boolean terms and
use those for filtering.</p>
</div>
</div>
</div>
</div>
</body>
</html>