Xapian: API Documentation: Xapian Namespace Reference

xapian-core 1.4.30

Namespaces | Classes | Typedefs | Enumerations | Functions | Variables
Xapian Namespace Reference

The Xapian namespace contains public interfaces for the Xapian library. More...

## Namespaces
namespace | Auto
| Database factory functions which determine the database type automatically.
namespace | Chert
| Database factory functions for the chert backend.
namespace | InMemory
| Database factory functions for the inmemory backend.
namespace | Remote
| Database factory functions for the remote backend.
namespace | Unicode
| Functions associated with handling Unicode characters.

## Classes
class | AssertionError
| AssertionError is thrown if a logical assertion inside Xapian fails. More...
class | BB2Weight
| This class implements the BB2 weighting scheme. More...
class | BM25PlusWeight
| Xapian::Weight subclass implementing the BM25+ probabilistic formula. More...
class | BM25Weight
| Xapian::Weight subclass implementing the BM25 probabilistic formula. More...
class | BoolWeight
| Class implementing a "boolean" weighting scheme. More...
class | Compactor
| Compact a database, or merge and compact several. More...
class | CoordWeight
| Xapian::Weight subclass implementing Coordinate Matching. More...
class | Database
| This class is used to access a database, or a group of databases. More...
class | DatabaseClosedError
| Indicates an attempt to access a closed database. More...
class | DatabaseCorruptError
| DatabaseCorruptError indicates database corruption was detected. More...
class | DatabaseCreateError
| DatabaseCreateError indicates a failure to create a database. More...
class | DatabaseError
| DatabaseError indicates some sort of database related error. More...
class | DatabaseLockError
| DatabaseLockError indicates failure to lock a database. More...
class | DatabaseModifiedError
| DatabaseModifiedError indicates a database was modified. More...
class | DatabaseNotFoundError
| Indicates an attempt to access a database not present. More...
class | DatabaseOpeningError
| DatabaseOpeningError indicates failure to open a database. More...
class | DatabaseVersionError
| DatabaseVersionError indicates that a database is in an unsupported format. More...
class | DateRangeProcessor
| Handle a date range. More...
class | DateValueRangeProcessor
| Handle a date range. More...
class | DecreasingValueWeightPostingSource
| Read weights from a value which is known to decrease as docid increases. More...
class | DLHWeight
| This class implements the DLH weighting scheme, which is a representative scheme of the Divergence from Randomness Framework by Gianni Amati. More...
class | DocNotFoundError
| Indicates an attempt to access a document not present in the database. More...
class | Document
| A handle representing a document in a Xapian database. More...
class | DPHWeight
| This class implements the DPH weighting scheme. More...
class | Enquire
| This class provides an interface to the information retrieval system for the purpose of searching. More...
class | Error
| All exceptions thrown by Xapian are subclasses of Xapian::Error. More...
class | ErrorHandler
| Decide if a Xapian::Error exception should be ignored. More...
class | ESet
| Class representing a list of search results. More...
class | ESetIterator
| Iterator over a Xapian::ESet. More...
class | ExpandDecider
| Virtual base class for expand decider functor. More...
class | ExpandDeciderAnd
| ExpandDecider subclass which rejects terms using two ExpandDeciders. More...
class | ExpandDeciderFilterPrefix
| ExpandDecider subclass which restrict terms to a particular prefix. More...
class | ExpandDeciderFilterTerms
| ExpandDecider subclass which rejects terms in a specified list. More...
class | FeatureUnavailableError
| Indicates an attempt to use a feature which is unavailable. More...
class | FieldProcessor
| Base class for field processors. More...
class | FixedWeightPostingSource
| A posting source which returns a fixed weight for all documents. More...
class | GreatCircleMetric
| Calculate the great-circle distance between two coordinates on a sphere. More...
class | IfB2Weight
| This class implements the IfB2 weighting scheme. More...
class | IneB2Weight
| This class implements the IneB2 weighting scheme. More...
class | InL2Weight
| This class implements the InL2 weighting scheme. More...
class | InternalError
| InternalError indicates a runtime problem of some sort. More...
class | InvalidArgumentError
| InvalidArgumentError indicates an invalid parameter value was passed to the API. More...
class | InvalidOperationError
| InvalidOperationError indicates the API was used in an invalid way. More...
class | KeyMaker
| Virtual base class for key making functors. More...
struct | LatLongCoord
| A latitude-longitude coordinate. More...
class | LatLongCoords
| A sequence of latitude-longitude coordinates. More...
class | LatLongCoordsIterator
| An iterator across the values in a LatLongCoords object. More...
class | LatLongDistanceKeyMaker
| KeyMaker subclass which sorts by distance from a latitude/longitude. More...
class | LatLongDistancePostingSource
| Posting source which returns a weight based on geospatial distance. More...
class | LatLongMetric
| Base class for calculating distances between two lat/long coordinates. More...
class | LMWeight
| Xapian::Weight subclass implementing the Language Model formula. More...
class | LogicError
| The base class for exceptions indicating errors in the program logic. More...
class | MatchDecider
| Base class for matcher decision functor. More...
class | MatchSpy
| Abstract base class for match spies. More...
class | MSet
| Class representing a list of search results. More...
class | MSetIterator
| Iterator over a Xapian::MSet. More...
class | MultiValueKeyMaker
| KeyMaker subclass which combines several values. More...
class | NetworkError
| Indicates a problem communicating with a remote database. More...
class | NetworkTimeoutError
| Indicates a timeout expired while communicating with a remote database. More...
class | NumberRangeProcessor
| Handle a number range. More...
class | NumberValueRangeProcessor
| Handle a number range. More...
class | PL2PlusWeight
| Xapian::Weight subclass implementing the PL2+ probabilistic formula. More...
class | PL2Weight
| This class implements the PL2 weighting scheme. More...
class | PositionIterator
| Class for iterating over term positions. More...
class | PostingIterator
| Class for iterating over a list of terms. More...
class | PostingSource
| Base class which provides an "external" source of postings. More...
class | Query
| Class representing a query. More...
class | QueryParser
| Build a Xapian::Query object from a user query string. More...
class | QueryParserError
| Indicates a query string can't be parsed. More...
class | RangeError
| RangeError indicates an attempt to access outside the bounds of a container. More...
class | RangeProcessor
| Base class for range processors. More...
class | Registry
| Registry for user subclasses. More...
class | RSet
| A relevance set (R-Set). More...
class | RuntimeError
| The base class for exceptions indicating errors only detectable at runtime. More...
class | SerialisationError
| Indicates an error in the std::string serialisation of an object. More...
class | SimpleStopper
| Simple implementation of Stopper class - this will suit most users. More...
class | Stem
| Class representing a stemming algorithm. More...
class | StemImplementation
| Class representing a stemming algorithm implementation. More...
class | Stopper
| Abstract base class for stop-word decision functor. More...
class | StringValueRangeProcessor
| Handle a string range. More...
class | TermGenerator
| Parses a piece of text and generate terms. More...
class | TermIterator
| Class for iterating over a list of terms. More...
class | TfIdfWeight
| Xapian::Weight subclass implementing the tf-idf weighting scheme. More...
class | TradWeight
| Xapian::Weight subclass implementing the traditional probabilistic formula. More...
class | UnimplementedError
| UnimplementedError indicates an attempt to use an unimplemented feature. More...
class | Utf8Iterator
| An iterator which returns Unicode character values from a UTF-8 encoded string. More...
class | ValueCountMatchSpy
| Class for counting the frequencies of values in the matching documents. More...
class | ValueIterator
| Class for iterating over document values. More...
class | ValueMapPostingSource
| A posting source which looks up weights in a map using values as the key. More...
class | ValuePostingSource
| A posting source which generates weights from a value slot. More...
class | ValueRangeProcessor
| Base class for value range processors. More...
class | ValueSetMatchDecider
| MatchDecider filtering results based on whether document values are in a user-defined set. More...
class | ValueWeightPostingSource
| A posting source which reads weights from a value slot. More...
class | Weight
| Abstract base class for weighting schemes. More...
class | WildcardError
| WildcardError indicates an error expanding a wildcarded query. More...
class | WritableDatabase
| This class provides read/write access to a database. More...

