QuartzDatabase Class Reference

A backend designed for efficient indexing and retrieval, using compressed posting lists and a btree storage scheme. More...

#include <quartz_database.h>

Inheritance diagram for QuartzDatabase:

Inheritance graph
[legend]
Collaboration diagram for QuartzDatabase:

Collaboration graph
[legend]
List of all members.

Public Member Functions

 QuartzDatabase (const string &db_dir_, int action=OM_DB_READONLY, unsigned int block_size=0u)
 Create and open a quartz database.
 ~QuartzDatabase ()
Xapian::doccount get_doccount () const
 Virtual methods of Database.
Xapian::docid get_lastdocid () const
 Return the last used document id of this (sub) database.
Xapian::doclength get_avlength () const
 Return the average length of a document in this (sub) database.
Xapian::doclength get_doclength (Xapian::docid did) const
 Get the length of a given document.
Xapian::doccount get_termfreq (const string &tname) const
 Return the number of documents indexed by a given term.
Xapian::termcount get_collection_freq (const string &tname) const
 Return the total number of occurrences of the given term.
bool term_exists (const string &tname) const
 Check whether a given term is in the database.
bool has_positions () const
 Check whether this database contains any positional information.
LeafPostListopen_post_list (const string &tname) const
 Open a posting list.
TermListopen_term_list (Xapian::docid did) const
 Open a term list.
Xapian::Document::Internalopen_document (Xapian::docid did, bool lazy=false) const
 Open a document.
PositionListopen_position_list (Xapian::docid did, const string &tname) const
 Open a position list for the given term in the given document.
TermListopen_allterms (const string &prefix) const
 Open an allterms list.

Private Member Functions

bool database_exists ()
 Return true if a database exists at the path specified for this database.
void create_and_open_tables (unsigned int blocksize)
 Create new tables, and open them.
void open_tables_consistent ()
 Open all tables at most recent consistent revision.
void get_database_write_lock ()
 Get a write lock on the database, or throw an Xapian::DatabaseLockError if failure.
void release_database_write_lock ()
 Release the database write lock.
void open_tables (quartz_revision_number_t revision)
 Open tables at specified revision number.
quartz_revision_number_t get_revision_number () const
 Get an object holding the revision number which the tables are opened at.
quartz_revision_number_t get_next_revision_number () const
 Get an object holding the next revision number which should be used in the tables.
void set_revision_number (quartz_revision_number_t new_revision)
 Set the revision number in the tables.
virtual void reopen ()
 Re-open tables to recover from an overwritten condition, or just get most up-to-date version.
void apply ()
 Apply any outstanding changes to the tables.
void cancel ()
 Cancel any outstanding changes to the tables.

Private Attributes

std::string db_dir
 Directory to store databases in.
bool readonly
 Whether the database is readonly.
QuartzMetaFile metafile
 The file describing the Quartz database.
QuartzPostListTable postlist_table
 Table storing posting lists.
QuartzPositionListTable positionlist_table
 Table storing position lists.
QuartzTermListTable termlist_table
 Table storing term lists.
QuartzValueTable value_table
 Table storing values.
QuartzRecordTable record_table
 Table storing records.
QuartzLog log
 Object for logging modifications.

Friends

class QuartzWritableDatabase
class QuartzTermList

Detailed Description

A backend designed for efficient indexing and retrieval, using compressed posting lists and a btree storage scheme.

Definition at line 48 of file quartz_database.h.


Constructor & Destructor Documentation

QuartzDatabase::QuartzDatabase ( const string &  db_dir_,
int  action = OM_DB_READONLY,
unsigned int  block_size = 0u 
)

Create and open a quartz database.

Exceptions:
Xapian::DatabaseCorruptError is thrown if there is no consistent revision available.
Xapian::DatabaseOpeningError thrown if database can't be opened.
Xapian::DatabaseVersionError thrown if database is in an unsupported format. This implies that the database was created by an older or newer version of Xapian.
Parameters:
dbdir directory holding quartz tables
block_size Block size, in bytes, to use when creating tables. This is only important, and has the correct value, when the database is being created. (ie, opened writable for the first time).

Definition at line 69 of file quartz_database.cc.

