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 Olly Betts
7 : * Copyright 2006 Richard Boulton
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/types.h>
33 : #include <xapian/positioniterator.h>
34 : #include <xapian/postingiterator.h>
35 : #include <xapian/termiterator.h>
36 : #include <xapian/visibility.h>
37 :
38 : /// The Xapian library lives in the Xapian namespace.
39 : namespace Xapian {
40 :
41 : class Document;
42 :
43 : /** This class is used to access a database, or a group of databases.
44 : *
45 : * For searching, this class is used in conjunction with an Enquire object.
46 : *
47 : * @exception InvalidArgumentError will be thrown if an invalid
48 : * argument is supplied, for example, an unknown database type.
49 : *
50 : * @exception DatabaseOpeningError may be thrown if the database cannot
51 : * be opened (for example, a required file cannot be found).
52 : *
53 : * @exception DatabaseVersionError may be thrown if the database is in an
54 : * unsupported format (for example, created by a newer version of Xapian
55 : * which uses an incompatible format).
56 : */
57 : class XAPIAN_VISIBILITY_DEFAULT Database {
58 : public:
59 : class Internal;
60 : /// @private @internal Reference counted internals.
61 : std::vector<Xapian::Internal::RefCntPtr<Internal> > internal;
62 :
63 : /** Add an existing database (or group of databases) to those
64 : * accessed by this object.
65 : *
66 : * @param database the database(s) to add.
67 : */
68 : void add_database(const Database & database);
69 :
70 : /** Create a Database with no databases in.
71 : */
72 : Database();
73 :
74 : /** Open a Database, automatically determining the database
75 : * backend to use.
76 : *
77 : * @param path directory that the database is stored in.
78 : */
79 : explicit Database(const std::string &path);
80 :
81 : /** @private @internal Create a Database from its internals.
82 : */
83 : explicit Database(Internal *internal);
84 :
85 : /** Destroy this handle on the database.
86 : *
87 : * If there are no copies of this object remaining, the database(s)
88 : * will be closed.
89 : */
90 : virtual ~Database();
91 :
92 : /** Copying is allowed. The internals are reference counted, so
93 : * copying is cheap.
94 : */
95 : Database(const Database &other);
96 :
97 : /** Assignment is allowed. The internals are reference counted,
98 : * so assignment is cheap.
99 : */
100 : void operator=(const Database &other);
101 :
102 : /** Re-open the database.
103 : * This re-opens the database(s) to the latest available version(s).
104 : * It can be used either to make sure the latest results are
105 : * returned, or to recover from a Xapian::DatabaseModifiedError.
106 : */
107 : void reopen();
108 :
109 : /// Return a string describing this object.
110 : virtual std::string get_description() const;
111 :
112 : /** An iterator pointing to the start of the postlist
113 : * for a given term.
114 : *
115 : * If the term name is the empty string, the iterator returned
116 : * will list all the documents in the database. Such an iterator
117 : * will always return a WDF value of 1, since there is no obvious
118 : * meaning for this quantity in this case.
119 : */
120 : PostingIterator postlist_begin(const std::string &tname) const;
121 :
122 : /** Corresponding end iterator to postlist_begin().
123 : */
124 10 : PostingIterator postlist_end(const std::string &) const {
125 10 : return PostingIterator(NULL);
126 : }
127 :
128 : /** An iterator pointing to the start of the termlist
129 : * for a given document.
130 : */
131 : TermIterator termlist_begin(Xapian::docid did) const;
132 :
133 : /** Corresponding end iterator to termlist_begin().
134 : */
135 : TermIterator termlist_end(Xapian::docid) const {
136 : return TermIterator(NULL);
137 : }
138 :
139 : /** Does this database have any positional information? */
140 : bool has_positions() const;
141 :
142 : /** An iterator pointing to the start of the position list
143 : * for a given term in a given document.
144 : */
145 : PositionIterator positionlist_begin(Xapian::docid did, const std::string &tname) const;
146 :
147 : /** Corresponding end iterator to positionlist_begin().
148 : */
149 : PositionIterator positionlist_end(Xapian::docid, const std::string &) const {
150 : return PositionIterator(NULL);
151 : }
152 :
153 : /** An iterator which runs across all terms in the database.
154 : */
155 : TermIterator allterms_begin() const;
156 :
157 : /** Corresponding end iterator to allterms_begin().
158 : */
159 : TermIterator allterms_end() const {
160 : return TermIterator(NULL);
161 : }
162 :
163 : /** An iterator which runs across all terms with a given prefix.
164 : *
165 : * This is functionally similar to getting an iterator with
166 : * allterms_begin() and then calling skip_to(prefix) on that iterator
167 : * to move to the start of the prefix, but is more convenient (because
168 : * it detects the end of the prefixed terms), and may be more
169 : * efficient than simply calling skip_to() after opening the iterator,
170 : * particularly for network databases.
171 : *
172 : * @param prefix The prefix to restrict the returned terms to.
173 : */
174 : TermIterator allterms_begin(const std::string & prefix) const;
175 :
176 : /** Corresponding end iterator to allterms_begin(prefix).
177 : */
178 1 : TermIterator allterms_end(const std::string &) const {
179 1 : return TermIterator(NULL);
180 : }
181 :
182 : /// Get the number of documents in the database.
183 : Xapian::doccount get_doccount() const;
184 :
185 : /// Get the highest document id which has been used in the database.
186 : Xapian::docid get_lastdocid() const;
187 :
188 : /// Get the average length of the documents in the database.
189 : Xapian::doclength get_avlength() const;
190 :
191 : /// Get the number of documents in the database indexed by a given term.
192 : Xapian::doccount get_termfreq(const std::string & tname) const;
193 :
194 : /** Check if a given term exists in the database.
195 : *
196 : * Return true if and only if the term exists in the database.
197 : * This is the same as (get_termfreq(tname) != 0), but will often be
198 : * more efficient.
199 : */
200 : bool term_exists(const std::string & tname) const;
201 :
202 : /** Return the total number of occurrences of the given term.
203 : *
204 : * This is the sum of the number of occurrences of the term in each
205 : * document it indexes: i.e., the sum of the within document
206 : * frequencies of the term.
207 : *
208 : * @param tname The term whose collection frequency is being
209 : * requested.
210 : */
211 : Xapian::termcount get_collection_freq(const std::string & tname) const;
212 :
213 : /** Get the length of a document.
214 : */
215 : Xapian::doclength get_doclength(Xapian::docid did) const;
216 :
217 : /** Send a "keep-alive" to remote databases to stop them timing
218 : * out.
219 : */
220 : void keep_alive();
221 :
222 : /** Get a document from the database, given its document id.
223 : *
224 : * This method returns a Xapian::Document object which provides the
225 : * information about a document.
226 : *
227 : * @param did The document id for which to retrieve the data.
228 : *
229 : * @return A Xapian::Document object containing the document data
230 : *
231 : * @exception Xapian::DocNotFoundError The document specified
232 : * could not be found in the database.
233 : */
234 : Xapian::Document get_document(Xapian::docid did) const;
235 :
236 : /** Suggest a spelling correction.
237 : *
238 : * @param word The potentially misspelled word.
239 : * @param max_edit_distance Only consider words which are at most
240 : * @a max_edit_distance edits from @a word. An edit is a
241 : * character insertion, deletion, or the transposition of two
242 : * adjacent characters (default is 2).
243 : */
244 : std::string get_spelling_suggestion(const std::string &word,
245 : unsigned max_edit_distance = 2) const;
246 :
247 : /** An iterator which returns all the spelling correction targets.
248 : *
249 : * This returns all the words which are considered as targets for the
250 : * spelling correction algorithm. The frequency of each word is
251 : * available as the term frequency of each entry in the returned
252 : * iterator.
253 : */
254 : Xapian::TermIterator spellings_begin() const;
255 :
256 : /// Corresponding end iterator to spellings_begin().
257 : Xapian::TermIterator spellings_end() const {
258 : return Xapian::TermIterator(NULL);
259 : }
260 :
261 : /** An iterator which returns all the synonyms for a given term.
262 : *
263 : * @param term The term to return synonyms for.
264 : */
265 : Xapian::TermIterator synonyms_begin(const std::string &term) const;
266 :
267 : /// Corresponding end iterator to synonyms_begin(term).
268 : Xapian::TermIterator synonyms_end(const std::string &) const {
269 : return Xapian::TermIterator(NULL);
270 : }
271 :
272 : /** An iterator which returns all terms which have synonyms.
273 : *
274 : * @param prefix If non-empty, only terms with this prefix are
275 : * returned.
276 : */
277 : Xapian::TermIterator synonym_keys_begin(const std::string &prefix = "") const;
278 :
279 : /// Corresponding end iterator to synonym_keys_begin(prefix).
280 : Xapian::TermIterator synonym_keys_end(const std::string & = "") const {
281 : return Xapian::TermIterator(NULL);
282 : }
283 :
284 : /** Get the user-specified metadata associated with a given key.
285 : *
286 : * User-specified metadata allows you to store arbitrary information
287 : * in the form of (key,tag) pairs. See @a
288 : * WritableDatabase::set_metadata() for more information.
289 : *
290 : * When invoked on a Xapian::Database object representing multiple
291 : * databases, currently only the metadata for the first is considered
292 : * but this behaviour may change in the future.
293 : *
294 : * If there is no piece of metadata associated with the specified
295 : * key, an empty string is returned (this applies even for backends
296 : * which don't support metadata).
297 : *
298 : * Empty keys are not valid, and specifying one will cause an
299 : * exception.
300 : *
301 : * @param key The key of the metadata item to access.
302 : *
303 : * @return The retrieved metadata item's value.
304 : *
305 : * @exception Xapian::InvalidArgumentError will be thrown if the
306 : * key supplied is empty.
307 : *
308 : * @exception Xapian::UnimplementedError will be thrown if the
309 : * database backend in use doesn't support user-specified
310 : * metadata.
311 : */
312 : std::string get_metadata(const std::string & key) const;
313 : };
314 :
315 : /** This class provides read/write access to a database.
316 : */
317 : class XAPIAN_VISIBILITY_DEFAULT WritableDatabase : public Database {
318 : public:
319 : /** Destroy this handle on the database.
320 : *
321 : * If there are no copies of this object remaining, the database
322 : * will be closed. If there are any transactions in progress
323 : * these will be aborted as if cancel_transaction had been called.
324 : */
325 : virtual ~WritableDatabase();
326 :
327 : /** Create an empty WritableDatabase.
328 : */
329 : WritableDatabase();
330 :
331 : /** Open a database for update, automatically determining the database
332 : * backend to use.
333 : *
334 : * If the database is to be created, Xapian will try
335 : * to create the directory indicated by path if it doesn't already
336 : * exist (but only the leaf directory, not recursively).
337 : *
338 : * @param path directory that the database is stored in.
339 : * @param action one of:
340 : * - Xapian::DB_CREATE_OR_OPEN open for read/write; create if no db
341 : * exists
342 : * - Xapian::DB_CREATE create new database; fail if db exists
343 : * - Xapian::DB_CREATE_OR_OVERWRITE overwrite existing db; create if
344 : * none exists
345 : * - Xapian::DB_OPEN open for read/write; fail if no db exists
346 : */
347 : WritableDatabase(const std::string &path, int action);
348 :
349 : /** @private @internal Create an WritableDatabase given its internals.
350 : */
351 : explicit WritableDatabase(Database::Internal *internal);
352 :
353 : /** Copying is allowed. The internals are reference counted, so
354 : * copying is cheap.
355 : */
356 : WritableDatabase(const WritableDatabase &other);
357 :
358 : /** Assignment is allowed. The internals are reference counted,
359 : * so assignment is cheap.
360 : *
361 : * Note that only an WritableDatabase may be assigned to an
362 : * WritableDatabase: an attempt to assign a Database is caught
363 : * at compile-time.
364 : */
365 : void operator=(const WritableDatabase &other);
366 :
367 : /** Flush to disk any modifications made to the database.
368 : *
369 : * For efficiency reasons, when performing multiple updates to a
370 : * database it is best (indeed, almost essential) to make as many
371 : * modifications as memory will permit in a single pass through
372 : * the database. To ensure this, Xapian batches up modifications.
373 : *
374 : * Flush may be called at any time to
375 : * ensure that the modifications which have been made are written to
376 : * disk: if the flush succeeds, all the preceding modifications will
377 : * have been written to disk.
378 : *
379 : * If any of the modifications fail, an exception will be thrown and
380 : * the database will be left in a state in which each separate
381 : * addition, replacement or deletion operation has either been fully
382 : * performed or not performed at all: it is then up to the
383 : * application to work out which operations need to be repeated.
384 : *
385 : * It's not valid to call flush within a transaction.
386 : *
387 : * Beware of calling flush too frequently: this will have a severe
388 : * performance cost.
389 : *
390 : * Note that flush need not be called explicitly: it will be called
391 : * automatically when the database is closed, or when a sufficient
392 : * number of modifications have been made.
393 : *
394 : * @exception Xapian::DatabaseError will be thrown if a problem occurs
395 : * while modifying the database.
396 : *
397 : * @exception Xapian::DatabaseCorruptError will be thrown if the
398 : * database is in a corrupt state.
399 : *
400 : * @exception Xapian::DatabaseLockError will be thrown if a lock
401 : * couldn't be acquired on the database.
402 : */
403 : void flush();
404 :
405 : /** Begin a transaction.
406 : *
407 : * In Xapian a transaction is a group of modifications to the database
408 : * which are linked such that either all will be applied
409 : * simultaneously or none will be applied at all. Even in the case of
410 : * a power failure, this characteristic should be preserved (as long
411 : * as the filesystem isn't corrupted, etc).
412 : *
413 : * A transaction is started with begin_transaction() and can
414 : * either be committed by calling commit_transaction() or aborted
415 : * by calling cancel_transaction().
416 : *
417 : * By default, a transaction implicitly calls flush before and after
418 : * so that the modifications stand and fall without affecting
419 : * modifications before or after.
420 : *
421 : * The downside of this flushing is that small transactions cause
422 : * modifications to be frequently flushed which can harm indexing
423 : * performance in the same way that explicitly calling flush
424 : * frequently can.
425 : *
426 : * If you're applying atomic groups of changes and only wish to
427 : * ensure that each group is either applied or not applied, then
428 : * you can prevent the automatic flush before and after the
429 : * transaction by starting the transaction with
430 : * begin_transaction(false). However, if cancel_transaction is
431 : * called (or if commit_transaction isn't called before the
432 : * WritableDatabase object is destroyed) then any changes which
433 : * were pending before the transaction began will also be discarded.
434 : *
435 : * Transactions aren't currently supported by the InMemory backend.
436 : *
437 : * @exception Xapian::UnimplementedError will be thrown if transactions
438 : * are not available for this database type.
439 : *
440 : * @exception Xapian::InvalidOperationError will be thrown if this is
441 : * called at an invalid time, such as when a transaction
442 : * is already in progress.
443 : */
444 : void begin_transaction(bool flushed=true);
445 :
446 : /** Complete the transaction currently in progress.
447 : *
448 : * If this method completes successfully and this is a flushed
449 : * transaction, all the database modifications
450 : * made during the transaction will have been committed to the
451 : * database.
452 : *
453 : * If an error occurs, an exception will be thrown, and none of
454 : * the modifications made to the database during the transaction
455 : * will have been applied to the database.
456 : *
457 : * In all cases the transaction will no longer be in progress.
458 : *
459 : * @exception Xapian::DatabaseError will be thrown if a problem occurs
460 : * while modifying the database.
461 : *
462 : * @exception Xapian::DatabaseCorruptError will be thrown if the
463 : * database is in a corrupt state.
464 : *
465 : * @exception Xapian::InvalidOperationError will be thrown if a
466 : * transaction is not currently in progress.
467 : *
468 : * @exception Xapian::UnimplementedError will be thrown if transactions
469 : * are not available for this database type.
470 : */
471 : void commit_transaction();
472 :
473 : /** Abort the transaction currently in progress, discarding the
474 : * potential modifications made to the database.
475 : *
476 : * If an error occurs in this method, an exception will be thrown,
477 : * but the transaction will be cancelled anyway.
478 : *
479 : * @exception Xapian::DatabaseError will be thrown if a problem occurs
480 : * while modifying the database.
481 : *
482 : * @exception Xapian::DatabaseCorruptError will be thrown if the
483 : * database is in a corrupt state.
484 : *
485 : * @exception Xapian::InvalidOperationError will be thrown if a
486 : * transaction is not currently in progress.
487 : *
488 : * @exception Xapian::UnimplementedError will be thrown if transactions
489 : * are not available for this database type.
490 : */
491 : void cancel_transaction();
492 :
493 : /** Add a new document to the database.
494 : *
495 : * This method adds the specified document to the database,
496 : * returning a newly allocated document ID. Automatically allocated
497 : * document IDs come from a per-database monotonically increasing
498 : * counter, so IDs from deleted documents won't be reused.
499 : *
500 : * If you want to specify the document ID to be used, you should
501 : * call replace_document() instead.
502 : *
503 : * Note that changes to the database won't be immediately committed to
504 : * disk; see flush() for more details.
505 : *
506 : * As with all database modification operations, the effect is
507 : * atomic: the document will either be fully added, or the document
508 : * fails to be added and an exception is thrown (possibly at a
509 : * later time when flush is called or the database is closed).
510 : *
511 : * @param document The new document to be added.
512 : *
513 : * @return The document ID of the newly added document.
514 : *
515 : * @exception Xapian::DatabaseError will be thrown if a problem occurs
516 : * while writing to the database.
517 : *
518 : * @exception Xapian::DatabaseCorruptError will be thrown if the
519 : * database is in a corrupt state.
520 : */
521 : Xapian::docid add_document(const Xapian::Document & document);
522 :
523 : /** Delete a document from the database.
524 : *
525 : * This method removes the document with the specified document ID
526 : * from the database.
527 : *
528 : * Note that changes to the database won't be immediately committed to
529 : * disk; see flush() for more details.
530 : *
531 : * As with all database modification operations, the effect is
532 : * atomic: the document will either be fully removed, or the document
533 : * fails to be removed and an exception is thrown (possibly at a
534 : * later time when flush is called or the database is closed).
535 : *
536 : * @param did The document ID of the document to be removed.
537 : *
538 : * @exception Xapian::DatabaseError will be thrown if a problem occurs
539 : * while writing to the database.
540 : *
541 : * @exception Xapian::DatabaseCorruptError will be thrown if the
542 : * database is in a corrupt state.
543 : */
544 : void delete_document(Xapian::docid did);
545 :
546 : /** Delete any documents indexed by a term from the database.
547 : *
548 : * This method removes any documents indexed by the specified term
549 : * from the database.
550 : *
551 : * A major use is for convenience when UIDs from another system are
552 : * mapped to terms in Xapian, although this method has other uses
553 : * (for example, you could add a "deletion date" term to documents at
554 : * index time and use this method to delete all documents due for
555 : * deletion on a particular date).
556 : *
557 : * @param unique_term The term to remove references to.
558 : *
559 : * @exception Xapian::DatabaseError will be thrown if a problem occurs
560 : * while writing to the database.
561 : *
562 : * @exception Xapian::DatabaseCorruptError will be thrown if the
563 : * database is in a corrupt state.
564 : */
565 : void delete_document(const std::string & unique_term);
566 :
567 : /** Replace a given document in the database.
568 : *
569 : * This method replaces the document with the specified document ID.
570 : * If document ID @a did isn't currently used, the document will be
571 : * added with document ID @a did.
572 : *
573 : * The monotonic counter used for automatically allocating document
574 : * IDs is increased so that the next automatically allocated document
575 : * ID will be did + 1. Be aware that if you use this method to
576 : * specify a high document ID for a new document, and also use
577 : * WritableDatabase::add_document(), Xapian may get to a state where
578 : * this counter wraps around and will be unable to automatically
579 : * allocate document IDs!
580 : *
581 : * Note that changes to the database won't be immediately committed to
582 : * disk; see flush() for more details.
583 : *
584 : * As with all database modification operations, the effect is
585 : * atomic: the document will either be fully replaced, or the document
586 : * fails to be replaced and an exception is thrown (possibly at a
587 : * later time when flush is called or the database is closed).
588 : *
589 : * @param did The document ID of the document to be replaced.
590 : * @param document The new document.
591 : *
592 : * @exception Xapian::DatabaseError will be thrown if a problem occurs
593 : * while writing to the database.
594 : *
595 : * @exception Xapian::DatabaseCorruptError will be thrown if the
596 : * database is in a corrupt state.
597 : */
598 : void replace_document(Xapian::docid did,
599 : const Xapian::Document & document);
600 :
601 : /** Replace any documents matching a term.
602 : *
603 : * This method replaces any documents indexed by the specified term
604 : * with the specified document. If any documents are indexed by the
605 : * term, the lowest document ID will be used for the document,
606 : * otherwise a new document ID will be generated as for add_document.
607 : *
608 : * The intended use is to allow UIDs from another system to easily
609 : * be mapped to terms in Xapian, although this method probably has
610 : * other uses.
611 : *
612 : * Note that changes to the database won't be immediately committed to
613 : * disk; see flush() for more details.
614 : *
615 : * As with all database modification operations, the effect is
616 : * atomic: the document(s) will either be fully replaced, or the
617 : * document(s) fail to be replaced and an exception is thrown
618 : * (possibly at a
619 : * later time when flush is called or the database is closed).
620 : *
621 : * @param unique_term The "unique" term.
622 : * @param document The new document.
623 : *
624 : * @return The document ID that document was given.
625 : *
626 : * @exception Xapian::DatabaseError will be thrown if a problem occurs
627 : * while writing to the database.
628 : *
629 : * @exception Xapian::DatabaseCorruptError will be thrown if the
630 : * database is in a corrupt state.
631 : */
632 : Xapian::docid replace_document(const std::string & unique_term,
633 : const Xapian::Document & document);
634 :
635 : /** Add a word to the spelling dictionary.
636 : *
637 : * If the word is already present, its frequency is increased.
638 : *
639 : * @param word The word to add.
640 : * @param freqinc How much to increase its frequency by (default 1).
641 : */
642 : void add_spelling(const std::string & word,
643 : Xapian::termcount freqinc = 1) const;
644 :
645 : /** Remove a word from the spelling dictionary.
646 : *
647 : * The word's frequency is decreased, and if would become zero or less
648 : * then the word is removed completely.
649 : *
650 : * @param word The word to remove.
651 : * @param freqdec How much to decrease its frequency by (default 1).
652 : */
653 : void remove_spelling(const std::string & word,
654 : Xapian::termcount freqdec = 1) const;
655 :
656 : /** Add a synonym for a term.
657 : *
658 : * If @a synonym is already a synonym for @a term, then no action is
659 : * taken.
660 : */
661 : void add_synonym(const std::string & term,
662 : const std::string & synonym) const;
663 :
664 : /** Remove a synonym for a term.
665 : *
666 : * If @a synonym isn't a synonym for @a term, then no action is taken.
667 : */
668 : void remove_synonym(const std::string & term,
669 : const std::string & synonym) const;
670 :
671 : /** Remove all synonyms for a term.
672 : *
673 : * If @a term has no synonyms, no action is taken.
674 : */
675 : void clear_synonyms(const std::string & term) const;
676 :
677 : /** Set the user-specified metadata associated with a given key.
678 : *
679 : * This method sets the metadata value associated with a given key.
680 : * If there is already a metadata value stored in the database with
681 : * the same key, the old value is replaced. If you want to delete an
682 : * existing item of metadata, just set its value to the empty string.
683 : *
684 : * User-specified metadata allows you to store arbitrary information
685 : * in the form of (key,tag) pairs.
686 : *
687 : * There's no hard limit on the number of metadata items, or the size
688 : * of the metadata values. Metadata keys have a limited length, which
689 : * depends on the backend. We recommend limiting them to 200 bytes.
690 : * Empty keys are not valid, and specifying one will cause an
691 : * exception.
692 : *
693 : * Metadata modifications are committed to disk in the same way as
694 : * modifications to the documents in the database are: i.e.,
695 : * modifications are atomic, and won't be committed to disk
696 : * immediately (see flush() for more details). This allows metadata
697 : * to be used to link databases with versioned external resources
698 : * by storing the appropriate version number in a metadata item.
699 : *
700 : * You can also use the metadata to store arbitrary extra information
701 : * associated with terms, documents, or postings by encoding the
702 : * termname and/or document id into the metadata key.
703 : *
704 : * @param key The key of the metadata item to set.
705 : *
706 : * @param value The value of the metadata item to set.
707 : *
708 : * @exception Xapian::DatabaseError will be thrown if a problem occurs
709 : * while writing to the database.
710 : *
711 : * @exception Xapian::DatabaseCorruptError will be thrown if the
712 : * database is in a corrupt state.
713 : *
714 : * @exception Xapian::InvalidArgumentError will be thrown if the
715 : * key supplied is empty.
716 : */
717 : void set_metadata(const std::string & key, const std::string & value);
718 :
719 : /// Return a string describing this object.
720 : std::string get_description() const;
721 : };
722 :
723 : /** Open for read/write; create if no db exists. */
724 : const int DB_CREATE_OR_OPEN = 1;
725 : /** Create a new database; fail if db exists. */
726 : const int DB_CREATE = 2;
727 : /** Overwrite existing db; create if none exists. */
728 : const int DB_CREATE_OR_OVERWRITE = 3;
729 : /** Open for read/write; fail if no db exists. */
730 : const int DB_OPEN = 4;
731 : // Can't see any sensible use for this one
732 : // const int DB_OVERWRITE = XXX;
733 :
734 : }
735 :
736 : #endif /* XAPIAN_INCLUDED_DATABASE_H */
|