Search::Xapian(3pm)

1Xapian(3)             User Contributed Perl Documentation            Xapian(3)
2
3
4

NAME

6       Search::Xapian - Perl XS frontend to the Xapian C++ search library.
7

SYNOPSIS

9         use Search::Xapian;
10
11         my $db = Search::Xapian::Database->new( '[DATABASE DIR]' );
12         my $enq = $db->enquire( '[QUERY TERM]' );
13
14         printf "Running query '%s'\n", $enq->get_query()->get_description();
15
16         my @matches = $enq->matches(0, 10);
17
18         print scalar(@matches) . " results found\n";
19
20         foreach my $match ( @matches ) {
21           my $doc = $match->get_document();
22           printf "ID %d %d%% [ %s ]\n", $match->get_docid(), $match->get_percent(), $doc->get_data();
23         }
24

DESCRIPTION

26       This module wraps most methods of most Xapian classes. The missing
27       classes and methods should be added in the future. It also provides a
28       simplified, more 'perlish' interface to some common operations, as
29       demonstrated above.
30
31       There are some gaps in the POD documentation for wrapped classes, but
32       you can read the Xapian C++ API documentation at
33       <https://xapian.org/docs/apidoc/html/annotated.html> for details of
34       these.  Alternatively, take a look at the code in the examples and
35       tests.
36
37       If you want to use Search::Xapian and the threads module together, make
38       sure you're using Search::Xapian >= 1.0.4.0 and Perl >= 5.8.7.  As of
39       1.0.4.0, Search::Xapian uses CLONE_SKIP to make sure that the perl
40       wrapper objects aren't copied to new threads - without this the
41       underlying C++ objects can get destroyed more than once.
42
43       If you encounter problems, or have any comments, suggestions, patches,
44       etc please email the Xapian-discuss mailing list (details of which can
45       be found at <https://xapian.org/lists>).
46
47   EXPORT
48       None by default.
49

:db

51       DB_OPEN
52           Open a database, fail if database doesn't exist.
53
54       DB_CREATE
55           Create a new database, fail if database exists.
56
57       DB_CREATE_OR_OPEN
58           Open an existing database, without destroying data, or create a new
59           database if one doesn't already exist.
60
61       DB_CREATE_OR_OVERWRITE
62           Overwrite database if it exists.
63

:ops

65       OP_AND
66           Match if both subqueries are satisfied.
67
68       OP_OR
69           Match if either subquery is satisfied.
70
71       OP_AND_NOT
72           Match if left but not right subquery is satisfied.
73
74       OP_XOR
75           Match if left or right, but not both queries are satisfied.
76
77       OP_AND_MAYBE
78           Match if left is satisfied, but use weights from both.
79
80       OP_FILTER
81           Like OP_AND, but only weight using the left query.
82
83       OP_NEAR
84           Match if the words are near each other. The window should be
85           specified, as a parameter to "Search::Xapian::Query::Query", but it
86           defaults to the number of terms in the list.
87
88       OP_PHRASE
89           Match as a phrase (All words in order).
90
91       OP_ELITE_SET
92           Select an elite set from the subqueries, and perform a query with
93           these combined as an OR query.
94
95       OP_VALUE_RANGE
96           Filter by a range test on a document value.
97

:qpflags

99       FLAG_DEFAULT
100           This gives the QueryParser default flag settings, allowing you to
101           easily add flags to the default ones.
102
103       FLAG_BOOLEAN
104           Support AND, OR, etc and bracketed subexpressions.
105
106       FLAG_LOVEHATE
107           Support + and -.
108
109       FLAG_PHRASE
110           Support quoted phrases.
111
112       FLAG_BOOLEAN_ANY_CASE
113           Support AND, OR, etc even if they aren't in ALLCAPS.
114
115       FLAG_WILDCARD
116           Support right truncation (e.g. Xap*).
117
118       FLAG_PURE_NOT
119           Allow queries such as 'NOT apples'.
120
121           These require the use of a list of all documents in the database
122           which is potentially expensive, so this feature isn't enabled by
123           default.
124
125       FLAG_PARTIAL
126           Enable partial matching.
127
128           Partial matching causes the parser to treat the query as a
129           "partially entered" search.  This will automatically treat the
130           final word as a wildcarded match, unless it is followed by
131           whitespace, to produce more stable results from interactive
132           searches.
133
134       FLAG_SPELLING_CORRECTION
135       FLAG_SYNONYM
136       FLAG_AUTO_SYNONYMS
137       FLAG_AUTO_MULTIWORD_SYNONYMS
138

:qpstem

140       STEM_ALL
141           Stem all terms.
142
143       STEM_NONE
144           Don't stem any terms.
145
146       STEM_SOME
147           Stem some terms, in a manner compatible with Omega (capitalised
148           words and those in phrases aren't stemmed).
149

:enq_order

151       ENQ_ASCENDING
152           docids sort in ascending order (default)
153
154       ENQ_DESCENDING
155           docids sort in descending order
156
157       ENQ_DONT_CARE
158           docids sort in whatever order is most efficient for the backend
159

:standard

161       Standard is db + ops + qpflags + qpstem
162

Version functions

164       major_version
165           Returns the major version of the Xapian C++ library being used.
166           E.g. for Xapian 1.0.9 this would return 1.
167
168       minor_version
169           Returns the minor version of the Xapian C++ library being used.
170           E.g. for Xapian 1.0.9 this would return 0.
171
172       revision
173           Returns the revision of the Xapian C++ library being used.  E.g.
174           for Xapian 1.0.9 this would return 9.  In a stable release series,
175           Xapian libraries with the same minor and major versions are usually
176           ABI compatible, so this often won't match the third component of
177           $Search::Xapian::VERSION (which is the version of the
178           Search::Xapian XS wrappers).
179

Numeric encoding functions

181       sortable_serialise NUMBER
182           Convert a floating point number to a string, preserving sort order.
183
184           This method converts a floating point number to a string, suitable
185           for using as a value for numeric range restriction, or for use as a
186           sort key.
187
188           The conversion is platform independent.
189
190           The conversion attempts to ensure that, for any pair of values
191           supplied to the conversion algorithm, the result of comparing the
192           original values (with a numeric comparison operator) will be the
193           same as the result of comparing the resulting values (with a string
194           comparison operator).  On platforms which represent doubles with
195           the precisions specified by IEEE_754, this will be the case: if the
196           representation of doubles is more precise, it is possible that two
197           very close doubles will be mapped to the same string, so will
198           compare equal.
199
200           Note also that both zero and -zero will be converted to the same
201           representation: since these compare equal, this satisfies the
202           comparison constraint, but it's worth knowing this if you wish to
203           use the encoding in some situation where this distinction matters.
204
205           Handling of NaN isn't (currently) guaranteed to be sensible.
206
207       sortable_unserialise SERIALISED_NUMBER
208           Convert a string encoded using sortable_serialise back to a
209           floating point number.
210
211           This expects the input to be a string produced by
212           sortable_serialise().  If the input is not such a string, the value
213           returned is undefined (but no error will be thrown).
214
215           The result of the conversion will be exactly the value which was
216           supplied to sortable_serialise() when making the string on
217           platforms which represent doubles with the precisions specified by
218           IEEE_754, but may be a different (nearby) value on other platforms.
219

TODO

221       Error Handling
222           Error handling for all methods liable to generate them.
223
224       Documentation
225           Add POD documentation for all classes, where possible just adapted
226           from Xapian docs.
227
228       Unwrapped classes
229           The following Xapian classes are not yet wrapped: ErrorHandler,
230           standard ExpandDecider subclasses (user-defined ones works), user-
231           defined weight classes.
232
233       Unwrapped methods
234           The following methods are not yet wrapped: Enquire::get_eset(...)
235           with more than two arguments, Query ctor optional "parameter"
236           parameter, Remote::open(...), static
237           Stem::get_available_languages().
238
239           We wrap MSet::swap() and MSet::operator[](), but not ESet::swap(),
240           ESet::operator[]().  Is swap actually useful?  Should we instead
241           tie MSet and ESet to allow them to just be used as lists?
242

CREDITS

244       Thanks to Tye McQueen <tye@metronet.com> for explaining the finer
245       points of how best to write XS frontends to C++ libraries, James Aylett
246       <james@tartarus.org> for clarifying the less obvious aspects of the
247       Xapian API, Tim Brody for patches wrapping ::QueryParser and ::Stopper
248       and especially Olly Betts <olly@survex.com> for contributing advice,
249       bugfixes, and wrapper code for the more obscure classes.
250

AUTHOR

252       Alex Bowley <kilinrax@cpan.org>
253
254       Please report any bugs/suggestions to <xapian-discuss@lists.xapian.org>
255       or use the Xapian bug tracker <https://xapian.org/bugs>.  Please do NOT
256       use the CPAN bug tracker or mail any of the authors individually.
257

LICENSE

259       This program is free software; you can redistribute it and/or modify it
260       under the same terms as Perl itself.
261