## Typedefs
typedef unsigned XAPIAN_DOCID_BASE_TYPE | doccount
| A count of documents.
typedef XAPIAN_DOCID_BASE_TYPE | doccount_diff
| A signed difference between two counts of documents.
typedef unsigned XAPIAN_DOCID_BASE_TYPE | docid
| A unique identifier for a document.
typedef double | doclength
| A normalised document length.
typedef int | percent
| The percentage score for a document in an MSet.
typedef unsigned XAPIAN_TERMCOUNT_BASE_TYPE | termcount
| A counts of terms.
typedef XAPIAN_TERMCOUNT_BASE_TYPE | termcount_diff
| A signed difference between two counts of terms.
typedef unsigned XAPIAN_TERMPOS_BASE_TYPE | termpos
| A term position within a document or query.
typedef XAPIAN_TERMPOS_BASE_TYPE | termpos_diff
| A signed difference between two term positions.
typedef unsigned | timeout
| A timeout value in milliseconds.
typedef unsigned | valueno
| The number for a value slot in a document.
typedef int | valueno_diff
| A signed difference between two value slot numbers.
typedef double | weight
| The weight of a document or term.
typedef XAPIAN_REVISION_TYPE | rev
| Revision number of a database.
typedef XAPIAN_TOTALLENGTH_TYPE | totallength
| The total length of all documents in a database.