References Btree::commit(), create_and_open_tables(), database_exists(), Xapian::DB_CREATE, Xapian::DB_CREATE_OR_OVERWRITE, db_dir, Xapian::DB_OPEN, DEBUGCALL, file_exists(), get_database_write_lock(), QuartzRecordTable::get_doccount(), QuartzRecordTable::get_lastdocid(), Btree::get_latest_revision_number(), get_next_revision_number(), Btree::get_open_revision_number(), log, QuartzLog::make_entry(), mkdir(), OM_DB_READONLY, om_tostring(), open_tables_consistent(), positionlist_table, postlist_table, record_table, S_ISDIR, QuartzRecordTable::set_total_length_and_lastdocid(), stat(), termlist_table, and value_table.

QuartzDatabase::~QuartzDatabase (  ) 

Definition at line 174 of file quartz_database.cc.

References DEBUGCALL, log, QuartzLog::make_entry(), readonly, and release_database_write_lock().


Member Function Documentation

bool QuartzDatabase::database_exists (  )  [private]

Return true if a database exists at the path specified for this database.

Definition at line 183 of file quartz_database.cc.

References DEBUGCALL, Btree::exists(), positionlist_table, postlist_table, record_table, termlist_table, and value_table.

Referenced by create_and_open_tables(), and QuartzDatabase().

void QuartzDatabase::create_and_open_tables ( unsigned int  blocksize  )  [private]

Create new tables, and open them.

Any existing tables will be removed first.

Definition at line 193 of file quartz_database.cc.

References Assert, Btree::create(), QuartzMetaFile::create(), database_exists(), DEBUGCALL, Btree::get_open_revision_number(), log, QuartzLog::make_entry(), metafile, om_tostring(), Btree::open(), QuartzMetaFile::open(), positionlist_table, postlist_table, record_table, Xapian::revision(), QuartzRecordTable::set_total_length_and_lastdocid(), termlist_table, and value_table.

Referenced by QuartzDatabase().

void QuartzDatabase::open_tables_consistent (  )  [private]

Open all tables at most recent consistent revision.

Exceptions:
Xapian::DatabaseCorruptError is thrown if there is no consistent revision available.

Definition at line 237 of file quartz_database.cc.

References DEBUGCALL, Btree::get_open_revision_number(), log, QuartzLog::make_entry(), metafile, om_tostring(), Btree::open(), QuartzMetaFile::open(), positionlist_table, postlist_table, record_table, Xapian::revision(), termlist_table, and value_table.

Referenced by QuartzDatabase(), and reopen().

void QuartzDatabase::get_database_write_lock (  )  [private]

Get a write lock on the database, or throw an Xapian::DatabaseLockError if failure.

Definition at line 356 of file quartz_database.cc.

References db_dir, DEBUGCALL, DEBUGLINE, om_tostring(), Xapian::Remote::open(), stat(), and unlink().

Referenced by QuartzDatabase().

void QuartzDatabase::release_database_write_lock (  )  [private]

Release the database write lock.

Definition at line 454 of file quartz_database.cc.

References db_dir, DEBUGCALL, and unlink().

Referenced by ~QuartzDatabase().

void QuartzDatabase::open_tables ( quartz_revision_number_t  revision  )  [private]

Open tables at specified revision number.

Exceptions:
Xapian::InvalidArgumentError is thrown if the specified revision is not available.

Definition at line 300 of file quartz_database.cc.

References DEBUGCALL, log, QuartzLog::make_entry(), metafile, om_tostring(), Btree::open(), QuartzMetaFile::open(), positionlist_table, postlist_table, record_table, termlist_table, and value_table.

Referenced by apply().

quartz_revision_number_t QuartzDatabase::get_revision_number (  )  const [private]

Get an object holding the revision number which the tables are opened at.

Returns:
the current revision number.

Definition at line 314 of file quartz_database.cc.

References DEBUGCALL, Btree::get_open_revision_number(), postlist_table, and RETURN.

Referenced by apply().

quartz_revision_number_t QuartzDatabase::get_next_revision_number (  )  const [private]

Get an object holding the next revision number which should be used in the tables.

Returns:
the next revision number.

Definition at line 322 of file quartz_database.cc.

References DEBUGCALL, Btree::get_latest_revision_number(), postlist_table, and RETURN.

Referenced by apply(), and QuartzDatabase().

void QuartzDatabase::set_revision_number ( quartz_revision_number_t  new_revision  )  [private]

Set the revision number in the tables.

