Ayende @ Rahien

My name is Oren Eini
Founder of Hibernating Rhinos LTD and RavenDB.
You can reach me by phone or email:


+972 52-548-6969

, @ Q c

Posts: 6,026 | Comments: 44,844

filter by tags archive

RavenDB – The great simplification

time to read 2 min | 313 words

There is always a tension between giving users an interface that is simple to use and giving them something that is powerful.

With RavenDB, we run into a problem with the session interface. I mean, just take a look…


Look how many operations you can do here! Yes, it is powerful, but it is also very complex to talk about & explain. For that matter, look at the interface:


We have 4(!) different ways of querying (actually, we have more, but that is beside the point).

Something had to be done, but we didn’t want to lose any power. So we decided on the following method:


Basically, we grouped all the common methods into a super simple session interface. This means that when you need to use the session, you see only:


4 of those methods (Equals, GetHashCode, GetType, ToString) are from System.Object and one is from IDisposable. Users pretty much are going to not see those methods.  The CRUD interface is there, as well as the starting point for querying. And that is it.

I think that it makes it very easy to get started with RavenDB. And all those operations that are important but uncommonly used are still there, they just require an explicit step to access them.



Good technique. Few people know how to design APIs these days.

Matt Warren

Addy: if you use that attribute you won't see the method at all. The technique outlined in the post just "hides" the methods that aren't applicable for most users by making them type "session.Advanced" before they can see all the rest of the functions.

Cory Foy

@Matt - Actually, you can use that to specify "Advanced" properties which are only shown if you check the "Show Advanced Members" option for Intellisense. Not that I'd recommend it.

@Ayende - I'm unsure about this. I mean, I love the simplification effort. But having Advanced as an option seems not right. Seems like that's only a problem because we are using the var keyword, so we can't be specific to Intellisense.

For example, if you simply had the class implement both Interfaces, and you were being intentional in the code, you'd get something like:

IDocumentSession session = //whatever

So when I typed session <dot I'd only see those. If I wanted the advanced methods, I'd use the advanced interface.

But like I said, I'm not really sure. I'm intrigued, and kudos for working to make things simpler!

Alex Vilela

Very interesting idea, thanks.

Would you expect a scenario where you would like to have an advancedSession instance and want to have access to all methods?

Ayende Rahien


I agree that we could do it using different interfaces, sure.

But the var keyword exists, and widely used.

Ayende Rahien


You already can access all the methods.

Frans Bouma

Clever :)

I wonder how you can pull this off with released code out there already? Wouldn't this change break everything?

Ayende Rahien


Yes, it does breaks everything.

BUT, this isn't a problem for me right now, because the change is minor in terms of the code changes required.

Frans Bouma

I meant: for the user of RavenDB: their code using the session with all the methods now has to be refactored all of a sudden when they use a later build.

(not sure if that's a given / expected anyway)

Ayende Rahien


Yes, it is something that the user would need to do, but I think that this is an acceptable pain consider the work required and the benefits given from that.

Comment preview

Comments have been closed on this topic.


No future posts left, oh my!


  1. Technical observations from my wife (3):
    13 Nov 2015 - Production issues
  2. Production postmortem (13):
    13 Nov 2015 - The case of the “it is slow on that machine (only)”
  3. Speaking (5):
    09 Nov 2015 - Community talk in Kiev, Ukraine–What does it take to be a good developer
  4. Find the bug (5):
    11 Sep 2015 - The concurrent memory buster
  5. Buffer allocation strategies (3):
    09 Sep 2015 - Bad usage patterns
View all series


Main feed Feed Stats
Comments feed   Comments Feed Stats