xapian Package

xapian Package

Xapian is a highly adaptable toolkit which allows developers to easily add advanced indexing and search facilities to their own applications. It has built-in support for several families of weighting models and also supports a rich set of boolean query operators.

In addition to the doc strings provided by this python library, you may wish to look at the library’s overall documentation, either installed along with the bindings or online at <https://xapian.org/docs/bindings/python/>, as well as the library’s documentation, possibly installed with the library or with its development files, or again online at <https://xapian.org/docs/>.

exception xapian.AssertionError(*args)

Bases: xapian.LogicError

AssertionError is thrown if a logical assertion inside Xapian fails.

In a debug build of Xapian, a failed assertion in the core library code will cause AssertionError to be thrown.

This represents a bug in Xapian (either an invariant, precondition, etc has been violated, or the assertion is incorrect!)

property thisown

The membership flag

class xapian.BB2Weight(*args)

Bases: xapian.Weight

This class implements the BB2 weighting scheme.

BB2 is a representative scheme of the Divergence from Randomness Framework by Gianni Amati.

It uses the Bose-Einstein probabilistic distribution (B) along with Stirling’s power approximation, the Bernoulli method to find the aftereffect of sampling (B) and the second wdf normalization proposed by Amati to normalize the wdf in the document to the length of the document (H2).

For more information about the DFR Framework and the BB2 scheme, please refer to : Gianni Amati and Cornelis Joost Van Rijsbergen Probabilistic models of information retrieval based on measuring the divergence from randomness ACM Transactions on Information Systems (TOIS) 20, (4), 2002, pp. 357-389.

create_from_parameters()

Create from a human-readable parameter string.

BB2Weight * Xapian::BB2Weight::create_from_parameters(const char *params) const Xapian::BB2Weight::create_from_parameters

params: string containing weighting scheme parameter values.

2.0.0

property thisown

The membership flag

class xapian.BM25PlusWeight(*args)

Bases: xapian.Weight

Xapian::Weight subclass implementing the BM25+ probabilistic formula.

create_from_parameters()

Create from a human-readable parameter string.

BM25PlusWeight * Xapian::BM25PlusWeight::create_from_parameters(const char *params) const Xapian::BM25PlusWeight::create_from_parameters

params: string containing weighting scheme parameter values.

2.0.0

property thisown

The membership flag

class xapian.BM25Weight(*args)

Bases: xapian.Weight

Xapian::Weight subclass implementing the BM25 probabilistic formula.

create_from_parameters()

Create from a human-readable parameter string.

BM25Weight * Xapian::BM25Weight::create_from_parameters(const char *params) const Xapian::BM25Weight::create_from_parameters

params: string containing weighting scheme parameter values.

2.0.0

property thisown

The membership flag

class xapian.BoolWeight

Bases: xapian.Weight

Class implementing a “boolean” weighting scheme.

This weighting scheme gives all documents zero weight.

create_from_parameters()

Create from a human-readable parameter string.

BoolWeight * Xapian::BoolWeight::create_from_parameters(const char *params) const Xapian::BoolWeight::create_from_parameters

params: string containing weighting scheme parameter values.

2.0.0

property thisown

The membership flag

class xapian.Compactor

Bases: object

Compact a database, or merge and compact several.

FULL = 1

FULLER = 2

STANDARD = 0

resolve_duplicate_metadata()

Resolve multiple user metadata entries with the same key.

virtual std::string Xapian::Compactor::resolve_duplicate_metadata(const std::string &key, size_t num_tags, const std::string tags[]) Xapian::Compactor::resolve_duplicate_metadata When merging, if the same user metadata key is set in more than one input, then this method is called to allow this to be resolving in an appropriate way.

The default implementation just returns tags[0].

For multipass this will currently get called multiple times for the same key if there are duplicates to resolve in each pass, but this may change in the future.

Since 1.4.6, an implementation of this method can return an empty string to indicate that the appropriate result is to not set a value for this user metadata key in the output database. In older versions, you should not return an empty string.

key: The metadata key with duplicate entries.

num_tags: How many tags there are.

tags: An array of num_tags strings containing the tags to merge.

set_status()

Update progress.

virtual void Xapian::Compactor::set_status(const std::string &table, const std::string &status) Xapian::Compactor::set_status Subclass this method if you want to get progress updates during compaction. This is called for each table first with empty status, And then one or more times with non-empty status.

The default implementation does nothing.

table: The table currently being compacted.

status: A status message.

property thisown

The membership flag

class xapian.CoordWeight

Bases: xapian.Weight

Xapian::Weight subclass implementing Coordinate Matching.

Each matching term scores one point. See Managing Gigabytes, Second Edition p181.

create_from_parameters()

Create from a human-readable parameter string.

CoordWeight * Xapian::CoordWeight::create_from_parameters(const char *params) const Xapian::CoordWeight::create_from_parameters

params: string containing weighting scheme parameter values.

2.0.0

init()

Allow the subclass to perform any initialisation it needs to.

void Xapian::CoordWeight::init(double factor_) Xapian::CoordWeight::init

factor: Any scaling factor (e.g. from OP_SCALE_WEIGHT). If the Weight object is for the term-independent weight supplied by get_sumextra()/get_maxextra(), then init(0.0) is called (starting from Xapian 1.2.11 and 1.3.1 - earlier versions failed to call init() for such Weight objects).

property thisown

The membership flag

class xapian.DLHWeight

Bases: xapian.Weight

This class implements the DLH weighting scheme, which is a representative scheme of the Divergence from Randomness Framework by Gianni Amati.

This is a parameter free weighting scheme and it should be used with query expansion to obtain better results. It uses the HyperGeometric Probabilistic model and Laplace’s normalization to calculate the risk gain.

For more information about the DFR Framework and the DLH scheme, please refer to : a.) Gianni Amati and Cornelis Joost Van Rijsbergen Probabilistic models of information retrieval based on measuring the divergence from randomness ACM Transactions on Information Systems (TOIS) 20, (4), 2002, pp. 357-389. b.) FUB, IASI-CNR and University of Tor Vergata at TREC 2007 Blog Track. G. Amati and E. Ambrosi and M. Bianchi and C. Gaibisso and G. Gambosi. Proceedings of the 16th Text REtrieval Conference (TREC-2007), 2008.

create_from_parameters()

Create from a human-readable parameter string.

DLHWeight * Xapian::DLHWeight::create_from_parameters(const char *params) const Xapian::DLHWeight::create_from_parameters

params: string containing weighting scheme parameter values.

2.0.0

property thisown

The membership flag

class xapian.DPHWeight

Bases: xapian.Weight

This class implements the DPH weighting scheme.

DPH is a representative scheme of the Divergence from Randomness Framework by Gianni Amati.

This is a parameter free weighting scheme and it should be used with query expansion to obtain better results. It uses the HyperGeometric Probabilistic model and Popper’s normalization to calculate the risk gain.

For more information about the DFR Framework and the DPH scheme, please refer to : a.) Gianni Amati and Cornelis Joost Van Rijsbergen Probabilistic models of information retrieval based on measuring the divergence from randomness ACM Transactions on Information Systems (TOIS) 20, (4), 2002, pp. 357-389. b.) FUB, IASI-CNR and University of Tor Vergata at TREC 2007 Blog Track. G. Amati and E. Ambrosi and M. Bianchi and C. Gaibisso and G. Gambosi. Proceedings of the 16th Text Retrieval Conference (TREC-2007), 2008.

create_from_parameters()

Create from a human-readable parameter string.

DPHWeight * Xapian::DPHWeight::create_from_parameters(const char *params) const Xapian::DPHWeight::create_from_parameters

params: string containing weighting scheme parameter values.

2.0.0

property thisown

The membership flag

class xapian.Database(*args)

Bases: object

An indexed database of documents.

A Database object contains zero or more shards, and operations are performed across these shards.

To perform a search on a Database, you need to use an Enquire object.

2.0.0 This class is a reference counted handle like many other Xapian API classes. In earlier versions, it worked like a typedef to std::vector<database_shard>. The key difference is that previously copying or assigning a Xapian::Database made a deep copy, whereas now it makes a shallow copy. Most methods can throw:

Xapian::DatabaseCorruptError: if database corruption is detected

Xapian::DatabaseError: in various situation (for example, if there’s an I/O error).

Xapian::DatabaseModifiedError: if the revision being read has been discarded

Xapian::DatabaseClosedError: may be thrown by some methods after after close() has been called

Xapian::NetworkError: when remote databases are in use

add_database()

Add shards from another Database.

void Xapian::Database::add_database(const Database &other) Xapian::Database::add_database Any shards in other are appended to the list of shards in this object. The shards are reference counted and also remain in other.

other: Another Database to add shards from

Xapian::InvalidArgumentError: if other is the same object as this.

allterms(prefix=None)

Get an iterator over all the terms in the database.

The iterator will return TermListItem objects, but these will not support access to wdf, or position information.

Access to term frequency information is only available until the iterator has moved on.

If prefix is supplied, only terms which start with that prefix will be returned.

static check()

close()

Close the database.

void Xapian::Database::close() Xapian::Database::close This closes the database and closes all its file handles.

For a WritableDatabase, if a transaction is active it will be aborted, while if no transaction is active commit() will be implicitly called. Also the write lock is released.

Calling close() on an object cannot be undone - in particular, a subsequent call to reopen() on the same object will not reopen it, but will instead throw a Xapian::DatabaseClosedError exception.

Calling close() again on an object which has already been closed has no effect (and doesn’t raise an exception).

After close() has been called, calls to other methods of the database, and to methods of other objects associated with the database, will either:

behave exactly as they would have done if the database had not been closed (this can only happen if all the required data is cached)

raise a Xapian::DatabaseClosedError exception.

The reason for this behaviour is that otherwise we’d have to check that the database is still open on every method call on every object associated with a Database, when in many cases they are working on data which has already been loaded and so they are able to just behave correctly.

This method was added in Xapian 1.1.0.

compact()

Produce a compact version of this database.

void Xapian::Database::compact(int fd, unsigned flags, int block_size, Xapian::Compactor &compactor) Xapian::Database::compact The compactor functor allows handling progress output and specifying how user metadata is merged.

This variant writes a single-file database to the specified file descriptor. Only the glass backend supports such databases, so this form is only supported for this backend.

fd: File descriptor to write the compact version to. The descriptor needs to be readable and writable (open with O_RDWR) and seekable. The current file offset is used, allowing compacting to a single file database embedded within another file. Xapian takes ownership of the file descriptor and will close it before returning.

flags: Any of the following combined using bitwise-or (| in C++): Xapian::DBCOMPACT_NO_RENUMBER By default the document ids will be renumbered the output - currently by applying the same offset to all the document ids in a particular source database. If this flag is specified, then this renumbering doesn’t happen, but all the document ids must be unique over all source databases. Currently the ranges of document ids in each source must not overlap either, though this restriction may be removed in the future.

Xapian::DBCOMPACT_MULTIPASS If merging more than 3 databases, merge the postlists in multiple passes, which is generally faster but requires more disk space for temporary files.

Xapian::DBCOMPACT_SINGLE_FILE Produce a single-file database (only supported for glass currently).

At most one of: Xapian::Compactor::STANDARD - Don’t split items unnecessarily.

Xapian::Compactor::FULL - Split items whenever it saves space (the default).

Xapian::Compactor::FULLER - Allow oversize items to save more space (not recommended if you ever plan to update the compacted database).

1.4.31 Has the same effect as FULL.

block_size: This specifies the block size (in bytes) for to use for the output. For glass, the block size must be a power of 2 between 2048 and 65536 (inclusive), and the default (also used if an invalid value is passed) is 8192 bytes.

compactor: Functor

1.3.4 This method was added to replace various methods of the Compactor class.

get_average_length()

Get the mean document length in the database.

double Xapian::Database::get_average_length() const Xapian::Database::get_average_length

get_avlength()

Old name for get_average_length() for backward compatibility.

double Xapian::Database::get_avlength() const Xapian::Database::get_avlength

get_collection_freq()

Get the total number of occurrences of a specified term.

Xapian::termcount Xapian::Database::get_collection_freq(std::string_view term) const Xapian::Database::get_collection_freq The collection frequency of a term is defined as the total number of times it occurs in the database, which is the sum of its wdf in all the documents it indexes.

term: The term to get the collection frequency of. An empty string acts as a special pseudo-term which indexes all the documents in the database, so returns get_doccount(). If the term isn’t present in the database, 0 is returned.

get_doccount()

Get the number of documents in the database.

Xapian::doccount Xapian::Database::get_doccount() const Xapian::Database::get_doccount

get_doclength()

Get the length of a specified document.

Xapian::termcount Xapian::Database::get_doclength(Xapian::docid did) const Xapian::Database::get_doclength

did: The document id of the document

Xapian defines a document’s length as the sum of the wdf of all the terms which index it.

get_doclength_lower_bound()

Get a lower bound on the length of a document in this DB.

Xapian::termcount Xapian::Database::get_doclength_lower_bound() const Xapian::Database::get_doclength_lower_bound This bound does not include any zero-length documents.

get_doclength_upper_bound()

Get an upper bound on the length of a document in this DB.

Xapian::termcount Xapian::Database::get_doclength_upper_bound() const Xapian::Database::get_doclength_upper_bound

get_document()

Get a document from the database.

Xapian::Document Xapian::Database::get_document(Xapian::docid did, unsigned flags=0) const Xapian::Database::get_document The returned object acts as a handle which lazily fetches information about the specified document from the database.

did: The document ID of the document to be get

flags: Zero or more flags bitwise-or-ed together (currently only Xapian::DOC_ASSUME_VALID is supported). (default: 0)

The flags parameter was added in Xapian 2.0.0.

Xapian::InvalidArgumentError: is thrown if did is 0.

Xapian::DocNotFoundError: is thrown if the specified docid is not present in this database.

get_lastdocid()

Get the highest document id which has been used in the database.

Xapian::docid Xapian::Database::get_lastdocid() const Xapian::Database::get_lastdocid

get_metadata()

Get the user-specified metadata associated with a given key.

std::string Xapian::Database::get_metadata(std::string_view key) const Xapian::Database::get_metadata User-specified metadata allows you to store arbitrary information in the form of (key, value) pairs. See WritableDatabase::set_metadata() for more information.

When invoked on a Xapian::Database object representing multiple databases, currently only the metadata for the first is considered but this behaviour may change in the future.

If there is no piece of metadata associated with the specified key, an empty string is returned (this applies even for backends which don’t support metadata).

Empty keys are not valid, and specifying one will cause an exception.

key: The key of the metadata item to access.

The retrieved metadata item’s value.

Xapian::InvalidArgumentError: will be thrown if the key supplied is empty.

get_revision()

Get the revision of the database.

Xapian::rev Xapian::Database::get_revision() const Xapian::Database::get_revision The revision is an unsigned integer which increases with each commit.

Xapian::InvalidOperationError: If the database consists of more than one shard.

Xapian::UnimplementedError: Currently this is only implemented for glass.

In: Xapian < 1.4.13, if the database consists of no shards; In Xapian >= 1.4.13 this method returns 0 if there are no shards.

Experimental - seehttps://xapian.org/docs/deprecation#experimental- features

get_spelling_suggestion()

Suggest a spelling correction.

std::string Xapian::Database::get_spelling_suggestion(std::string_view word, unsigned max_edit_distance=2) const Xapian::Database::get_spelling_suggestion

word: The potentially misspelled word.

max_edit_distance: Only consider words which are at most max_edit_distance edits from word. An edit is a character insertion, deletion, or the transposition of two adjacent characters (default is 2).

get_termfreq()

Get the number of documents indexed by a specified term.

Xapian::doccount Xapian::Database::get_termfreq(std::string_view term) const Xapian::Database::get_termfreq

term: The term to get the frequency of. An empty string acts as a special pseudo-term which indexes all the documents in the database, so returns get_doccount(). If the term isn’t present in the database, 0 is returned.

get_total_length()

Get the total length of all the documents in the database.

Xapian::totallength Xapian::Database::get_total_length() const Xapian::Database::get_total_length

Added in Xapian 1.4.5.

get_unique_terms()

Get the number of unique terms in a specified document.

Xapian::termcount Xapian::Database::get_unique_terms(Xapian::docid did) const Xapian::Database::get_unique_terms

did: The document id of the document

This is the number of different terms which index the given document.

get_unique_terms_lower_bound()

Get a lower bound on the unique terms size of a document in this DB.

Xapian::termcount Xapian::Database::get_unique_terms_lower_bound() const Xapian::Database::get_unique_terms_lower_bound

Added in Xapian 2.0.0.

get_unique_terms_upper_bound()

Get an upper bound on the unique terms size of a document in this DB.

Xapian::termcount Xapian::Database::get_unique_terms_upper_bound() const Xapian::Database::get_unique_terms_upper_bound

Added in Xapian 2.0.0.

get_uuid()

Get the UUID for the database.

std::string Xapian::Database::get_uuid() const Xapian::Database::get_uuid The UUID will persist for the lifetime of the database.

Replicas (eg, made with the replication protocol, or by copying all the database files) will have the same UUID. However, copies (made with copydatabase, or xapian-compact) will have different UUIDs.

If the backend does not support UUIDs or this database has no subdatabases, the UUID will be empty.

If this database has multiple sub-databases, the UUID string will contain the UUIDs of all the sub-databases separated by colons.

get_value_freq()

Return the frequency of a given value slot.

Xapian::doccount Xapian::Database::get_value_freq(Xapian::valueno slot) const Xapian::Database::get_value_freq This is the number of documents which have a (non-empty) value stored in the slot.

slot: The value slot to examine.

get_value_lower_bound()

Get a lower bound on the values stored in the given value slot.

std::string Xapian::Database::get_value_lower_bound(Xapian::valueno slot) const Xapian::Database::get_value_lower_bound If there are no values stored in the given value slot, this will return an empty string.