## Enumerations
enum | { RP_SUFFIX = 1 , RP_REPEATED = 2 , RP_DATE_PREFER_MDY = 4 }

## Functions
const char * | version_string ()
| Report the version string of the library which the program is linked with.
int | major_version ()
| Report the major version of the library which the program is linked with.
int | minor_version ()
| Report the minor version of the library which the program is linked with.
int | revision ()
| Report the revision of the library which the program is linked with.
bool | operator== (const ESetIterator &a, const ESetIterator &b)
| Equality test for ESetIterator objects.
bool | operator!= (const ESetIterator &a, const ESetIterator &b)
| Inequality test for ESetIterator objects.
bool | operator< (const ESetIterator &a, const ESetIterator &b)
| Inequality test for ESetIterator objects.
bool | operator> (const ESetIterator &a, const ESetIterator &b)
| Inequality test for ESetIterator objects.
bool | operator>= (const ESetIterator &a, const ESetIterator &b)
| Inequality test for ESetIterator objects.
bool | operator<= (const ESetIterator &a, const ESetIterator &b)
| Inequality test for ESetIterator objects.
ESetIterator | operator+ (ESetIterator::difference_type n, const ESetIterator &it)
| Return ESetIterator it incremented by n positions.
double | miles_to_metres (double miles)
| Convert from miles to metres.
double | metres_to_miles (double metres)
| Convert from metres to miles.
bool | operator!= (const LatLongCoordsIterator &a, const LatLongCoordsIterator &b)
| Inequality test for LatLongCoordsIterator objects.
bool | operator== (const MSetIterator &a, const MSetIterator &b)
| Equality test for MSetIterator objects.
bool | operator!= (const MSetIterator &a, const MSetIterator &b)
| Inequality test for MSetIterator objects.
bool | operator< (const MSetIterator &a, const MSetIterator &b)
| Inequality test for MSetIterator objects.
bool | operator> (const MSetIterator &a, const MSetIterator &b)
| Inequality test for MSetIterator objects.
bool | operator>= (const MSetIterator &a, const MSetIterator &b)
| Inequality test for MSetIterator objects.
bool | operator<= (const MSetIterator &a, const MSetIterator &b)
| Inequality test for MSetIterator objects.
MSetIterator | operator+ (MSetIterator::difference_type n, const MSetIterator &it)
| Return MSetIterator it incremented by n positions.
bool | operator== (const PositionIterator &a, const PositionIterator &b)
| Equality test for PositionIterator objects.
bool | operator!= (const PositionIterator &a, const PositionIterator &b)
| Inequality test for PositionIterator objects.
bool | operator== (const PostingIterator &a, const PostingIterator &b)
| Equality test for PostingIterator objects.
bool | operator!= (const PostingIterator &a, const PostingIterator &b)
| Inequality test for PostingIterator objects.
const Query | operator& (const Query &a, const Query &b)
| Combine two Xapian::Query objects using OP_AND.
const Query | operator| (const Query &a, const Query &b)
| Combine two Xapian::Query objects using OP_OR.
const Query | operator^ (const Query &a, const Query &b)
| Combine two Xapian::Query objects using OP_XOR.
const Query | operator* (double factor, const Query &q)
| Scale a Xapian::Query object using OP_SCALE_WEIGHT.
const Query | operator* (const Query &q, double factor)
| Scale a Xapian::Query object using OP_SCALE_WEIGHT.
const Query | operator/ (const Query &q, double factor)
| Inverse-scale a Xapian::Query object using OP_SCALE_WEIGHT.
const Query | operator& (const Query &a, const InvertedQuery_ &b)
| Combine two Xapian::Query objects using OP_AND_NOT.
const Query | operator&= (Query &a, const InvertedQuery_ &b)
| Combine two Xapian::Query objects using OP_AND_NOT with result in the first.
std::string | sortable_serialise (double value)
| Convert a floating point number to a string, preserving sort order.
double | sortable_unserialise (const std::string &serialised)
| Convert a string encoded using sortable_serialise back to a floating point number.
bool | operator== (const TermIterator &a, const TermIterator &b)
| Equality test for TermIterator objects.
bool | operator!= (const TermIterator &a, const TermIterator &b)
| Inequality test for TermIterator objects.
bool | operator== (const ValueIterator &a, const ValueIterator &b)
| Equality test for ValueIterator objects.
bool | operator!= (const ValueIterator &a, const ValueIterator &b)
| Inequality test for ValueIterator objects.