This updates the disk tables so that the currently open revision becomes the specified revision number.

Parameters:
new_revision The new revision number to store. This must be greater than the latest revision number (see get_latest_revision_number()), or undefined behaviour will result.

Definition at line 336 of file quartz_database.cc.

References Btree::commit(), DEBUGCALL, positionlist_table, postlist_table, record_table, termlist_table, and value_table.

Referenced by apply().

void QuartzDatabase::reopen (  )  [private, virtual]

Re-open tables to recover from an overwritten condition, or just get most up-to-date version.

Reimplemented from Xapian::Database::Internal.

Definition at line 347 of file quartz_database.cc.

References DEBUGCALL, open_tables_consistent(), and readonly.

void QuartzDatabase::apply (  )  [private]

Apply any outstanding changes to the tables.

If an error occurs during the operation, this will be signalled by a return value of false. The tables on disk will be left in an unmodified state (though possibly with increased revision numbers), and the changes made will be lost.

Returns:
true if the operation completed successfully, false otherwise.

Definition at line 461 of file quartz_database.cc.

References cancel(), Btree::commit(), DEBUGCALL, Xapian::Error::get_description(), get_next_revision_number(), get_revision_number(), Btree::is_modified(), log, QuartzLog::make_entry(), om_tostring(), open_tables(), positionlist_table, postlist_table, record_table, set_revision_number(), termlist_table, and value_table.

Referenced by QuartzWritableDatabase::do_flush_const().

void QuartzDatabase::cancel (  )  [private, virtual]

Cancel any outstanding changes to the tables.

Reimplemented from Xapian::Database::Internal.

Definition at line 516 of file quartz_database.cc.

References Btree::cancel(), DEBUGCALL, positionlist_table, postlist_table, record_table, termlist_table, and value_table.

Referenced by apply(), and QuartzWritableDatabase::cancel().

Xapian::doccount QuartzDatabase::get_doccount (  )  const [virtual]

Virtual methods of Database.

Implements Xapian::Database::Internal.

Definition at line 527 of file quartz_database.cc.

References DEBUGCALL, QuartzRecordTable::get_doccount(), record_table, and RETURN.

Referenced by QuartzWritableDatabase::get_avlength(), QuartzWritableDatabase::get_doccount(), open_post_list(), and open_term_list().

Xapian::docid QuartzDatabase::get_lastdocid (  )  const [virtual]

Return the last used document id of this (sub) database.

Implements Xapian::Database::Internal.

Definition at line 534 of file quartz_database.cc.

References DEBUGCALL, QuartzRecordTable::get_lastdocid(), record_table, and RETURN.

Referenced by QuartzWritableDatabase::cancel().

Xapian::doclength QuartzDatabase::get_avlength (  )  const [virtual]

Return the average length of a document in this (sub) database.

See Database::Internal::get_doclength() for the meaning of document length within Xapian.

Implements Xapian::Database::Internal.

Definition at line 541 of file quartz_database.cc.

References DEBUGCALL, QuartzRecordTable::get_doccount(), QuartzRecordTable::get_total_length(), record_table, and RETURN.

Xapian::doclength QuartzDatabase::get_doclength ( Xapian::docid  did  )  const [virtual]

Get the length of a given document.

Document length, for the purposes of Xapian, is defined to be the number of instances of terms within a document. Expressed differently, the sum of the within document frequencies over all the terms in the document.

Parameters:
did The document id of the document whose length is being requested.

Implements Xapian::Database::Internal.

Definition at line 550 of file quartz_database.cc.

References Assert, DEBUGCALL, QuartzTermList::get_doclength(), RETURN, and termlist_table.

Referenced by QuartzWritableDatabase::get_doclength().

Xapian::doccount QuartzDatabase::get_termfreq ( const string &  tname  )  const [virtual]

Return the number of documents indexed by a given term.

This may be an approximation, but must be an upper bound (ie, greater or equal to the true value), and should be as accurate as possible.

Parameters:
tname The term whose term frequency is being requested.

Implements Xapian::Database::Internal.

Definition at line 560 of file quartz_database.cc.

References Assert, DEBUGCALL, QuartzPostListTable::get_collection_freq(), QuartzPostListTable::get_termfreq(), postlist_table, and RETURN.

Referenced by QuartzWritableDatabase::get_termfreq().

