Subscriptions in RavenDB allow you to build persistent queries, batch operations and respond immediately to changes in your data. You can read more about them in this post, and I have dedicated a full chapter to discussing them in the book.

In RavenDB 4.1 we improved subscription support by adding the ability to include related documents directly as part of the subscription. Consider the following subscription:

The output of this subscription is going to be orders where the geographical coordinates of the subscriptions are not known. We use that to enrich the data by adding the missing location data from the shipping address. This is important for features such as spatial searches, planning deliveries, etc.  For the purpose of this post, we’ll assume that we accept user’s addresses, which do not have spatial information on them and we use a background process to fill them in.

On the one hand, we do want to add the location data as soon as possible but on the other hand, we want to avoid making too many address resolution requests, to avoid having to pay for them. Here is what we come up with to resolve this.

You can see that there are a bunch of interesting things in this code:

• We can access the related company on the order using Load, and it will not trigger any network call.
• If the company already has this address, we can use the known location, without having to make an expensive geo-location call.
• If the company doesn’t have an address, we’ll fill this in for the next run.
• If the company’s address doesn’t have location, only then we’ll make a remote call to get the actual location data.
• We don’t call Store() anywhere, because we are using the session instance from the batch, when we call SaveChanges(), all the changes to the loaded documents (either orders or companies) will be saved as a single transaction.
• Because we update the Location field on the order, we won’t be called again with the updated order, since the subscription filters this.

All in all, this is a pretty neat way to handle the scenario in a very efficient manner.