lib: Document the metadata stored within the Xapian database.

[notmuch] / lib / database.cc

diff --git a/lib/database.cc b/lib/database.cc
index 2511caec7a8623e36c20ba92d32613f28f662ae7..415b0d77c3439abb9165d8236c5106d3f1cfffee 100644 (file)
--- a/lib/database.cc
+++ b/lib/database.cc
@@ -44,7 +44,8 @@ typedef struct {
 
 /* Here's the current schema for our database (for NOTMUCH_DATABASE_VERSION):
  *
- * We currently have two different types of documents: mail and directory.
+ * We currently have two different types of documents (mail and
+ * directory) and also some metadata.
  *
  * Mail document
  * -------------
@@ -118,6 +119,49 @@ typedef struct {
  *
  * The data portion of a directory document contains the path of the
  * directory (relative to the database path).
+ *
+ * Database metadata
+ * -----------------
+ * Xapian allows us to store arbitrary name-value pairs as
+ * "metadata". We currently use the following metadata names with the
+ * given meanings:
+ *
+ *     version         The database schema version, (which is distinct
+ *                     from both the notmuch package version (see
+ *                     notmuch --version) and the libnotmuch library
+ *                     version. The version is stored as an base-10
+ *                     ASCII integer. The initial database version
+ *                     was 1, (though a schema existed before that
+ *                     were no "version" database value existed at
+ *                     all). Succesive versions are allocated as
+ *                     changes are made to the database (such as by
+ *                     indexing new fields).
+ *
+ *     last_thread_id  The last thread ID generated. This is stored
+ *                     as a 16-byte hexadecimal ASCII representation
+ *                     of a 64-bit unsigned integer. The first ID
+ *                     generated is 1 and the value will be
+ *                     incremented for each thread ID.
+ *
+ *     thread_id_*     A pre-allocated thread ID for a particular
+ *                     message. This is actually an arbitarily large
+ *                     family of metadata name. Any particular name
+ *                     is formed by concatenating "thread_id_" with a
+ *                     message ID. The value stored is a thread ID.
+ *
+ *                     These thread ID metadata values are stored
+ *                     whenever a message references a parent message
+ *                     that does not yet exist in the database. A
+ *                     thread ID will be allocated and stored, and if
+ *                     the message is later added, the stored thread
+ *                     ID will be used (and the metadata value will
+ *                     be cleared).
+ *
+ *                     Even before a message is added, it's
+ *                     pre-allocated thread ID is useful so that all
+ *                     descendant messages that reference this common
+ *                     parent can be recognized as belonging to the
+ *                     same thread.
  */
 
 /* With these prefix values we follow the conventions published here:
@@ -1376,17 +1420,27 @@ _notmuch_database_link_message (notmuch_database_t *notmuch,
                                notmuch_message_file_t *message_file)
 {
     notmuch_status_t status;
-    const char *thread_id = NULL;
-    char *metadata_key = _get_metadata_thread_id_key (message,
-            notmuch_message_get_message_id (message));
+    const char *message_id, *thread_id = NULL;
+    char *metadata_key;
+    string stored_id;
+
+    message_id = notmuch_message_get_message_id (message);
+    metadata_key = _get_metadata_thread_id_key (message, message_id);
+
     /* Check if we have already seen related messages to this one.
      * If we have then use the thread_id that we stored at that time.
      */
-    string stored_id = notmuch->xapian_db->get_metadata (metadata_key);
-    if (!stored_id.empty()) {
-        Xapian::WritableDatabase *db = static_cast <Xapian::WritableDatabase *> (notmuch->xapian_db);
+    stored_id = notmuch->xapian_db->get_metadata (metadata_key);
+    if (! stored_id.empty()) {
+        Xapian::WritableDatabase *db;
+
+       db = static_cast <Xapian::WritableDatabase *> (notmuch->xapian_db);
+
+       /* Clear the metadata for this message ID. We don't need it
+        * anymore. */
         db->set_metadata (metadata_key, "");
         thread_id = stored_id.c_str();
+
         _notmuch_message_add_term (message, "thread", thread_id);
     }
     talloc_free (metadata_key);