search-xapian/Xapian/Enquire.pm

   1 package Search::Xapian::Enquire;
   2
   3 use 5.006;
   4 use strict;
   5 use warnings;
   6 use Carp;
   7
   8 require DynaLoader;
   9
  10 our @ISA = qw(DynaLoader);
  11
  12 # Preloaded methods go here.
  13
  14 # In a new thread, copy objects of this class to unblessed, undef values.
  15 sub CLONE_SKIP { 1 }
  16
  17 sub set_query {
  18   my $self = shift;
  19   my $query = shift;
  20   if( ref( $query ) ne 'Search::Xapian::Query' ) {
  21     $query = Search::Xapian::Query->new( $query, @_ );
  22     $self->set_query1( $query );
  23     return;
  24   }
  25   my $nargs = scalar(@_);
  26   if( $nargs > 1) {
  27     Carp::carp( "USAGE: \$enquire->set_query(\$query) or \$enquire->set_query(\$query, \$length)" );
  28     exit;
  29   }
  30   if( $nargs == 0 ) {
  31     $self->set_query1( $query );
  32   } else {
  33     $self->set_query2( $query, shift );
  34   }
  35 }
  36
  37 sub get_mset {
  38   my $self = shift;
  39   my $nargs = scalar(@_);
  40   if( $nargs == 3 ) {
  41     my $type = ref( $_[2] );
  42     if ( $type eq 'CODE' ) {
  43       # get_mset(first, max, matchdecider) [perl extra]
  44       return $self->get_mset2(@_);
  45     }
  46     if ( $type eq 'Search::Xapian::RSet' ) {
  47       # get_mset(first, max, rset)
  48       splice @_, 2, 0, (0); # insert checkatleast
  49     }
  50   } elsif( $nargs == 4 && ref( $_[3] ) eq 'CODE' ) {
  51     # get_mset(first, max, rset, matchdecider)
  52     splice @_, 2, 0, (0); # insert checkatleast
  53   }
  54   return $self->get_mset1( @_ );
  55 }
  56
  57 sub matches {
  58   my $self = shift;
  59   return $self->get_mset(@_)->items();
  60 }
  61
  62 sub get_matching_terms_begin {
  63   my $self = shift;
  64   if( scalar(@_) == 1 ) {
  65     my $arg = shift;
  66     my $arg_class = ref( $arg );
  67     if( $arg_class eq 'Search::Xapian::MSetIterator' ) {
  68       return $self->get_matching_terms_begin2($arg);
  69     } else {
  70       return $self->get_matching_terms_begin1($arg);
  71     }
  72   }
  73   Carp::carp( "USAGE: \$enquire->get_matching_terms_begin(\$docid) or \$enquire->get_matching_terms_begin(\$msetiterator)" );
  74   exit;
  75 }
  76
  77 sub get_matching_terms_end {
  78   my $self = shift;
  79   if( scalar(@_) == 1 ) {
  80     my $arg = shift;
  81     my $arg_class = ref( $arg );
  82     if( $arg_class eq 'Search::Xapian::MSetIterator' ) {
  83       return $self->get_matching_terms_end2($arg);
  84     } else {
  85       return $self->get_matching_terms_end1($arg);
  86     }
  87   }
  88   Carp::carp( "USAGE: \$enquire->get_matching_terms_end(\$docid) or \$enquire->get_matching_terms_end(\$msetiterator)" );
  89   exit;
  90 }
  91
  92 1;
  93
  94 __END__
  95
  96 =head1 NAME
  97
  98 Search::Xapian::Enquire - Make queries against a database
  99
 100 =head1 DESCRIPTION
 101
 102 This class provides an interface to the information retrieval system for the
 103 purpose of searching.
 104
 105 =head1 METHODS
 106
 107 =over 4
 108
 109 =item new
 110
 111 =item set_query
 112
 113 takes either a ready made L<Search::Xapian::Query> or a scalar containing
 114 a query, which in that case will be passed to L<Search::Xapian::Query>'s
 115 constructor, together with any other passed arguments.
 116
 117 =item set_query_object <query>
 118
 119 =item get_query
 120
 121 =item matches <start> <size> [<check_at_least>]
 122
 123 Takes the start element, and maximum number of elements (and optionally
 124 the minimum number of matches to check), and returns an array tied to
 125 L<Search::Xapian::MSet::Tied>.
 126
 127 =item get_matching_terms_begin
 128
 129 Returns a L<Search::Xapian::TermIterator>, pointing to the start
 130 of the stream.
 131
 132 =item get_matching_terms_end
 133
 134 Returns a L<Search::Xapian::TermIterator>, pointing to the end
 135 of the stream.
 136
 137 =item set_collapse_key <collapse_key>
 138
 139 =item set_docid_order <order>
 140
 141 Set the direction in which documents are ordered by document id
 142 in the returned MSet.
 143
 144 This order only has an effect on documents which would otherwise
 145 have equal rank.  For a weighted probabilistic match with no sort
 146 value, this means documents with equal weight.  For a boolean match,
 147 with no sort value, this means all documents.  And if a sort value
 148 is used, this means documents with equal sort value (and also equal
 149 weight if ordering on relevance after the sort).
 150
 151 order can be ENQ_ASCENDING (the default, docids sort in ascending order),
 152 ENQ_DESCENDING (docds sort in descending order), or ENQ_DONT_CARE (docids sort
 153 in whatever order is most efficient for the backend.)
 154
 155 Note: If you add documents in strict date order, then a boolean
 156 search - i.e. set_weighting_scheme(Search::Xapian::BoolWeight->new())
 157 - with set_docid_order(ENQ_DESCENDING) is a very efficient
 158 way to perform "sort by date, newest first".
 159
 160 =item set_cutoff <percent_cutoff> [<weight_cutoff>]
 161
 162 =item set_sort_by_relevance
 163
 164 Set the sorting to be by relevance only.  This is the default.
 165
 166 =item set_sort_by_value <sort_key> [<ascending>]
 167
 168 Set the sorting to be by value only.
 169
 170 sort_key - value number to reorder on.  Sorting is with a
 171 string compare.  If ascending is true (the default) higher
 172 is better; if ascending is false, lower is better.
 173
 174 ascending - If true, document values which sort higher by
 175 string compare are better.  If false, the sort order
 176 is reversed.  (default true)
 177
 178 =item set_sort_by_value_then_relevance <sort_key> [<ascending>]
 179
 180 Set the sorting to be by value, then by relevance for documents
 181 with the same value.
 182
 183 sort_key - value number to reorder on.  Sorting is with a
 184 string compare.  If ascending is true (the default) higher
 185 is better; if ascending is false, lower is better.
 186
 187 ascending - If true, document values which sort higher by
 188 string compare are better.  If false, the sort order
 189 is reversed.  (default true)
 190
 191 =item set_sort_by_relevance_then_value <sort_key> [<ascending>]
 192
 193 Set the sorting to be by relevance then value.
 194
 195 Note that with the default BM25 weighting scheme parameters,
 196 non-identical documents will rarely have the same weight, so
 197 this setting will give very similar results to
 198 set_sort_by_relevance().  It becomes more useful with particular
 199 BM25 parameter settings (e.g. BM25Weight(1,0,1,0,0)) or custom
 200 weighting schemes.
 201
 202 sort_key - value number to reorder on.  Sorting is with a
 203 string compare.  If ascending is true (the default) higher
 204 is better; if ascending is false, lower is better.
 205
 206 ascending - If true, document values which sort higher by
 207 string compare are better.  If false, the sort order
 208 is reversed.  (default true)
 209
 210 =item set_sort_by_key <sorter> [<ascending>]
 211
 212 Set the sorting to be by key only.
 213
 214 sorter - the functor to use to build the key.
 215
 216 ascending - If true, keys which sort higher by
 217 string compare are better.  If false, the sort order
 218 is reversed.  (default true)
 219
 220 =item set_sort_by_key_then_relevance <sorter> [<ascending>]
 221
 222 Set the sorting to be by key, then by relevance for documents
 223 with the same key.
 224
 225 sorter - the functor to use to build the key.
 226
 227 ascending - If true, keys which sort higher by
 228 string compare are better.  If false, the sort order
 229 is reversed.  (default true)
 230
 231 =item set_sort_by_relevance_then_key <sorter> [<ascending>]
 232
 233 Set the sorting to be by relevance then key.
 234
 235 sorter - the functor to use to build the key.
 236
 237 ascending - If true, keys which sort higher by
 238 string compare are better.  If false, the sort order
 239 is reversed.  (default true)
 240
 241 =item get_mset
 242
 243 Get match set.
 244
 245 =item get_eset <maxitems> <rset> [<decider>]
 246
 247 Get set of query expansion terms.
 248
 249 =item get_description
 250
 251 Return a description of this object.
 252
 253 =item add_matchspy <spy>
 254
 255 Add a matchspy.
 256
 257 This matchspy will be called with some of the documents which match the query, during the match process.
 258
 259 =item clear_matchspies
 260
 261 Remove all the matchspies.
 262
 263 =back
 264
 265 =head1 SEE ALSO
 266
 267 L<Search::Xapian::Query>,
 268 L<Search::Xapian::Database>,
 269 L<Search::Xapian::MatchSpy>
 270
 271 =cut