How to create a data subscription?

In order to create a data subscription you have to specify the criteria that documents must match to be incorporated into subscription results. Note there are two types of criteria you can pass into Create method:

long Create(SubscriptionCriteria criteria, string database = null);

long Create<T>(SubscriptionCriteria<T> criteria, string database = null);

The first one is SubscriptionCriteria, where you can specify the following filters:

• KeyStartsWith - a document id must starts with a specified prefix,
• BelongsToAnyCollection - list of collections that the subscription deals with,
• PropertiesMatch - dictionary of field names and related values that a document must have,
• PropertiesNotMatch - dictionary of field names and related values that a document must not have,
• StartEtag - an etag of a document which a subscription is going to consider as already acknowledged and start processing docs with higher etags.

The second one is generic SubscriptionCriteria<T> where T is an entity type. Analogously you can set:

• KeyStartsWith,
• PropertiesMatch,
• PropertiesNotMatch,
• StartEtag

BelongsToAnyCollection will be automatically filled in by a single value based on the entity type (see FindTypeTagName convention).

Additionally the criteria object has StartEtag property which sets the etag of the first document that the subscription starts from (in large databases can be used to skip documents that you already know they won't match the given criteria).

The execution of Create method will create a data subscription in a database and return its identifier (you can see Raven/Subscriptions/[id] documents in the database). This identifier is needed to open the subscription so you need to keep that information to be able to make use of it later.

Example I

var id = store.Subscriptions.Create(new SubscriptionCriteria
{
	KeyStartsWith = "employees/",
	PropertiesNotMatch = new Dictionary<string, RavenJToken>()
	{
		{ "Address.City", "Seattle" }
	}
});

In this case we want to get all documents that id starts with employees/ but does not contain Address.City field with value Seattle. Note that although we specified employees/ prefix id it doesn't mean we will get documents belonging to the same collection. It can return a developer (employees/developers/1) as well as a manager (employees/managers/1), anyhow we can be sure that none of them is living in Seattle.

Example II

var id = store.Subscriptions.Create(new SubscriptionCriteria<Order>()
{
	PropertiesMatch = new Dictionary<Expression<Func<Order, object>>, RavenJToken>()
	{
		{ x => x.Employee, "employees/1"}
	}
});

In this case, it will give us all the orders, but only those which are handled by employees/1 employee. Here we used generic type criteria, so we can specify properties filtering in strongly typed way. Also we can be sure that all returned documents belong to Orders collection (so we will be able to open the strongly typed subscription).