This class is used to access a database, or a group of databases. More...

#include <database.h>

Inheritance diagram for Xapian::Database:

Collaboration diagram for Xapian::Database:

Classes
class	Internal
	Base class for databases. More...

Public Member Functions
void	add_database (const Database &database)
	Add an existing database (or group of databases) to those accessed by this object. More...

size_t	size () const
	Return number of shards in this Database object. More...

	Database ()
	Create a Database with no databases in. More...

	Database (const std::string &path, int flags=0)
	Open a Database, automatically determining the database backend to use. More...

	Database (int fd, int flags=0)
	Open a single-file Database. More...

virtual	~Database ()
	Destroy this handle on the database. More...

	Database (const Database &other)
	Copying is allowed. More...

void	operator= (const Database &other)
	Assignment is allowed. More...

bool	reopen ()
	Re-open the database. More...

virtual void	close ()
	Close the database. More...

virtual std::string	get_description () const
	Return a string describing this object. More...

PostingIterator	postlist_begin (const std::string &tname) const
	An iterator pointing to the start of the postlist for a given term. More...

PostingIterator	postlist_end (const std::string &) const
	Corresponding end iterator to postlist_begin(). More...

TermIterator	termlist_begin (Xapian::docid did) const
	An iterator pointing to the start of the termlist for a given document. More...

TermIterator	termlist_end (Xapian::docid) const
	Corresponding end iterator to termlist_begin(). More...

bool	has_positions () const
	Does this database have any positional information? More...

PositionIterator	positionlist_begin (Xapian::docid did, const std::string &tname) const
	An iterator pointing to the start of the position list for a given term in a given document. More...

PositionIterator	positionlist_end (Xapian::docid, const std::string &) const
	Corresponding end iterator to positionlist_begin(). More...

TermIterator	allterms_begin (const std::string &prefix=std::string()) const
	An iterator which runs across all terms with a given prefix. More...

TermIterator	allterms_end (const std::string &=std::string()) const
	Corresponding end iterator to allterms_begin(prefix). More...

Xapian::doccount	get_doccount () const
	Get the number of documents in the database. More...

Xapian::docid	get_lastdocid () const
	Get the highest document id which has been used in the database. More...

Xapian::doclength	get_avlength () const
	Get the average length of the documents in the database. More...

double	get_average_length () const
	New name for get_avlength(). More...

Xapian::totallength	get_total_length () const
	Get the total length of all the documents in the database. More...

Xapian::doccount	get_termfreq (const std::string &tname) const
	Get the number of documents in the database indexed by a given term. More...

bool	term_exists (const std::string &tname) const
	Check if a given term exists in the database. More...

Xapian::termcount	get_collection_freq (const std::string &tname) const
	Return the total number of occurrences of the given term. More...

Xapian::doccount	get_value_freq (Xapian::valueno slot) const
	Return the frequency of a given value slot. More...

std::string	get_value_lower_bound (Xapian::valueno slot) const
	Get a lower bound on the values stored in the given value slot. More...

std::string	get_value_upper_bound (Xapian::valueno slot) const
	Get an upper bound on the values stored in the given value slot. More...

Xapian::termcount	get_doclength_lower_bound () const
	Get a lower bound on the length of a document in this DB. More...

Xapian::termcount	get_doclength_upper_bound () const
	Get an upper bound on the length of a document in this DB. More...

Xapian::termcount	get_wdf_upper_bound (const std::string &term) const
	Get an upper bound on the wdf of term term. More...

ValueIterator	valuestream_begin (Xapian::valueno slot) const
	Return an iterator over the value in slot slot for each document. More...

ValueIterator	valuestream_end (Xapian::valueno) const
	Return end iterator corresponding to valuestream_begin(). More...

Xapian::termcount	get_doclength (Xapian::docid did) const
	Get the length of a document. More...

Xapian::termcount	get_unique_terms (Xapian::docid did) const
	Get the number of unique terms in document. More...

void	keep_alive ()
	Send a "keep-alive" to remote databases to stop them timing out. More...

Xapian::Document	get_document (Xapian::docid did) const
	Get a document from the database, given its document id. More...

Xapian::Document	get_document (Xapian::docid did, unsigned flags) const
	Get a document from the database, given its document id. More...

std::string	get_spelling_suggestion (const std::string &word, unsigned max_edit_distance=2) const
	Suggest a spelling correction. More...

Xapian::TermIterator	spellings_begin () const
	An iterator which returns all the spelling correction targets. More...

Xapian::TermIterator	spellings_end () const
	Corresponding end iterator to spellings_begin(). More...

Xapian::TermIterator	synonyms_begin (const std::string &term) const
	An iterator which returns all the synonyms for a given term. More...

Xapian::TermIterator	synonyms_end (const std::string &) const
	Corresponding end iterator to synonyms_begin(term). More...

Xapian::TermIterator	synonym_keys_begin (const std::string &prefix=std::string()) const
	An iterator which returns all terms which have synonyms. More...

Xapian::TermIterator	synonym_keys_end (const std::string &=std::string()) const
	Corresponding end iterator to synonym_keys_begin(prefix). More...

