xapian-bindings/perl/Xapian/WritableDatabase.pm

   1 package Xapian::WritableDatabase;
   2
   3 =head1 NAME
   4
   5 Xapian::WritableDatabase - writable database object
   6
   7 =head1 DESCRIPTION
   8
   9 This class represents a Xapian database for indexing. It's a subclass of
  10 L<Xapian::Database>, which is used for searching.
  11
  12 =head1 METHODS
  13
  14 =over 4
  15
  16 =item new <database> or new <path> <mode>
  17
  18 Class constructor. Takes either a database object, or a path and one
  19 of DB_OPEN, DB_CREATE, DB_CREATE_OR_OPEN or DB_CREATE_OR_OVERWRITE.
  20 These are exported by L<Xapian> with the 'db' option.
  21
  22 =item clone
  23
  24 Return a clone of this class.
  25
  26 =item commit
  27
  28 Commit any modifications made to the database.
  29
  30 For efficiency reasons, when performing multiple updates to a database it is
  31 best (indeed, almost essential) to make as many modifications as memory will
  32 permit in a single pass through the database. To ensure this, Xapian batches
  33 up modifications.
  34
  35 Commit may be called at any time to ensure that the modifications which have
  36 been made are written to disk: if the commit succeeds, all the preceding
  37 modifications will have been written to disk.
  38
  39 If any of the modifications fail, an exception will be thrown and the database
  40 will be left in a state in which each separate addition, replacement or
  41 deletion operation has either been fully performed or not performed at all:
  42 it is then up to the application to work out which operations need to be
  43 repeated.
  44
  45 Beware of calling commit too frequently: this will have a severe performance
  46 cost.
  47
  48 Note that commit need not be called explicitly: it will be called automatically
  49 when the database is closed, or when a sufficient number of modifications
  50 have been made.
  51
  52 =item add_document <document>
  53
  54 Add a new document to the database.
  55
  56 This method adds the specified document to the database, returning a newly
  57 allocated document ID.
  58
  59 Note that this does not mean the document will immediately appear in the
  60 database; see commit() for more details.
  61
  62 As with all database modification operations, the effect is atomic: the
  63 document will either be fully added, or the document fails to be added and
  64 an exception is thrown (possibly at a later time when commit is called or the
  65 database is closed).
  66
  67 =item delete_document <doc_id>
  68
  69 Delete a document from the database. This method removes the document with
  70 the specified document ID from the database.
  71
  72 Note that this does not mean the document will immediately disappear from
  73 the database; see commit() for more details.
  74
  75 As with all database modification operations, the effect is atomic: the
  76 document will either be fully removed, or the document fails to be removed
  77 and an exception is thrown (possibly at a later time when commit is called or
  78 the database is closed).
  79
  80 =item delete_document_by_term <term>
  81
  82 Delete any documents indexed by a term from the database. This method removes
  83 any documents indexed by the specified term from the database.
  84
  85 The intended use is to allow UIDs from another system to easily be mapped to
  86 terms in Xapian, although this method probably has other uses.
  87
  88 =item replace_document <doc_id> <document>
  89
  90 eplace a given document in the database.
  91
  92 This method replaces the document with the specified document ID. Note that
  93 this does not mean the document will immediately change in the database; see
  94 commit() for more details.
  95
  96 As with all database modification operations, the effect is atomic: the
  97 document will either be fully replaced, or the document fails to be replaced
  98 and an exception is thrown (possibly at a later time when commit is called or
  99 the database is closed).
 100
 101 =item replace_document_by_term <unique_term> <document>
 102
 103 Replace any documents matching an unique term.
 104
 105 This method replaces any documents indexed by the specified term with the
 106 specified document. If any documents are indexed by the term, the lowest
 107 document ID will be used for the document, otherwise a new document ID
 108 will be generated as for add_document.
 109
 110 The intended use is to allow UIDs from another system to easily be mapped
 111 to terms in Xapian, although this method probably has other uses.
 112
 113 Note that this does not mean the document(s) will immediately change in the
 114 database; see commit() for more details.
 115
 116 As with all database modification operations, the effect is atomic: the
 117 document(s) will either be fully replaced, or the document(s) fail to be
 118 replaced and an exception is thrown (possibly at a later time when commit is
 119 called or the database is closed).
 120
 121 =item add_spelling <word> <freqinc>
 122
 123 Add a word to the spelling dictionary.
 124
 125 If the word is already present, its frequency is increased.
 126
 127 Parameters:
 128     word     The word to add.
 129     freqinc  How much to increase its frequency by (default 1).
 130
 131 =item remove_spelling <word> <freqdec>
 132
 133 Remove a word from the spelling dictionary.
 134
 135 The word's frequency is decreased, and if would become zero or less
 136 then the word is removed completely.
 137
 138 Parameters:
 139     word     The word to remove.
 140     freqdec  How much to decrease its frequency by (default 1).
 141
 142 =item reopen
 143
 144 Re-open the database to ensure you are using the latest revision.
 145
 146 =item close
 147
 148 Close the database. This also implies a commit() unless a transaction is in
 149 progress.
 150
 151 =back
 152
 153 =head1 SEE ALSO
 154
 155 L<Xapian>,
 156 L<Xapian::Enquire>,
 157 L<Xapian::Database>
 158
 159 =cut
 160 1;