Xapian::termcount QuartzDatabase::get_collection_freq ( const string &  tname  )  const [virtual]

Return the total number of occurrences of the given term.

This is the sum of the number of ocurrences of the term in each document: ie, the sum of the within document frequencies of the term.

Parameters:
tname The term whose collection frequency is being requested.

Implements Xapian::Database::Internal.

Definition at line 570 of file quartz_database.cc.

References Assert, DEBUGCALL, QuartzPostListTable::get_collection_freq(), postlist_table, and RETURN.

Referenced by QuartzWritableDatabase::get_collection_freq().

bool QuartzDatabase::term_exists ( const string &  tname  )  const [virtual]

Check whether a given term is in the database.

Parameters:
tname The term whose presence is being checked.

Implements Xapian::Database::Internal.

Definition at line 579 of file quartz_database.cc.

References Assert, Btree::cursor_get(), DEBUGCALL, pack_string_preserving_sort(), and postlist_table.

bool QuartzDatabase::has_positions (  )  const [virtual]

Check whether this database contains any positional information.

Implements Xapian::Database::Internal.

Definition at line 590 of file quartz_database.cc.

References Btree::get_entry_count(), and positionlist_table.

Referenced by QuartzWritableDatabase::has_positions().

LeafPostList * QuartzDatabase::open_post_list ( const string &  tname  )  const [virtual]

Open a posting list.

Method defined by subclass to open a posting list. This is a list of all the documents which contain a given term.

Parameters:
tname The term whose posting list is being requested.
Returns:
A pointer to the newly created posting list. If the term doesn't exist, a new EmptyPostList object (or an object which behaves the same way) is returned instead, which makes it easier to implement a search over multiple databases. This object must be deleted by the caller after use.

Implements Xapian::Database::Internal.

Definition at line 597 of file quartz_database.cc.

References DEBUGCALL, get_doccount(), positionlist_table, postlist_table, RETURN, and termlist_table.

TermList * QuartzDatabase::open_term_list ( Xapian::docid  did  )  const [virtual]

Open a term list.

This is a list of all the terms contained by a given document.

Parameters:
did The document id whose term list is being requested.
Returns:
A pointer to the newly created term list. This object must be deleted by the caller after use.

Implements Xapian::Database::Internal.

Definition at line 615 of file quartz_database.cc.

References Assert, DEBUGCALL, get_doccount(), QuartzTermList, RETURN, and termlist_table.

Referenced by open_position_list().

Xapian::Document::Internal * QuartzDatabase::open_document ( Xapian::docid  did,
bool  lazy = false 
) const [virtual]

Open a document.

This is used to access the values and data associated with a document. See class Xapian::Document::Internal for further details.

Parameters:
did The document id which is being requested.
lazy Don't check the document exists immediately - use from within the matcher where we know the document exists, and don't want to read the record when we just want the values.
Returns:
A pointer to the newly created document object. This object must be deleted by the caller after use.

Implements Xapian::Database::Internal.

Definition at line 625 of file quartz_database.cc.

References Assert, DEBUGCALL, record_table, RETURN, and value_table.

PositionList * QuartzDatabase::open_position_list ( Xapian::docid  did,
const string &  tname 
) const [virtual]

Open a position list for the given term in the given document.

Parameters:
did The document id for which a position list is being requested.
tname The term for which a position list is being requested.
Returns:
A pointer to the newly created position list. This object must be deleted by the caller after use.

Implements Xapian::Database::Internal.

Definition at line 639 of file quartz_database.cc.

References Assert, open_term_list(), positionlist_table, and AutoPtr< _Tp >::release().

TermList * QuartzDatabase::open_allterms ( const string &  prefix  )  const [virtual]

Open an allterms list.

This is a list of all the terms in the database

Parameters:
prefix The prefix to restrict the terms to.
Returns:
A pointer to the newly created allterms list. This object must be deleted by the caller after use.

Implements Xapian::Database::Internal.

Definition at line 659 of file quartz_database.cc.

References Btree::cursor_get(), DEBUGCALL, Btree::get_entry_count(), postlist_table, and RETURN.


Friends And Related Function Documentation

friend class QuartzWritableDatabase [friend]

Definition at line 49 of file quartz_database.h.

friend class QuartzTermList [friend]

Definition at line 50 of file quartz_database.h.

Referenced by open_term_list().


