xapian-core/docs/valueranges.rst

   1 ============
   2 Value Ranges
   3 ============
   4
   5 .. contents:: Table of contents
   6
   7 Introduction
   8 ============
   9
  10 The ``Xapian::ValueRangeProcessor`` was introduced in Xapian 1.0.0.  It
  11 provides a powerful and flexible way to parse range queries in the users'
  12 query string.
  13
  14 This document describes the ``Xapian::ValueRangeProcessor`` class and
  15 its standard subclasses, how to create your own subclasses, and how
  16 these classes are used with ``Xapian::QueryParser``.
  17
  18 ``Xapian::ValueRangeProcessor`` is a virtual base class, so you need to
  19 use a subclass of it.  ``Xapian::QueryParser`` maintains a list of
  20 ``Xapian::ValueRangeProcessor`` objects which it tries in order for
  21 each range search in the query until one accepts it, or all have been
  22 tried (in which case an error is reported).
  23
  24 The ``Xapian::StringValueRangeProcessor`` subclass supports setting a prefix or
  25 suffix string which must be present for the range to be recognised by that
  26 object, and ``Xapian::DateValueRangeProcessor`` and
  27 ``Xapian::NumberValueRangeProcessor`` are subclasses of this so also
  28 support a prefix or suffix (since Xapian 1.1.2 - before this all there were
  29 direct subclasses of ``Xapian::ValueRangeProcessor``, with only
  30 ``Xapian::NumberValueRangeProcessor`` supporting this).
  31
  32 So you can support multiple filters distinguished by a prefix or suffix.  For
  33 example, if you want to support range filters on price and weight, you can do
  34 that like this::
  35
  36     Xapian::QueryParser qp;
  37     Xapian::NumberValueRangeProcessor price_proc(0, "$", true);
  38     Xapian::NumberValueRangeProcessor weight_proc(1, "kg", false);
  39     qp.add_valuerangeprocessor(&price_proc);
  40     qp.add_valuerangeprocessor(&weight_proc);
  41
  42 Then the user can enter queries like::
  43
  44     laptop $300..800 ..1.5kg
  45
  46 A common way to use this feature is with a prefix string which is a "field
  47 name" followed by a colon, for example::
  48
  49     created:1/1/1999..1/1/2003
  50
  51 Each ``Xapian::ValueRangeProcessor`` is passed the start and end of the
  52 range.  If it doesn't understand the range, it should return
  53 ``Xapian::BAD_VALUENO``.  If it does understand the range, it should return
  54 the value number to use with ``Xapian::Query::OP_VALUE_RANGE`` and if it
  55 wants to, it can modify the start and end values (to convert them to the
  56 correct format so that for the string comparison which ``OP_VALUE_RANGE``
  57 uses).
  58
  59 In Xapian 1.2.1 and later, ``Xapian::QueryParser`` supports open-ended
  60 ranges - if the start of the range is empty, that means any value less than
  61 the end, and similarly if the end is empty, that means any value greater
  62 than the start.  The start and end can't both be empty.
  63
  64 StringValueRangeProcessor
  65 =========================
  66
  67 This is the simplest of the standard subclasses.  It understands any range
  68 passed (so it should always be the last ``ValueRangeProcessor``) and it
  69 doesn't alter the range start or end.
  70
  71 For example, suppose you have stored author names in value number 4, and want
  72 the user to be able to filter queries by specifying ranges of values such as::
  73
  74     mars asimov..bradbury
  75
  76 To do this, you can use a ``StringValueRangeProcessor`` like so::
  77
  78     Xapian::QueryParser qp;
  79     Xapian::StringValueRangeProcessor author_proc(4);
  80     qp.add_valuerangeprocessor(&author_proc);
  81
  82 The parsed query will use ``OP_VALUE_RANGE``, so ``query.get_description()``
  83 would report::
  84
  85     Xapian::Query(mars:(pos=1) FILTER (VALUE_RANGE 4 asimov bradbury)
  86
  87 The ``VALUE_RANGE`` subquery will only match documents where value 4 is
  88 >= asimov and <= bradbury (using a string comparison).
  89
  90 DateValueRangeProcessor
  91 =======================
  92
  93 This class allows you to implement date range searches.  As well as the value
  94 number to search, you can tell it whether to prefer US-style month/day/year
  95 or European-style day/month/year, and specify the epoch year to use for
  96 interpreting 2 digit years (the default is day/month/year with an epoch of
  97 1970).  The best choice of settings depends on the expectations of your users.
  98 As these settings are only applied at search time, you can also easily offer
  99 different versions of your search front-end with different settings if that is
 100 useful.
 101
 102 For example, if your users are American and the dates present in your database
 103 can extend a decade or so into the future, you might use something like this
 104 which specifies to prefer US-style dates and that the epoch year is 1930 (so
 105 02/01/29 is February 1st 2029 while 02/01/30 is February 1st 1930)::
 106
 107     Xapian::QueryParser qp;
 108     Xapian::DateValueRangeProcessor date_proc(0, true, 1930);
 109     qp.add_valuerangeprocessor(&date_proc);
 110
 111 The dates are converted to the format YYYYMMDD, so the values you index also
 112 need to also be in this format - for example, if ``doc_time`` is a ``time_t``::
 113
 114     char buf[9];
 115     if (strftime(buf, sizeof(buf), "%Y%m%d", gmtime(&doc_time))) {
 116         doc.add_value(0, buf);
 117     }
 118
 119 NumberValueRangeProcessor
 120 =========================
 121
 122 .. note:: This class had a design flaw in Xapian 1.0.0 and 1.0.1 - you should
 123    avoid using it with releases of Xapian earlier than 1.0.2.
 124
 125 This class allows you to implement numeric range searches.  The numbers used
 126 may be any number which is representable as a double, but requires that the
 127 stored values which the range is being applied have been converted to strings
 128 at index time using the ``Xapian::sortable_serialise()`` method::
 129
 130     Xapian::Document doc;
 131     doc.add_value(0, Xapian::sortable_serialise(price));
 132
 133 This method produces strings which will sort in numeric order, so you can use
 134 it if you want to be able to sort based on the value in numeric order, too.
 135
 136 Custom subclasses
 137 =================
 138
 139 You can easily create your own subclasses of ``Xapian::ValueRangeProcessor``.
 140 Your subclass needs to implement a method
 141 ``Xapian::valueno operator()(std::string &begin, std::string &end)``
 142 so for example you could implement a better version of the author range
 143 described above which only matches ranges with a prefix (e.g.
 144 ``author:asimov..bradbury``) and lower-cases the names::
 145
 146     struct AuthorValueRangeProcessor : public Xapian::StringValueRangeProcessor {
 147         AuthorValueRangeProcessor()
 148             : StringValueRangeProcessor(4, "author:", true) { }
 149
 150         Xapian::valueno operator()(std::string &begin, std::string &end) {
 151             // Let the base class do the prefix check.
 152             if (StringValueRangeProcessor::operator()(begin, end) == BAD_VALUENO)
 153                 return BAD_VALUENO;
 154             begin = Xapian::Unicode::tolower(begin);
 155             end = Xapian::Unicode::tolower(end);
 156             return valno;
 157         }
 158     };
 159
 160 If you want to support open-ended ranges, you need to handle begin or end
 161 being empty suitably.  ``Xapian::QueryParser`` won't call your subclass
 162 with *both* begin and end being empty.
 163
 164 Using Several ValueRangeProcessors
 165 ==================================
 166
 167 If you want to allow the user to specify different types of ranges, you can
 168 specify multiple ``ValueRangeProcessor`` objects to use.  Just add them in
 169 the order you want them to be checked::
 170
 171     Xapian::QueryParser qp;
 172     AuthorValueRangeProcessor author_proc();
 173     qp.add_valuerangeprocessor(&author_proc);
 174     Xapian::DateValueRangeProcessor date_proc(0, false, 1930);
 175     qp.add_valuerangeprocessor(&date_proc);
 176
 177 And then you can parse queries such as
 178 ``mars author:Asimov..Bradbury 01/01/1960..31/12/1969`` successfully.