slot: The value slot to examine.

get_value_upper_bound()

Get an upper bound on the values stored in the given value slot.

std::string Xapian::Database::get_value_upper_bound(Xapian::valueno slot) const Xapian::Database::get_value_upper_bound If there are no values stored in the given value slot, this will return an empty string.

slot: The value slot to examine.

get_wdf_upper_bound()

Get an upper bound on the wdf of term term.

Xapian::termcount Xapian::Database::get_wdf_upper_bound(std::string_view term) const Xapian::Database::get_wdf_upper_bound

get_wdfdocmax()

Get the maximum wdf value in a specified document.

Xapian::termcount Xapian::Database::get_wdfdocmax(Xapian::docid did) const Xapian::Database::get_wdfdocmax

did: The document id of the document

Added in Xapian 2.0.0.

has_positions()

Does this database have any positional information?

bool Xapian::Database::has_positions() const Xapian::Database::has_positions

keep_alive()

Send a keep-alive message.

void Xapian::Database::keep_alive() Xapian::Database::keep_alive For remote databases, this method sends a message to the server to reset the timeout timer. As well as preventing timeouts at the Xapian remote protocol level, this message will also avoid timeouts at lower levels.

For local databases, this method does nothing.

lock()

Lock a read-only database for writing.

Xapian::WritableDatabase Xapian::Database::lock(int flags=0) Xapian::Database::lock If the database is actually already writable (i.e. a WritableDatabase via a Database reference) then the same database is returned (with its flags updated, so this provides an efficient way to modify flags on an open WritableDatabase).

Unlike unlock(), the object this is called on remains open.

flags: The flags to use for the writable database. Flags which specify how to open the database are ignored (e.g. DB_CREATE_OR_OVERWRITE doesn’t result in the database being wiped), and flags which specify the backend are also ignored as they are only relevant when creating a new database.

A WritableDatabase object open on the same database.

Added in Xapian 2.0.0.

locked()

Test if this database is currently locked for writing.

bool Xapian::Database::locked() const Xapian::Database::locked If the underlying object is actually a WritableDatabase, always returns true unless close() has been called.

Otherwise tests if there’s a writer holding the lock (or if we can’t test for a lock without taking it on the current platform, throw Xapian::UnimplementedError). If there’s an error while trying to test the lock, throws Xapian::DatabaseLockError.

For multi-databases, this tests each sub-database and returns true if any of them are locked.

metadata_keys(prefix='')

Get an iterator which returns all the metadata keys.

The iterator will return string objects.

If prefix is non-empty, only metadata keys with this prefix are returned.

positionlist(docid, tname)

Get an iterator over all the positions in a given document of a term.

The iterator will return integers, in ascending order.

postlist(tname)

Get an iterator over the postings which are indexed by a given term.

If tname is empty, an iterator over all the documents will be returned (this will contain one entry for each document, will always return a wdf of 1, and will not allow access to a position iterator).

reconstruct_text()

Reconstruct document text.

std::string Xapian::Database::reconstruct_text(Xapian::docid did, size_t length=0, std::string_view prefix={}, Xapian::termpos start_pos=0, Xapian::termpos end_pos=0) const Xapian::Database::reconstruct_text This uses term positional information to reconstruct the document text which was indexed. Reading the required positional information is potentially quite I/O intensive.

The reconstructed text will be missing punctuation and most capitalisation.

did: The document id of the document to reconstruct

length: Number of bytes of text to aim for - note that slightly more may be returned (default: 0 meaning unlimited)

prefix: Term prefix to reconstruct (default: none)

start_pos: First position to reconstruct (default: 0)

end_pos: Last position to reconstruct (default: 0 meaning all)

Added in Xapian 2.0.0.

reopen()

Reopen the database at the latest available revision.

bool Xapian::Database::reopen() Xapian::Database::reopen Xapian databases (at least with most backends) support versioning such that a Database object uses a snapshot of the database. However, write operations may cause this snapshot to be discarded, which can cause Xapian::DatabaseModifiedError to be thrown. You can recover from this situation by calling reopen() and restarting the search operation.

All shards are updated to the latest available revision. This should be a cheap operation if they’re already at the latest revision, so if you’re using the same Database object for many searches it’s reasonable to call reopen() before each search.

true if one or more shards have moved to a newer revision (if false is returned then it’s definitely the case that no shards were reopened, which applications may find useful when caching results, etc). In Xapian < 1.3.0, this method did not return a value.

Xapian::DatabaseError: is thrown if close() has been called on any of the shards.

size()

Return number of shards in this Database object.

size_t Xapian::Database::size() const Xapian::Database::size If you want the number of documents, see @ get_doccount().

Xapian 1.4.12

spellings()

Get an iterator which returns all the spelling correction targets

The iterator will return TermListItem objects. Only the term frequency is available; wdf and positions are not meaningful.

synonym_keys(prefix='')

Get an iterator which returns all the terms which have synonyms.

The iterator will return string objects.

If prefix is non-empty, only terms with this prefix are returned.

synonyms(term)

Get an iterator which returns all the synonyms for a given term.

The term to return synonyms for is specified by the term parameter.

The iterator will return string objects.

term_exists()

Test is a particular term is present in any document.

bool Xapian::Database::term_exists(std::string_view term) const Xapian::Database::term_exists

term: The term to test for. An empty string acts as a special pseudo- term which indexes all the documents in the database, so returns true if the database contains any documents.

db.term_exists(t) gives the same answer as db.get_termfreq(t) != 0, but is typically more efficient.

termlist(docid)

Get an iterator over all the terms which index a given document ID.

The iterator will return TermListItem objects.

Access to term frequency and position information is only available until the iterator has moved on.

property thisown

The membership flag

unlock()

Release a database write lock.

Xapian::Database Xapian::Database::unlock() Xapian::Database::unlock If called on a read-only database then the same database is returned.

If called on a writable database, the object this method was called on is closed.

A Database object open on the same database.

Added in Xapian 2.0.0.

valuestream(slot)

Get an iterator over all the values stored in a slot in the database.

The iterator will return ValueStreamItem objects, in ascending order of document id.

exception xapian.DatabaseClosedError(*args)

Bases: xapian.DatabaseError

Indicates an attempt to access a closed database.

property thisown

The membership flag

exception xapian.DatabaseCorruptError(*args)

Bases: xapian.DatabaseError

DatabaseCorruptError indicates database corruption was detected.

property thisown

The membership flag

exception xapian.DatabaseCreateError(*args)

Bases: xapian.DatabaseError

DatabaseCreateError indicates a failure to create a database.

property thisown

The membership flag

exception xapian.DatabaseError(*args)

Bases: xapian.RuntimeError

DatabaseError indicates some sort of database related error.

property thisown

The membership flag

exception xapian.DatabaseLockError(*args)

Bases: xapian.DatabaseError

DatabaseLockError indicates failure to lock a database.

property thisown

The membership flag

exception xapian.DatabaseModifiedError(*args)

Bases: xapian.DatabaseError

DatabaseModifiedError indicates a database was modified.

To recover after catching this error, you need to call Xapian::Database::reopen() on the Database and repeat the operation which failed.

property thisown

The membership flag

exception xapian.DatabaseNotFoundError(*args)

Bases: xapian.DatabaseOpeningError

Indicates an attempt to access a database not present.

property thisown

The membership flag

exception xapian.DatabaseOpeningError(*args)

Bases: xapian.DatabaseError

DatabaseOpeningError indicates failure to open a database.

property thisown

The membership flag

exception xapian.DatabaseVersionError(*args)

Bases: xapian.DatabaseOpeningError

DatabaseVersionError indicates that a database is in an unsupported format.

From time to time, new versions of Xapian will require the database format to be changed, to allow new information to be stored or new optimisations to be performed. Backwards compatibility will sometimes be maintained, so that new versions of Xapian can open old databases, but in some cases Xapian will be unable to open a database because it is in too old (or new) a format. This can be resolved either be upgrading or downgrading the version of Xapian in use, or by rebuilding the database from scratch with the current version of Xapian.

property thisown

The membership flag

class xapian.DateRangeProcessor(*args)

Bases: xapian.RangeProcessor

Handle a date range.

Begin and end must be dates in a recognised format.

property thisown

The membership flag

class xapian.DecreasingValueWeightPostingSource(slot_, range_start_=0, range_end_=0)

Bases: xapian.ValueWeightPostingSource

Read weights from a value which is known to decrease as docid increases.

This posting source can be used, like ValueWeightPostingSource, to add a weight contribution to a query based on the values stored in a slot. The values in the slot must be serialised as by sortable_serialise().

However, this posting source is additionally given an inclusive range of document IDs within which the weight is known to be decreasing, so if documents in this range have IDs A and B and B > A then weight of B <= weight of A. This can allow the posting source to skip to the end of the range quickly if insufficient weight is left in the posting source for a particular query to match.

By default, the range is assumed to cover all document IDs.

The ordering property would typically be arranged at index time by controlling the order that documents are indexed in.

property thisown

The membership flag

class xapian.DiceWeight

Bases: xapian.Weight

Xapian::Weight subclass implementing Dice Coefficient.

The Dice Coefficient measures the degree of similarity between pairs of sets (in Xapian, these sets are words in a document and words in a query).

https://en.wikipedia.org/wiki/Dice-S%C3%B8rensen_coefficient

(It’s named after Lee Raymond Dice rather than after cubes or other polyhedra with numbered sides which are rolled to generate random numbers in games.)

Ranking by the Dice Coefficient is the same ranking by the Jaccard coefficient since you can calculate Jaccard coefficient J from Dice coefficient D using equation J = D / (2 - D) which is a monotonic for the range [0,1] (the range of possible Dice coefficient values).

2.0.0

create_from_parameters()

Create from a human-readable parameter string.

DiceWeight * Xapian::DiceWeight::create_from_parameters(const char *params) const Xapian::DiceWeight::create_from_parameters

params: string containing weighting scheme parameter values.

2.0.0

property thisown

The membership flag

exception xapian.DocNotFoundError(*args)

Bases: xapian.RuntimeError

Indicates an attempt to access a document not present in the database.

property thisown

The membership flag

class xapian.Document

Bases: object

Class representing a document.

The term “document” shouldn’t be taken too literally - really it’s a “thing to retrieve”, as the list of search results is essentially a list of documents.

Document objects fetch information from the database lazily. Usually this behaviour isn’t visible to users (except for the speed benefits), but if the document in the database is modified or deleted then preexisting Document objects may return the old or new versions of data (or throw Xapian::DocNotFoundError in the case of deletion).

Since Database objects work on a snapshot of the database’s state, the situation above can only happen with a WritableDatabase object, or if you call Database::reopen() on the Database object which you got the Document from.

We recommend you avoid designs where this behaviour is an issue, but if you need a way to make a non-lazy version of a Document object, you can do this like so:doc = Xapian::Document::unserialise(doc.serialise());

add_boolean_term()

Add a boolean filter term to the document.

void Xapian::Document::add_boolean_term(std::string_view term) Xapian::Document::add_boolean_term This method adds term to the document with wdf of 0 - this is generally what you want for a term used for boolean filtering as the wdf of such terms is ignored, and it doesn’t make sense for them to contribute to the document’s length.

If the specified term already indexes this document, this method has no effect.

It is exactly the same as add_term(term, 0) and is provided as a way to make a common operation more explicit.

term: The term to add.

This method was added in Xapian 1.0.18.

add_posting()

Add a posting for a term.

void Xapian::Document::add_posting(std::string_view term, Xapian::termpos term_pos, Xapian::termcount wdf_inc=1) Xapian::Document::add_posting

add_term()

Add a term to this document.

void Xapian::Document::add_term(std::string_view term, Xapian::termcount wdf_inc=1) Xapian::Document::add_term

add_value()

Add a value to a slot in this document.

void Xapian::Document::add_value(Xapian::valueno slot, std::string_view value) Xapian::Document::add_value

slot: The slot to set

value: The new value

clear_terms()

Clear all terms from the document.

void Xapian::Document::clear_terms() Xapian::Document::clear_terms

clear_values()

Clear all value slots in this document.

void Xapian::Document::clear_values() Xapian::Document::clear_values

get_data()

Get the document data.

std::string Xapian::Document::get_data() const Xapian::Document::get_data

get_docid()

Get the document ID this document came from.

Xapian::docid Xapian::Document::get_docid() const Xapian::Document::get_docid If this document didn’t come from a database, this will be 0 (in Xapian 1.0.22/1.2.4 or later; prior to this the returned value was uninitialised in this case).

Note that if the document came from a sharded database, this is the docid in the shard it came from, not the docid in the combined database.

get_value()

Read a value slot in this document.

std::string Xapian::Document::get_value(Xapian::valueno slot) const Xapian::Document::get_value

slot: The slot to read the value from

The value in slot slot, or an empty string if not set.

remove_posting()

Remove posting for a term.

void Xapian::Document::remove_posting(std::string_view term, Xapian::termpos term_pos, Xapian::termcount wdf_dec=1) Xapian::Document::remove_posting The instance of the specified term at position term_pos will be removed, and the wdf reduced by wdf_dec (the wdf will not ever go below zero though - the resultant wdf is clamped to zero if it would).

If the term doesn’t occur at position term_pos then Xapian::InvalidArgumentError is thrown. If you want to remove a single position which may not be present without triggering an exception you can call remove_postings(term, pos, pos) instead.

Since 2.0.0, if the final position is removed and the wdf becomes zero then the term will be removed from the document.

remove_postings()

Remove a range of postings for a term.

Xapian::termpos Xapian::Document::remove_postings(std::string_view term, Xapian::termpos term_pos_first, Xapian::termpos term_pos_last, Xapian::termcount wdf_dec=1) Xapian::Document::remove_postings Any instances of the term at positions >= term_pos_first and <= term_pos_last will be removed, and the wdf reduced by wdf_dec for each instance removed (the wdf will not ever go below zero though - the resultant wdf is clamped to zero if it would).

If the term doesn’t occur in the range of positions specified (including if term_pos_first > term_pos_last) then this method does nothing (unlike remove_posting() which throws an exception if the specified position is not present).

Since 2.0.0, if all remaining positions are removed and the wdf becomes zero then the term will be removed from the document. Note that this only happens if some positions are removed though - calling this method on a term which has no positions and zero wdf won’t remove that term.

The number of postings removed.

Added in Xapian 1.4.8.

remove_term()

Remove a term from this document.

void Xapian::Document::remove_term(std::string_view term) Xapian::Document::remove_term

remove_value()

Remove any value from the specified slot.

void Xapian::Document::remove_value(Xapian::valueno slot) Xapian::Document::remove_value

slot: The slot to remove any value from.

serialise()

Serialise document into a string.

std::string Xapian::Document::serialise() const Xapian::Document::serialise The document representation may change between Xapian releases: even between minor versions. However, it is guaranteed not to change if the remote database protocol has not changed between releases.

set_data()

Set the document data.

void Xapian::Document::set_data(std::string_view data) Xapian::Document::set_data This is an opaque blob as far as Xapian is concerned - it’s up to you to impose whatever structure you want on it. If you want to store structured data, consider using something like protocol buffers.

termlist()

Get an iterator over all the terms in a document.

The iterator will return TermListItem objects.

Access to term frequency and position information is only available until the iterator has moved on.

Note that term frequency information is only meaningful for a document retrieved from a database. If term frequency information is requested for a document which was freshly created, an InvalidOperationError will be raised.

termlist_count()

Return the number of distinct terms in this document.

Xapian::termcount Xapian::Document::termlist_count() const Xapian::Document::termlist_count

property thisown

The membership flag

static unserialise()

values()

Get an iterator over all the values stored in a document.

The iterator will return ValueItem objects, in ascending order of value number.

values_count()

Count the value slots used in this document.

Xapian::valueno Xapian::Document::values_count() const Xapian::Document::values_count

class xapian.ESet

Bases: object

Class representing a list of search results.

back()

Return iterator pointing to the last object in this ESet.

ESetIterator Xapian::ESet::back() const Xapian::ESet::back

empty()

Return true if this ESet object is empty.

bool Xapian::ESet::empty() const Xapian::ESet::empty

get_ebound()

Return a bound on the full size of this ESet object.

Xapian::termcount Xapian::ESet::get_ebound() const Xapian::ESet::get_ebound This is a bound on size() if get_eset() had been called with maxitems set high enough that all results were returned.

size()

Return number of items in this ESet object.

Xapian::termcount Xapian::ESet::size() const Xapian::ESet::size

property thisown

The membership flag

class xapian.ESetItem(iter)

Bases: object

An item returned from iteration of the ESet.

The item supports access to the following attributes:

• term: The term corresponding to this ESet item.

• weight: The weight corresponding to this ESet item.

term

weight

class xapian.ESetIter(eset)

Bases: object

An iterator over the items in an ESet.

The iterator will return ESetItem objects.

class xapian.Enquire(db)

Bases: object

Querying session.

An Enquire object represents a querying session - most of the options for running a query can be set on it, and the query is run via Enquire::get_mset().

ASCENDING = 1

DESCENDING = 0

DONT_CARE = 2

INCLUDE_QUERY_TERMS = 1

USE_EXACT_TERMFREQ = 2

add_matchspy(decider)

Add a matchspy.

void Xapian::Enquire::add_matchspy(MatchSpy *spy) XAPIAN_NONNULL() Xapian::Enquire::add_matchspy This matchspy will be called with some of the documents which match the query, during the match process. Exactly which of the matching documents are passed to it depends on exactly when certain optimisations occur during the match process, but it can be controlled to some extent by setting the checkatleast parameter to get_mset().

In particular, if there are enough matching documents, at least the number specified by checkatleast will be passed to the matchspy. This means that you can force the matchspy to be shown all matching documents by setting checkatleast to the number of documents in the database.