std::string	get_metadata (const std::string &key) const
	Get the user-specified metadata associated with a given key. More...

Xapian::TermIterator	metadata_keys_begin (const std::string &prefix=std::string()) const
	An iterator which returns all user-specified metadata keys. More...

Xapian::TermIterator	metadata_keys_end (const std::string &=std::string()) const
	Corresponding end iterator to metadata_keys_begin(). More...

std::string	get_uuid () const
	Get a UUID for the database. More...

bool	locked () const
	Test if this database is currently locked for writing. More...

Xapian::rev	get_revision () const
	Get the revision of the database. More...

void	compact (const std::string &output, unsigned flags=0, int block_size=0)
	Produce a compact version of this database. More...

void	compact (int fd, unsigned flags=0, int block_size=0)
	Produce a compact version of this database. More...

void	compact (const std::string &output, unsigned flags, int block_size, Xapian::Compactor &compactor)
	Produce a compact version of this database. More...

void	compact (int fd, unsigned flags, int block_size, Xapian::Compactor &compactor)
	Produce a compact version of this database. More...

Static Public Member Functions
static size_t	check (const std::string &path, int opts=0, std::ostream *out=NULL)
	Check the integrity of a database or database table. More...

static size_t	check (int fd, int opts=0, std::ostream *out=NULL)
	Check the integrity of a single file database. More...

Private Member Functions
void	compact_ (const std::string output_ptr, int fd, unsigned flags, int block_size, Xapian::Compactor compactor) const
	Internal helper behind public compact() methods. More...

	Database (Internal *internal)

Static Private Member Functions
static size_t	check_ (const std::string path_ptr, int fd, int opts, std::ostream out)

Private Attributes
std::vector< Xapian::Internal::intrusive_ptr< Internal > >	internal

Detailed Description

This class is used to access a database, or a group of databases.

For searching, this class is used in conjunction with an Enquire object.

Exceptions

InvalidArgumentError	will be thrown if an invalid argument is supplied, for example, an unknown database type.
DatabaseOpeningError	may be thrown if the database cannot be opened (for example, a required file cannot be found).
DatabaseVersionError	may be thrown if the database is in an unsupported format (for example, created by a newer version of Xapian which uses an incompatible format).

Definition at line 68 of file database.h.

Constructor & Destructor Documentation

◆ Database() [1/5]

Xapian::Database::Database ( )

Create a Database with no databases in.

Definition at line 94 of file omdatabase.cc.

References LOGCALL_CTOR.

◆ Database() [2/5]

Xapian::Database::Database	(	const std::string &	path,
		int	flags = `0`
	)

explicit

Open a Database, automatically determining the database backend to use.

Parameters

path	directory that the database is stored in.
flags	Bitwise-or of Xapian::DB_* constants.

Definition at line 156 of file dbfactory.cc.

References BACKEND_GLASS, Xapian::DB_BACKEND_CHERT, Xapian::DB_BACKEND_GLASS, Xapian::DB_BACKEND_INMEMORY, Xapian::DB_BACKEND_STUB, file_exists(), LOGCALL_CTOR, Xapian::open_stub(), rare, S_ISDIR, S_ISREG, test_if_single_file_db(), and usual.

◆ Database() [3/5]

Xapian::Database::Database	(	int	fd,
		int	flags = `0`
	)

explicit

Open a single-file Database.

This method opens a single-file Database given a file descriptor open on it. Xapian looks starting at the current file offset, allowing a single file database to be easily embedded within another file.

Parameters

fd	file descriptor for the file. Xapian takes ownership of this and will close it when the database is closed.
flags	Bitwise-or of Xapian::DB_* constants.

Definition at line 260 of file dbfactory.cc.

References close(), Xapian::DB_BACKEND_GLASS, LOGCALL_CTOR, and rare.

◆ Database() [4/5]

Xapian::Database::Database ( Database::Internal * internal_ )

explicitprivate

Create a Database from its internals.

Definition at line 99 of file omdatabase.cc.

References LOGCALL_CTOR.

◆ ~Database()

Xapian::Database::~Database ( )

virtual

Destroy this handle on the database.

If there are no copies of this object remaining, the database(s) will be closed.

Definition at line 119 of file omdatabase.cc.

References LOGCALL_DTOR.

◆ Database() [5/5]

Xapian::Database::Database ( const Database & other )

Copying is allowed.

The internals are reference counted, so copying is cheap.

Parameters

other The object to copy.

Definition at line 106 of file omdatabase.cc.

References internal, and LOGCALL_CTOR.

Member Function Documentation

◆ add_database()

void Xapian::Database::add_database ( const Database & database )

Add an existing database (or group of databases) to those accessed by this object.

Parameters

database the database(s) to add.

Definition at line 148 of file omdatabase.cc.

References internal, LOGCALL_VOID, and LOGLINE.

Referenced by Xapian::WritableDatabase::add_database(), Xapian::Compactor::compact(), DEFINE_TESTCASE(), BackendManagerMulti::get_remote_database(), main(), and Xapian::open_stub().

◆ allterms_begin()

TermIterator Xapian::Database::allterms_begin ( const std::string & prefix = std::string() ) const