## Variables
const int | DB_CREATE_OR_OPEN = 0x00
| Create database if it doesn't already exist.
const int | DB_CREATE_OR_OVERWRITE = 0x01
| Create database if it doesn't already exist, or overwrite if it does.
const int | DB_CREATE = 0x02
| Create a new database.
const int | DB_OPEN = 0x03
| Open an existing database.
const int | DB_NO_SYNC = 0x04
| Don't attempt to ensure changes have hit disk.
const int | DB_FULL_SYNC = 0x08
| Try to ensure changes are really written to disk.
const int | DB_DANGEROUS = 0x10
| Update the database in-place.
const int | DB_NO_TERMLIST = 0x20
| When creating a database, don't create a termlist table.
const int | DB_RETRY_LOCK = 0x40
| If the database is already locked, retry the lock.
const int | DB_BACKEND_GLASS = 0x100
| Use the glass backend.
const int | DB_BACKEND_CHERT = 0x200
| Use the chert backend.
const int | DB_BACKEND_STUB = 0x300
| Open a stub database file.
const int | DB_BACKEND_INMEMORY = 0x400
| Use the "in memory" backend.
const int | DBCHECK_SHORT_TREE = 1
| Show a short-format display of the B-tree contents.
const int | DBCHECK_FULL_TREE = 2
| Show a full display of the B-tree contents.
const int | DBCHECK_SHOW_FREELIST = 4
| Show the bitmap for the B-tree.
const int | DBCHECK_SHOW_STATS = 8
| Show statistics for the B-tree.
const int | DBCHECK_FIX = 16
| Fix problems.
const int | DBCOMPACT_NO_RENUMBER = 4
| Use the same document ids in the output as in the input(s).
const int | DBCOMPACT_MULTIPASS = 8
| If merging more than 3 databases, merge the postlists in multiple passes.
const int | DBCOMPACT_SINGLE_FILE = 16
| Produce a single-file database.
const int | DOC_ASSUME_VALID = 1
| Assume document id is valid.
const valueno | BAD_VALUENO = 0xffffffff
| Reserved value to indicate "no valueno".

## Detailed Description