spy: The MatchSpy subclass to add. The caller must ensure that this remains valid while the Enquire object remains active, or until clear_matchspies() is called, or else allocate the MatchSpy object with new and then disown it by calling spy->release() before passing it in.

clear_matchspies()

Remove all the matchspies.

void Xapian::Enquire::clear_matchspies() Xapian::Enquire::clear_matchspies

get_eset()

Perform query expansion.

ESet Xapian::Enquire::get_eset(termcount maxitems, const RSet &rset, const ExpandDecider *edecider) const Xapian::Enquire::get_eset Perform query expansion using a Xapian::RSet indicating some documents which are relevant (typically based on the user marking results or similar).

maxitems: The maximum number of terms to return.

rset: Documents marked as relevant.

edecider: Xapian::ExpandDecider object - this acts as a yes/no filter on terms which are being considered.

Xapian::ESet object containing a list of terms with weights.

get_mset()

Run the query.

MSet Xapian::Enquire::get_mset(doccount first, doccount maxitems, const RSet *rset, const MatchDecider *mdecider=NULL) const Xapian::Enquire::get_mset Run the query using the settings in this Enquire object and those passed as parameters to the method, and return a Xapian::MSet object.

first: Zero-based index of the first result to return (which supports retrieving pages of results).

maxitems: The maximum number of documents to return.

rset: Documents marked as relevant (default: no documents have been marked as relevant)

mdecider: Xapian::MatchDecider object - this acts as a yes/no filter on documents which match the query. See also Xapian::PostingSource. (default: no Xapian::MatchDecider)

get_query()

Get the currently set query.

const Query & Xapian::Enquire::get_query() const Xapian::Enquire::get_query If set_query() is not called before calling get_query(), then the default query Xapian::MatchNothing will be returned.

matching_terms(which)

Get an iterator over the terms which match a given match set item.

The match set item to consider is specified by the which parameter, which may be a document ID, or an MSetItem object.

The iterator will return string objects.

set_collapse_key()

Control collapsing of results.

void Xapian::Enquire::set_collapse_key(valueno collapse_key, doccount collapse_max=1) Xapian::Enquire::set_collapse_key The MSet returned by get_mset() will have only the “best” (at most) collapse_max documents with each particular non-empty value in slot collapse_key (“best” being highest ranked - i.e. highest weight or highest sorting key).

An example use might be to create a value for each document containing an MD5 hash of the document contents. Then duplicate documents from different sources can be eliminated at search time by collapsing with collapse_max = 1 (it’s better to eliminate duplicates at index time, but this may not be always be possible - for example the search may be over more than one Xapian database).

Another use is to group matches in a particular category (e.g. you might collapse a mailing list search on the Subject: so that there’s only one result per discussion thread). In this case you can use get_collapse_count() to give the user some idea how many other results there are. And if you index the Subject: as a boolean term as well as putting it in a value, you can offer a link to a non-collapsed search restricted to that thread using a boolean filter.

collapse_key: value slot to collapse on (default is Xapian::BAD_VALUENO which means no collapsing).

collapse_max: Maximum number of documents with the same key to allow (default: 1).

set_cutoff()

Set lower bounds on percentage and/or weight.

void Xapian::Enquire::set_cutoff(int percent_threshold, double weight_threshold=0) Xapian::Enquire::set_cutoff

percent_threshold: Lower bound on percentage score

weight_threshold: Lower bound on weight (default: 0)

No thresholds are applied by default, and if either threshold is set to 0, then that threshold is disabled.

set_docid_order()

Set sort order for document IDs.

void Xapian::Enquire::set_docid_order(docid_order order) Xapian::Enquire::set_docid_order This order only has an effect on documents which would otherwise have equal rank. When ordering by relevance without a sort key, this means documents with equal weight. For a boolean match with no sort key, this means all documents. And if a sort key is used, this means documents with the same sort key (and also equal weight if ordering on relevance before or after the sort key).

order: This can be: Xapian::Enquire::ASCENDING docids sort in ascending order (default)

Xapian::Enquire::DESCENDING docids sort in descending order

Xapian::Enquire::DONT_CARE docids sort in whatever order is most efficient for the backend

Note: If you add documents in strict date order, then a boolean search - i.e. set_weighting_scheme(Xapian::BoolWeight()) - with set_docid_order(Xapian::Enquire::DESCENDING) is an efficient way to perform “sort by date, newest first”, and with set_docid_order(Xapian::Enquire::ASCENDING) a very efficient way to perform “sort by date, oldest first”.

set_expansion_scheme()

Set the weighting scheme to use for expansion.

void Xapian::Enquire::set_expansion_scheme(std::string_view eweightname, double expand_k=1.0) const Xapian::Enquire::set_expansion_scheme If you don’t call this method, the default is as if you’d used:

set_expansion_scheme(“prob”);

eweightname: A string in lowercase specifying the name of the scheme to be used. The following schemes are currently available: “bo1”: Bose-Einstein 1 model from the Divergence From Randomness framework.

“prob” : Probabilistic model (since 1.4.26).

“trad” : Deprecated alias for “prob”.

expand_k: Parameter k for probabilistic query expansion. A default value of 1.0 is used if none is specified.

set_query(query, qlen=0)

Set the query.

void Xapian::Enquire::set_query(const Query &query, termcount query_length=0) Xapian::Enquire::set_query If set_query() is not called before calling get_mset(), the default query used will be Xapian::MatchNothing.

query: The Xapian::Query object

query_length: The query length to use (default: query.get_length())

set_sort_by_key(sorter, reverse)

Set the sorting to be by key generated from values only.

void Xapian::Enquire::set_sort_by_key(KeyMaker *sorter, bool reverse) XAPIAN_NONNULL() Xapian::Enquire::set_sort_by_key

sorter: The functor to use for generating keys.

reverse: If true, reverses the sort order.

set_sort_by_key_then_relevance(sorter, reverse)

Set the sorting to be by keys generated from values, then by relevance for documents with identical keys.

void Xapian::Enquire::set_sort_by_key_then_relevance(KeyMaker *sorter, bool reverse) XAPIAN_NONNULL() Xapian::Enquire::set_sort_by_key_then_relevance

sorter: The functor to use for generating keys.

reverse: If true, reverses the sort order.

set_sort_by_relevance()

Set the sorting to be by relevance only.

void Xapian::Enquire::set_sort_by_relevance() Xapian::Enquire::set_sort_by_relevance This is the default.

set_sort_by_relevance_then_key(sorter, reverse)

Set the sorting to be by relevance, then by keys generated from values.

void Xapian::Enquire::set_sort_by_relevance_then_key(KeyMaker *sorter, bool reverse) XAPIAN_NONNULL() Xapian::Enquire::set_sort_by_relevance_then_key Note that with the default BM25 weighting scheme parameters, non- identical documents will rarely have the same weight, so this setting will give very similar results to set_sort_by_relevance(). It becomes more useful with particular BM25 parameter settings (e.g. BM25Weight(1,0,1,0,0)) or custom weighting schemes.

sorter: The functor to use for generating keys.

reverse: If true, reverses the sort order of the generated keys. Beware that in 1.2.16 and earlier, the sense of this parameter was incorrectly inverted and inconsistent with the other set_sort_by_… methods. This was fixed in 1.2.17, so make that version a minimum requirement if this detail matters to your application.

set_sort_by_relevance_then_value()

Set the sorting to be by relevance then value.

void Xapian::Enquire::set_sort_by_relevance_then_value(valueno sort_key, bool reverse) Xapian::Enquire::set_sort_by_relevance_then_value Note that sorting by values uses a string comparison, so to use this to sort by a numeric value you’ll need to store the numeric values in a manner which sorts appropriately. For example, you could use Xapian::sortable_serialise() (which works for floating point numbers as well as integers), or store numbers padded with leading zeros or spaces, or with the number of digits prepended.

Note that with the default BM25 weighting scheme parameters, non- identical documents will rarely have the same weight, so this setting will give very similar results to set_sort_by_relevance(). It becomes more useful with particular BM25 parameter settings (e.g. BM25Weight(1,0,1,0,0)) or custom weighting schemes.

sort_key: value number to sort on.

reverse: If true, reverses the sort order of sort_key. Beware that in 1.2.16 and earlier, the sense of this parameter was incorrectly inverted and inconsistent with the other set_sort_by_… methods. This was fixed in 1.2.17, so make that version a minimum requirement if this detail matters to your application.

set_sort_by_value()

Set the sorting to be by value only.

void Xapian::Enquire::set_sort_by_value(valueno sort_key, bool reverse) Xapian::Enquire::set_sort_by_value Note that sorting by values uses a string comparison, so to use this to sort by a numeric value you’ll need to store the numeric values in a manner which sorts appropriately. For example, you could use Xapian::sortable_serialise() (which works for floating point numbers as well as integers), or store numbers padded with leading zeros or spaces, or with the number of digits prepended.

sort_key: value number to sort on.

reverse: If true, reverses the sort order.

set_sort_by_value_then_relevance()

Set the sorting to be by value, then by relevance for documents with the same value.

void Xapian::Enquire::set_sort_by_value_then_relevance(valueno sort_key, bool reverse) Xapian::Enquire::set_sort_by_value_then_relevance Note that sorting by values uses a string comparison, so to use this to sort by a numeric value you’ll need to store the numeric values in a manner which sorts appropriately. For example, you could use Xapian::sortable_serialise() (which works for floating point numbers as well as integers), or store numbers padded with leading zeros or spaces, or with the number of digits prepended.

sort_key: value number to sort on.

reverse: If true, reverses the sort order.

set_time_limit()

Set a time limit for the match.

void Xapian::Enquire::set_time_limit(double time_limit) Xapian::Enquire::set_time_limit Matches with check_at_least set high can take a long time in some cases. You can set a time limit on this, after which check_at_least will be turned off.

time_limit: time in seconds after which to disable check_at_least (default: 0.0 which means no time limit)

Limitations:

This feature is currently supported on platforms which support POSIX interval timers. Interaction with the remote backend when using multiple databases may have bugs. There’s not currently a way to force the match to end after a certain time.

set_weighting_scheme()

Set the weighting scheme to use.

void Xapian::Enquire::set_weighting_scheme(const Weight &weight) Xapian::Enquire::set_weighting_scheme The Xapian::Weight object passed is cloned by calling weight.clone(), so doesn’t need to remain valid after the call.

If set_weighting_scheme() is not called before calling get_mset(), the default weighting scheme is Xapian::BM25Weight().

weight: Xapian::Weight object

property thisown

The membership flag

exception xapian.Error(*args, **kwargs)

Bases: Exception

All exceptions thrown by Xapian are subclasses of Xapian::Error.

This class can not be instantiated directly - instead a subclass should be used.

get_context()

Optional context information.

const std::string & Xapian::Error::get_context() const noexcept Xapian::Error::get_context This context is intended for machine use (for example to know which remote server an error came from), but it is typically a plain-text string, and so also fit for human consumption.

get_error_string()

Returns any system error string associated with this exception.

const char * Xapian::Error::get_error_string() const Xapian::Error::get_error_string The system error string may come from errno, h_errno (on UNIX), or GetLastError() (on MS Windows). If there is no associated system error string, NULL is returned.

get_msg()

Message giving details of the error, intended for human consumption.

const std::string & Xapian::Error::get_msg() const noexcept Xapian::Error::get_msg

get_type()

The type of this error (e.g. “DocNotFoundError”.).

const char * Xapian::Error::get_type() const noexcept Xapian::Error::get_type

property thisown

The membership flag

class xapian.ExpandDecider

Bases: object

Virtual base class for expand decider functor.

release()

Start reference counting this object.

const ExpandDecider * Xapian::ExpandDecider::release() const Xapian::ExpandDecider::release You can transfer ownership of a dynamically allocated ExpandDecider object to Xapian by calling release() and then passing the object to a Xapian method. Xapian will arrange to delete the object once it is no longer required.

property thisown

The membership flag

class xapian.ExpandDeciderAnd(first_, second_)

Bases: xapian.ExpandDecider

ExpandDecider subclass which rejects terms using two ExpandDeciders.

Terms are only accepted if they are accepted by both of the specified ExpandDecider objects.

property thisown

The membership flag

class xapian.ExpandDeciderFilterPrefix(prefix_)

Bases: xapian.ExpandDecider

ExpandDecider subclass which restrict terms to a particular prefix.

ExpandDeciderFilterPrefix provides an easy way to choose terms with a particular prefix when generating an ESet.

property thisown

The membership flag

exception xapian.FeatureUnavailableError(*args)

Bases: xapian.RuntimeError

Indicates an attempt to use a feature which is unavailable.

Typically a feature is unavailable because it wasn’t compiled in, or because it requires other software or facilities which aren’t available.

property thisown

The membership flag

class xapian.FieldProcessor

Bases: object

Base class for field processors.

release()

Start reference counting this object.

const FieldProcessor * Xapian::FieldProcessor::release() const Xapian::FieldProcessor::release You can transfer ownership of a dynamically allocated FieldProcessor object to Xapian by calling release() and then passing the object to a Xapian method. Xapian will arrange to delete the object once it is no longer required.

property thisown

The membership flag

class xapian.FixedWeightPostingSource(wt)

Bases: xapian.PostingSource

A posting source which returns a fixed weight for all documents.

This returns entries for all documents in the given database, with a fixed weight (specified by a parameter to the constructor). This can be used to boost a sub-query by OP_AND-ing a FixedWeightPostingSource with that sub-query - this OP_AND will match the same documents as the sub-query does, but documents matching the subquery will get the specified extra weight contribution.

property thisown

The membership flag

class xapian.GreatCircleMetric(*args)

Bases: xapian.LatLongMetric

Calculate the great-circle distance between two coordinates on a sphere.

Experimental - seehttps://xapian.org/docs/deprecation#experimental- features

This uses the haversine formula to calculate the distance. Note that this formula is subject to inaccuracy due to numerical errors for coordinates on the opposite side of the sphere.

Seehttps://en.wikipedia.org/wiki/Haversine_formula

property thisown

The membership flag

class xapian.IfB2Weight(*args)

Bases: xapian.Weight

This class implements the IfB2 weighting scheme.

IfB2 is a representative scheme of the Divergence from Randomness Framework by Gianni Amati.

It uses the Inverse term frequency model (If), the Bernoulli method to find the aftereffect of sampling (B) and the second wdf normalization proposed by Amati to normalize the wdf in the document to the length of the document (H2).

For more information about the DFR Framework and the IfB2 scheme, please refer to: Gianni Amati and Cornelis Joost Van Rijsbergen Probabilistic models of information retrieval based on measuring the divergence from randomness ACM Transactions on Information Systems (TOIS) 20, (4), 2002, pp. 357-389.

create_from_parameters()

Create from a human-readable parameter string.

IfB2Weight * Xapian::IfB2Weight::create_from_parameters(const char *params) const Xapian::IfB2Weight::create_from_parameters

params: string containing weighting scheme parameter values.

2.0.0

property thisown

The membership flag

class xapian.InL2Weight(*args)

Bases: xapian.Weight

This class implements the InL2 weighting scheme.

InL2 is a representative scheme of the Divergence from Randomness Framework by Gianni Amati.

This weighting scheme is useful for tasks that require early precision.

It uses the Inverse document frequency model (In), the Laplace method to find the aftereffect of sampling (L) and the second wdf normalization proposed by Amati to normalize the wdf in the document to the length of the document (H2).

For more information about the DFR Framework and the InL2 scheme, please refer to: Gianni Amati and Cornelis Joost Van Rijsbergen Probabilistic models of information retrieval based on measuring the divergence from randomness ACM Transactions on Information Systems (TOIS) 20, (4), 2002, pp. 357-389.

create_from_parameters()

Create from a human-readable parameter string.

InL2Weight * Xapian::InL2Weight::create_from_parameters(const char *params) const Xapian::InL2Weight::create_from_parameters

params: string containing weighting scheme parameter values.

2.0.0

property thisown

The membership flag

class xapian.IneB2Weight(*args)

Bases: xapian.Weight

This class implements the IneB2 weighting scheme.

IneB2 is a representative scheme of the Divergence from Randomness Framework by Gianni Amati.

It uses the Inverse expected document frequency model (Ine), the Bernoulli method to find the aftereffect of sampling (B) and the second wdf normalization proposed by Amati to normalize the wdf in the document to the length of the document (H2).

For more information about the DFR Framework and the IneB2 scheme, please refer to: Gianni Amati and Cornelis Joost Van Rijsbergen Probabilistic models of information retrieval based on measuring the divergence from randomness ACM Transactions on Information Systems (TOIS) 20, (4), 2002, pp. 357-389.

create_from_parameters()

Create from a human-readable parameter string.

IneB2Weight * Xapian::IneB2Weight::create_from_parameters(const char *params) const Xapian::IneB2Weight::create_from_parameters

params: string containing weighting scheme parameter values.

2.0.0

property thisown

The membership flag

exception xapian.InternalError(*args)

Bases: xapian.RuntimeError

InternalError indicates a runtime problem of some sort.

property thisown

The membership flag

exception xapian.InvalidArgumentError(*args)

Bases: xapian.LogicError

InvalidArgumentError indicates an invalid parameter value was passed to the API.

property thisown

The membership flag

exception xapian.InvalidOperationError(*args)

Bases: xapian.LogicError

InvalidOperationError indicates the API was used in an invalid way.

property thisown

The membership flag

class xapian.KeyMaker

Bases: object

Virtual base class for key making functors.

name()

Return the name of this KeyMaker.

virtual std::string Xapian::KeyMaker::name() const Xapian::KeyMaker::name This name is used by the remote backend. It is passed with the serialised parameters to the remote server so that it knows which class to create.

Return the full namespace-qualified name of your class here - if your class is called MyApp::FooKeyMaker, return “MyApp::FooKeyMaker” from this method.

