Xapian(3pm)

NAME

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

SYNOPSIS

use Search::Xapian;

my $db = Search::Xapian::Database->new( '[DATABASE DIR]' );
my $enq = $db->enquire( '[QUERY TERM]' );

printf "Running query '%s'\n", $enq->get_query()->get_description();

my @matches = $enq->matches(0, 10);

print scalar(@matches) . " results found\n";

foreach my $match ( @matches ) {
  my $doc = $match->get_document();
  printf "ID %d %d%% [ %s ]\n", $match->get_docid(), $match->get_percent(), $doc->get_data();
}

DESCRIPTION

This module wraps most methods of most Xapian classes. The missing
classes and methods should be added in the future. It also provides a
simplified, more 'perlish' interface to some common operations, as
demonstrated above.

There are some gaps in the POD documentation for wrapped classes, but
you can read the Xapian C++ API documentation at
<http://xapian.org/docs/apidoc/html/annotated.html> for details of
these. Alternatively, take a look at the code in the examples and
tests.

If you want to use Search::Xapian and the threads module together, make sure you're using Search::Xapian >= 1.0.4.0 and Perl >= 5.8.7. As of
1.0.4.0, Search::Xapian uses CLONE_SKIP to make sure that the perl
wrapper objects aren't copied to new threads - without this the
underlying C++ objects can get destroyed more than once.

If you encounter problems, or have any comments, suggestions, patches, etc please email the Xapian-discuss mailing list (details of which can be found at <http://xapian.org/lists>).
EXPORT: None by default.
:db
DB_OPEN: Open a database, fail if database doesn't exist.
DB_CREATE: Create a new database, fail if database exists.
DB_CREATE_OR_OPEN: Open an existing database, without destroying data, or create a new database if one doesn't already exist.
DB_CREATE_OR_OVERWRITE: Overwrite database if it exists.
:ops
OP_AND: Match if both subqueries are satisfied.
OP_OR: Match if either subquery is satisfied.
OP_AND_NOT: Match if left but not right subquery is satisfied.
OP_XOR: Match if left or right, but not both queries are satisfied.
OP_AND_MAYBE: Match if left is satisfied, but use weights from both.
OP_FILTER: Like OP_AND, but only weight using the left query.
OP_NEAR: Match if the words are near each other. The window should be
specified, as a parameter to "Search::Xapian::Query::Query", but it defaults to the number of terms in the list.
OP_PHRASE: Match as a phrase (All words in order).
OP_ELITE_SET: Select an elite set from the subqueries, and perform a query with
these combined as an OR query.
OP_VALUE_RANGE: Filter by a range test on a document value.
:qpflags
FLAG_DEFAULT: This gives the QueryParser default flag settings, allowing you to
easily add flags to the default ones.
FLAG_BOOLEAN: Support AND, OR, etc and bracketted subexpressions.
FLAG_LOVEHATE: Support + and -.
FLAG_PHRASE: Support quoted phrases.
FLAG_BOOLEAN_ANY_CASE: Support AND, OR, etc even if they aren't in ALLCAPS.
FLAG_WILDCARD: Support right truncation (e.g. Xap*).
FLAG_PURE_NOT: Allow queries such as 'NOT apples'.; These require the use of a list of all documents in the database
which is potentially expensive, so this feature isn't enabled by
default.
FLAG_PARTIAL: Enable partial matching.; Partial matching causes the parser to treat the query as a
"partially entered" search. This will automatically treat the
final word as a wildcarded match, unless it is followed by
whitespace, to produce more stable results from interactive
searches.
FLAG_SPELLING_CORRECTION FLAG_SYNONYM FLAG_AUTO_SYNONYMS FLAG_AUTO_MULTIWORD_SYNONYMS
:qpstem
STEM_ALL: Stem all terms.
STEM_NONE: Don't stem any terms.
STEM_SOME: Stem some terms, in a manner compatible with Omega (capitalised
words and those in phrases aren't stemmed).
:enq_order
ENQ_ASCENDING: docids sort in ascending order (default)
ENQ_DESCENDING: docids sort in descending order
ENQ_DONT_CARE: docids sort in whatever order is most efficient for the backend
:standard
Standard is db + ops + qpflags + qpstem

Version functions

major_version: Returns the major version of the Xapian C++ library being used.
E.g. for Xapian 1.0.9 this would return 1.
minor_version: Returns the minor version of the Xapian C++ library being used.
E.g. for Xapian 1.0.9 this would return 0.
revision: Returns the revision of the Xapian C++ library being used. E.g.
for Xapian 1.0.9 this would return 9. In a stable release series, Xapian libraries with the same minor and major versions are usually ABI compatible, so this often won't match the third component of
$Search::Xapian::VERSION (which is the version of the
Search::Xapian XS wrappers).

Numeric encoding functions

sortable_serialise NUMBER: Convert a floating point number to a string, preserving sort order.; This method converts a floating point number to a string, suitable for using as a value for numeric range restriction, or for use as a sort key.; The conversion is platform independent.; The conversion attempts to ensure that, for any pair of values
supplied to the conversion algorithm, the result of comparing the
original values (with a numeric comparison operator) will be the
same as the result of comparing the resulting values (with a string comparison operator). On platforms which represent doubles with
the precisions specified by IEEE_754, this will be the case: if the representation of doubles is more precise, it is possible that two very close doubles will be mapped to the same string, so will
compare equal.; Note also that both zero and -zero will be converted to the same
representation: since these compare equal, this satisfies the
comparison constraint, but it's worth knowing this if you wish to
use the encoding in some situation where this distinction matters.; Handling of NaN isn't (currently) guaranteed to be sensible.
sortable_unserialise SERIALISED_NUMBER: Convert a string encoded using sortable_serialise back to a
floating point number.; This expects the input to be a string produced by
sortable_serialise(). If the input is not such a string, the value returned is undefined (but no error will be thrown).; The result of the conversion will be exactly the value which was
supplied to sortable_serialise() when making the string on platforms which represent doubles with the precisions specified by IEEE_754, but may be a different (nearby) value on other platforms.

TODO

Error Handling: Error handling for all methods liable to generate them.
Documentation: Add POD documentation for all classes, where possible just adapted from Xapian docs.
Unwrapped classes: The following Xapian classes are not yet wrapped: Error (and
subclasses), ErrorHandler, standard ExpandDecider subclasses (userdefined ones works), user-defined weight classes.; We don't yet wrap Xapian::Query::MatchAll,
Xapian::Query::MatchNothing, or Xapian::BAD_VALUENO.
Unwrapped methods: The following methods are not yet wrapped: Enquire::get_eset(...)
with more than two arguments, Query ctor optional "parameter"
parameter, Remote::open(...), static
Stem::get_available_languages().; We wrap MSet::swap() and MSet::operator[](), but not ESet::swap(), ESet::operator[](). Is swap actually useful? Should we instead
tie MSet and ESet to allow them to just be used as lists?

CREDITS

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

AUTHOR

Alex Bowley <kilinrax@cpan.org>

Please report any bugs/suggestions to <xapian-discuss@lists.xapian.org> or use the Xapian bug tracker <http://xapian.org/bugs>. Please do NOT use the CPAN bug tracker or mail any of the authors individually.

docs.sk

comprehensive documentation repository

Most Viewed