The Xapian namespace contains public interfaces for the Xapian library.

## Typedef Documentation

## ◆ doccount

typedef unsigned XAPIAN_DOCID_BASE_TYPE Xapian::doccount

A count of documents.

This is used to hold values such as the number of documents in a database and the frequency of a term in the database.

## ◆ doccount_diff

typedef XAPIAN_DOCID_BASE_TYPE Xapian::doccount_diff

A signed difference between two counts of documents.

This is used by the Xapian classes which are STL containers of documents for "difference_type".

## ◆ docid

typedef unsigned XAPIAN_DOCID_BASE_TYPE Xapian::docid

A unique identifier for a document.

Docid 0 is invalid, providing an "out of range" value which can be used to mean "not a valid document".

## ◆ doclength

typedef double Xapian::doclength

A normalised document length.

The normalised document length is the document length divided by the average document length in the database.

## ◆ percent

typedef int Xapian::percent

The percentage score for a document in an MSet.

Deprecated:
  This type is deprecated as of Xapian 1.3.0 - use the standard type int instead, which should work with older Xapian too.

## ◆ rev

typedef XAPIAN_REVISION_TYPE Xapian::rev

Revision number of a database.

For databases which support this, it increases with each commit.

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

## ◆ termcount

typedef unsigned XAPIAN_TERMCOUNT_BASE_TYPE Xapian::termcount

A counts of terms.

This is used to hold values such as the Within Document Frequency (wdf).

## ◆ termcount_diff

typedef XAPIAN_TERMCOUNT_BASE_TYPE Xapian::termcount_diff

A signed difference between two counts of terms.

This is used by the Xapian classes which are STL containers of terms for "difference_type".

## ◆ termpos_diff

typedef XAPIAN_TERMPOS_BASE_TYPE Xapian::termpos_diff

A signed difference between two term positions.

This is used by the Xapian classes which are STL containers of positions for "difference_type".

## ◆ timeout

typedef unsigned Xapian::timeout

A timeout value in milliseconds.

There are 1000 milliseconds in a second, so for example, to set a timeout of 5 seconds use 5000.

Deprecated:
  This type is deprecated as of Xapian 1.3.0 - use the standard POSIX type useconds_t instead, which should work with older Xapian too.

## ◆ totallength

typedef XAPIAN_TOTALLENGTH_TYPE Xapian::totallength

The total length of all documents in a database.

Added in Xapian 1.4.5.

## ◆ valueno

typedef unsigned Xapian::valueno

The number for a value slot in a document.

Value slot numbers are unsigned and (currently) a 32-bit quantity, with Xapian::BAD_VALUENO being represented by the largest possible value. Therefore value slots 0 to 0xFFFFFFFE are available for use.

## ◆ valueno_diff

typedef int Xapian::valueno_diff

A signed difference between two value slot numbers.

This is used by the Xapian classes which are STL containers of values for "difference_type".

## ◆ weight

typedef double Xapian::weight

The weight of a document or term.

Deprecated:
  This type is deprecated as of Xapian 1.3.0 - use the standard C++ type double instead, which should work with older Xapian too.

## Function Documentation

## ◆ major_version()

int Xapian::major_version | ( |  | ) |
| inline

Report the major version of the library which the program is linked with.

This may be different to the version compiled against (given by XAPIAN_MAJOR_VERSION) if shared libraries are being used.

## ◆ metres_to_miles()

double Xapian::metres_to_miles | ( | double | metres | ) |
| inline

Convert from metres to miles.

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

## ◆ miles_to_metres()

double Xapian::miles_to_metres | ( | double | miles | ) |
| inline

Convert from miles to metres.

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

## ◆ minor_version()

int Xapian::minor_version | ( |  | ) |
| inline

Report the minor version of the library which the program is linked with.

This may be different to the version compiled against (given by XAPIAN_MINOR_VERSION) if shared libraries are being used.

## ◆ operator&()

const Query Xapian::operator& | ( | const Query & | a,
|  | const InvertedQuery_ & | b
| ) |  |
| inline

Combine two Xapian::Query objects using OP_AND_NOT.