If you don’t want to support the remote backend in your KeyMaker, you can use the default implementation which simply throws Xapian::UnimplementedError.

release()

Start reference counting this object.

const KeyMaker * Xapian::KeyMaker::release() const Xapian::KeyMaker::release You can transfer ownership of a dynamically allocated KeyMaker object to Xapian by calling release() and then passing the object to a Xapian method. Xapian will arrange to delete the object once it is no longer required.

property thisown

The membership flag

class xapian.LM2StageWeight(_lambda=0.7, mu=2000.0)

Bases: xapian.Weight

Language Model weighting with Two Stage smoothing.

As described in:

Zhai, C., & Lafferty, J.D. (2004). A study of smoothing methods for language models applied to information retrieval. ACM Trans. Inf. Syst., 22, 179-214.

2.0.0

create_from_parameters()

Create from a human-readable parameter string.

LM2StageWeight * Xapian::LM2StageWeight::create_from_parameters(const char *params) const Xapian::LM2StageWeight::create_from_parameters

params: string containing weighting scheme parameter values.

2.0.0

property thisown

The membership flag

class xapian.LMAbsDiscountWeight(delta=0.7)

Bases: xapian.Weight

Language Model weighting with Absolute Discount smoothing.

As described in:

Zhai, C., & Lafferty, J.D. (2004). A study of smoothing methods for language models applied to information retrieval. ACM Trans. Inf. Syst., 22, 179-214.

2.0.0

create_from_parameters()

Create from a human-readable parameter string.

LMAbsDiscountWeight * Xapian::LMAbsDiscountWeight::create_from_parameters(const char *params) const Xapian::LMAbsDiscountWeight::create_from_parameters

params: string containing weighting scheme parameter values.

2.0.0

property thisown

The membership flag

class xapian.LMDirichletWeight(mu=2000.0, delta=0.05)

Bases: xapian.Weight

Language Model weighting with Dirichlet or Dir+ smoothing.

Dirichlet smoothing is as described in:

Zhai, C., & Lafferty, J.D. (2004). A study of smoothing methods for language models applied to information retrieval. ACM Trans. Inf. Syst., 22, 179-214.

Dir+ is described in:

Lv, Y., & Zhai, C. (2011). Lower-bounding term frequency normalization. International Conference on Information and Knowledge Management.

2.0.0

create_from_parameters()

Create from a human-readable parameter string.

LMDirichletWeight * Xapian::LMDirichletWeight::create_from_parameters(const char *params) const Xapian::LMDirichletWeight::create_from_parameters

params: string containing weighting scheme parameter values.

2.0.0

property thisown

The membership flag

class xapian.LMJMWeight(_lambda=0.0)

Bases: xapian.Weight

Language Model weighting with Jelinek-Mercer smoothing.

As described in:

Zhai, C., & Lafferty, J.D. (2004). A study of smoothing methods for language models applied to information retrieval. ACM Trans. Inf. Syst., 22, 179-214.

2.0.0

create_from_parameters()

Create from a human-readable parameter string.

LMJMWeight * Xapian::LMJMWeight::create_from_parameters(const char *params) const Xapian::LMJMWeight::create_from_parameters

params: string containing weighting scheme parameter values.

2.0.0

property thisown

The membership flag

class xapian.LatLongCoord(*args)

Bases: object

A latitude-longitude coordinate.

Experimental - seehttps://xapian.org/docs/deprecation#experimental- features

Note that latitude-longitude coordinates are only precisely meaningful if the datum used to define them is specified. This class ignores this issue - it is up to the caller to ensure that the datum used for each coordinate in a system is consistent.

property latitude

property longitude

serialise()

Return a serialised representation of the coordinate.

std::string Xapian::LatLongCoord::serialise() const Xapian::LatLongCoord::serialise

property thisown

The membership flag

unserialise()

Unserialise a buffer and set this object to its coordinate.

void Xapian::LatLongCoord::unserialise(const char **ptr, const char *end) Xapian::LatLongCoord::unserialise The buffer may contain further data after that for the coordinate.

ptr: A pointer to the start of the string. This will be updated to point to the end of the data representing the coordinate.

end: A pointer to the end of the string.

Xapian::SerialisationError: if the string does not start with a valid serialised latitude- longitude pair.

class xapian.LatLongCoords(*args)

Bases: object

A sequence of latitude-longitude coordinates.

Experimental - seehttps://xapian.org/docs/deprecation#experimental- features

append()

Append a coordinate to the end of the sequence.

void Xapian::LatLongCoords::append(const LatLongCoord &coord) Xapian::LatLongCoords::append

begin()

Get a begin iterator for the coordinates.

LatLongCoordsIterator Xapian::LatLongCoords::begin() const Xapian::LatLongCoords::begin

empty()

Return true if and only if there are no coordinates in the container.

bool Xapian::LatLongCoords::empty() const Xapian::LatLongCoords::empty

end()

Get an end iterator for the coordinates.

LatLongCoordsIterator Xapian::LatLongCoords::end() const Xapian::LatLongCoords::end

serialise()

Return a serialised form of the coordinate list.

std::string Xapian::LatLongCoords::serialise() const Xapian::LatLongCoords::serialise

size()

Get the number of coordinates in the container.

size_t Xapian::LatLongCoords::size() const Xapian::LatLongCoords::size

property thisown

The membership flag

unserialise()

Unserialise a string and set this object to the coordinates in it.

void Xapian::LatLongCoords::unserialise(std::string_view serialised) Xapian::LatLongCoords::unserialise

serialised: the string to unserialise the coordinates from.

Xapian::SerialisationError: if the string does not contain a valid serialised latitude-longitude pair, or contains junk at the end of it.

class xapian.LatLongCoordsIter(start, end)

Bases: object

An iterator over all the coordinates in a LatLongCoords object.

The iterator returns LatLongCoord objects.

class xapian.LatLongDistanceKeyMaker(*args)

Bases: xapian.KeyMaker

KeyMaker subclass which sorts by distance from a latitude/longitude.

Experimental - seehttps://xapian.org/docs/deprecation#experimental- features

Results are ordered by the distance from a fixed point, or list of points, calculated according to the metric supplied. If multiple points are supplied (either in the constructor, or in the coordinates stored in a document), the closest pointwise distance is used.

If a document contains no coordinate stored in the specified slot, a special value for the distance will be used. This defaults to a large number, so that such results get a low rank, but may be specified by a constructor parameter.

property thisown

The membership flag

class xapian.LatLongDistancePostingSource(*args)

Bases: xapian.ValuePostingSource

Posting source which returns a weight based on geospatial distance.

Experimental - seehttps://xapian.org/docs/deprecation#experimental- features

Results are weighted by the distance from a fixed point, or list of points, calculated according to the metric supplied. If multiple points are supplied (either in the constructor, or in the coordinates stored in a document), the closest pointwise distance is used.

Documents further away than a specified maximum range (or with no location stored in the specified slot) will not be returned.

The weight returned is computed from the distance using the formula:

k1 * pow(distance + k1, -k2)

(Where k1 and k2 are (strictly) positive, floating point constants, which default to 1000 and 1, respectively. Distance is measured in metres, so this means that something at the centre gets a weight of 1.0, something 1km away gets a weight of 0.5, and something 3km away gets a weight of 0.25, etc)

property thisown

The membership flag

class xapian.LatLongMetric

Bases: object

Base class for calculating distances between two lat/long coordinates.

Experimental - seehttps://xapian.org/docs/deprecation#experimental- features

name()

Return the full name of the metric.

virtual std::string Xapian::LatLongMetric::name() const =0 Xapian::LatLongMetric::name This is used when serialising and unserialising metrics; for example, for performing remote searches.

If the subclass is in a C++ namespace, the namespace should be included in the name, using “::” as a separator. For example, for a LatLongMetric subclass called “FooLatLongMetric” in the “Xapian” namespace the result of this call should be “Xapian::FooLatLongMetric”.

pointwise_distance()

Return the distance between two coordinates, in metres.

virtual double Xapian::LatLongMetric::pointwise_distance(const LatLongCoord &a, const LatLongCoord &b) const =0 Xapian::LatLongMetric::pointwise_distance

property thisown

The membership flag

exception xapian.LogicError(*args, **kwargs)

Bases: xapian.Error

The base class for exceptions indicating errors in the program logic.

A subclass of LogicError will be thrown if Xapian detects a violation of a class invariant or a logical precondition or postcondition, etc.

property thisown

The membership flag

class xapian.MSet

Bases: object

Class representing a list of search results.

SNIPPET_BACKGROUND_MODEL = 1

SNIPPET_CJK_NGRAM = 2048

SNIPPET_EMPTY_WITHOUT_MATCH = 4

SNIPPET_EXHAUSTIVE = 2

SNIPPET_NGRAMS = 2048

SNIPPET_WORD_BREAKS = 4096

back()

Return iterator pointing to the last object in this MSet.

MSetIterator Xapian::MSet::back() const Xapian::MSet::back

convert_to_percent()

Convert the weight of the current iterator position to a percentage.

int Xapian::MSet::convert_to_percent(const MSetIterator &it) const Xapian::MSet::convert_to_percent If the weighting scheme gives everything zero weight (like Xapian::BoolWeight does) then all results will score 100%.

Otherwise the percentage is calculated as a linear scaling of the relevance weight, with the scale factor determined by the matching document with the highest weight. This result scores 100% if it matches all the weighted query terms, and proportionally less if it only matches some.

The returned percentage is an integer. If the calculated percentage before rounding is non-zero but less than 1% it is rounded up to 1% so that a result scoring 0% means it has zero weight.

Similarly, percentages over 99% but less than 100% are always rounded down, so a result scoring 100% means it matches all weighted query terms.

Note that these generally aren’t percentages of anything meaningful (unless you use a custom weighting formula where they are!) but like the weights they are based on, higher values should indicate more relevant results.

empty()

Return true if this MSet object is empty.

bool Xapian::MSet::empty() const Xapian::MSet::empty

fetch()

Prefetch hint the whole MSet.

void Xapian::MSet::fetch() const Xapian::MSet::fetch For a remote database, this may start a pipelined fetch of the requested documents from the remote server.

For a disk-based database, this may send prefetch hints to the operating system such that the disk blocks the requested documents are stored in are more likely to be in the cache when we come to actually read them.

get_docid()

get_document()

get_document_percentage()

get_firstitem()

Rank of first item in this MSet.

Xapian::doccount Xapian::MSet::get_firstitem() const Xapian::MSet::get_firstitem This is the parameter first passed to Xapian::Enquire::get_mset().

get_hit(index)

Get an item from the MSet.

The supplied index is relative to the start of the MSet, not the absolute rank of the item.

Returns an MSetItem.

get_matches_estimated()

Estimate of the total number of matching documents.

Xapian::doccount Xapian::MSet::get_matches_estimated() const Xapian::MSet::get_matches_estimated

get_matches_lower_bound()

Lower bound on the total number of matching documents.

Xapian::doccount Xapian::MSet::get_matches_lower_bound() const Xapian::MSet::get_matches_lower_bound

get_matches_upper_bound()

Upper bound on the total number of matching documents.

Xapian::doccount Xapian::MSet::get_matches_upper_bound() const Xapian::MSet::get_matches_upper_bound

get_max_attained()

The maximum weight attained by any document.

double Xapian::MSet::get_max_attained() const Xapian::MSet::get_max_attained

get_max_possible()

The maximum possible weight any document could achieve.

double Xapian::MSet::get_max_possible() const Xapian::MSet::get_max_possible

get_termfreq()

Get the termfreq of a term.

Xapian::doccount Xapian::MSet::get_termfreq(std::string_view term) const Xapian::MSet::get_termfreq

The number of documents which term occurs in. This considers all documents in the database being searched, so gives the same answer as db.get_termfreq(term) (but is more efficient for query terms as it returns a value cached during the search.) Since 2.0.0, this method returns 0 if called on an MSet which is not associated with a database (which is consistent with Database::get_termfreq() returning 0 when called on a Database with no sub-databases); in earlier versions, Xapian::InvalidOperationError was thrown in this case.

get_termweight()

Get the term weight of a term.

double Xapian::MSet::get_termweight(std::string_view term) const Xapian::MSet::get_termweight

The maximum weight that term could have contributed to a document. Since 2.0.0, this method returns 0.0 if called on an MSet which is not associated with a database, or with a term which wasn’t present in the query (since in both cases the term contributes no weight to any matching documents); in earlier versions, Xapian::InvalidOperationError was thrown for the first case, and Xapian::InvalidArgumentError for the second.

get_uncollapsed_matches_estimated()

Estimate of the total number of matching documents before collapsing.

Xapian::doccount Xapian::MSet::get_uncollapsed_matches_estimated() const Xapian::MSet::get_uncollapsed_matches_estimated Conceptually the same as get_matches_estimated() for the same query without any collapse part (though the actual value may differ).

get_uncollapsed_matches_lower_bound()

Lower bound on the total number of matching documents before collapsing.

Xapian::doccount Xapian::MSet::get_uncollapsed_matches_lower_bound() const Xapian::MSet::get_uncollapsed_matches_lower_bound Conceptually the same as get_matches_lower_bound() for the same query without any collapse part (though the actual value may differ).

get_uncollapsed_matches_upper_bound()

Upper bound on the total number of matching documents before collapsing.

Xapian::doccount Xapian::MSet::get_uncollapsed_matches_upper_bound() const Xapian::MSet::get_uncollapsed_matches_upper_bound Conceptually the same as get_matches_upper_bound() for the same query without any collapse part (though the actual value may differ).

size()

Return number of items in this MSet object.

Xapian::doccount Xapian::MSet::size() const Xapian::MSet::size

snippet()

Generate a snippet.

std::string Xapian::MSet::snippet(std::string_view text, size_t length=500, const Xapian::Stem &stemmer=Xapian::Stem(), unsigned flags=SNIPPET_BACKGROUND_MODEL|SNIPPET_EXHAUSTIVE, std::string_view hi_start=”<b>”, std::string_view hi_end=”</b>”, std::string_view omit=”…”) const Xapian::MSet::snippet This method selects a continuous run of words from text, based mainly on where the query matches (currently terms, exact phrases and wildcards are taken into account). If flag SNIPPET_BACKGROUND_MODEL is used (which it is by default) then the selection algorithm also considers the non-query terms in the text with the aim of showing a context which provides more useful information.

The size of the text selected can be controlled by the length parameter, which specifies a number of bytes of text to aim to select. However slightly more text may be selected. Also the size of any escaping, highlighting or omission markers is not considered.

The returned text is escaped to make it suitable for use in HTML (though beware that in upstream releases 1.4.5 and earlier this escaping was sometimes incomplete), and matches with the query will be highlighted using hi_start and hi_end.

If the snippet seems to start or end mid-sentence, then omit is prepended or append (respectively) to indicate this.

The same stemming algorithm which was used to build the query should be specified in stemmer.

And flags contains flags controlling behaviour.

Added in 1.3.5.

sort_by_relevance()

Sorts the list of documents in MSet according to their weights.

void Xapian::MSet::sort_by_relevance() Xapian::MSet::sort_by_relevance Use after calling MSet::replace_weights.

This invalidates any MSetIterator objects active on this MSet.

Added in Xapian 2.0.0.

property thisown

The membership flag

class xapian.MSetItem(iter, mset)

Bases: object

An item returned from iteration of the MSet.

The item supports access to the following attributes and properties:

• docid: The Xapian document ID corresponding to this MSet item.

• weight: The weight corresponding to this MSet item.

• rank: The rank of this MSet item. The rank is the position in the total set of matching documents of this item. The highest document is given a rank of 0. If the MSet did not start at the highest matching document, because a non-zero ‘start’ parameter was supplied to get_mset(), the first document in the MSet will have a rank greater than 0 (in fact, it will be equal to the value of ‘start’ supplied to get_mset()).

• percent: The percentage score assigned to this MSet item.

• document: The document for this MSet item. This can be used to access the document data, or any other information stored in the document (such as term lists). It is lazily evaluated.

• collapse_key: The value of the key which was used for collapsing.

• collapse_count: An estimate of the number of documents that have been collapsed into this one.

The collapse count estimate will always be less than or equal to the actual number of other documents satisfying the match criteria with the same collapse key as this document. If may be 0 even though there are other documents with the same collapse key which satisfying the match criteria. However if this method returns non-zero, there definitely are other such documents. So this method may be used to inform the user that there are “at least N other matches in this group”, or to control whether to offer a “show other documents in this group” feature (but note that it may not offer it in every case where it would show other documents).

collapse_count

collapse_key

docid

property document

The document object corresponding to this MSet item.

percent

rank

weight

class xapian.MSetIter(mset)

Bases: object

An iterator over the items in an MSet.

The iterator will return MSetItem objects, which will be evaluated lazily where appropriate.

class xapian.MatchDecider

Bases: object

Abstract base class for match deciders.

property thisown

The membership flag

class xapian.MatchSpy

Bases: object

Abstract base class for match spies.

The subclasses will generally accumulate information seen during the match, to calculate aggregate functions, or other profiles of the matching documents.

merge_results()

Unserialise some results, and merge them into this matchspy.

virtual void Xapian::MatchSpy::merge_results(const std::string &serialised) Xapian::MatchSpy::merge_results The order in which results are merged should not be significant, since this order is not specified (and will vary depending on the speed of the search in each sub-database).

If you don’t want to support the remote backend in your match spy, you can use the default implementation which simply throws Xapian::UnimplementedError.

serialised: A string containing the serialised results.

name()

Return the name of this match spy.

virtual std::string Xapian::MatchSpy::name() const Xapian::MatchSpy::name This name is used by the remote backend. It is passed with the serialised parameters to the remote server so that it knows which class to create.

Return the full namespace-qualified name of your class here - if your class is called MyApp::FooMatchSpy, return “MyApp::FooMatchSpy” from this method.

