Case in point, let us look at the new referenced document indexing, which allows you to index data from a related document, and have RavenDB automatically keep it up to date. This was a feature that was requested quite often. Implementing that was complex, but straightforward. We now track what are the documents are referenced by each document, and we know how to force reindexing of a document if a document it was referencing was changed.

So far, so good. It was actually quite easy for us to force re-indexing, all we had to do was to force the referencing document etag to change, and the indexing code would pick it up and re-index that. Simple & easy.

Except… we use Etags for a lot more than just indexing. For example, we use etags for replication.

Now, imagine, if you will, two nodes setup as master/master. Both nodes have an index that uses LoadDocument to refer to another document.

We are now in a stable state, both nodes have all documents.  We modify a document, which causes that document to be replicated to the second node. That trigger (on both servers) re-indexing of the referencing document.  And that, in turn, would cause both servers to want to replicate the new “change” to the other one. What is worse, RavenDB is smart enough to detect that isn’t a conflict, so what we actually get is an infinite distributed loop.

Or, another case, pre fetching. As you probably know, an important optimization in RavenDB is the ability to prefetch documents from disk and not have to wait for them. We even augment that by putting incoming documents directly into the prefetching queue, never needing to hit the disk throughout the process.

Except that when we designed prefetching, there was never the idea of a having holes in the middle. But touching a document (updating its etag), causes just that. Let us assume that we have three documents (items/1, items/2, items/3).

We are saving items/1 and items/3 as part of our standard work. items/1 is being referenced by items/2. That means that on disk, we would have the following etags: (4 – items/1, 5 – items/2, 6 – items/3). However, the prefetching queue will have just (4 – items/1, 6 - items/3). This is a hole, and we didn’t use to have those (we might have gaps, but there were never any documents in those gaps). So we had to re-write the prefeteching behavior to accommodate that (along the way, we made it much better, but still).

Then there were issues relating to optimizations, it turned out that allowing a lot of holes was also not a good idea, so we changed our etag implementation to reduce the chance of holes, and…

It is interesting work, but it can be quite a hurdle when we want to do a new feature.

And then there are the really tough questions. When we load another document during the indexing of another document, what operation should we pass to the read trigger that decide if we can or cannot see this index? Is it Index operation, which means that you won’t be able to load versioned documents? Or is it Load documents, which would allow us to read versioned documents, but bring the question of how to deal with this situation? Add a new option? And make each read trigger chose its own behavior?

It is a sign of maturity, and I really like the RavenDB codebase, but it is increasing in complexity.