Member Data Documentation

std::string QuartzDatabase::db_dir [private]

Directory to store databases in.

Definition at line 54 of file quartz_database.h.

Referenced by get_database_write_lock(), QuartzDatabase(), and release_database_write_lock().

bool QuartzDatabase::readonly [private]

Whether the database is readonly.

Definition at line 58 of file quartz_database.h.

Referenced by reopen(), and ~QuartzDatabase().

QuartzMetaFile QuartzDatabase::metafile [private]

The file describing the Quartz database.

This file has information about the format of the database which can't easily be stored in any of the individual tables.

Definition at line 64 of file quartz_database.h.

Referenced by create_and_open_tables(), open_tables(), and open_tables_consistent().

QuartzPostListTable QuartzDatabase::postlist_table [private]

Table storing posting lists.

Whenever an update is performed, this table is the first to be updated: therefore, its most recent revision number is the most recent anywhere in the database.

Definition at line 72 of file quartz_database.h.

Referenced by apply(), cancel(), create_and_open_tables(), database_exists(), QuartzWritableDatabase::do_flush_const(), get_collection_freq(), get_next_revision_number(), get_revision_number(), get_termfreq(), QuartzWritableDatabase::open_allterms(), open_allterms(), QuartzWritableDatabase::open_post_list(), open_post_list(), open_tables(), open_tables_consistent(), QuartzDatabase(), set_revision_number(), and term_exists().

QuartzPositionListTable QuartzDatabase::positionlist_table [private]

Table storing position lists.

Definition at line 76 of file quartz_database.h.

Referenced by QuartzWritableDatabase::add_document_(), apply(), cancel(), create_and_open_tables(), database_exists(), QuartzWritableDatabase::delete_document(), has_positions(), QuartzWritableDatabase::open_position_list(), open_position_list(), QuartzWritableDatabase::open_post_list(), open_post_list(), open_tables(), open_tables_consistent(), QuartzDatabase(), QuartzWritableDatabase::replace_document(), and set_revision_number().

QuartzTermListTable QuartzDatabase::termlist_table [private]

Table storing term lists.

Definition at line 80 of file quartz_database.h.

Referenced by QuartzWritableDatabase::add_document_(), apply(), cancel(), create_and_open_tables(), database_exists(), QuartzWritableDatabase::delete_document(), get_doclength(), QuartzWritableDatabase::open_post_list(), open_post_list(), open_tables(), open_tables_consistent(), QuartzWritableDatabase::open_term_list(), open_term_list(), QuartzDatabase(), QuartzWritableDatabase::replace_document(), and set_revision_number().

QuartzValueTable QuartzDatabase::value_table [private]

Table storing values.

Definition at line 84 of file quartz_database.h.

Referenced by QuartzWritableDatabase::add_document_(), apply(), cancel(), create_and_open_tables(), database_exists(), QuartzWritableDatabase::delete_document(), QuartzWritableDatabase::open_document(), open_document(), open_tables(), open_tables_consistent(), QuartzDatabase(), QuartzWritableDatabase::replace_document(), and set_revision_number().

QuartzRecordTable QuartzDatabase::record_table [private]

Table storing records.

Whenever an update is performed, this table is the last to be updated: therefore, its most recent revision number is the most recent consistent revision available. If this tables most recent revision number is not available for all tables, there is no consistent revision available, and the database is corrupt.

Definition at line 94 of file quartz_database.h.

Referenced by QuartzWritableDatabase::add_document_(), apply(), QuartzWritableDatabase::cancel(), cancel(), create_and_open_tables(), database_exists(), QuartzWritableDatabase::delete_document(), QuartzWritableDatabase::do_flush_const(), get_avlength(), get_doccount(), get_lastdocid(), QuartzWritableDatabase::open_document(), open_document(), open_tables(), open_tables_consistent(), QuartzDatabase(), QuartzWritableDatabase::replace_document(), and set_revision_number().

QuartzLog QuartzDatabase::log [private]

Object for logging modifications.

Definition at line 98 of file quartz_database.h.

Referenced by apply(), create_and_open_tables(), open_tables(), open_tables_consistent(), QuartzDatabase(), and ~QuartzDatabase().


The documentation for this class was generated from the following files:
Documentation for Xapian (version 1.0.10).
Generated on 24 Dec 2008 by Doxygen 1.5.2.