If you don’t want to support the remote backend in your match spy, you can use the default implementation which simply throws Xapian::UnimplementedError.

release()

Start reference counting this object.

const MatchSpy * Xapian::MatchSpy::release() const Xapian::MatchSpy::release You can transfer ownership of a dynamically allocated MatchSpy object to Xapian by calling release() and then passing the object to a Xapian method. Xapian will arrange to delete the object once it is no longer required.

property thisown

The membership flag

class xapian.MultiValueKeyMaker

Bases: xapian.KeyMaker

KeyMaker subclass which combines several values.

When the result is used for sorting, results are ordered by the first value. In the event of a tie, the second is used. If this is the same for both, the third is used, and so on. If reverse is true for a value, then the sort order for that value is reversed.

When used for collapsing, the documents will only be considered equal if all the values specified match. If none of the specified values are set then the generated key will be empty, so such documents won’t be collapsed (which is consistent with the behaviour in the “collapse on a value” case). If you’d prefer that documents with none of the keys set are collapsed together, then you can set reverse for at least one of the values. Other than this, it isn’t useful to set reverse for collapsing.

add_value()

Add a value slot to the list to build a key from.

void Xapian::MultiValueKeyMaker::add_value(Xapian::valueno slot, bool reverse=false, std::string_view defvalue={}) Xapian::MultiValueKeyMaker::add_value

slot: The value slot to add

reverse: Adjust values from this slot to reverse their sort order (default: false)

defvalue: Value to use for documents which don’t have a value set in this slot (default: empty). This can be used to make such documents sort after all others by passing get_value_upper_bound(slot) + “x” this is guaranteed to be greater than any value in this slot.

property thisown

The membership flag

exception xapian.NetworkError(*args)

Bases: xapian.RuntimeError

Indicates a problem communicating with a remote database.

property thisown

The membership flag

exception xapian.NetworkTimeoutError(*args)

Bases: xapian.NetworkError

Indicates a timeout expired while communicating with a remote database.

property thisown

The membership flag

class xapian.NumberRangeProcessor(*args)

Bases: xapian.RangeProcessor

Handle a number range.

This class must be used on values which have been encoded using Xapian::sortable_serialise() which turns numbers into strings which will sort in the same order as the numbers (the same values can be used to implement a numeric sort).

property thisown

The membership flag

class xapian.PL2PlusWeight(*args)

Bases: xapian.Weight

Xapian::Weight subclass implementing the PL2+ probabilistic formula.

create_from_parameters()

Create from a human-readable parameter string.

PL2PlusWeight * Xapian::PL2PlusWeight::create_from_parameters(const char *params) const Xapian::PL2PlusWeight::create_from_parameters

params: string containing weighting scheme parameter values.

2.0.0

property thisown

The membership flag

class xapian.PL2Weight(*args)

Bases: xapian.Weight

This class implements the PL2 weighting scheme.

PL2 is a representative scheme of the Divergence from Randomness Framework by Gianni Amati.

This weighting scheme is useful for tasks that require early precision.

It uses the Poisson approximation of the Binomial Probabilistic distribution (P) along with Stirling’s approximation for the factorial value, the Laplace method to find the aftereffect of sampling (L) and the second wdf normalization proposed by Amati to normalize the wdf in the document to the length of the document (H2).

For more information about the DFR Framework and the PL2 scheme, please refer to : Gianni Amati and Cornelis Joost Van Rijsbergen Probabilistic models of information retrieval based on measuring the divergence from randomness ACM Transactions on Information Systems (TOIS) 20, (4), 2002, pp. 357-389.

create_from_parameters()

Create from a human-readable parameter string.

PL2Weight * Xapian::PL2Weight::create_from_parameters(const char *params) const Xapian::PL2Weight::create_from_parameters

params: string containing weighting scheme parameter values.

2.0.0

property thisown

The membership flag

class xapian.PositionIter(start=0, end=0)

Bases: object

An iterator over a position list.

The iterator will return integers, in ascending order.

class xapian.PostingItem(iter)

Bases: object

An item returned from iteration of a posting list.

The item supports access to the following attributes and properties:

• docid: The document ID corresponding to this PostingItem.

• doclength: The length of the document corresponding to this PostingItem.

• wdf: The within document frequency of the term which the posting list is for in the document corresponding to this PostingItem.

• positer: An iterator over the positions which the term corresponing to this posting list occurs at in the document corresponding to this PostingItem. This is only available until the iterator which returned this item next moves.

docid

doclength

property positer

A position iterator for the current posting (if meaningful).

The iterator will return integers representing the positions that the term occurs at.

This will raise a InvalidOperationError exception if the iterator this item came from doesn’t support position lists, or if the iterator has moved on since the item was returned from it.

wdf

class xapian.PostingIter(start, end, has_positions=False)

Bases: object

An iterator over a posting list.

The iterator will return PostingItem objects, which will be evaluated lazily where appropriate.

skip_to(docid)

Skip the iterator forward.

The iterator is advanced to the first document with a document ID which is greater than or equal to the supplied document ID.

If there are no such items, this will raise StopIteration.

This returns the item which the iterator is moved to. The subsequent item will be returned the next time that next() is called (unless skip_to() is called again first).

class xapian.PostingSource

Bases: object

Base class which provides an “external” source of postings.

at_end()

Return true if the current position is past the last entry in this list.

virtual bool Xapian::PostingSource::at_end() const =0 Xapian::PostingSource::at_end At least one of next(), skip_to() or check() will be called before this method is first called.

check()

Check if the specified docid occurs.

virtual bool Xapian::PostingSource::check(Xapian::docid did, double min_wt) Xapian::PostingSource::check The caller is required to ensure that the specified document id did actually exists in the database. If it does, it must move to that document id, and return true. If it does not, it may either:

return true, having moved to a definite position (including “at_end”), which must be the same position as skip_to() would have moved to.

or

return false, having moved to an “indeterminate” position, such that a subsequent call to next() or skip_to() will move to the next matching position after did.

Generally, this method should act like skip_to() and return true if that can be done at little extra cost.

Otherwise it should simply check if a particular docid is present, returning true if it is, and false if it isn’t.

The default implementation calls skip_to() and always returns true.

Xapian will always call reset() on a PostingSource before calling this for the first time.

Note: in the case of a multi-database search, the docid specified is the docid in the single subdatabase relevant to this posting source. See the reset() method for details.

did: The document id to check.

min_wt: The minimum weight contribution that is needed (this is just a hint which subclasses may ignore).

get_docid()

Return the current docid.

virtual Xapian::docid Xapian::PostingSource::get_docid() const =0 Xapian::PostingSource::get_docid This method may assume that it will only be called when there is a “current document”. See get_weight() for details.

Note: in the case of a multi-database search, the returned docid should be in the single subdatabase relevant to this posting source. See the reset() method for details.

get_maxweight()

Return the currently set upper bound on what get_weight() can return.

double Xapian::PostingSource::get_maxweight() const noexcept Xapian::PostingSource::get_maxweight

get_termfreq_est()

An estimate of the number of documents this object can return.

virtual Xapian::doccount Xapian::PostingSource::get_termfreq_est() const =0 Xapian::PostingSource::get_termfreq_est It must always be true that:

get_termfreq_min() <= get_termfreq_est() <= get_termfreq_max()

Xapian will always call reset() on a PostingSource before calling this for the first time.

get_termfreq_max()

An upper bound on the number of documents this object can return.

virtual Xapian::doccount Xapian::PostingSource::get_termfreq_max() const =0 Xapian::PostingSource::get_termfreq_max Xapian will always call reset() on a PostingSource before calling this for the first time.

get_termfreq_min()

A lower bound on the number of documents this object can return.

virtual Xapian::doccount Xapian::PostingSource::get_termfreq_min() const =0 Xapian::PostingSource::get_termfreq_min Xapian will always call reset() on a PostingSource before calling this for the first time.

get_weight()

Return the weight contribution for the current document.

virtual double Xapian::PostingSource::get_weight() const Xapian::PostingSource::get_weight This default implementation always returns 0, for convenience when implementing “weight-less” PostingSource subclasses.

This method may assume that it will only be called when there is a “current document”. In detail: Xapian will always call reset() on a PostingSource before calling this for the first time. It will also only call this if the PostingSource reports that it is pointing to a valid document (ie, it will not call it before calling at least one of next(), skip_to() or check(), and will ensure that the PostingSource is not at the end by calling at_end()).

init()

Older method which did the same job as reset().

virtual void Xapian::PostingSource::init(const Database &db) Xapian::PostingSource::init Prior to 2.0.0, instead of reset() there was a method called init() taking one parameter. The default implementation of reset() calls init() to allow existing subclasses to continue to work.

A default implementation of init() is provided so that new subclasses can just override reset() (the default implementation should not actually get called, and will throw Xapian::InvalidOperationError if it is).

name()

Name of the posting source class.

virtual std::string Xapian::PostingSource::name() const Xapian::PostingSource::name This is used when serialising and unserialising posting sources; for example, for performing remote searches.

If the subclass is in a C++ namespace, the namespace should be included in the name, using “::” as a separator. For example, for a PostingSource subclass called “FooPostingSource” in the “Xapian” namespace the result of this call should be “Xapian::FooPostingSource”.

This should only be implemented if serialise() and unserialise() are also implemented. The default implementation returns an empty string.

If this returns an empty string, Xapian will assume that serialise() and unserialise() are not implemented.

release()

Start reference counting this object.

const PostingSource * Xapian::PostingSource::release() const Xapian::PostingSource::release You can transfer ownership of a dynamically allocated PostingSource object to Xapian by calling release() and then passing the object to a Xapian method. Xapian will arrange to delete the object once it is no longer required.

reset()

Set this PostingSource to the start of the list of postings.

virtual void Xapian::PostingSource::reset(const Database &db, Xapian::doccount shard_index) Xapian::PostingSource::reset This is called automatically by the matcher prior to each query being processed.

If a PostingSource is used for multiple searches, reset() will therefore be called multiple times, and must handle this by using the database passed in the most recent call.

db: The database which the PostingSource should iterate through.

shard_index: The 0-based index indicating which shard in a multi- database db is. This can be useful if you have an external source of postings corresponding to each shard.

Note: in the case of a multi-database search, a separate PostingSource will be used for each database (the separate PostingSources will be obtained using clone()), and each PostingSource will be passed one of the sub-databases as the db parameter here. The db parameter will therefore always refer to a single database. All docids passed to, or returned from, the PostingSource refer to docids in that single database, rather than in the multi- database.

A default implementation is provided which calls the older init() method to allow existing subclasses to continue to work, but the default implementation of init() throws Xapian::InvalidOperationError so you must override either this method or init(). In new code, override this method in preference.

Added in Xapian 2.0.0.

set_maxweight()

Specify an upper bound on what get_weight() will return from now on.

void Xapian::PostingSource::set_maxweight(double max_weight) Xapian::PostingSource::set_maxweight This upper bound is used by the matcher to perform various optimisations, so if you can return a good bound, then matches will generally run faster.

This method should be called after calling reset(), and may be called during iteration if the upper bound drops. It is probably only useful to call from subclasses (it was actually a “protected” method prior to Xapian 1.3.4, but that makes it tricky to wrap for other languages).

It is valid for the posting source to have returned a higher value from get_weight() earlier in the iteration, but the posting source must not return a higher value from get_weight() than the currently set upper bound, and the upper bound must not be increased (until reset() has been called).

If you don’t call this method, the upper bound will default to 0, for convenience when implementing “weight-less” PostingSource subclasses.

max_weight: The upper bound to set.

skip_to()

Advance to the specified docid.

virtual void Xapian::PostingSource::skip_to(Xapian::docid did, double min_wt) Xapian::PostingSource::skip_to If the specified docid isn’t in the list, position ourselves on the first document after it (or at_end() if no greater docids are present).

If the current position is already the specified docid, this method will leave the position unmodified.

If the specified docid is earlier than the current position, the behaviour is unspecified. A sensible behaviour would be to leave the current position unmodified, but it is also reasonable to move to the specified docid.

The default implementation calls next() repeatedly, which works but skip_to() can often be implemented much more efficiently.

Xapian will always call reset() on a PostingSource before calling this for the first time.

Note: in the case of a multi-database search, the docid specified is the docid in the single subdatabase relevant to this posting source. See the reset() method for details.

did: The document id to advance to.

min_wt: The minimum weight contribution that is needed (this is just a hint which subclasses may ignore).

property thisown

The membership flag

class xapian.Query(*args)

Bases: object

Class representing a query.

MatchAll = <xapian.Query; proxy of <Swig Object of type 'Xapian::Query *'> >

MatchNothing = <xapian.Query; proxy of <Swig Object of type 'Xapian::Query *'> >

OP_AND = 0

OP_AND_MAYBE = 4

OP_AND_NOT = 2

OP_EDIT_DISTANCE = 16

OP_ELITE_SET = 10

OP_FILTER = 5

OP_INVALID = 99

OP_MAX = 14

OP_NEAR = 6

OP_OR = 1

OP_PHRASE = 7

OP_SCALE_WEIGHT = 9

OP_SYNONYM = 13

OP_VALUE_GE = 11

OP_VALUE_LE = 12

OP_VALUE_RANGE = 8

OP_WILDCARD = 15

OP_XOR = 3

WILDCARD_LIMIT_ERROR = 0

WILDCARD_LIMIT_FIRST = 1

WILDCARD_LIMIT_MOST_FREQUENT = 2

WILDCARD_PATTERN_GLOB = 48

WILDCARD_PATTERN_MULTI = 16

WILDCARD_PATTERN_SINGLE = 32

empty()

Check if this query is Xapian::Query::MatchNothing.

bool Xapian::Query::empty() const noexcept Xapian::Query::empty

get_leaf_pos()

Get the pos parameter of a leaf node.

Xapian::termpos Xapian::Query::get_leaf_pos() const Xapian::Query::get_leaf_pos

Added in Xapian 2.0.0.

get_leaf_wqf()

Get the wqf parameter of a leaf node.

Xapian::termcount Xapian::Query::get_leaf_wqf() const Xapian::Query::get_leaf_wqf

Added in Xapian 2.0.0.

get_length()

Return the length of this query object.

Xapian::termcount Xapian::Query::get_length() const noexcept Xapian::Query::get_length

get_num_subqueries()

Get the number of subqueries of the top level query.

size_t Xapian::Query::get_num_subqueries() const noexcept Xapian::Query::get_num_subqueries

get_subquery()

Read a top level subquery.

const Query Xapian::Query::get_subquery(size_t n) const Xapian::Query::get_subquery

n: Return the n-th subquery (starting from 0) - only valid when 0 <= n < get_num_subqueries().

get_type()

Get the type of the top level of the query.

op Xapian::Query::get_type() const noexcept Xapian::Query::get_type

get_unique_terms_begin()

Begin iterator for unique terms in the query object.

const TermIterator Xapian::Query::get_unique_terms_begin() const Xapian::Query::get_unique_terms_begin Terms are sorted and terms with the same name removed from the list.

If you want the terms in ascending query position order, see get_terms_begin().

get_unique_terms_end()

End iterator for unique terms in the query object.

const TermIterator Xapian::Query::get_unique_terms_end() const noexcept Xapian::Query::get_unique_terms_end

serialise()

Serialise this object into a string.

std::string Xapian::Query::serialise() const Xapian::Query::serialise

property thisown

The membership flag

static unserialise()

class xapian.QueryParser

Bases: object

Build a Xapian::Query object from a user query string.

FLAG_ACCUMULATE = 65536

FLAG_AUTO_MULTIWORD_SYNONYMS = 1024

FLAG_AUTO_SYNONYMS = 512

FLAG_BOOLEAN = 1

FLAG_BOOLEAN_ANY_CASE = 8

FLAG_CJK_NGRAM = 2048

FLAG_DEFAULT = 7

FLAG_FUZZY = 32768

FLAG_LOVEHATE = 4

FLAG_NGRAMS = 2048

FLAG_NO_POSITIONS = 131072

FLAG_NO_PROPER_NOUN_HEURISTIC = 262144

FLAG_PARTIAL = 64

FLAG_PHRASE = 2

FLAG_PURE_NOT = 32

FLAG_SPELLING_CORRECTION = 128

FLAG_SYNONYM = 256

FLAG_WILDCARD = 16

FLAG_WILDCARD_GLOB = 24576

FLAG_WILDCARD_MULTI = 8192

FLAG_WILDCARD_SINGLE = 16384

FLAG_WORD_BREAKS = 4096

STEM_ALL = 2

STEM_ALL_Z = 3

STEM_NONE = 0

STEM_SOME = 1

STEM_SOME_FULL_POS = 4

STOP_ALL = 1

STOP_NONE = 0

STOP_STEMMED = 2

add_boolean_prefix(s, proc, exclusive=True)

Register a FieldProcessor for a boolean prefix.

void Xapian::QueryParser::add_boolean_prefix(std::string_view field, Xapian::FieldProcessor *proc, bool exclusive) Xapian::QueryParser::add_boolean_prefix This is an older version of this method - use the version with the grouping parameter in preference to this one.

add_prefix(s, proc)

Register a FieldProcessor.

void Xapian::QueryParser::add_prefix(std::string_view field, Xapian::FieldProcessor *proc) Xapian::QueryParser::add_prefix

add_rangeprocessor(rproc)

Register a RangeProcessor.

void Xapian::QueryParser::add_rangeprocessor(Xapian::RangeProcessor *range_proc, const std::string *grouping=NULL) Xapian::QueryParser::add_rangeprocessor

get_corrected_query_string()

Get the spelling-corrected query string.

std::string Xapian::QueryParser::get_corrected_query_string() const Xapian::QueryParser::get_corrected_query_string This will only be set if FLAG_SPELLING_CORRECTION is specified when QueryParser::parse_query() was last called.

If there were no corrections, an empty string is returned.

get_default_op()

Get the current default operator.

