One decision I decided to make is that BlitzDB will only support a BTREE index via TC’s B+Tree API in it’s first release. Ignoring BlitzDB for now, several people I’ve talked to about key/value data structures often ask why I love B+Tree so much when it’s faster to work with a hash table. Please don’t take it wrong, O(1) operations are beautiful and I love hash tables but stereotyping key/value structures to it is not. Everything has it’s ups and downs and hash table/map is not an exception. In this blog entry, I will describe why B+Tree is good for index scanning.

Why a B+Tree Index

A search algorithm of O(1) like hashing is clearly faster than O(log n) unless there’s something fishy about the implementation or the dataset is too small for the time complexity to matter. However, this is only true for looking up and fetching the value. For those that are only interested in fetching a particular value, that’s probably the best you can ask for. However things are different if you look into things beyond lookups like fetching or scanning through a range of keys.

To do this with a typical hash table, either your data structure must be able to provide a list of stored keys OR your application must do some housekeeping and save a list of relevant keys elsewhere for future use. Your application would then need to compute the subset of keys that you’re interested in and fetch them with a loop. Algorithmically speaking, each fetch operation is O(1) but what’s expensive here is that you end up doing a lot of random access. This is obviously going to kill your performance, especially when you need to chew through a heavy workload (though this _could_ change when SSD becomes standard).

B+Tree on the other hand is fantastic for this use-case. The actual data are stored at the leaf node and they are usually logically linked so that you don’t need to re-traverse the tree to get the next greater key (if you run out of relevant pages in the node, you move on to the neighbor leaf node). The pages are aligned on disk, which means sequential access. Another bonus is that most of the time, you can keep the entire internal nodes on memory which is small and inexpensive but effective for searching.

Solution to this? well, mine is to implement a combination play of the two data structures and take advantage of the different characteristics. In BlitzDB, the actual rows are stored in TC’s Hash Database and the index will store keys to the row. So, a clustered index.

What I’ve mentioned so far is all theoretical without providing any benchmark results but all I’m trying to say is, it’s all about access patterns and use-cases. My current interest is in index scan and therefore the decision. However, if there is enough people that asks me for a HASH index, I can write that functionality relatively easily later on :)

Next Stop

I would love to keep writing but it is currently past 3am in Japan and I’m dozing out here. Apologies for not covering Tokyo Cabinet’s in-depth concurrency model but I will cover it in my next post of the series and how this impacts BlitzDB’s design.

Well, the answer depends on which data structure you choose to construct a TC database. If you’re interested in TC’s hash database then you’re out of luck but TC’s B+Tree database will allow you to write duplicate keys. If you just want the answer, here’s a compilable source of how to do it. For those that are interested in how it works, keep on reading :)

So here’s how it’s done. You write the record(s) using TC’s tcbdbputdup() function so that upon key collision, TC will write the record next to the existing one. The following snippet will write three records to Tokyo Cabinet using an identical key.

const char *key = "key";
const char *r1 = "record 1";
const char *r2 = "record 2";
const char *r3 = "record 3";
 
/* store three different records with the same key.
   note that "database_handle" is a TCBDB object. */
if (!tcbdbputdup(database_handle, key, 3, r1, strlen(r1)) ||
    !tcbdbputdup(database_handle, key, 3, r2, strlen(r2)) ||
    !tcbdbputdup(database_handle, key, 3, r3, strlen(r3))) {
  fprintf(stderr, "failed to store data\n");
 
  if (!tcbdbclose(database_handle)) {
    fprintf(stderr, "failed to close the database\n");
    return 1;
  }   
  tcbdbdel(database_handle);
  return 1;
}

Something to watch out here is that because you’ve allowed duplication, running the above code multiple times will respectively keep appending the records to the database.

The next question is, how do we retrieve _only_ the records that corresponds to the key that we just inserted with. Simple! just traverse the tree from the first occurrence of the key and keep retrieving the data as we go until we hit a different key.

First thing that must be done is to create a cursor and move it to the first occurrence of the key.

BDBCUR *cursor;
 
if ((cursor = tcbdbcurnew(db)) == NULL) {
  /* FAIL. do the right thing for your application */ 
}
 
/* move the cursor to the first occurrence of the key */
if (!tcbdbcurjump(cursor, key, strlen(key))) {
  /* FAIL. do the right thing for your application */ 
}

Now we’re ready to traverse the tree. Remember that we’re only interested in a certain key so we only want to traverse the tree until we hit a different key. The following code snippet will do exactly that and print the discovered record as it traverses the tree. So in our case it would print, “record 1″, “record 2″ and “record 3″.

char *fetched_key;
char *fetched_value;
 
/* traverse the tree. terminates if the entire tree is
   traversed _OR_ if it hits a different key */
while (tcbdbcurkey2(cursor) != NULL) {
  fetched_key = tcbdbcurkey2(cursor);
 
  /* different key so break out of the loop */
  if (strcmp(key, fetched_key) != 0) {
    free(fetched_key);
    break;
  }
 
  fetched_value = tcbdbcurval2(cursor);
 
  if (fetched_value) {
    fprintf(stdout, "fetched: %s\n", fetched_value);
    free(fetched_value);
  }
  tcbdbcurnext(cursor);
}

The above tree traversal requires one additional lookup to terminate (if the entire tree isn’t traversed) but the chances are that the records are stored in the same page so this additional operation is cheap.

Alternatively, TC provides a function called tcbdbget4() which returns an allocated list of records that corresponds to the key you provide. If you decide to take this approach, you should consider whether the memory allocation cost and linked list construction overhead is feasible for your application or not.