An iterator which runs across all terms with a given prefix.

The terms are returned in ascending string order (by byte value).

Parameters

prefix The prefix to restrict the returned terms to (default: iterate all terms)

Definition at line 223 of file omdatabase.cc.

References LOGCALL, rare, and RETURN.

Referenced by check_equal_dbs(), check_sparse_uid_terms(), dbcheck(), DEFINE_TESTCASE(), CheckStatsWeight::get_sumpart(), RemoteServer::msg_allterms(), closedb1_iterators::perform(), closedb1_iterators::setup(), show_db_stats(), and show_termlist().

◆ allterms_end()

TermIterator Xapian::Database::allterms_end ( const std::string & = std::string() ) const

inline

Corresponding end iterator to allterms_begin(prefix).

Definition at line 269 of file database.h.

Referenced by check_equal_dbs(), check_sparse_uid_terms(), dbcheck(), DEFINE_TESTCASE(), CheckStatsWeight::get_sumpart(), RemoteServer::msg_allterms(), closedb1_iterators::setup(), show_db_stats(), and show_termlist().

◆ check() [1/2]

static size_t Xapian::Database::check	(	const std::string &	path,
		int	opts = `0`,
		std::ostream *	out = `NULL`
	)

inlinestatic

Check the integrity of a database or database table.

Parameters

path	Path to database or table
opts	Options to use for check
out	std::ostream to write output to (NULL for no output)

Definition at line 564 of file database.h.

Referenced by DEFINE_TESTCASE(), and main().

◆ check() [2/2]

static size_t Xapian::Database::check	(	int	fd,
		int	opts = `0`,
		std::ostream *	out = `NULL`
	)

inlinestatic

Check the integrity of a single file database.

Parameters

fd	file descriptor for the database. The current file offset is used, allowing checking a single file database which is embedded within another file. Xapian takes ownership of the file descriptor and will close it before returning.
opts	Options to use for check
out	std::ostream to write output to (NULL for no output)

Definition at line 579 of file database.h.

◆ check_()

size_t Xapian::Database::check_	(	const std::string *	path_ptr,
		int	fd,
		int	opts,
		std::ostream *	out
	)

staticprivate

Implementation behind check() static methods.

Definition at line 430 of file dbcheck.cc.

References BACKEND_CHERT, BACKEND_GLASS, BACKEND_UNKNOWN, check_db_dir(), check_db_fd(), check_db_table(), Xapian::check_stub(), Xapian::DBCHECK_FIX, endswith(), GLASS_TABLE_EXTENSION, S_ISDIR, S_ISREG, test_if_single_file_db(), and throw_no_db_to_check().

◆ close()

void Xapian::Database::close ( )

virtual

Close the database.

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.

Closing a database cannot be undone - in particular, calling reopen() after close() will not reopen it, but will instead throw a Xapian::DatabaseError exception.

Calling close() again on a database 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::DatabaseError exception indicating that the database is closed.

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.

Definition at line 138 of file omdatabase.cc.

References LOGCALL_VOID.

Referenced by BackendManagerMulti::createdb_multi(), DEFINE_TESTCASE(), BackendManagerGlass::do_get_database_path(), and BackendManagerChert::do_get_database_path().

◆ compact() [1/4]

void Xapian::Database::compact	(	const std::string &	output,
		unsigned	flags = `0`,
		int	block_size = `0`
	)

inline

Produce a compact version of this database.

New 1.3.4. Various methods of the Compactor class were deprecated in 1.3.4.

Parameters

output	Path to write the compact version to. This can be the same as an input if that input is a stub database (in which case the database(s) listed in the stub will be compacted to a new database and then the stub will be atomically updated to point to this new database).
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).
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.

Definition at line 627 of file database.h.

Referenced by Xapian::Compactor::compact(), DEFINE_TESTCASE(), BackendManagerSingleFile::do_get_database_path(), BackendManagerSingleFile::finalise_generated_database(), and main().

◆ compact() [2/4]

void Xapian::Database::compact	(	int	fd,
		unsigned	flags = `0`,
		int	block_size = `0`
	)

inline

Produce a compact version of this database.

New 1.3.4. Various methods of the Compactor class were deprecated in 1.3.4.

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.

Parameters

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) - this flag is implied in this form and need not be specified explicitly.
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.

Definition at line 675 of file database.h.

◆ compact() [3/4]

void Xapian::Database::compact	(	const std::string &	output,
		unsigned	flags,
		int	block_size,
		Xapian::Compactor &	compactor
	)

inline

Produce a compact version of this database.

New 1.3.4. Various methods of the Compactor class were deprecated in 1.3.4.

The compactor functor allows handling progress output and specifying how user metadata is merged.

Parameters

output	Path to write the compact version to. This can be the same as an input if that input is a stub database (in which case the database(s) listed in the stub will be compacted to a new database and then the stub will be atomically updated to point to this new database).
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).
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

Definition at line 723 of file database.h.

◆ compact() [4/4]

void Xapian::Database::compact	(	int	fd,
		unsigned	flags,
		int	block_size,
		Xapian::Compactor &	compactor
	)