Query::op Xapian::QueryParser::get_default_op() const Xapian::QueryParser::get_default_op

parse_query()

Parse a query.

Query Xapian::QueryParser::parse_query(std::string_view query_string, unsigned flags=FLAG_DEFAULT, std::string_view default_prefix={}) Xapian::QueryParser::parse_query

query_string: A free-text query as entered by a user

flags: Zero or more QueryParser::feature_flag specifying what features the QueryParser should support. Combine multiple values with bitwise-or (|) (default FLAG_DEFAULT).

default_prefix: The default term prefix to use (default none). For example, you can pass “A” when parsing an “Author” field.

If: the query string can’t be parsed, then Xapian::QueryParserError is thrown. You can get an English error message to report to the user by catching it and calling get_msg() on the caught exception. The current possible values (in case you want to translate them) are:

Unknown range operation

parse error

Syntax: <expression> AND <expression>

Syntax: <expression> AND NOT <expression>

Syntax: <expression> NOT <expression>

Syntax: <expression> OR <expression>

Syntax: <expression> XOR <expression>

set_database()

Specify the database being searched.

void Xapian::QueryParser::set_database(const Database &db) Xapian::QueryParser::set_database

db: The database to use for spelling correction (FLAG_SPELLING_CORRECTION), and synonyms (FLAG_SYNONYM, FLAG_AUTO_SYNONYMS, and FLAG_AUTO_MULTIWORD_SYNONYMS).

set_default_op()

Set the default operator.

void Xapian::QueryParser::set_default_op(Query::op default_op) Xapian::QueryParser::set_default_op

default_op: The operator to use to combine non-filter query items when no explicit operator is used.

So for example, ‘weather forecast’ is parsed as if it were ‘weather OR forecast’ by default.

The most useful values for this are OP_OR (the default) and OP_AND. OP_NEAR, OP_PHRASE, OP_ELITE_SET, OP_SYNONYM and OP_MAX are also permitted. Passing other values will result in InvalidArgumentError being thrown.

set_max_expansion()

Specify the maximum expansion of a wildcard and/or partial and/or fuzzy term.

void Xapian::QueryParser::set_max_expansion(Xapian::termcount max_expansion, int max_type=Xapian::Query::WILDCARD_LIMIT_ERROR, unsigned flags=FLAG_WILDCARD|FLAG_PARTIAL|FLAG_FUZZY) Xapian::QueryParser::set_max_expansion Note: you must also set FLAG_WILDCARD and/or FLAG_PARTIAL and/or FLAG_FUZZY in the flags parameter to parse_query() for this setting to have anything to affect.

If you don’t call this method, the default settings are no limit on wildcard and fuzzy expansion, and partial terms expanding to the most frequent 100 terms - i.e. as if you’d called:

set_max_expansion(0); set_max_expansion(100, Xapian::Query::WILDCARD_LIMIT_MOST_FREQUENT, Xapian::QueryParser::FLAG_PARTIAL);

max_expansion: The maximum number of terms each wildcard in the query can expand to, or 0 for no limit (which is the default).

max_type: Xapian::Query::WILDCARD_LIMIT_ERROR, Xapian::Query::WILDCARD_LIMIT_FIRST or Xapian::Query::WILDCARD_LIMIT_MOST_FREQUENT (default: Xapian::Query::WILDCARD_LIMIT_ERROR).

flags: What to set the limit for (default: FLAG_WILDCARD|FLAG_PARTIAL|FLAG_FUZZY, setting the limit for all types).

1.3.3

set_min_wildcard_prefix()

Specify minimum length for fixed initial portion in wildcard patterns.

void Xapian::QueryParser::set_min_wildcard_prefix(unsigned min_prefix_len, unsigned flags=FLAG_WILDCARD|FLAG_PARTIAL) Xapian::QueryParser::set_min_wildcard_prefix It can be desirable for performance reasons to restrict use of wildcards to patterns with a fixed initial portion, so this method provides a way to specify a minimum length. A wildcard pattern with a shorter (or no) fixed initial portion will result in Xapian::QueryParser being thrown. The default minimum length is 0.

It also provides a way to specify the minimum length of a word to expand for partial matching (see FLAG_PARTIAL). In this case a shorter word at the end of the query simply result in no partial matching. The default minimum length for this case is 2 (since 2.0.0 - in earlier versions it was effectively 0).

min_prefix_len: Minimum length of fixed initial portion in Unicode characters.

flags: What to set the minimum length for (default: FLAG_WILDCARD|FLAG_PARTIAL, setting the limit for both wildcards and partial terms).

Added in Xapian 2.0.0.

set_stemmer()

Set the stemmer.

void Xapian::QueryParser::set_stemmer(const Xapian::Stem &stemmer) Xapian::QueryParser::set_stemmer This sets the stemming algorithm which will be used by the query parser. The stemming algorithm will be used according to the stemming strategy set by set_stemming_strategy(). As of 1.3.1, this defaults to STEM_SOME, but in earlier versions the default was STEM_NONE. If you want to work with older versions, you should explicitly set a stemming strategy as well as setting a stemmer, otherwise your stemmer won’t actually be used.

stemmer: The Xapian::Stem object to set.

set_stemming_strategy()

Set the stemming strategy.

void Xapian::QueryParser::set_stemming_strategy(stem_strategy strategy) Xapian::QueryParser::set_stemming_strategy This controls how the query parser will apply the stemming algorithm. Note that the stemming algorithm is only applied to words in free-text fields - boolean filter terms are never stemmed.

strategy: The strategy to use - possible values are: STEM_NONE: Don’t perform any stemming. (default in Xapian <= 1.3.0)