E.g. Xapian::Query q = q1 &~ q2;

References Xapian::Query::OP_AND_NOT.

## ◆ operator&=()

const Query Xapian::operator&= | ( | Query & | a,
|  | const InvertedQuery_ & | b
| ) |  |
| inline

Combine two Xapian::Query objects using OP_AND_NOT with result in the first.

E.g. q1 &=~ q2;

References Xapian::Query::OP_AND_NOT.

## ◆ operator*() [1/2]

const Query Xapian::operator* | ( | const Query & | q,
|  | double | factor
| ) |  |
| inline

Scale a Xapian::Query object using OP_SCALE_WEIGHT.

Parameters

  q | Xapian::Query object.
  factor | Non-negative real number to multiply weights by.

## ◆ operator*() [2/2]

const Query Xapian::operator* | ( | double | factor,
|  | const Query & | q
| ) |  |
| inline

Scale a Xapian::Query object using OP_SCALE_WEIGHT.

Parameters

  factor | Non-negative real number to multiply weights by.
  q | Xapian::Query object.

## ◆ operator+() [1/2]

ESetIterator Xapian::operator+ | ( | ESetIterator::difference_type | n,
|  | const ESetIterator & | it
| ) |  |
| inline

Return ESetIterator it incremented by n positions.

If n is negative, decrements by (-n) positions.

## ◆ operator+() [2/2]

MSetIterator Xapian::operator+ | ( | MSetIterator::difference_type | n,
|  | const MSetIterator & | it
| ) |  |
| inline

Return MSetIterator it incremented by n positions.

If n is negative, decrements by (-n) positions.

## ◆ operator/()

const Query Xapian::operator/ | ( | const Query & | q,
|  | double | factor
| ) |  |
| inline

Inverse-scale a Xapian::Query object using OP_SCALE_WEIGHT.

Parameters

  factor | Positive real number to divide weights by.
  q | Xapian::Query object.

## ◆ revision()

int Xapian::revision | ( |  | ) |
| inline

Report the revision of the library which the program is linked with.

This may be different to the version compiled against (given by XAPIAN_REVISION) if shared libraries are being used.

## ◆ sortable_serialise()

std::string Xapian::sortable_serialise | ( | double | value | ) |
| inline

Convert a floating point number to a string, preserving sort order.

This method converts a floating point number to a string, suitable for using as a value for numeric range restriction, or for use as a sort key.

The conversion is platform independent.

The conversion attempts to ensure that, for any pair of values supplied to the conversion algorithm, the result of comparing the original values (with a numeric comparison operator) will be the same as the result of comparing the resulting values (with a string comparison operator). On platforms which represent doubles with the precisions specified by IEEE_754, this will be the case: if the representation of doubles is more precise, it is possible that two very close doubles will be mapped to the same string, so will compare equal.

Note also that both zero and -zero will be converted to the same representation: since these compare equal, this satisfies the comparison constraint, but it's worth knowing this if you wish to use the encoding in some situation where this distinction matters.

Handling of NaN isn't (currently) guaranteed to be sensible.

Parameters

  value | The number to serialise.

Referenced by Xapian::LatLongDistanceKeyMaker::LatLongDistanceKeyMaker(), and Xapian::LatLongDistanceKeyMaker::LatLongDistanceKeyMaker().

## ◆ sortable_unserialise()

double Xapian::sortable_unserialise | ( | const std::string & | serialised | ) |

Convert a string encoded using sortable_serialise back to a floating point number.

This expects the input to be a string produced by sortable_serialise(). If the input is not such a string, the value returned is undefined (but no error will be thrown).

The result of the conversion will be exactly the value which was supplied to sortable_serialise() when making the string on platforms which represent doubles with the precisions specified by IEEE_754, but may be a different (nearby) value on other platforms.

Parameters

  serialised | The serialised string to decode.

## ◆ version_string()

const char * Xapian::version_string | ( |  | ) |
| inline

Report the version string of the library which the program is linked with.

This may be different to the version compiled against (given by XAPIAN_VERSION) if shared libraries are being used.