inline

Produce a compact version of this database.

New 1.3.4. Various methods of the Compactor class were deprecated in 1.3.4.

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.

Parameters

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) - this flag is implied in this form and need not be specified explicitly.
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

Definition at line 778 of file database.h.

◆ compact_()

void Xapian::Database::compact_	(	const std::string *	output_ptr,
		int	fd,
		unsigned	flags,
		int	block_size,
		Xapian::Compactor *	compactor
	)		const

private

Internal helper behind public compact() methods.

Definition at line 178 of file compactor.cc.

References Assert, AssertEq, AssertRel, Xapian::PostingIterator::Internal::at_end(), BACKEND_CHERT, BACKEND_GLASS, backend_mismatch(), BACKEND_UNKNOWN, GlassDatabase::compact(), ChertDatabase::compact(), ChertVersion::create(), Xapian::DBCOMPACT_NO_RENUMBER, Xapian::DBCOMPACT_SINGLE_FILE, dir_exists(), DIR_SEPS, file_exists(), Xapian::Compactor::FULL, Xapian::Compactor::FULLER, Xapian::Database::Internal::get_doccount(), Xapian::PostingIterator::Internal::get_docid(), Xapian::Database::Internal::get_lastdocid(), Xapian::Database::Internal::get_used_docid_range(), io_tmp_rename(), LOGCALL_VOID, Xapian::PostingIterator::Internal::next(), RealTime::now(), Xapian::Database::Internal::open_post_list(), Xapian::PostingIterator::Internal::skip_to(), srcdir, Xapian::Compactor::STANDARD, and Xapian::Internal::str().

◆ get_average_length()

double Xapian::Database::get_average_length ( ) const

inline

New name for get_avlength().

Added for forward compatibility with the next release series.

Since: 1.4.17.

Definition at line 288 of file database.h.

◆ get_avlength()

Xapian::doclength Xapian::Database::get_avlength ( ) const

Get the average length of the documents in the database.

Definition at line 293 of file omdatabase.cc.

References LOGCALL, LOGLINE, and RETURN.

Referenced by dbcheck(), DEFINE_TESTCASE(), CheckStatsWeight::get_sumpart(), and show_db_stats().

◆ get_collection_freq()

Xapian::termcount Xapian::Database::get_collection_freq ( const std::string & tname ) const

Return the total number of occurrences of the given term.

This is the sum of the number of occurrences of the term in each document it indexes: i.e., the sum of the within document frequencies of the term.

Parameters

tname The term whose collection frequency is being requested.

Definition at line 339 of file omdatabase.cc.

References LOGCALL, and RETURN.

Referenced by dbcheck(), DEFINE_TESTCASE(), CheckStatsWeight::get_sumpart(), RemoteServer::msg_collfreq(), RemoteServer::msg_freqs(), RemoteServer::msg_postlist(), closedb1_iterators::perform(), show_termlist(), termstats_to_string(), test_emptyterm1_helper(), and test_emptyterm2_helper().

◆ get_description()

string Xapian::Database::get_description ( ) const

virtual

Return a string describing this object.

Todo:: display contents of the database

Reimplemented in Xapian::WritableDatabase.

Definition at line 548 of file omdatabase.cc.

Referenced by DEFINE_TESTCASE(), and Xapian::Enquire::Internal::get_description().

◆ get_doccount()

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

Get the number of documents in the database.

Definition at line 267 of file omdatabase.cc.

References LOGCALL, and RETURN.

Referenced by check_equal_dbs(), check_vals(), dbcheck(), DEFINE_TESTCASE(), MultiMatch::get_mset(), Xapian::Enquire::Internal::get_mset(), CheckStatsWeight::get_sumpart(), MyDontAskWeightPostingSource::init(), Xapian::FixedWeightPostingSource::init(), main(), RemoteServer::msg_update(), show_db_stats(), test_emptyterm1_helper(), and test_emptyterm2_helper().

◆ get_doclength()

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

Get the length of a document.

Definition at line 461 of file omdatabase.cc.

References docid_zero_invalid(), LOGCALL, no_subdatabases(), rare, and RETURN.

Referenced by dbcheck(), DEFINE_TESTCASE(), docstats_to_string(), MultiPostList::get_doclength(), RemoteServer::msg_doclength(), RemoteServer::msg_termlist(), and closedb1_iterators::perform().

◆ get_doclength_lower_bound()

Xapian::termcount Xapian::Database::get_doclength_lower_bound ( ) const

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

This bound does not include any zero-length documents.

Definition at line 401 of file omdatabase.cc.

References LOGCALL, rare, and RETURN.

Referenced by dbcheck(), DEFINE_TESTCASE(), CheckBoundsPostingSource::init(), Xapian::Weight::init_(), RemoteServer::msg_update(), and show_db_stats().

◆ get_doclength_upper_bound()

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

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

Definition at line 421 of file omdatabase.cc.

References LOGCALL, and RETURN.

Referenced by dbcheck(), DEFINE_TESTCASE(), CheckBoundsPostingSource::init(), Xapian::Weight::init_(), RemoteServer::msg_update(), and show_db_stats().