STEM_SOME: Stem all terms except for those which start with a capital letter, or are followed by certain characters (currently: (/@<>=*[{” ), or are used with operators which need positional information. Stemmed terms are prefixed with ‘Z’. (default in Xapian >= 1.3.1)

STEM_SOME_FULL_POS: Like STEM_SOME but also stems terms used with operators which need positional information. Added in Xapian 1.4.8.

STEM_ALL: Stem all terms (note: no ‘Z’ prefix is added).

STEM_ALL_Z: Stem all terms (note: ‘Z’ prefix is added). (new in Xapian 1.2.11 and 1.3.1)

set_stopper(stopper)

Set the stopper.

void Xapian::QueryParser::set_stopper(const Stopper *stop=NULL) Xapian::QueryParser::set_stopper

stop: The Stopper object to set (default NULL, which means no stopwords).

set_stopper_strategy()

Set the stopper strategy.

void Xapian::QueryParser::set_stopper_strategy(stop_strategy strategy) Xapian::QueryParser::set_stopper_strategy This method controls how the stopper is used.

You need to also call set_stopper() for this to have any effect.

strategy: The strategy to use - possible values are: STOP_NONE: Don’t use the stopper.

STOP_ALL: If a word is identified as a stop word, skip it completely. This makes some queries less useful (e.g. “to be or not to be that is the question” would become a search for just question if the other words were all stopwords). If you index with STOP_ALL you should use it when parsing queries too.

STOP_STEMMED: If a word is identified as a stop word, assume it was still indexed unstemmed and don’t treat it as a stopword in contexts where we would use the unstemmed form (for example, phrase searches, ADJ, NEAR). (This is the default mode).

Added in Xapian 2.0.0.

stoplist()

Get an iterator over all the stopped terms from the previous query.

This returns an iterator over all the terms which were omitted from the previously parsed query due to being considered to be stopwords. Each instance of a word omitted from the query is represented in the returned list, in the order in which the

The iterator will return string objects.

property thisown

The membership flag

unstemlist(tname)

Get an iterator over all the unstemmed forms of a stemmed term.

This returns an iterator which returns all the unstemmed words which were stemmed to the stemmed form specified by tname when parsing the previous query. Each instance of a word which stems to tname is returned by the iterator in the order in which the words appeared in the query - an individual unstemmed word may thus occur multiple times.

The iterator will return string objects.

exception xapian.QueryParserError(*args)

Bases: xapian.RuntimeError

Indicates a query string can’t be parsed.

property thisown

The membership flag

class xapian.RSet

Bases: object

Class representing a set of documents judged as relevant.

add_document()

Mark a document as relevant.

void Xapian::RSet::add_document(const Xapian::MSetIterator &it) Xapian::RSet::add_document If did is already marked as relevant, nothing happens.

contains()

Check if a document is marked as relevant.

bool Xapian::RSet::contains(const Xapian::MSetIterator &it) const Xapian::RSet::contains

empty()

Return true if this RSet object is empty.

bool Xapian::RSet::empty() const Xapian::RSet::empty

remove_document()

Unmark a document as relevant.

void Xapian::RSet::remove_document(const Xapian::MSetIterator &it) Xapian::RSet::remove_document If did is not marked as relevant, nothing happens.

size()

Return number of documents in this RSet object.

Xapian::doccount Xapian::RSet::size() const Xapian::RSet::size

property thisown

The membership flag

exception xapian.RangeError(*args)

Bases: xapian.RuntimeError

RangeError indicates an attempt to access outside the bounds of a container.

property thisown

The membership flag

class xapian.RangeProcessor(*args)

Bases: object

Base class for range processors.

check_range()

Check prefix/suffix on range.

Xapian::Query Xapian::RangeProcessor::check_range(const std::string &b, const std::string &e) Xapian::RangeProcessor::check_range If they match, remove the prefix/suffix and then call operator()() to try to handle the range.

release()

Start reference counting this object.

const RangeProcessor * Xapian::RangeProcessor::release() const Xapian::RangeProcessor::release You can transfer ownership of a dynamically allocated RangeProcessor object to Xapian by calling release() and then passing the object to a Xapian method. Xapian will arrange to delete the object once it is no longer required.

property thisown

The membership flag

class xapian.Registry

Bases: object

Registry for user subclasses.

This class provides a way for the remote server to look up user subclasses when unserialising.

get_key_maker()

Get a KeyMaker given a name.

const Xapian::KeyMaker * Xapian::Registry::get_key_maker(std::string_view name) const Xapian::Registry::get_key_maker

name: The name of the KeyMaker to find.

An object with the requested name, or NULL if the KeyMaker could not be found. The returned object must not be deleted by the caller.

Added in Xapian 2.0.0.

get_lat_long_metric()

Get a lat-long metric given a name.

const Xapian::LatLongMetric * Xapian::Registry::get_lat_long_metric(std::string_view name) const Xapian::Registry::get_lat_long_metric The returned metric is owned by the registry object.

Returns NULL if the metric could not be found.

get_match_spy()

Get a match spy given a name.

const Xapian::MatchSpy * Xapian::Registry::get_match_spy(std::string_view name) const Xapian::Registry::get_match_spy

name: The name of the match spy to find.

An object with the requested name, or NULL if the match spy could not be found. The returned object is owned by the registry and so must not be deleted by the caller.

get_posting_source()

Get a posting source given a name.

const Xapian::PostingSource * Xapian::Registry::get_posting_source(std::string_view name) const Xapian::Registry::get_posting_source

name: The name of the posting source to find.

An object with the requested name, or NULL if the posting source could not be found. The returned object is owned by the registry and so must not be deleted by the caller.

get_weighting_scheme()

Get the weighting scheme given a name.

const Xapian::Weight * Xapian::Registry::get_weighting_scheme(std::string_view name) const Xapian::Registry::get_weighting_scheme

name: The name of the weighting scheme to find.

An object with the requested name, or NULL if the weighting scheme could not be found. The returned object is owned by the registry and so must not be deleted by the caller.

register_key_maker()

Register a user-defined KeyMaker subclass.

void Xapian::Registry::register_key_maker(Xapian::KeyMaker *keymaker) Xapian::Registry::register_key_maker

keymaker: The KeyMaker subclass to register. The clean up of this object is handled via Xapian’s optional reference counting. The simplest way to do so is to allocate it with new and call release() on it before passing it to this method to tell Xapian to manage its lifetime. The alternative approach is for the caller to ensure the KeyMaker object remains valid for the lifetime of the Registry object.

Added in Xapian 2.0.0.

register_lat_long_metric()

Register a user-defined lat-long metric class.

void Xapian::Registry::register_lat_long_metric(const Xapian::LatLongMetric &metric) Xapian::Registry::register_lat_long_metric

register_match_spy()

Register a user-defined match spy class.

void Xapian::Registry::register_match_spy(const Xapian::MatchSpy &spy) Xapian::Registry::register_match_spy

spy: The match spy to register.

register_posting_source()

Register a user-defined posting source class.

void Xapian::Registry::register_posting_source(const Xapian::PostingSource &source) Xapian::Registry::register_posting_source

source: The posting source to register.

register_weighting_scheme()

Register a weighting scheme.

void Xapian::Registry::register_weighting_scheme(const Xapian::Weight &wt) Xapian::Registry::register_weighting_scheme

wt: The weighting scheme to register.

property thisown

The membership flag

exception xapian.RuntimeError(*args, **kwargs)

Bases: xapian.Error

The base class for exceptions indicating errors only detectable at runtime.

A subclass of RuntimeError will be thrown if Xapian detects an error which is exception derived from RuntimeError is thrown when an error is caused by problems with the data or environment rather than a programming mistake.

property thisown

The membership flag

exception xapian.SerialisationError(*args)

Bases: xapian.RuntimeError

Indicates an error in the std::string serialisation of an object.

property thisown

The membership flag

class xapian.SimpleStopper(*args)

Bases: xapian.Stopper

Simple implementation of Stopper class - this will suit most users.

add()

Add a single stop word.

void Xapian::SimpleStopper::add(const std::string &word) Xapian::SimpleStopper::add

property thisown

The membership flag

class xapian.Stem(*args)

Bases: object

Class representing a stemming algorithm.

static get_available_languages()

is_none()

Return true if this is a no-op stemmer.

bool Xapian::Stem::is_none() const Xapian::Stem::is_none

property thisown

The membership flag

class xapian.StemImplementation

Bases: object

Class representing a stemming algorithm implementation.

property thisown

The membership flag

use_proper_noun_heuristic()

Should QueryParser suppress stemming for capitalised words?

virtual bool Xapian::StemImplementation::use_proper_noun_heuristic() const Xapian::StemImplementation::use_proper_noun_heuristic See QueryParser::feature_flag value FLAG_NO_PROPER_NOUN_HEURISTIC for details.

The default implementation of this method returns false.

Xapian 2.0.0.

class xapian.Stopper

Bases: object

Abstract base class for stop-word decision functor.

If you just want to use an existing stopword list, see Xapian::SimpleStopper.

release()

Start reference counting this object.

const Stopper * Xapian::Stopper::release() const Xapian::Stopper::release You can transfer ownership of a dynamically allocated Stopper object to Xapian by calling release() and then passing the object to a Xapian method. Xapian will arrange to delete the object once it is no longer required.

property thisown

The membership flag

class xapian.TermGenerator

Bases: object

Parses a piece of text and generate terms.

This module takes a piece of text and parses it to produce words which are then used to generate suitable terms for indexing. The terms generated are suitable for use with Query objects produced by the QueryParser class.

FLAG_CJK_NGRAM = 2048

FLAG_NGRAMS = 2048

FLAG_SPELLING = 128

FLAG_WORD_BREAKS = 4096

STEM_ALL = 2

STEM_ALL_Z = 3

STEM_NONE = 0

STEM_SOME = 1

STEM_SOME_FULL_POS = 4

STOP_ALL = 1

STOP_NONE = 0

STOP_STEMMED = 2

get_document()

Get the current document.

const Xapian::Document & Xapian::TermGenerator::get_document() const Xapian::TermGenerator::get_document

get_termpos()

Get the current term position.

Xapian::termpos Xapian::TermGenerator::get_termpos() const Xapian::TermGenerator::get_termpos

increase_termpos()

Increase the term position used by index_text.

void Xapian::TermGenerator::increase_termpos(Xapian::termpos delta=100) Xapian::TermGenerator::increase_termpos This can be used between indexing text from different fields or other places to prevent phrase searches from spanning between them (e.g. between the title and body text, or between two chapters in a book).

delta: Amount to increase the term position by (default: 100).

index_text()

Index some text.

void Xapian::TermGenerator::index_text(std::string_view text, Xapian::termcount wdf_inc=1, std::string_view prefix={}) Xapian::TermGenerator::index_text

text: The text to index.

wdf_inc: The wdf increment (default 1).

prefix: The term prefix to use (default is no prefix).

index_text_without_positions()

Index some text without positional information.

void Xapian::TermGenerator::index_text_without_positions(std::string_view text, Xapian::termcount wdf_inc=1, std::string_view prefix={}) Xapian::TermGenerator::index_text_without_positions Just like index_text, but no positional information is generated. This means that the database will be significantly smaller, but that phrase searching and NEAR won’t be supported.

text: The text to index.

wdf_inc: The wdf increment (default 1).

prefix: The term prefix to use (default is no prefix).

set_database()

Set the database to index spelling data to.

void Xapian::TermGenerator::set_database(const Xapian::WritableDatabase &db) Xapian::TermGenerator::set_database

set_document()

Set the current document.

void Xapian::TermGenerator::set_document(const Xapian::Document &doc) Xapian::TermGenerator::set_document

set_flags()

Set flags.

flags Xapian::TermGenerator::set_flags(flags toggle, flags mask=flags(0)) Xapian::TermGenerator::set_flags The new value of flags is: (flags & mask) ^ toggle

To just set the flags, pass the new flags in toggle and the default value for mask.

toggle: Flags to XOR.

mask: Flags to AND with first.

The old flags setting.

set_max_word_length()

Set the maximum length word to index.

void Xapian::TermGenerator::set_max_word_length(unsigned max_word_length) Xapian::TermGenerator::set_max_word_length The limit is on the length of a word prior to stemming and prior to adding any term prefix.

The backends mostly impose a limit on the length of terms (often of about 240 bytes), but it’s generally useful to have a lower limit to help prevent the index being bloated by useless junk terms from trying to indexing things like binary data, uuencoded data, ASCII art, etc.

max_word_length: The maximum length word to index, in bytes in UTF-8 representation. Default is 64.

Added in Xapian 1.3.1.

set_stemmer()

Set the Xapian::Stem object to be used for generating stemmed terms.

void Xapian::TermGenerator::set_stemmer(const Xapian::Stem &stemmer) Xapian::TermGenerator::set_stemmer

set_stemming_strategy()

Set the stemming strategy.

void Xapian::TermGenerator::set_stemming_strategy(stem_strategy strategy) Xapian::TermGenerator::set_stemming_strategy This method controls how the stemming algorithm is applied.

strategy: The strategy to use - possible values are: STEM_NONE: Don’t perform any stemming - only unstemmed terms are generated.

STEM_SOME: Generate both stemmed (with a “Z” prefix) and unstemmed terms. No positional information is stored for unstemmed terms. This is the default strategy.

STEM_SOME_FULL_POS: Like STEM_SOME but positional information is stored for both stemmed and unstemmed terms. Added in Xapian 1.4.8.

STEM_ALL: Generate only stemmed terms (but without a “Z” prefix).

STEM_ALL_Z: Generate only stemmed terms (with a “Z” prefix).

Added in Xapian 1.3.1.

set_stopper(stopper)

Set the Xapian::Stopper object to be used for identifying stopwords.

void Xapian::TermGenerator::set_stopper(const Xapian::Stopper *stop=NULL) Xapian::TermGenerator::set_stopper Stemmed forms of stopwords aren’t indexed, but unstemmed forms still are so that searches for phrases including stop words still work.

stop: The Stopper object to set (default NULL, which means no stopwords).

set_stopper_strategy()

Set the stopper strategy.

void Xapian::TermGenerator::set_stopper_strategy(stop_strategy strategy) Xapian::TermGenerator::set_stopper_strategy The method controls how the stopper is used.

You need to also call set_stopper() for this to have any effect.

strategy: The strategy to use - possible values are: STOP_NONE: Don’t use the stopper.

STOP_ALL: If a word is identified as a stop word, skip it completely.

STOP_STEMMED: If a word is identified as a stop word, index its unstemmed form but skip the stem. Unstemmed forms are indexed with positional information by default, so this allows searches for phrases containing stopwords to be supported. (This is the default mode).

Added in Xapian 1.4.1.

set_termpos()

Set the current term position.

void Xapian::TermGenerator::set_termpos(Xapian::termpos termpos) Xapian::TermGenerator::set_termpos

termpos: The new term position to set.

set_termpos_limit()

Set the term position limit.

void Xapian::TermGenerator::set_termpos_limit(Xapian::termpos termpos_limit) Xapian::TermGenerator::set_termpos_limit

termpos_limit: Upper bound on term positions that can be added.

By default the only limit is the maximum value of the Xapian::termpos type.

Added in Xapian 2.0.0.

property thisown

The membership flag

class xapian.TermIter(start, end, has_termfreq=0, has_wdf=0, has_positions=0, return_strings=False)

Bases: object

An iterator over a term list.

The iterator will return TermListItem objects, which will be evaluated lazily where appropriate.

EAGER = 2

INVALID = 0

LAZY = 1

skip_to(term)

Skip the iterator forward.

The iterator is advanced to the first term at or after the current position which is greater than or equal to the supplied term.

If there are no such items, this will raise StopIteration.

This returns the item which the iterator is moved to. The subsequent item will be returned the next time that next() is called (unless skip_to() is called again first).

class xapian.TermListItem(iter, term)

Bases: object

An item returned from iteration of a term list.

The item supports access to the following attributes and properties:

• term: The term corresponding to this TermListItem.

• wdf: The within document frequency of this term.

• termfreq: The number of documents in the collection which are indexed by the term

• positer: An iterator over the positions which the term appears at in the document. This is only available until the iterator which returned this item next moves.

property positer

A position iterator for the current term (if meaningful).

The iterator will return integers representing the positions that the term occurs at.

This will raise a InvalidOperationError exception if the iterator this item came from doesn’t support position lists, or if the iterator has moved on since the item was returned from it.

term

property termfreq

The term frequency of the current term (if meaningful).

This is the number of documents in the collection which are indexed by the term.

This will raise a InvalidOperationError exception if the iterator this item came from doesn’t support term frequencies.

property wdf

The within-document-frequency of the current term (if meaningful).

This will raise a InvalidOperationError exception if the iterator this item came from doesn’t support within-document-frequencies.

class xapian.TfIdfWeight(*args)

Bases: xapian.Weight

Xapian::Weight subclass implementing the tf-idf weighting scheme.

create_from_parameters()

Create from a human-readable parameter string.

TfIdfWeight * Xapian::TfIdfWeight::create_from_parameters(const char *params) const Xapian::TfIdfWeight::create_from_parameters

params: string containing weighting scheme parameter values.

2.0.0

idf_norm_FREQ = 4

idf_norm_GLOBAL_FREQ = 7

idf_norm_INCREMENTED_GLOBAL_FREQ = 9

idf_norm_LOG_GLOBAL_FREQ = 8

idf_norm_NONE = 1

idf_norm_PIVOTED = 6

idf_norm_PROB = 5

idf_norm_SQRT_GLOBAL_FREQ = 10

idf_norm_SQUARE = 3

idf_norm_TFIDF = 2

property thisown

The membership flag

wdf_norm_AUG = 11

wdf_norm_AUG_AVERAGE = 9

wdf_norm_AUG_LOG = 7

wdf_norm_BOOLEAN = 2

wdf_norm_LOG = 4

wdf_norm_LOG_AVERAGE = 6

wdf_norm_MAX = 10

wdf_norm_NONE = 1

wdf_norm_PIVOTED = 5

wdf_norm_SQRT = 8

wdf_norm_SQUARE = 3

wt_norm_NONE = 1

class xapian.TradWeight(k=1.0)

Bases: xapian.BM25Weight

Xapian::Weight subclass implementing the traditional probabilistic formula.

This class implements the “traditional” Probabilistic Weighting scheme, as described by the early papers on Probabilistic Retrieval. BM25 generally gives better results.

TradWeight(k) is equivalent to BM25Weight(k, 0, 0, 1, 0), and since Xapian 2.0.0 TradWeight is actually implemented as a subclass of BM25Weight. In earlier versions is was a separate class which was equivalent except it returned weights (k+1) times smaller.

Deprecated Use BM25Weight(k, 0, 0, 1, 0) instead.

property thisown

The membership flag

exception xapian.UnimplementedError(*args)

Bases: xapian.LogicError

UnimplementedError indicates an attempt to use an unimplemented feature.

property thisown

The membership flag

class xapian.UnitRangeProcessor(*args)

Bases: xapian.RangeProcessor

Handle a byte unit range.

This class must be used on values which have been encoded using Xapian::sortable_serialise() which turns numbers into strings which will sort in the same order as the numbers (the same values can be used to implement a numeric sort).

Added in Xapian 2.0.0.

property thisown

The membership flag

class xapian.ValueCountMatchSpy(*args)

Bases: xapian.MatchSpy

Class for counting the frequencies of values in the matching documents.

get_total()

Return the total number of documents tallied.

size_t Xapian::ValueCountMatchSpy::get_total() const noexcept Xapian::ValueCountMatchSpy::get_total

property thisown

The membership flag

top_values(maxvalues)

Get an iterator over the most frequent values for the slot.

Values will be returned in descending order of frequency. Values with the same frequency will be returned in ascending alphabetical order.

The iterator will return TermListItem objects: the value can be accessed as the term property, and the frequency can be accessed as the termfreq property.

values()

Get an iterator over all the values in the slot.

Values will be returned in ascending alphabetical order.

The iterator will return TermListItem objects: the value can be accessed as the term property, and the frequency can be accessed as the termfreq property.

class xapian.ValueItem(num, value)

Bases: object

An item returned from iteration of the values in a document.

The item supports access to the following attributes:

• num: The number of the value.

• value: The contents of the value.

num

value

class xapian.ValueIter(start, end)

Bases: object

An iterator over all the values stored in a document.

The iterator will return ValueItem objects, in ascending order of value number.

class xapian.ValueMapPostingSource(slot_)

Bases: xapian.ValuePostingSource

A posting source which looks up weights in a map using values as the key.

This allows will return entries for all documents in the given database which have a value in the slot specified. The values will be mapped to the corresponding weight in the weight map. If there is no mapping for a particular value, the default weight will be returned (which itself defaults to 0.0).

add_mapping()

Add a mapping.

void Xapian::ValueMapPostingSource::add_mapping(const std::string &key, double wt) Xapian::ValueMapPostingSource::add_mapping

key: The key looked up from the value slot.

wt: The weight to give this key.

clear_mappings()

Clear all mappings.

void Xapian::ValueMapPostingSource::clear_mappings() Xapian::ValueMapPostingSource::clear_mappings

set_default_weight()

Set a default weight for document values not in the map.

void Xapian::ValueMapPostingSource::set_default_weight(double wt) Xapian::ValueMapPostingSource::set_default_weight

wt: The weight to set as the default.

property thisown

The membership flag

class xapian.ValuePostingSource(slot_)

Bases: xapian.PostingSource

A posting source which generates weights from a value slot.

This is a base class for classes which generate weights using values stored in the specified slot. For example, ValueWeightPostingSource uses sortable_unserialise to convert values directly to weights.

The upper bound on the weight returned is set to DBL_MAX. Subclasses should call set_maxweight() in their init() methods after calling ValuePostingSource::init() if they know a tighter bound on the weight.

at_end()

Return true if the current position is past the last entry in this list.

bool Xapian::ValuePostingSource::at_end() const Xapian::ValuePostingSource::at_end At least one of next(), skip_to() or check() will be called before this method is first called.

check()

Check if the specified docid occurs.

bool Xapian::ValuePostingSource::check(Xapian::docid min_docid, double min_wt) Xapian::ValuePostingSource::check The caller is required to ensure that the specified document id did actually exists in the database. If it does, it must move to that document id, and return true. If it does not, it may either:

return true, having moved to a definite position (including “at_end”), which must be the same position as skip_to() would have moved to.

or

return false, having moved to an “indeterminate” position, such that a subsequent call to next() or skip_to() will move to the next matching position after did.

Generally, this method should act like skip_to() and return true if that can be done at little extra cost.

Otherwise it should simply check if a particular docid is present, returning true if it is, and false if it isn’t.

The default implementation calls skip_to() and always returns true.

Xapian will always call reset() on a PostingSource before calling this for the first time.

Note: in the case of a multi-database search, the docid specified is the docid in the single subdatabase relevant to this posting source. See the reset() method for details.

did: The document id to check.

min_wt: The minimum weight contribution that is needed (this is just a hint which subclasses may ignore).

done()

End the iteration.

void Xapian::ValuePostingSource::done() Xapian::ValuePostingSource::done Calls to at_end() will return true after calling this method.

Added in 1.2.23 and 1.3.5.

get_database()

The database we’re reading values from.

Xapian::Database Xapian::ValuePostingSource::get_database() const Xapian::ValuePostingSource::get_database

Added in 1.2.23 and 1.3.5.

get_docid()

Return the current docid.

Xapian::docid Xapian::ValuePostingSource::get_docid() const Xapian::ValuePostingSource::get_docid This method may assume that it will only be called when there is a “current document”. See get_weight() for details.

Note: in the case of a multi-database search, the returned docid should be in the single subdatabase relevant to this posting source. See the reset() method for details.

get_slot()

The slot we’re reading values from.

Xapian::valueno Xapian::ValuePostingSource::get_slot() const Xapian::ValuePostingSource::get_slot

Added in 1.2.23 and 1.3.5.

get_started()

Flag indicating if we’ve started (true if we have).

bool Xapian::ValuePostingSource::get_started() const Xapian::ValuePostingSource::get_started

Added in 1.2.23 and 1.3.5.

get_termfreq_est()

An estimate of the number of documents this object can return.

Xapian::doccount Xapian::ValuePostingSource::get_termfreq_est() const Xapian::ValuePostingSource::get_termfreq_est It must always be true that:

get_termfreq_min() <= get_termfreq_est() <= get_termfreq_max()

Xapian will always call reset() on a PostingSource before calling this for the first time.

get_termfreq_max()

An upper bound on the number of documents this object can return.

Xapian::doccount Xapian::ValuePostingSource::get_termfreq_max() const Xapian::ValuePostingSource::get_termfreq_max Xapian will always call reset() on a PostingSource before calling this for the first time.

get_termfreq_min()

A lower bound on the number of documents this object can return.

Xapian::doccount Xapian::ValuePostingSource::get_termfreq_min() const Xapian::ValuePostingSource::get_termfreq_min Xapian will always call reset() on a PostingSource before calling this for the first time.

get_value()

Read current value.

std::string Xapian::ValuePostingSource::get_value() const Xapian::ValuePostingSource::get_value

Added in 1.2.23 and 1.3.5.

reset()

Set this PostingSource to the start of the list of postings.

void Xapian::ValuePostingSource::reset(const Database &db_, Xapian::doccount shard_index) Xapian::ValuePostingSource::reset This is called automatically by the matcher prior to each query being processed.

If a PostingSource is used for multiple searches, reset() will therefore be called multiple times, and must handle this by using the database passed in the most recent call.

db: The database which the PostingSource should iterate through.

shard_index: The 0-based index indicating which shard in a multi- database db is. This can be useful if you have an external source of postings corresponding to each shard.

Note: in the case of a multi-database search, a separate PostingSource will be used for each database (the separate PostingSources will be obtained using clone()), and each PostingSource will be passed one of the sub-databases as the db parameter here. The db parameter will therefore always refer to a single database. All docids passed to, or returned from, the PostingSource refer to docids in that single database, rather than in the multi- database.

A default implementation is provided which calls the older init() method to allow existing subclasses to continue to work, but the default implementation of init() throws Xapian::InvalidOperationError so you must override either this method or init(). In new code, override this method in preference.

Added in Xapian 2.0.0.

set_termfreq_est()

An estimate of the term frequency.

void Xapian::ValuePostingSource::set_termfreq_est(Xapian::doccount termfreq_est_) Xapian::ValuePostingSource::set_termfreq_est Subclasses should set this if they are overriding the next(), skip_to() or check() methods.

Added in 1.2.23 and 1.3.5.

set_termfreq_max()

An upper bound on the term frequency.

void Xapian::ValuePostingSource::set_termfreq_max(Xapian::doccount termfreq_max_) Xapian::ValuePostingSource::set_termfreq_max Subclasses should set this if they are overriding the next(), skip_to() or check() methods.

Added in 1.2.23 and 1.3.5.

set_termfreq_min()

Set a lower bound on the term frequency.

void Xapian::ValuePostingSource::set_termfreq_min(Xapian::doccount termfreq_min_) Xapian::ValuePostingSource::set_termfreq_min Subclasses should set this if they are overriding the next(), skip_to() or check() methods to return fewer documents.

Added in 1.2.23 and 1.3.5.

skip_to()

Advance to the specified docid.

void Xapian::ValuePostingSource::skip_to(Xapian::docid min_docid, double min_wt) Xapian::ValuePostingSource::skip_to If the specified docid isn’t in the list, position ourselves on the first document after it (or at_end() if no greater docids are present).

If the current position is already the specified docid, this method will leave the position unmodified.

If the specified docid is earlier than the current position, the behaviour is unspecified. A sensible behaviour would be to leave the current position unmodified, but it is also reasonable to move to the specified docid.

The default implementation calls next() repeatedly, which works but skip_to() can often be implemented much more efficiently.

Xapian will always call reset() on a PostingSource before calling this for the first time.

Note: in the case of a multi-database search, the docid specified is the docid in the single subdatabase relevant to this posting source. See the reset() method for details.

did: The document id to advance to.

min_wt: The minimum weight contribution that is needed (this is just a hint which subclasses may ignore).

property thisown

The membership flag

class xapian.ValueSetMatchDecider(slot, inclusive_)

Bases: xapian.MatchDecider

MatchDecider filtering results based on whether document values are in a user- defined set.

add_value()

Add a value to the test set.

void Xapian::ValueSetMatchDecider::add_value(const std::string &value) Xapian::ValueSetMatchDecider::add_value

value: The value to add to the test set.

remove_value()

Remove a value from the test set.

void Xapian::ValueSetMatchDecider::remove_value(const std::string &value) Xapian::ValueSetMatchDecider::remove_value

value: The value to remove from the test set.

property thisown

The membership flag

class xapian.ValueStreamItem(docid, value)

Bases: object

An item returned from iteration of the values in a document.

The item supports access to the following attributes:

• docid: The docid for the item.

• value: The contents of the value.

docid

value

class xapian.ValueStreamIter(start, end)

Bases: object

An iterator over all the values stored in a document.

The iterator will return ValueStreamItem objects, in ascending order of value number.

skip_to(docid)

Skip the iterator forward.

The iterator is advanced to the first document with a document ID which is greater than or equal to the supplied document ID.

If there are no such items, this will raise StopIteration.

This returns the item which the iterator is moved to. The subsequent item will be returned the next time that next() is called (unless skip_to() is called again first).

class xapian.ValueWeightPostingSource(slot_)

Bases: xapian.ValuePostingSource

A posting source which reads weights from a value slot.

This returns entries for all documents in the given database which have a non empty values in the specified slot. It returns a weight calculated by applying sortable_unserialise to the value stored in the slot (so the values stored should probably have been calculated by applying sortable_serialise to a floating point number at index time).

The upper bound on the weight returned is set using the upper bound on the values in the specified slot, or DBL_MAX if value bounds aren’t supported by the current backend.

For efficiency, this posting source doesn’t check that the stored values are valid in any way, so it will never raise an exception due to invalid stored values. In particular, it doesn’t ensure that the unserialised values are positive, which is a requirement for weights. The behaviour if the slot contains values which unserialise to negative values is undefined.

get_weight()

Return the weight contribution for the current document.

double Xapian::ValueWeightPostingSource::get_weight() const Xapian::ValueWeightPostingSource::get_weight This default implementation always returns 0, for convenience when implementing “weight-less” PostingSource subclasses.

This method may assume that it will only be called when there is a “current document”. In detail: Xapian will always call reset() on a PostingSource before calling this for the first time. It will also only call this if the PostingSource reports that it is pointing to a valid document (ie, it will not call it before calling at least one of next(), skip_to() or check(), and will ensure that the PostingSource is not at the end by calling at_end()).

name()

Name of the posting source class.

std::string Xapian::ValueWeightPostingSource::name() const Xapian::ValueWeightPostingSource::name This is used when serialising and unserialising posting sources; for example, for performing remote searches.

If the subclass is in a C++ namespace, the namespace should be included in the name, using “::” as a separator. For example, for a PostingSource subclass called “FooPostingSource” in the “Xapian” namespace the result of this call should be “Xapian::FooPostingSource”.

This should only be implemented if serialise() and unserialise() are also implemented. The default implementation returns an empty string.

If this returns an empty string, Xapian will assume that serialise() and unserialise() are not implemented.

reset()

Set this PostingSource to the start of the list of postings.

void Xapian::ValueWeightPostingSource::reset(const Database &db_, Xapian::doccount shard_index) Xapian::ValueWeightPostingSource::reset This is called automatically by the matcher prior to each query being processed.

If a PostingSource is used for multiple searches, reset() will therefore be called multiple times, and must handle this by using the database passed in the most recent call.

db: The database which the PostingSource should iterate through.

shard_index: The 0-based index indicating which shard in a multi- database db is. This can be useful if you have an external source of postings corresponding to each shard.

Note: in the case of a multi-database search, a separate PostingSource will be used for each database (the separate PostingSources will be obtained using clone()), and each PostingSource will be passed one of the sub-databases as the db parameter here. The db parameter will therefore always refer to a single database. All docids passed to, or returned from, the PostingSource refer to docids in that single database, rather than in the multi- database.

A default implementation is provided which calls the older init() method to allow existing subclasses to continue to work, but the default implementation of init() throws Xapian::InvalidOperationError so you must override either this method or init(). In new code, override this method in preference.

Added in Xapian 2.0.0.

property thisown

The membership flag

class xapian.Weight(*args, **kwargs)

Bases: object

Abstract base class for weighting schemes.

static create()

create_from_parameters()

Create from a human-readable parameter string.

virtual Weight * Xapian::Weight::create_from_parameters(const char *params) const Xapian::Weight::create_from_parameters

params: string containing weighting scheme parameter values.

2.0.0

get_maxextra()

Return an upper bound on what get_sumextra() can return for any document.

virtual double Xapian::Weight::get_maxextra() const Xapian::Weight::get_maxextra The default implementation always returns 0 (in Xapian < 2.0.0 this was a pure virtual method).

This information is used by the matcher to perform various optimisations, so strive to make the bound as tight as possible.

get_maxpart()

Return an upper bound on what get_sumpart() can return for any document.

virtual double Xapian::Weight::get_maxpart() const =0 Xapian::Weight::get_maxpart This information is used by the matcher to perform various optimisations, so strive to make the bound as tight as possible.

get_sumextra()

Calculate the term-independent weight component for a document.

virtual double Xapian::Weight::get_sumextra(Xapian::termcount doclen, Xapian::termcount uniqterms, Xapian::termcount wdfdocmax) const Xapian::Weight::get_sumextra The default implementation always returns 0 (in Xapian < 2.0.0 this was a pure virtual method).

The parameter gives information about the document which may be used in the calculations:

doclen: The document’s length (unnormalised). You need to call need_stat(DOC_LENGTH) if you use this value.

uniqterms: Number of unique terms in the document. You need to call need_stat(UNIQUE_TERMS) if you use this value.

wdfdocmax: Maximum wdf value in the document. You need to call need_stat(WDF_DOC_MAX) if you use this value.

The wdfdocmax parameter was added in Xapian 2.0.0.

get_sumpart()

Calculate the weight contribution for this object’s term to a document.

virtual double Xapian::Weight::get_sumpart(Xapian::termcount wdf, Xapian::termcount doclen, Xapian::termcount uniqterms, Xapian::termcount wdfdocmax) const =0 Xapian::Weight::get_sumpart The parameters give information about the document which may be used in the calculations:

wdf: The within document frequency of the term in the document. You need to call need_stat(WDF) if you use this value.

doclen: The document’s length (unnormalised). You need to call need_stat(DOC_LENGTH) if you use this value.

uniqterms: Number of unique terms in the document. You need to call need_stat(UNIQUE_TERMS) if you use this value.

wdfdocmax: Maximum wdf value in the document. You need to call need_stat(WDF_DOC_MAX) if you use this value.

You can rely of wdf <= doclen if you call both need_stat(WDF) and need_stat(DOC_LENGTH) - this is trivially true for terms, but Xapian also ensure it’s true for OP_SYNONYM, where the wdf is approximated.

The wdfdocmax parameter was added in Xapian 2.0.0.

name()

Return the name of this weighting scheme, e.g.

virtual std::string Xapian::Weight::name() const Xapian::Weight::name “bm25+”.

This is the name that the weighting scheme gets registered under when passed to Xapian:Registry::register_weighting_scheme().

As a result:

this is the name that needs to be used in Weight::create() to create a Weight object from a human-readable string description.

it is also used by the remote backend where it is sent (along with the serialised parameters) to the remote server so that it knows which class to create.

For 1.4.x and earlier we recommended returning the full namespace- qualified name of your class here, but now we recommend returning a just the name in lower case, e.g. “foo” instead of “FooWeight”, “bm25+” instead of “Xapian::BM25PlusWeight”.

If you don’t want to support creation via Weight::create() or the remote backend, you can use the default implementation which simply returns an empty string.

property thisown

The membership flag

exception xapian.WildcardError(*args)

Bases: xapian.RuntimeError

WildcardError indicates an error expanding a wildcarded query.

property thisown

The membership flag

class xapian.WritableDatabase(*args)

Bases: xapian.Database

This class provides read/write access to a database.

A WritableDatabase object contains zero or more shards, and operations are performed across these shards. Documents added by add_document() are stored to the shards in a round-robin fashion.

2.0.0 This class is a reference counted handle like many other Xapian API classes. In earlier versions, it worked like a typedef to std::vector<database_shard>. The key difference is that previously copying or assigning a Xapian::Database made a deep copy, whereas now it makes a shallow copy. Most methods can throw:

Xapian::DatabaseCorruptError: if database corruption is detected

Xapian::DatabaseError: in various situation (for example, calling methods after close() has been called)

Xapian::NetworkError: when remote databases are in use

add_database()

Add shards from another WritableDatabase.

void Xapian::WritableDatabase::add_database(const WritableDatabase &other) Xapian::WritableDatabase::add_database Any shards in other are added to the list of shards in this object. The shards are reference counted and also remain in other.

other: Another WritableDatabase to add shards from

Xapian::InvalidArgumentError: if other is the same object as this.

add_document()

Add a document to the database.

Xapian::docid Xapian::WritableDatabase::add_document(const Xapian::Document &doc) Xapian::WritableDatabase::add_document The document is allocated document ID ( get_lastdocid() + 1) - the next highest document ID which has never previously been used by this database (so docids from deleted documents won’t be reused).

If you want to specify the document ID to be used, you should call replace_document() instead.

If a transaction is active, the document addition is added to the transaction; otherwise it is added to the current batch of changes. Either way, it won’t be visible to readers right away (unless we’re not in a transaction and the addition triggers an automatic commit).

doc: The Document object to be added.

The document ID allocated to the document.

add_spelling()

Add a word to the spelling dictionary.

void Xapian::WritableDatabase::add_spelling(std::string_view word, Xapian::termcount freqinc=1) const Xapian::WritableDatabase::add_spelling If the word is already present, its frequency is increased.

word: The word to add.

freqinc: How much to increase its frequency by (default 1).

add_synonym()

Add a synonym for a term.

void Xapian::WritableDatabase::add_synonym(std::string_view term, std::string_view synonym) const Xapian::WritableDatabase::add_synonym

term: The term to add a synonym for.

synonym: The synonym to add. If this is already a synonym for term, then no action is taken.

begin_transaction()

Begin a transaction.

void Xapian::WritableDatabase::begin_transaction(bool flushed=true) Xapian::WritableDatabase::begin_transaction A Xapian transaction is a set of consecutive modifications to be committed as an atomic unit - in any committed revision of the database either none are present or they all are.

However, note that if called on a sharded database, atomicity isn’t guaranteed between shards. Within each shard, the transaction will still act atomically.

A transaction is started with begin_transaction() and can either be completed by calling commit_transaction() or aborted by calling cancel_transaction().

Closing the database (by an explicit call to close() or by its destructor being called) when a transaction is active will implicitly call cancel_transaction() to abort the transaction and discard the changes in it.

By default, commit() is implicitly called by begin_transaction() and commit_transaction() so that the changes in the transaction are committed or not independent of changes before or after it.

The downside of these implicit calls to commit() is that small transactions can harm indexing performance in the same way that explicitly calling commit() frequently can.

If you’re applying atomic groups of changes and only wish to ensure that each group is either applied or not applied, then you can prevent the automatic commit() before and after the transaction by starting the transaction with begin_transaction(false). However, if cancel_transaction() is called (or if commit_transaction() isn’t called before the WritableDatabase object is destroyed) then any changes which were pending before the transaction began will also be discarded.

flushed: Is this a flushed transaction? By default transactions are “flushed”, which means that committing a transaction will ensure those changes are permanently written to the database. By contrast, unflushed transactions only ensure that changes within the transaction are either all applied or all aren’t.

Xapian::UnimplementedError: is thrown if this is an InMemory database, which don’t currently support transactions.

Xapian::InvalidOperationError: will be thrown if a transaction is already active.

cancel_transaction()

Abort the transaction currently in progress.

void Xapian::WritableDatabase::cancel_transaction() Xapian::WritableDatabase::cancel_transaction Changes made within the current transaction will be discarded (if the transaction was not begun as a flushed transaction, any changes made but not committed before begin_transaction() will also be discarded).

Xapian::UnimplementedError: is thrown if this is an InMemory database, which don’t currently support transactions.

Xapian::InvalidOperationError: is thrown if no transaction was active.

clear_synonyms()

Remove all synonyms for a term.

void Xapian::WritableDatabase::clear_synonyms(std::string_view term) const Xapian::WritableDatabase::clear_synonyms

term: The term to remove all synonyms for. If the term has no synonyms, no action is taken.

commit()

Commit pending modifications.

void Xapian::WritableDatabase::commit() Xapian::WritableDatabase::commit Updates to a Xapian database are more efficient when applied in bulk, so by default Xapian stores modifications in memory until a threshold is exceeded and then they are committed to disk.

When the database is closed (by an explicit call to close() or its destructor being called) then commit() is implicitly called unless a transaction is active.

You can force any such pending modifications to be committed by calling this method, but bear in mind that the batching happens for a reason and calling commit() a lot is likely to slow down indexing.

If the commit operation succeeds then the changes are reliably written to disk and available to readers. If the commit operation fails, then any pending modifications are discarded.

However, note that if called on a sharded database, atomicity isn’t guaranteed between shards - it’s possible for the changes to one shard to be committed but changes to another shard to fail.

It’s not valid to call commit() within a transaction - see begin_transaction() for more details of how transactions work in Xapian.

Currently batched modifications are automatically committed every 10000 documents added, deleted, or modified. This value is rather conservative, and if you have a machine with plenty of memory, you can improve indexing throughput dramatically by setting XAPIAN_FLUSH_THRESHOLD in the environment to a larger value.

This method was new in Xapian 1.1.0 - in earlier versions it was called flush().

commit_transaction()

Complete the transaction currently in progress.

void Xapian::WritableDatabase::commit_transaction() Xapian::WritableDatabase::commit_transaction If the transaction was begun as a flushed transaction then the changes in it have been committed to the database upon successful completion of this method.

If an exception is thrown, then the changes in the transaction will be discarded (if the transaction was not begun as a flushed transaction, any changes made but not committed before begin_transaction() will also be discarded).

In all cases the transaction will no longer be in progress.

Note that if called on a sharded database, atomicity isn’t guaranteed between shards. Within each shard, the transaction will still act atomically.

Xapian::UnimplementedError: is thrown if this is an InMemory database, which don’t currently support transactions.

Xapian::InvalidOperationError: is thrown if no transaction was active.

delete_document()

Delete any documents indexed by a term from the database.

void Xapian::WritableDatabase::delete_document(std::string_view unique_term) Xapian::WritableDatabase::delete_document This method removes any documents indexed by the specified term from the database.

A major use is for convenience when UIDs from another system are mapped to terms in Xapian, although this method has other uses (for example, you could add a “deletion date” term to documents at index time and use this method to delete all documents due for deletion on a particular date).

unique_term: The term to remove references to.

2.0.0 The changes made by this method are made atomically. Previously automatic commits could happen during the batch.

remove_spelling()

Remove a word from the spelling dictionary.

termcount Xapian::WritableDatabase::remove_spelling(std::string_view word, termcount freqdec=1) const Xapian::WritableDatabase::remove_spelling The word’s frequency is decreased, and if would become zero or less then the word is removed completely.

word: The word to remove.

freqdec: How much to decrease its frequency by (default 1).

Any “unused” freqdec (if the word’s frequency was less than freqdec then the difference is returned, else 0 is returned). Prior to 2.0.0 this method had void return type.

remove_synonym()

Remove a synonym for a term.

void Xapian::WritableDatabase::remove_synonym(std::string_view term, std::string_view synonym) const Xapian::WritableDatabase::remove_synonym

term: The term to remove a synonym for.

synonym: The synonym to remove. If this isn’t currently a synonym for term, then no action is taken.

replace_document()

Replace any documents matching a term.

Xapian::docid Xapian::WritableDatabase::replace_document(std::string_view unique_term, const Xapian::Document &document) Xapian::WritableDatabase::replace_document This method replaces any documents indexed by the specified term with the specified document. If any documents are indexed by the term, the lowest document ID will be used for the document, otherwise a new document ID will be generated as for add_document.

One common use is to allow UIDs from another system to easily be mapped to terms in Xapian. Note that this method doesn’t automatically add unique_term as a term, so you’ll need to call document.add_term(unique_term) first when using replace_document() in this way.

Note that changes to the database won’t be immediately committed to disk; see commit() for more details.

unique_term: The “unique” term.

document: The new document.

The document ID used by the new document. If term existed in the database, this will be the first document ID that was indexed by that term; otherwise the database allocates ( get_lastdocid() + 1) as it does for add_document().

2.0.0 The changes made by this method are made atomically. Previously automatic commits could happen during the batch.

set_metadata()

Set the user-specified metadata associated with a given key.

void Xapian::WritableDatabase::set_metadata(std::string_view key, std::string_view metadata) Xapian::WritableDatabase::set_metadata This method sets the metadata value associated with a given key. If there is already a metadata value stored in the database with the same key, the old value is replaced. If you want to delete an existing item of metadata, just set its value to the empty string.

User-specified metadata allows you to store arbitrary information in the form of (key, value) pairs.

There’s no hard limit on the number of metadata items, or the size of the metadata values. Metadata keys have a limited length, which depend on the backend. We recommend limiting them to 200 bytes. Empty keys are not valid, and specifying one will cause an exception.

Metadata modifications are committed to disk in the same way as modifications to the documents in the database are: i.e., modifications are atomic, and won’t be committed to disk immediately (see commit() for more details). This allows metadata to be used to link databases with versioned external resources by storing the appropriate version number in a metadata item.

You can also use the metadata to store arbitrary extra information associated with terms, documents, or postings by encoding the termname and/or document id into the metadata key.

key: The key of the metadata item to set.

metadata: The value of the metadata item to set.

Xapian::DatabaseError: will be thrown if a problem occurs while writing to the database.

Xapian::DatabaseCorruptError: will be thrown if the database is in a corrupt state.

Xapian::InvalidArgumentError: will be thrown if the key supplied is empty.

Xapian::UnimplementedError: will be thrown if the database backend in use doesn’t support user- specified metadata.

property thisown

The membership flag

xapian.major_version()

xapian.metres_to_miles()

xapian.miles_to_metres()

xapian.minor_version()

xapian.remote_open()

Construct a Database object for read-only access to a remote database accessed via a program.

Database Xapian::Remote::open(std::string_view program, std::string_view args, unsigned timeout=10000) Xapian::Remote::open Access to the remote database is done by running an external program and communicating with it on stdin/stdout.

program: the external program to run.

args: space-separated list of arguments to pass to program.

timeout: timeout in milliseconds. If this timeout is exceeded for any individual operation on the remote database then Xapian::NetworkTimeoutError is thrown. A timeout of 0 means don’t timeout. (Default is 10000ms, which is 10 seconds).

xapian.remote_open_writable()

Construct a WritableDatabase object for update access to a remote database accessed via a program.

WritableDatabase Xapian::Remote::open_writable(std::string_view program, std::string_view args, unsigned timeout=0, int flags=0) Xapian::Remote::open_writable Access to the remote database is done by running an external program and communicating with it on stdin/stdout.

program: the external program to run.

args: space-separated list of arguments to pass to program.

timeout: timeout in milliseconds. If this timeout is exceeded for any individual operation on the remote database then Xapian::NetworkTimeoutError is thrown. (Default is 0, which means don’t timeout).

flags: Xapian::DB_RETRY_LOCK or 0.

xapian.revision()

xapian.sortable_serialise()

xapian.sortable_unserialise()

xapian.version_string()