## Variable Documentation

## ◆ DB_BACKEND_CHERT

const int Xapian::DB_BACKEND_CHERT = 0x200

Use the chert backend.

When opening a WritableDatabase, this means create a chert database if a new database is created. If there's an existing database (of any type) at the specified path, this flag has no effect.

When opening a Database, this flag means to only open it if it's a chert database. There's rarely a good reason to do this - it's mostly provided as equivalent functionality to Xapian::Chert::open() in Xapian 1.2.

Referenced by Xapian::Chert::open(), and Xapian::Chert::open().

## ◆ DB_BACKEND_GLASS

const int Xapian::DB_BACKEND_GLASS = 0x100

Use the glass backend.

When opening a WritableDatabase, this means create a glass database if a new database is created. If there's an existing database (of any type) at the specified path, this flag has no effect.

When opening a Database, this flag means to only open it if it's a glass database. There's rarely a good reason to do this - it's mostly provided as equivalent functionality to that provided by the namespaced open() functions in Xapian 1.2.

## ◆ DB_BACKEND_INMEMORY

const int Xapian::DB_BACKEND_INMEMORY = 0x400

Use the "in memory" backend.

The filename is currently ignored when this flag is used, but an empty string should be passed to allow for future expansion.

A new empty database is created, so when creating a Database object this creates an empty read-only database - sometimes useful to avoid special casing this situation, but otherwise of limited use. It's more useful when creating a WritableDatabase object, though beware that the current inmemory backend implementation was not built for performance and scalability.

This provides an equivalent to Xapian::InMemory::open() in Xapian 1.2.

Referenced by Xapian::InMemory::open().

## ◆ DB_BACKEND_STUB

const int Xapian::DB_BACKEND_STUB = 0x300

Open a stub database file.

When opening a Database, this flag means to only open it if it's a stub database file. There's rarely a good reason to do this - it's mostly provided as equivalent functionality to Xapian::Auto::open_stub() in Xapian 1.2.

Referenced by Xapian::Auto::open_stub(), and Xapian::Auto::open_stub().

## ◆ DB_CREATE

const int Xapian::DB_CREATE = 0x02

Create a new database.

If the database already exists, an exception will be thrown.

## ◆ DB_CREATE_OR_OPEN

const int Xapian::DB_CREATE_OR_OPEN = 0x00

Create database if it doesn't already exist.

If no opening mode is specified, this is the default.

## ◆ DB_DANGEROUS

const int Xapian::DB_DANGEROUS = 0x10

Update the database in-place.

Xapian's disk-based backends use block-based storage, with copy-on-write to allow the previous revision to be searched while a new revision forms.