◆ get_document() [1/2]

Document Xapian::Database::get_document ( Xapian::docid did ) const

Get a document from the database, given its document id.

This method returns a Xapian::Document object which provides the information about a document.

Parameters

did	The document id of the document to retrieve.

Returns: A Xapian::Document object containing the document data

Exceptions

Xapian::DocNotFoundError	The document specified could not be found in the database.
Xapian::InvalidArgumentError	did was 0, which is not a valid document id.

Definition at line 490 of file omdatabase.cc.

References docid_zero_invalid(), LOGCALL, no_subdatabases(), rare, and RETURN.

Referenced by check_vals(), dbcheck(), DEFINE_TESTCASE(), main(), make_orcheck_db(), RemoteServer::msg_document(), closedb1_iterators::perform(), show_docdata(), show_value(), and show_values().

◆ get_document() [2/2]

Document Xapian::Database::get_document	(	Xapian::docid	did,
		unsigned	flags
	)		const

Get a document from the database, given its document id.

This method returns a Xapian::Document object which provides the information about a document.

Parameters

did	The document id of the document to retrieve.
flags	Zero or more flags bitwise-or-ed together (currently only Xapian::DOC_ASSUME_VALID is supported).

Returns: A Xapian::Document object containing the document data

Exceptions

Xapian::DocNotFoundError	The document specified could not be found in the database.
Xapian::InvalidArgumentError	did was 0, which is not a valid document id.

Definition at line 507 of file omdatabase.cc.

References Xapian::DOC_ASSUME_VALID, docid_zero_invalid(), LOGCALL, no_subdatabases(), rare, and RETURN.

◆ get_lastdocid()

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

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

Definition at line 279 of file omdatabase.cc.

References LOGCALL, and RETURN.

Referenced by Xapian::WritableDatabase::add_document(), check_equal_dbs(), check_vals(), dbcheck(), DEFINE_TESTCASE(), MyDontAskWeightPostingSource::init(), OnlyTheFirstPostingSource::init(), RemoteServer::msg_update(), Xapian::WritableDatabase::replace_document(), and show_db_stats().

◆ get_metadata()

string Xapian::Database::get_metadata ( const std::string & key ) const

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

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.

Parameters

key	The key of the metadata item to access.

Returns: The retrieved metadata item's value.

Exceptions

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

Definition at line 758 of file omdatabase.cc.

References empty_metadata_key(), LOGCALL, rare, and RETURN.

Referenced by DEFINE_TESTCASE(), main(), and RemoteServer::msg_getmetadata().

◆ get_revision()

Xapian::rev Xapian::Database::get_revision ( ) const

Get the revision of the database.

The revision is an unsigned integer which increases with each commit.

The database must have exactly one sub-database, which must be of type chert or glass. Otherwise an exception will be thrown.

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

Definition at line 805 of file omdatabase.cc.

References LOGCALL, rare, Xapian::revision(), and unpack_uint().

Referenced by DEFINE_TESTCASE(), and show_db_stats().

◆ get_spelling_suggestion()

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

Suggest a spelling correction.

Parameters

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).

Definition at line 594 of file omdatabase.cc.

References edit_distance_unsigned(), Xapian::freq_edit_lower_bound(), Xapian::TermIterator::Internal::get_termname(), LOGCALL, LOGLINE, Xapian::TermIterator::Internal::next(), RETURN, Glass::SPELLING, and TRIGRAM_SCORE_THRESHOLD.

Referenced by DEFINE_TESTCASE().

◆ get_termfreq()

Xapian::doccount Xapian::Database::get_termfreq ( const std::string & tname ) const

Get the number of documents in the database indexed by a given term.

Definition at line 323 of file omdatabase.cc.

References LOGCALL, and RETURN.

Referenced by dbcheck(), DEFINE_TESTCASE(), CheckStatsWeight::get_sumpart(), MultiTermList::get_termfreq(), Xapian::Enquire::Internal::get_termfreq(), RemoteServer::msg_freqs(), RemoteServer::msg_postlist(), RemoteServer::msg_termfreq(), closedb1_iterators::perform(), termstats_to_string(), test_emptyterm1_helper(), and test_emptyterm2_helper().

◆ get_total_length()

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

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

Added in Xapian 1.4.5.

Definition at line 312 of file omdatabase.cc.

References LOGCALL, RETURN, and sub_db().

Referenced by DEFINE_TESTCASE(), CheckStatsWeight::get_sumpart(), RemoteServer::msg_update(), and show_db_stats().

◆ get_unique_terms()

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

Get the number of unique terms in document.

Definition at line 476 of file omdatabase.cc.

References docid_zero_invalid(), LOGCALL, no_subdatabases(), rare, and RETURN.

Referenced by dbcheck(), DEFINE_TESTCASE(), MultiPostList::get_unique_terms(), RemoteServer::msg_uniqueterms(), and closedb1_iterators::perform().

◆ get_uuid()

std::string Xapian::Database::get_uuid ( ) const

Get a UUID for the database.

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.

Definition at line 776 of file omdatabase.cc.

References LOGCALL, and RETURN.

