Data Subscriptions: How to Create a Data Subscription


Subscriptions are created by performing a request to the server with certain subscription creations parameters, see Creation API summary.
Once created, it's definition and progress will be stored on the cluster, and not in a single server.
Upon subscription creation, the cluster will choose a preferred node that will run the subscription (unless client has stated a mentor node).
From that point and on, clients that will connect to a server in order to consume the subscription will be redirected to the node mentioned above.

In this page:

Subscription creation prerequisites
Subscription name
Responsible node


Subscription creation prerequisites

Data subscription is a batch processing mechanism, that send the clients documents that answer a specific criteria.
In order to create a data subscription, we first need to define the criteria. The minimum is to provide the collection to which the data subscription belongs. However, the criteria can be a complex RQL-like expression defining JavaScript functions for the filtering and the projections. See a simple example:

name = store.subscriptions().create(Order.class);

Fore more complex usage examples see examples

Subscription name

Another important, but not mandatory subscription property is its name:

SubscriptionCreationOptions options = new SubscriptionCreationOptions();
options.setName("OrdersProcessingSubscription");
name = store.subscriptions().create(Order.class, options);

In order to consume a data subscription, a subscription name is required to identify it.
By default, the server can generate a subscription name by its own, but it's also possible to pass a custom name. A dedicated name can be useful for use cases like dedicated, long running batch processing mechanisms, where it'll be more comfortable to use a human readable name in the code and even use the same name between different environments (as long as subscription creation is taken care of up front).

Uniqueness

Note that subscription name is unique and it will not be possible to create two subscriptions with the same name in the same database.

Responsible node

As stated above, upon creation, the cluster will choose a node that will be responsible for the data subscription server side processing. Once chosen, that node will be the node that will the only node to process the subscription. There is an enterprise license level feature that support subscription (and any other ongoing task) failover between nodes, but eventually, as long as the originally assigned node is online, it will be the one to process the data subscription.
Nevertheless, there is an option to manually decide the node that will be responsible for the subscription processing, it's called the MentorNode:

SubscriptionCreationOptions options = new SubscriptionCreationOptions();
options.setMentorNode("D");
name = store.subscriptions().create(Order.class, options);

The mentor node receives the responsible node tag, as can be seen in the subscription topology.
Setting that node manually can help manually choosing a more fitting server from resources, client proximity or any other point of view.