This option means changed blocks get written back over the top of the old version. The benefits of this are that less I/O is required during indexing, and the result of indexing is more compact. The downsides are that you can't concurrently search while indexing, transactions can't be cancelled, and if indexing ends uncleanly (i.e. without commit() or WritableDatabase's destructor being called) then the database won't be usable.

Currently all the base files will be removed upon the first modification, and new base files will be written upon commit. This prevents new readers from opening the database while it unsafe to do so, but there's not currently a mechanism in Xapian to handle notifying existing readers.

## ◆ DB_FULL_SYNC

const int Xapian::DB_FULL_SYNC = 0x08

Try to ensure changes are really written to disk.

Generally fsync() and similar functions only ensure that data has been sent to the drive. Modern drives have large write-back caches for performance, and a power failure could still lose data which is in the write-back cache waiting to be written.

Some platforms provide a way to ensure data has actually been written and setting DB_FULL_SYNC will attempt to do so where possible. The downside is that committing changes takes longer, and other I/O to the same disk may be delayed too.

Currently only macOS is supported, and only on some filing system types

- if not supported, Xapian will use fsync() or similar instead.

## ◆ DB_NO_SYNC

const int Xapian::DB_NO_SYNC = 0x04

Don't attempt to ensure changes have hit disk.

By default, Xapian ask the OS to ensure changes have hit disk (by calling fdatasync(), fsync() or similar functions). If these calls do their job, this should mean that when WritableDatabase::commit() returns, the changes are durable, but this comes at a performance cost, and if you don't mind losing changes in the case of a crash, power failure, etc, then this option can speed up indexing significantly.

## ◆ DB_NO_TERMLIST

const int Xapian::DB_NO_TERMLIST = 0x20

When creating a database, don't create a termlist table.

For backends which support it (currently glass), this will prevent creation of a termlist table. This saves on the disk space that would be needed to store it, and the CPU and I/O needed to update it, but some features either inherently need the termlist table, or the current implementation of them requires it.

The following probably can't be sensibly implemented without it:

- Database::termlist_begin()
- Document::termlist_begin()
- Document::termlist_count()
- Enquire::get_eset()

And the following currently require it:

- Enquire::matching_terms_begin() - we could record this information during the match, though it might be hard to do without a speed penalty.
- WritableDatabase::delete_document() - we could allow this with inexact statistics (like how Lucene does).
- WritableDatabase::replace_document() if the document exists already (again, possible with inexact statistics).
- Currently the list of which values are used in each document is stored in the termlist table, so things like iterating the values in a document require it (which is probably reasonable since iterating the terms in a document requires it).

You can also convert an existing database to not have a termlist table by simply deleting termlist.*.

## ◆ DB_OPEN

const int Xapian::DB_OPEN = 0x03

Open an existing database.

If the database doesn't exist, an exception will be thrown.

## ◆ DB_RETRY_LOCK

const int Xapian::DB_RETRY_LOCK = 0x40

If the database is already locked, retry the lock.

By default, if the database is already locked by a writer, trying to open it again for writing will fail by throwing Xapian::DatabaseLockError. If this flag is specified, then Xapian will instead wait for the lock (indefinitely, unless it gets an error trying to do so).

## ◆ DBCHECK_FIX

const int Xapian::DBCHECK_FIX = 16

Fix problems.

For use with Xapian::Database::check().

Currently this is supported for chert, and will:

- regenerate the "iamchert" file if it isn't valid (so if it is lost, you can just create it empty and then "fix problems").

- regenerate base files (currently the algorithm for finding the root block may not work if there was a change partly written but not committed).

## ◆ DBCHECK_FULL_TREE

const int Xapian::DBCHECK_FULL_TREE = 2

Show a full display of the B-tree contents.

For use with Xapian::Database::check().

## ◆ DBCHECK_SHORT_TREE

const int Xapian::DBCHECK_SHORT_TREE = 1

Show a short-format display of the B-tree contents.

For use with Xapian::Database::check().

## ◆ DBCHECK_SHOW_FREELIST

const int Xapian::DBCHECK_SHOW_FREELIST = 4

Show the bitmap for the B-tree.

For use with Xapian::Database::check().

## ◆ DBCHECK_SHOW_STATS

const int Xapian::DBCHECK_SHOW_STATS = 8

Show statistics for the B-tree.

For use with Xapian::Database::check().

## ◆ DBCOMPACT_MULTIPASS

const int Xapian::DBCOMPACT_MULTIPASS = 8

If merging more than 3 databases, merge the postlists in multiple passes.

This is generally faster but requires more disk space for temporary files.

Referenced by Xapian::Compactor::set_multipass().

## ◆ DBCOMPACT_NO_RENUMBER

const int Xapian::DBCOMPACT_NO_RENUMBER = 4

Use the same document ids in the output as in the input(s).

By default compaction renumbers the document ids in the output database, 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.

Referenced by Xapian::Compactor::set_renumber().

## ◆ DBCOMPACT_SINGLE_FILE

const int Xapian::DBCOMPACT_SINGLE_FILE = 16

Produce a single-file database.

Only supported by the glass backend currently.

## ◆ DOC_ASSUME_VALID

const int Xapian::DOC_ASSUME_VALID = 1

Assume document id is valid.

By default, Database::get_document() checks that the document id passed is actually in use and throws DocNotFoundError if not. This flag can be used to disable this check - useful to save a bit of work when you know for sure that the document id is valid.

Some database backends may check anyway - the remote backend currently does.