Referenced by check_equal_dbs(), DEFINE_TESTCASE(), RemoteServer::msg_update(), and show_db_stats().

◆ get_value_freq()

Xapian::doccount Xapian::Database::get_value_freq ( Xapian::valueno slot ) const

Return the frequency of a given value slot.

This is the number of documents which have a (non-empty) value stored in the slot.

Parameters

slot	The value slot to examine.

Definition at line 355 of file omdatabase.cc.

References LOGCALL, and RETURN.

Referenced by DEFINE_TESTCASE(), Xapian::ValuePostingSource::init(), RemoteServer::msg_valuestats(), and closedb1_iterators::perform().

◆ get_value_lower_bound()

string Xapian::Database::get_value_lower_bound ( Xapian::valueno slot ) const

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

If there are no values stored in the given value slot, this will return an empty string.

Parameters

slot	The value slot to examine.

Definition at line 368 of file omdatabase.cc.

References LOGCALL, rare, and RETURN.

Referenced by dbcheck(), DEFINE_TESTCASE(), RemoteServer::msg_valuestats(), and closedb1_iterators::perform().

◆ get_value_upper_bound()

std::string Xapian::Database::get_value_upper_bound ( Xapian::valueno slot ) const

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

If there are no values stored in the given value slot, this will return an empty string.

Parameters

slot	The value slot to examine.

Definition at line 386 of file omdatabase.cc.

References LOGCALL, and RETURN.

Referenced by dbcheck(), DEFINE_TESTCASE(), Xapian::ValueWeightPostingSource::init(), RemoteServer::msg_valuestats(), and closedb1_iterators::perform().

◆ get_wdf_upper_bound()

Xapian::termcount Xapian::Database::get_wdf_upper_bound ( const std::string & term ) const

Get an upper bound on the wdf of term term.

Definition at line 435 of file omdatabase.cc.

References LOGCALL, and RETURN.

Referenced by dbcheck(), DEFINE_TESTCASE(), Xapian::Weight::init_(), and show_termlist().

◆ has_positions()

bool Xapian::Database::has_positions ( ) const

Does this database have any positional information?

Definition at line 238 of file omdatabase.cc.

References LOGCALL, and RETURN.

Referenced by DEFINE_TESTCASE(), MultiMatch::full_db_has_positions(), RemoteServer::msg_update(), and show_db_stats().

◆ keep_alive()

void Xapian::Database::keep_alive ( )

Send a "keep-alive" to remote databases to stop them timing out.

Has no effect on non-remote databases.

Definition at line 538 of file omdatabase.cc.

References LOGCALL_VOID.

Referenced by DEFINE_TESTCASE(), and RemoteServer::msg_keepalive().

◆ locked()

bool Xapian::Database::locked ( ) const

Test if this database is currently locked for writing.

If the underlying object is actually a WritableDatabase, always returns true.

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.

Definition at line 793 of file omdatabase.cc.

References LOGCALL, and RETURN.

Referenced by DEFINE_TESTCASE(), and show_db_stats().

◆ metadata_keys_begin()

Xapian::TermIterator Xapian::Database::metadata_keys_begin ( const std::string & prefix = std::string() ) const

An iterator which returns all user-specified metadata keys.

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 the backend doesn't support metadata, then this method returns an iterator which compares equal to that returned by metadata_keys_end().

Parameters

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

Exceptions

Xapian::UnimplementedError will be thrown if the backend implements user-specified metadata, but doesn't implement iterating its keys (currently this happens for the InMemory backend).

Definition at line 768 of file omdatabase.cc.

References LOGCALL, and RETURN.

Referenced by DEFINE_TESTCASE(), main(), and RemoteServer::msg_openmetadatakeylist().

◆ metadata_keys_end()

Xapian::TermIterator Xapian::Database::metadata_keys_end ( const std::string & = std::string() ) const

inline

Corresponding end iterator to metadata_keys_begin().

Definition at line 510 of file database.h.

Referenced by DEFINE_TESTCASE(), main(), and RemoteServer::msg_openmetadatakeylist().

◆ operator=()

void Xapian::Database::operator= ( const Database & other )

default

Assignment is allowed.

The internals are reference counted, so assignment is cheap.

Parameters

other The object to copy.

Definition at line 113 of file omdatabase.cc.

References internal, and LOGCALL_VOID.

Referenced by Xapian::WritableDatabase::operator=().

◆ positionlist_begin()

PositionIterator Xapian::Database::positionlist_begin	(	Xapian::docid	did,
		const std::string &	tname
	)		const

An iterator pointing to the start of the position list for a given term in a given document.

Definition at line 250 of file omdatabase.cc.

References docid_zero_invalid(), LOGCALL, no_subdatabases(), rare, and RETURN.

Referenced by DEFINE_TESTCASE(), main(), RemoteServer::msg_positionlist(), closedb1_iterators::perform(), closedb1_iterators::setup(), test_emptyterm1_helper(), and test_emptyterm2_helper().

◆ positionlist_end()

PositionIterator Xapian::Database::positionlist_end	(	Xapian::docid	,
		const std::string &
	)		const

inline

