Data Subscriptions

In this post, I’m going to share with you one of the RavenDB 4 features that I like the most: Data Subscriptions.

Data Subscriptions?

It’s simpler to explain this concept with an example. Consider the following query:

from Orders 
where Lines.length > 5

This would retrieve all the big orders from your database. But, what if a new big order is added after you run this query. What if you want to be notified whenever a big order occurs? YEAH! THIS IS WHAT I WAS TALKING ABOUT.

Creating a Data Subscription

I assume that, at this point, you know how to open the Studio and the Northwind database. If this is not the case, I would recommend you to read this post where I teach you, step-by-step, the basics.

Do that! I will wait…

Done?!

To create a Data Subscription, you need to open the Settings section of your database, click on the Manage Ongoing Tasks option, then click on the Add Task button.

Then, click on Subscription. RavenDB will ask you a Task Name (let’s call it Big Orders) and a query. In this demo, I will provide the very same query we used before.

The user interface allows me to do a test before save (I did it!).

Subscribing the Data Subscription

Now, I will show you how to subscribe and consume a data subscription.

• Data subscriptions are consumed by clients, called subscription workers.
• In any given moment, only one worker can be connected to a data subscription.
• A worker connected to a data subscription receives a batch of documents and gets to process it.
• When it’s done (depends on the code that the client gave the worker, can take from seconds to hours), it informs the server about the progress and the server is ready to send the next batch.

Subscriptions are consumed by processing batches of documents received from the server.

static void Main(string[] args)
{
    var subscriptionWorker = DocumentStoreHolder.Store
        .Subscriptions
        .GetSubscriptionWorker("Big Orders");

    var subscriptionRuntimeTask = subscriptionWorker.Run(batch =>
    {
        foreach (var order in batch.Items)
        {
            // business logic here.
            Console.WriteLine(order.Id);
        }
    });

    WriteLine("Press any key to exit...");
    ReadKey();
}

How do Data Subscriptions work?

There are some important facts that you need to know to use this feature correctly.

• Documents that match pre-defined criteria are sent in batches from the server to the clients
• The client sends an acknowledgment to the server once it is done with processing the batch.
• The server keeps track of the latest document that was acknowledged by the client so that processing can be continued from the latest acknowledged position if it was paused or interrupted.

It’s time to action

Pretty exciting feature. Am I right? So, please, share the scenarios where you would like to use it. I would be glad to help you if you need.