1/** \file database.h
2 * \brief API for working with Xapian databases
3 */
4/* Copyright 1999,2000,2001 BrightStation PLC
5 * Copyright 2002 Ananova Ltd
6 * Copyright 2002,2003,2004,2005,2006,2007,2008,2009,2011 Olly Betts
7 * Copyright 2006,2008 Lemur Consulting Ltd
8 *
9 * This program is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU General Public License as
11 * published by the Free Software Foundation; either version 2 of the
12 * License, or (at your option) any later version.
13 *
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with this program; if not, write to the Free Software
21 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301
22 * USA
23 */
24
25#ifndef XAPIAN_INCLUDED_DATABASE_H
26#define XAPIAN_INCLUDED_DATABASE_H
27
28#include <string>
29#include <vector>
30
31#include <xapian/base.h>
32#include <xapian/document.h>
33#include <xapian/types.h>
34#include <xapian/positioniterator.h>
35#include <xapian/postingiterator.h>
36#include <xapian/termiterator.h>
37#include <xapian/valueiterator.h>
38#include <xapian/visibility.h>
39
40namespace Xapian {
41
42/** This class is used to access a database, or a group of databases.
43 *
44 * For searching, this class is used in conjunction with an Enquire object.
45 *
46 * @exception InvalidArgumentError will be thrown if an invalid
47 * argument is supplied, for example, an unknown database type.
48 *
49 * @exception DatabaseOpeningError may be thrown if the database cannot
50 * be opened (for example, a required file cannot be found).
51 *
52 * @exception DatabaseVersionError may be thrown if the database is in an
53 * unsupported format (for example, created by a newer version of Xapian
54 * which uses an incompatible format).
55 */
56class XAPIAN_VISIBILITY_DEFAULT Database {
57 public:
58 class Internal;
59 /// @private @internal Reference counted internals.
60 std::vector<Xapian::Internal::RefCntPtr<Internal> > internal;
61
62 /** @private @internal Get a document from the database, but doesn't
63 * need to check if it exists.
64 *
65 * This method returns a Xapian::Document object which provides the
66 * information about a document. If the document doesn't exist,
67 * either a NULL pointer may be returned, or the returned object will
68 * throw DocNotFoundError when you try to access it.
69 *
70 * The caller should delete the returned object when it has finished
71 * with it.
72 *
73 * @param did The document id of the document to retrieve.
74 *
75 * @return Pointer to Document::Internal object.
76 */
77 Document::Internal * get_document_lazily(Xapian::docid did) const;
78
79 /** Add an existing database (or group of databases) to those
80 * accessed by this object.
81 *
82 * @param database the database(s) to add.
83 */
84 void add_database(const Database & database);
85
86 /** Create a Database with no databases in.
87 */
88 Database();
89
90 /** Open a Database, automatically determining the database
91 * backend to use.
92 *
93 * @param path directory that the database is stored in.
94 */
95 explicit Database(const std::string &path);
96
97 /** @private @internal Create a Database from its internals.
98 */
99 explicit Database(Internal *internal);
100
101 /** Destroy this handle on the database.
102 *
103 * If there are no copies of this object remaining, the database(s)
104 * will be closed.
105 */
106 virtual ~Database();
107
108 /** Copying is allowed. The internals are reference counted, so
109 * copying is cheap.
110 *
111 * @param other The object to copy.
112 */
113 Database(const Database &other);
114
115 /** Assignment is allowed. The internals are reference counted,
116 * so assignment is cheap.
117 *
118 * @param other The object to copy.
119 */
120 void operator=(const Database &other);
121
122 /** Re-open the database.
123 *
124 * This re-opens the database(s) to the latest available version(s).
125 * It can be used either to make sure the latest results are returned,
126 * or to recover from a Xapian::DatabaseModifiedError.
127 *
128 * Calling reopen() on a database which has been closed (with @a
129 * close()) will always raise a Xapian::DatabaseError.
130 */
131 void reopen();
132
133 /** Close the database.
134 *
135 * This closes the database and closes all its file handles.
136 *
137 * For a WritableDatabase, if a transaction is active it will be
138 * aborted, while if no transaction is active commit() will be
139 * implicitly called. Also the write lock is released.
140 *
141 * Closing a database cannot be undone - in particular, calling
142 * reopen() after close() will not reopen it, but will instead throw a
143 * Xapian::DatabaseError exception.
144 *
145 * Calling close() again on a database which has already been closed
146 * has no effect (and doesn't raise an exception).
147 *
148 * After close() has been called, calls to other methods of the
149 * database, and to methods of other objects associated with the
150 * database, will either:
151 *
152 * - behave exactly as they would have done if the database had not
153 * been closed (this can only happen if all the required data is
154 * cached)
155 *
156 * - raise a Xapian::DatabaseError exception indicating that the
157 * database is closed.
158 *
159 * The reason for this behaviour is that otherwise we'd have to check
160 * that the database is still open on every method call on every
161 * object associated with a Database, when in many cases they are
162 * working on data which has already been loaded and so they are able
163 * to just behave correctly.
164 *
165 * This method was added in Xapian 1.1.0.
166 */
167 virtual void close();
168
169 /// Return a string describing this object.
170 virtual std::string get_description() const;
171
172 /** An iterator pointing to the start of the postlist
173 * for a given term.
174 *
175 * @param tname The termname to iterate postings for. If the
176 * term name is the empty string, the iterator
177 * returned will list all the documents in the
178 * database. Such an iterator will always return
179 * a WDF value of 1, since there is no obvious
180 * meaning for this quantity in this case.
181 */
182 PostingIterator postlist_begin(const std::string &tname) const;
183
184 /** Corresponding end iterator to postlist_begin().
185 */
186 PostingIterator postlist_end(const std::string &) const {
187 return PostingIterator();
188 }
189
190 /** An iterator pointing to the start of the termlist
191 * for a given document.
192 *
193 * @param did The document id of the document to iterate terms for.
194 */
195 TermIterator termlist_begin(Xapian::docid did) const;
196
197 /** Corresponding end iterator to termlist_begin().
198 */
199 TermIterator termlist_end(Xapian::docid) const {
200 return TermIterator();
201 }
202
203 /** Does this database have any positional information? */
204 bool has_positions() const;
205
206 /** An iterator pointing to the start of the position list
207 * for a given term in a given document.
208 */
209 PositionIterator positionlist_begin(Xapian::docid did, const std::string &tname) const;
210
211 /** Corresponding end iterator to positionlist_begin().
212 */
213 PositionIterator positionlist_end(Xapian::docid, const std::string &) const {
214 return PositionIterator();
215 }
216
217 /** An iterator which runs across all terms in the database.
218 */
219 TermIterator allterms_begin() const;
220
221 /** Corresponding end iterator to allterms_begin().
222 */
223 TermIterator allterms_end() const {
224 return TermIterator();
225 }
226
227 /** An iterator which runs across all terms with a given prefix.
228 *
229 * This is functionally similar to getting an iterator with
230 * allterms_begin() and then calling skip_to(prefix) on that iterator
231 * to move to the start of the prefix, but is more convenient (because
232 * it detects the end of the prefixed terms), and may be more
233 * efficient than simply calling skip_to() after opening the iterator,
234 * particularly for remote databases.
235 *
236 * @param prefix The prefix to restrict the returned terms to.
237 */
238 TermIterator allterms_begin(const std::string & prefix) const;
239
240 /** Corresponding end iterator to allterms_begin(prefix).
241 */
242 TermIterator allterms_end(const std::string &) const {
243 return TermIterator();
244 }
245
246 /// Get the number of documents in the database.
247 Xapian::doccount get_doccount() const;
248
249 /// Get the highest document id which has been used in the database.
250 Xapian::docid get_lastdocid() const;
251
252 /// Get the average length of the documents in the database.
253 Xapian::doclength get_avlength() const;
254
255 /// Get the number of documents in the database indexed by a given term.
256 Xapian::doccount get_termfreq(const std::string & tname) const;
257
258 /** Check if a given term exists in the database.
259 *
260 * @param tname The term to test the existence of.
261 *
262 * @return true if and only if the term exists in the database.
263 * This is the same as (get_termfreq(tname) != 0), but
264 * will often be more efficient.
265 */
266 bool term_exists(const std::string & tname) const;
267
268 /** Return the total number of occurrences of the given term.
269 *
270 * This is the sum of the number of occurrences of the term in each
271 * document it indexes: i.e., the sum of the within document
272 * frequencies of the term.
273 *
274 * @param tname The term whose collection frequency is being
275 * requested.
276 */
277 Xapian::termcount get_collection_freq(const std::string & tname) const;
278
279 /** Return the frequency of a given value slot.
280 *
281 * This is the number of documents which have a (non-empty) value
282 * stored in the slot.
283 *
284 * @param slot The value slot to examine.
285 *
286 * @exception UnimplementedError The frequency of the value isn't
287 * available for this database type.
288 */
289 Xapian::doccount get_value_freq(Xapian::valueno slot) const;
290
291 /** Get a lower bound on the values stored in the given value slot.
292 *
293 * If there are no values stored in the given value slot, this will
294 * return an empty string.
295 *
296 * If the lower bound isn't available for the given database type,
297 * this will return the lowest possible bound - the empty string.
298 *
299 * @param slot The value slot to examine.
300 */
301 std::string get_value_lower_bound(Xapian::valueno slot) const;
302
303 /** Get an upper bound on the values stored in the given value slot.
304 *
305 * If there are no values stored in the given value slot, this will
306 * return an empty string.
307 *
308 * @param slot The value slot to examine.
309 *
310 * @exception UnimplementedError The upper bound of the values isn't
311 * available for this database type.
312 */
313 std::string get_value_upper_bound(Xapian::valueno slot) const;
314
315 /** Get a lower bound on the length of a document in this DB.
316 *
317 * This bound does not include any zero-length documents.
318 */
319 Xapian::termcount get_doclength_lower_bound() const;
320
321 /// Get an upper bound on the length of a document in this DB.
322 Xapian::termcount get_doclength_upper_bound() const;
323
324 /// Get an upper bound on the wdf of term @a term.
325 Xapian::termcount get_wdf_upper_bound(const std::string & term) const;
326
327 /// Return an iterator over the value in slot @a slot for each document.
328 ValueIterator valuestream_begin(Xapian::valueno slot) const;
329
330 /// Return end iterator corresponding to valuestream_begin().
331 ValueIteratorEnd_ valuestream_end(Xapian::valueno) const {
332 return ValueIteratorEnd_();
333 }
334
335 /// Get the length of a document.
336 Xapian::termcount get_doclength(Xapian::docid did) const;
337
338 /** Send a "keep-alive" to remote databases to stop them timing out.
339 *
340 * Has no effect on non-remote databases.
341 */
342 void keep_alive();
343
344 /** Get a document from the database, given its document id.
345 *
346 * This method returns a Xapian::Document object which provides the
347 * information about a document.
348 *
349 * @param did The document id of the document to retrieve.
350 *
351 * @return A Xapian::Document object containing the document data
352 *
353 * @exception Xapian::DocNotFoundError The document specified
354 * could not be found in the database.
355 *
356 * @exception Xapian::InvalidArgumentError did was 0, which is not
357 * a valid document id.
358 */
359 Xapian::Document get_document(Xapian::docid did) const;
360
361 /** Suggest a spelling correction.
362 *
363 * @param word The potentially misspelled word.
364 * @param max_edit_distance Only consider words which are at most
365 * @a max_edit_distance edits from @a word. An edit is a
366 * character insertion, deletion, or the transposition of two
367 * adjacent characters (default is 2).
368 */
369 std::string get_spelling_suggestion(const std::string &word,
370 unsigned max_edit_distance = 2) const;
371
372 /** An iterator which returns all the spelling correction targets.
373 *
374 * This returns all the words which are considered as targets for the
375 * spelling correction algorithm. The frequency of each word is
376 * available as the term frequency of each entry in the returned
377 * iterator.
378 */
379 Xapian::TermIterator spellings_begin() const;
380
381 /// Corresponding end iterator to spellings_begin().
382 Xapian::TermIterator spellings_end() const {
383 return Xapian::TermIterator();
384 }
385
386 /** An iterator which returns all the synonyms for a given term.
387 *
388 * @param term The term to return synonyms for.
389 */
390 Xapian::TermIterator synonyms_begin(const std::string &term) const;
391
392 /// Corresponding end iterator to synonyms_begin(term).
393 Xapian::TermIterator synonyms_end(const std::string &) const {
394 return Xapian::TermIterator();
395 }
396
397 /** An iterator which returns all terms which have synonyms.
398 *
399 * @param prefix If non-empty, only terms with this prefix are
400 * returned.
401 */
402 Xapian::TermIterator synonym_keys_begin(const std::string &prefix = std::string()) const;
403
404 /// Corresponding end iterator to synonym_keys_begin(prefix).
405 Xapian::TermIterator synonym_keys_end(const std::string & = std::string()) const {
406 return Xapian::TermIterator();
407 }
408
409 /** Get the user-specified metadata associated with a given key.
410 *
411 * User-specified metadata allows you to store arbitrary information
412 * in the form of (key,tag) pairs. See @a
413 * WritableDatabase::set_metadata() for more information.
414 *
415 * When invoked on a Xapian::Database object representing multiple
416 * databases, currently only the metadata for the first is considered
417 * but this behaviour may change in the future.
418 *
419 * If there is no piece of metadata associated with the specified
420 * key, an empty string is returned (this applies even for backends
421 * which don't support metadata).
422 *
423 * Empty keys are not valid, and specifying one will cause an
424 * exception.
425 *
426 * @param key The key of the metadata item to access.
427 *
428 * @return The retrieved metadata item's value.
429 *
430 * @exception Xapian::InvalidArgumentError will be thrown if the
431 * key supplied is empty.
432 */
433 std::string get_metadata(const std::string & key) const;
434
435 /** An iterator which returns all user-specified metadata keys.
436 *
437 * When invoked on a Xapian::Database object representing multiple
438 * databases, currently only the metadata for the first is considered
439 * but this behaviour may change in the future.
440 *
441 * If the backend doesn't support metadata, then this method returns
442 * an iterator which compares equal to that returned by
443 * metadata_keys_end().
444 *
445 * @param prefix If non-empty, only keys with this prefix are
446 * returned.
447 *
448 * @exception Xapian::UnimplementedError will be thrown if the
449 * backend implements user-specified metadata, but
450 * doesn't implement iterating its keys (currently
451 * this happens for the InMemory backend).
452 */
453 Xapian::TermIterator metadata_keys_begin(const std::string &prefix = std::string()) const;
454
455 /// Corresponding end iterator to metadata_keys_begin().
456 Xapian::TermIterator metadata_keys_end(const std::string & = std::string()) const {
457 return Xapian::TermIterator();
458 }
459
460 /** Get a UUID for the database.
461 *
462 * The UUID will persist for the lifetime of the database.
463 *
464 * Replicas (eg, made with the replication protocol, or by copying all
465 * the database files) will have the same UUID. However, copies (made
466 * with copydatabase, or xapian-compact) will have different UUIDs.
467 *
468 * If the backend does not support UUIDs or this database has no
469 * subdatabases, the UUID will be empty.
470 *
471 * If this database has multiple sub-databases, the UUID string will
472 * contain the UUIDs of all the sub-databases.
473 */
474 std::string get_uuid() const;
475};
476
477/** This class provides read/write access to a database.
478 */
479class XAPIAN_VISIBILITY_DEFAULT WritableDatabase : public Database {
480 public:
481 /** Destroy this handle on the database.
482 *
483 * If no other handles to this database remain, the database will be
484 * closed.
485 *
486 * If a transaction is active cancel_transaction() will be implicitly
487 * called; if no transaction is active commit() will be implicitly
488 * called, but any exception will be swallowed (because throwing
489 * exceptions in C++ destructors is problematic). If you aren't using
490 * transactions and want to know about any failure to commit changes,
491 * call commit() explicitly before the destructor gets called.
492 */
493 virtual ~WritableDatabase();
494
495 /** Create an empty WritableDatabase.
496 */
497 WritableDatabase();
498
499 /** Open a database for update, automatically determining the database
500 * backend to use.
501 *
502 * If the database is to be created, Xapian will try
503 * to create the directory indicated by path if it doesn't already
504 * exist (but only the leaf directory, not recursively).
505 *
506 * @param path directory that the database is stored in.
507 * @param action one of:
508 * - Xapian::DB_CREATE_OR_OPEN open for read/write; create if no db
509 * exists
510 * - Xapian::DB_CREATE create new database; fail if db exists
511 * - Xapian::DB_CREATE_OR_OVERWRITE overwrite existing db; create if
512 * none exists
513 * - Xapian::DB_OPEN open for read/write; fail if no db exists
514 *
515 * @exception Xapian::DatabaseCorruptError will be thrown if the
516 * database is in a corrupt state.
517 *
518 * @exception Xapian::DatabaseLockError will be thrown if a lock
519 * couldn't be acquired on the database.
520 */
521 WritableDatabase(const std::string &path, int action);
522
523 /** @private @internal Create an WritableDatabase given its internals.
524 */
525 explicit WritableDatabase(Database::Internal *internal);
526
527 /** Copying is allowed. The internals are reference counted, so
528 * copying is cheap.
529 *
530 * @param other The object to copy.
531 */
532 WritableDatabase(const WritableDatabase &other);
533
534 /** Assignment is allowed. The internals are reference counted,
535 * so assignment is cheap.
536 *
537 * Note that only an WritableDatabase may be assigned to an
538 * WritableDatabase: an attempt to assign a Database is caught
539 * at compile-time.
540 *
541 * @param other The object to copy.
542 */
543 void operator=(const WritableDatabase &other);
544
545 /** Commit any pending modifications made to the database.
546 *
547 * For efficiency reasons, when performing multiple updates to a
548 * database it is best (indeed, almost essential) to make as many
549 * modifications as memory will permit in a single pass through
550 * the database. To ensure this, Xapian batches up modifications.
551 *
552 * This method may be called at any time to commit any pending
553 * modifications to the database.
554 *
555 * If any of the modifications fail, an exception will be thrown and
556 * the database will be left in a state in which each separate
557 * addition, replacement or deletion operation has either been fully
558 * performed or not performed at all: it is then up to the
559 * application to work out which operations need to be repeated.
560 *
561 * It's not valid to call commit() within a transaction.
562 *
563 * Beware of calling commit() too frequently: this will make indexing
564 * take much longer.
565 *
566 * Note that commit() need not be called explicitly: it will be called
567 * automatically when the database is closed, or when a sufficient
568 * number of modifications have been made. By default, this is every
569 * 10000 documents added, deleted, or modified. This value is rather
570 * conservative, and if you have a machine with plenty of memory,
571 * you can improve indexing throughput dramatically by setting
572 * XAPIAN_FLUSH_THRESHOLD in the environment to a larger value.
573 *
574 * This method was new in Xapian 1.1.0 - in earlier versions it was
575 * called flush().
576 *
577 * @exception Xapian::DatabaseError will be thrown if a problem occurs
578 * while modifying the database.
579 *
580 * @exception Xapian::DatabaseCorruptError will be thrown if the
581 * database is in a corrupt state.
582 */
583 void commit();
584
585 /** Pre-1.1.0 name for commit().
586 *
587 * Use commit() instead in new code. This alias may be deprecated in
588 * the future.
589 */
590 void flush() { commit(); }
591
592 /** Begin a transaction.
593 *
594 * In Xapian a transaction is a group of modifications to the database
595 * which are linked such that either all will be applied
596 * simultaneously or none will be applied at all. Even in the case of
597 * a power failure, this characteristic should be preserved (as long
598 * as the filesystem isn't corrupted, etc).
599 *
600 * A transaction is started with begin_transaction() and can
601 * either be committed by calling commit_transaction() or aborted
602 * by calling cancel_transaction().
603 *
604 * By default, a transaction implicitly calls commit() before and
605 * after so that the modifications stand and fall without affecting
606 * modifications before or after.
607 *
608 * The downside of these implicit calls to commit() is that small
609 * transactions can harm indexing performance in the same way that
610 * explicitly calling commit() frequently can.
611 *
612 * If you're applying atomic groups of changes and only wish to
613 * ensure that each group is either applied or not applied, then
614 * you can prevent the automatic commit() before and after the
615 * transaction by starting the transaction with
616 * begin_transaction(false). However, if cancel_transaction is
617 * called (or if commit_transaction isn't called before the
618 * WritableDatabase object is destroyed) then any changes which
619 * were pending before the transaction began will also be discarded.
620 *
621 * Transactions aren't currently supported by the InMemory backend.
622 *
623 * @param flushed Is this a flushed transaction? By default
624 * transactions are "flushed", which means that
625 * committing a transaction will ensure those
626 * changes are permanently written to the
627 * database. By contrast, unflushed transactions
628 * only ensure that changes within the transaction
629 * are either all applied or all aren't.
630 *
631 * @exception Xapian::UnimplementedError will be thrown if transactions
632 * are not available for this database type.
633 *
634 * @exception Xapian::InvalidOperationError will be thrown if this is
635 * called at an invalid time, such as when a transaction
636 * is already in progress.
637 */
638 void begin_transaction(bool flushed=true);
639
640 /** Complete the transaction currently in progress.
641 *
642 * If this method completes successfully and this is a flushed
643 * transaction, all the database modifications
644 * made during the transaction will have been committed to the
645 * database.
646 *
647 * If an error occurs, an exception will be thrown, and none of
648 * the modifications made to the database during the transaction
649 * will have been applied to the database.
650 *
651 * In all cases the transaction will no longer be in progress.
652 *
653 * @exception Xapian::DatabaseError will be thrown if a problem occurs
654 * while modifying the database.
655 *
656 * @exception Xapian::DatabaseCorruptError will be thrown if the
657 * database is in a corrupt state.
658 *
659 * @exception Xapian::InvalidOperationError will be thrown if a
660 * transaction is not currently in progress.
661 *
662 * @exception Xapian::UnimplementedError will be thrown if transactions
663 * are not available for this database type.
664 */
665 void commit_transaction();
666
667 /** Abort the transaction currently in progress, discarding the
668 * pending modifications made to the database.
669 *
670 * If an error occurs in this method, an exception will be thrown,
671 * but the transaction will be cancelled anyway.
672 *
673 * @exception Xapian::DatabaseError will be thrown if a problem occurs
674 * while modifying the database.
675 *
676 * @exception Xapian::DatabaseCorruptError will be thrown if the
677 * database is in a corrupt state.
678 *
679 * @exception Xapian::InvalidOperationError will be thrown if a
680 * transaction is not currently in progress.
681 *
682 * @exception Xapian::UnimplementedError will be thrown if transactions
683 * are not available for this database type.
684 */
685 void cancel_transaction();
686
687 /** Add a new document to the database.
688 *
689 * This method adds the specified document to the database,
690 * returning a newly allocated document ID. Automatically allocated
691 * document IDs come from a per-database monotonically increasing
692 * counter, so IDs from deleted documents won't be reused.
693 *
694 * If you want to specify the document ID to be used, you should
695 * call replace_document() instead.
696 *
697 * Note that changes to the database won't be immediately committed to
698 * disk; see commit() for more details.
699 *
700 * As with all database modification operations, the effect is
701 * atomic: the document will either be fully added, or the document
702 * fails to be added and an exception is thrown (possibly at a
703 * later time when commit() is called or the database is closed).
704 *
705 * @param document The new document to be added.
706 *
707 * @return The document ID of the newly added document.
708 *
709 * @exception Xapian::DatabaseError will be thrown if a problem occurs
710 * while writing to the database.
711 *
712 * @exception Xapian::DatabaseCorruptError will be thrown if the
713 * database is in a corrupt state.
714 */
715 Xapian::docid add_document(const Xapian::Document & document);
716
717 /** Delete a document from the database.
718 *
719 * This method removes the document with the specified document ID
720 * from the database.
721 *
722 * Note that changes to the database won't be immediately committed to
723 * disk; see commit() for more details.
724 *
725 * As with all database modification operations, the effect is
726 * atomic: the document will either be fully removed, or the document
727 * fails to be removed and an exception is thrown (possibly at a
728 * later time when commit() is called or the database is closed).
729 *
730 * @param did The document ID of the document to be removed.
731 *
732 * @exception Xapian::DatabaseError will be thrown if a problem occurs
733 * while writing to the database.
734 *
735 * @exception Xapian::DatabaseCorruptError will be thrown if the
736 * database is in a corrupt state.
737 */
738 void delete_document(Xapian::docid did);
739
740 /** Delete any documents indexed by a term from the database.
741 *
742 * This method removes any documents indexed by the specified term
743 * from the database.
744 *
745 * A major use is for convenience when UIDs from another system are
746 * mapped to terms in Xapian, although this method has other uses
747 * (for example, you could add a "deletion date" term to documents at
748 * index time and use this method to delete all documents due for
749 * deletion on a particular date).
750 *
751 * @param unique_term The term to remove references to.
752 *
753 * @exception Xapian::DatabaseError will be thrown if a problem occurs
754 * while writing to the database.
755 *
756 * @exception Xapian::DatabaseCorruptError will be thrown if the
757 * database is in a corrupt state.
758 */
759 void delete_document(const std::string & unique_term);
760
761 /** Replace a given document in the database.
762 *
763 * This method replaces the document with the specified document ID.
764 * If document ID @a did isn't currently used, the document will be
765 * added with document ID @a did.
766 *
767 * The monotonic counter used for automatically allocating document
768 * IDs is increased so that the next automatically allocated document
769 * ID will be did + 1. Be aware that if you use this method to
770 * specify a high document ID for a new document, and also use
771 * WritableDatabase::add_document(), Xapian may get to a state where
772 * this counter wraps around and will be unable to automatically
773 * allocate document IDs!
774 *
775 * Note that changes to the database won't be immediately committed to
776 * disk; see commit() for more details.
777 *
778 * As with all database modification operations, the effect is
779 * atomic: the document will either be fully replaced, or the document
780 * fails to be replaced and an exception is thrown (possibly at a
781 * later time when commit() is called or the database is closed).
782 *
783 * @param did The document ID of the document to be replaced.
784 * @param document The new document.
785 *
786 * @exception Xapian::DatabaseError will be thrown if a problem occurs
787 * while writing to the database.
788 *
789 * @exception Xapian::DatabaseCorruptError will be thrown if the
790 * database is in a corrupt state.
791 */
792 void replace_document(Xapian::docid did,
793 const Xapian::Document & document);
794
795 /** Replace any documents matching a term.
796 *
797 * This method replaces any documents indexed by the specified term
798 * with the specified document. If any documents are indexed by the
799 * term, the lowest document ID will be used for the document,
800 * otherwise a new document ID will be generated as for add_document.
801 *
802 * One common use is to allow UIDs from another system to easily be
803 * mapped to terms in Xapian. Note that this method doesn't
804 * automatically add unique_term as a term, so you'll need to call
805 * document.add_term(unique_term) first when using replace_document()
806 * in this way.
807 *
808 * Note that changes to the database won't be immediately committed to
809 * disk; see commit() for more details.
810 *
811 * As with all database modification operations, the effect is
812 * atomic: the document(s) will either be fully replaced, or the
813 * document(s) fail to be replaced and an exception is thrown
814 * (possibly at a
815 * later time when commit() is called or the database is closed).
816 *
817 * @param unique_term The "unique" term.
818 * @param document The new document.
819 *
820 * @return The document ID that document was given.
821 *
822 * @exception Xapian::DatabaseError will be thrown if a problem occurs
823 * while writing to the database.
824 *
825 * @exception Xapian::DatabaseCorruptError will be thrown if the
826 * database is in a corrupt state.
827 */
828 Xapian::docid replace_document(const std::string & unique_term,
829 const Xapian::Document & document);
830
831 /** Add a word to the spelling dictionary.
832 *
833 * If the word is already present, its frequency is increased.
834 *
835 * @param word The word to add.
836 * @param freqinc How much to increase its frequency by (default 1).
837 */
838 void add_spelling(const std::string & word,
839 Xapian::termcount freqinc = 1) const;
840
841 /** Remove a word from the spelling dictionary.
842 *
843 * The word's frequency is decreased, and if would become zero or less
844 * then the word is removed completely.
845 *
846 * @param word The word to remove.
847 * @param freqdec How much to decrease its frequency by (default 1).
848 */
849 void remove_spelling(const std::string & word,
850 Xapian::termcount freqdec = 1) const;
851
852 /** Add a synonym for a term.
853 *
854 * @param term The term to add a synonym for.
855 * @param synonym The synonym to add. If this is already a
856 * synonym for @a term, then no action is taken.
857 */
858 void add_synonym(const std::string & term,
859 const std::string & synonym) const;
860
861 /** Remove a synonym for a term.
862 *
863 * @param term The term to remove a synonym for.
864 * @param synonym The synonym to remove. If this isn't currently
865 * a synonym for @a term, then no action is taken.
866 */
867 void remove_synonym(const std::string & term,
868 const std::string & synonym) const;
869
870 /** Remove all synonyms for a term.
871 *
872 * @param term The term to remove all synonyms for. If the
873 * term has no synonyms, no action is taken.
874 */
875 void clear_synonyms(const std::string & term) const;
876
877 /** Set the user-specified metadata associated with a given key.
878 *
879 * This method sets the metadata value associated with a given key.
880 * If there is already a metadata value stored in the database with
881 * the same key, the old value is replaced. If you want to delete an
882 * existing item of metadata, just set its value to the empty string.
883 *
884 * User-specified metadata allows you to store arbitrary information
885 * in the form of (key,tag) pairs.
886 *
887 * There's no hard limit on the number of metadata items, or the size
888 * of the metadata values. Metadata keys have a limited length, which
889 * depends on the backend. We recommend limiting them to 200 bytes.
890 * Empty keys are not valid, and specifying one will cause an
891 * exception.
892 *
893 * Metadata modifications are committed to disk in the same way as
894 * modifications to the documents in the database are: i.e.,
895 * modifications are atomic, and won't be committed to disk
896 * immediately (see commit() for more details). This allows metadata
897 * to be used to link databases with versioned external resources
898 * by storing the appropriate version number in a metadata item.
899 *
900 * You can also use the metadata to store arbitrary extra information
901 * associated with terms, documents, or postings by encoding the
902 * termname and/or document id into the metadata key.
903 *
904 * @param key The key of the metadata item to set.
905 *
906 * @param value The value of the metadata item to set.
907 *
908 * @exception Xapian::DatabaseError will be thrown if a problem occurs
909 * while writing to the database.
910 *
911 * @exception Xapian::DatabaseCorruptError will be thrown if the
912 * database is in a corrupt state.
913 *
914 * @exception Xapian::InvalidArgumentError will be thrown if the
915 * key supplied is empty.
916 *
917 * @exception Xapian::UnimplementedError will be thrown if the
918 * database backend in use doesn't support user-specified
919 * metadata.
920 */
921 void set_metadata(const std::string & key, const std::string & value);
922
923 /// Return a string describing this object.
924 std::string get_description() const;
925};
926
927/** Open for read/write; create if no db exists. */
928const int DB_CREATE_OR_OPEN = 1;
929/** Create a new database; fail if db exists. */
930const int DB_CREATE = 2;
931/** Overwrite existing db; create if none exists. */
932const int DB_CREATE_OR_OVERWRITE = 3;
933/** Open for read/write; fail if no db exists. */
934const int DB_OPEN = 4;
935
936}
937
938#endif /* XAPIAN_INCLUDED_DATABASE_H */
939