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 | |
40 | namespace 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 | */ |
56 | class 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 | */ |
479 | class 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. */ |
928 | const int DB_CREATE_OR_OPEN = 1; |
929 | /** Create a new database; fail if db exists. */ |
930 | const int DB_CREATE = 2; |
931 | /** Overwrite existing db; create if none exists. */ |
932 | const int DB_CREATE_OR_OVERWRITE = 3; |
933 | /** Open for read/write; fail if no db exists. */ |
934 | const int DB_OPEN = 4; |
935 | |
936 | } |
937 | |
938 | #endif /* XAPIAN_INCLUDED_DATABASE_H */ |
939 | |