Corresponding end iterator to positionlist_begin().

Definition at line 254 of file database.h.

Referenced by DEFINE_TESTCASE(), main(), RemoteServer::msg_positionlist(), and closedb1_iterators::setup().

◆ postlist_begin()

PostingIterator Xapian::Database::postlist_begin ( const std::string & tname ) const

An iterator pointing to the start of the postlist for a given term.

Parameters

tname The termname to iterate postings for. If the term name is the empty string, the iterator returned will list all the documents in the database. Such an iterator will always return a WDF value of 1, since there is no obvious meaning for this quantity in this case.

Definition at line 162 of file omdatabase.cc.

References Assert, LOGCALL, rare, and RETURN.

Referenced by check_sparse_uid_terms(), dbcheck(), DEFINE_TESTCASE(), main(), RemoteServer::msg_postlist(), Xapian::FixedWeightPostingSource::next(), closedb1_iterators::perform(), postlist_to_string(), Xapian::WritableDatabase::replace_document(), closedb1_iterators::setup(), show_db_stats(), and Xapian::FixedWeightPostingSource::skip_to().

◆ postlist_end()

PostingIterator Xapian::Database::postlist_end ( const std::string & ) const

inline

Corresponding end iterator to postlist_begin().

Definition at line 225 of file database.h.

Referenced by Xapian::FixedWeightPostingSource::at_end(), dbcheck(), DEFINE_TESTCASE(), main(), RemoteServer::msg_postlist(), Xapian::FixedWeightPostingSource::next(), postlist_to_string(), Xapian::WritableDatabase::replace_document(), closedb1_iterators::setup(), show_db_stats(), and Xapian::FixedWeightPostingSource::skip_to().

◆ reopen()

bool Xapian::Database::reopen ( )

Re-open the database.

This re-opens the database(s) to the latest available version(s). It can be used either to make sure the latest results are returned, or to recover from a Xapian::DatabaseModifiedError.

Calling reopen() on a database which has been closed (with close()) will always raise a Xapian::DatabaseError.

Returns: true if the database might have been reopened (if false is returned, the database definitely hasn't been reopened, which applications may find useful when caching results, etc). In Xapian < 1.3.0, this method did not return a value.

Definition at line 125 of file omdatabase.cc.

References LOGCALL, and RETURN.

Referenced by DEFINE_TESTCASE(), RemoteServer::msg_reopen(), and closedb1_iterators::perform().

◆ size()

size_t Xapian::Database::size ( ) const

inline

Return number of shards in this Database object.

Definition at line 93 of file database.h.

References close().

Referenced by BackendManagerMulti::createdb_multi(), DEFINE_TESTCASE(), Xapian::DatabaseReplica::Internal::get_revision_info(), and show_db_stats().

◆ spellings_begin()

TermIterator Xapian::Database::spellings_begin ( ) const

An iterator which returns all the spelling correction targets.

This returns all the words which are considered as targets for the spelling correction algorithm. The frequency of each word is available as the term frequency of each entry in the returned iterator.

Definition at line 704 of file omdatabase.cc.

References LOGCALL, and RETURN.

Referenced by DEFINE_TESTCASE(), and main().

◆ spellings_end()

Xapian::TermIterator Xapian::Database::spellings_end ( ) const

inline

Corresponding end iterator to spellings_begin().

Definition at line 436 of file database.h.

Referenced by DEFINE_TESTCASE(), and main().

◆ synonym_keys_begin()

TermIterator Xapian::Database::synonym_keys_begin ( const std::string & prefix = std::string() ) const

An iterator which returns all terms which have synonyms.

Parameters

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

Definition at line 740 of file omdatabase.cc.

References LOGCALL, and RETURN.

Referenced by TermGroup::as_group(), DEFINE_TESTCASE(), and main().

◆ synonym_keys_end()

Xapian::TermIterator Xapian::Database::synonym_keys_end ( const std::string & = std::string() ) const

inline

Corresponding end iterator to synonym_keys_begin(prefix).

Definition at line 459 of file database.h.

Referenced by TermGroup::as_group(), DEFINE_TESTCASE(), and main().

◆ synonyms_begin()

TermIterator Xapian::Database::synonyms_begin ( const std::string & term ) const

An iterator which returns all the synonyms for a given term.

Parameters

term	The term to return synonyms for.

Definition at line 722 of file omdatabase.cc.

References LOGCALL, and RETURN.

Referenced by TermGroup::as_group(), DEFINE_TESTCASE(), Term::get_query_with_synonyms(), and main().

◆ synonyms_end()

Xapian::TermIterator Xapian::Database::synonyms_end ( const std::string & ) const

inline

Corresponding end iterator to synonyms_begin(term).

Definition at line 447 of file database.h.

Referenced by TermGroup::as_group(), DEFINE_TESTCASE(), Term::get_query_with_synonyms(), and main().

◆ term_exists()

bool Xapian::Database::term_exists ( const std::string & tname ) const

Check if a given term exists in the database.

Parameters

tname The term to test the existence of.

Returns: true if and only if the term exists in the database. This is the same as (get_termfreq(tname) != 0), but will often be more efficient.

Definition at line 524 of file omdatabase.cc.

References LOGCALL, and RETURN.

Referenced by dbcheck(), DEFINE_TESTCASE(), RemoteServer::msg_termexists(), closedb1_iterators::perform(), test_emptyterm1_helper(), and test_emptyterm2_helper().

◆ termlist_begin()

TermIterator Xapian::Database::termlist_begin ( Xapian::docid did ) const

An iterator pointing to the start of the termlist for a given document.

The terms are returned in ascending string order (by byte value).

Parameters

did	The document id of the document to iterate terms for.

Definition at line 198 of file omdatabase.cc.

References Assert, docid_zero_invalid(), LOGCALL, no_subdatabases(), rare, and RETURN.

Referenced by dbcheck(), DEFINE_TESTCASE(), docterms_to_string(), Xapian::Enquire::Internal::get_matching_terms(), main(), RemoteServer::msg_termlist(), closedb1_iterators::perform(), closedb1_iterators::setup(), show_termlist(), and test_termlist3_helper().

◆ termlist_end()

TermIterator Xapian::Database::termlist_end ( Xapian::docid ) const

inline

Corresponding end iterator to termlist_begin().

Definition at line 240 of file database.h.

Referenced by dbcheck(), DEFINE_TESTCASE(), docterms_to_string(), Xapian::Enquire::Internal::get_matching_terms(), main(), RemoteServer::msg_termlist(), closedb1_iterators::setup(), and show_termlist().

◆ valuestream_begin()

ValueIterator Xapian::Database::valuestream_begin ( Xapian::valueno slot ) const

Return an iterator over the value in slot slot for each document.

Definition at line 450 of file omdatabase.cc.

References LOGCALL, and RETURN.

Referenced by Xapian::ValuePostingSource::check(), dbcheck(), DEFINE_TESTCASE(), Xapian::ValuePostingSource::next(), closedb1_iterators::perform(), and Xapian::ValuePostingSource::skip_to().

◆ valuestream_end()

ValueIterator Xapian::Database::valuestream_end ( Xapian::valueno ) const

inline

Return end iterator corresponding to valuestream_begin().

Definition at line 363 of file database.h.

Referenced by Xapian::ValuePostingSource::at_end(), Xapian::ValuePostingSource::check(), dbcheck(), DEFINE_TESTCASE(), Xapian::ValuePostingSource::done(), Xapian::ValuePostingSource::next(), and Xapian::ValuePostingSource::skip_to().

Member Data Documentation

◆ internal

std::vector<Xapian::Internal::intrusive_ptr<Internal> > Xapian::Database::internal

private

Reference counted internals.

Definition at line 81 of file database.h.

Referenced by add_database(), backend_mismatch(), Xapian::build_termlist_tree(), Database(), Xapian::Enquire::Internal::get_document(), MultiMatch::get_mset(), Xapian::Enquire::Internal::Internal(), MultiMatch::MultiMatch(), operator=(), Xapian::Enquire::Internal::read_doc(), Xapian::Enquire::Internal::request_doc(), ValueStreamDocument::set_document(), and Xapian::DatabaseMaster::write_changesets_to_fd().

The documentation for this class was generated from the following files:

include/xapian/database.h
api/compactor.cc
api/omdatabase.cc
backends/dbcheck.cc
backends/dbfactory.cc

Classes

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Database() [1/5]

◆ Database() [2/5]

◆ Database() [3/5]

◆ Database() [4/5]

◆ ~Database()

◆ Database() [5/5]

Member Function Documentation

◆ add_database()

◆ allterms_begin()

◆ allterms_end()

◆ check() [1/2]

◆ check() [2/2]

◆ check_()

◆ close()

◆ compact() [1/4]

◆ compact() [2/4]

◆ compact() [3/4]

◆ compact() [4/4]

◆ compact_()

◆ get_average_length()

◆ get_avlength()

◆ get_collection_freq()

◆ get_description()

◆ get_doccount()

◆ get_doclength()

◆ get_doclength_lower_bound()

◆ get_doclength_upper_bound()

◆ get_document() [1/2]

◆ get_document() [2/2]

◆ get_lastdocid()

◆ get_metadata()

◆ get_revision()

◆ get_spelling_suggestion()

◆ get_termfreq()

◆ get_total_length()

◆ get_unique_terms()

◆ get_uuid()

◆ get_value_freq()

◆ get_value_lower_bound()

◆ get_value_upper_bound()

◆ get_wdf_upper_bound()

◆ has_positions()

◆ keep_alive()

◆ locked()

◆ metadata_keys_begin()

◆ metadata_keys_end()

◆ operator=()

◆ positionlist_begin()

◆ positionlist_end()

◆ postlist_begin()

◆ postlist_end()

◆ reopen()

◆ size()

◆ spellings_begin()

◆ spellings_end()

◆ synonym_keys_begin()

◆ synonym_keys_end()

◆ synonyms_begin()

◆ synonyms_end()

◆ term_exists()

◆ termlist_begin()

◆ termlist_end()

◆ valuestream_begin()

◆ valuestream_end()

Member Data Documentation

◆ internal