How to Create a Data Subscription
-
A subscription task can be created in two ways:
- From the client API:
The client can create a subscription task on the server using this creation API. - From the Studio:
See creating subscription task to learn how to create a subscription task on the server via the Studio.
- From the client API:
-
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
Data subscription is a batch processing mechanism that sends documents that meet specific criteria to connected clients.
In order to create a data subscription, we first need to define the criteria.
The basic requirement is to specify the collection from which the subscription will retrieve documents.
However, the criteria can be a complex RQL-like expression defining JavaScript functions that filter documents and project their content.
- The following is a simple subscription definition:
// With the following subscription definition, the server will send ALL documents
// from the 'Orders' collection to a client that connects to this subscription.
name = store.subscriptions().create(Order.class);
- For more complex subscription definitions, see these examples.
Subscription name
In order to consume a data subscription, a subscription name is required to identify it.
If you don't specify a name when creating the subscription, the server will automatically generate a default name.
However, you have the option to provide a custom name for the subscription.
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 upfront).
SubscriptionCreationOptions options = new SubscriptionCreationOptions();
options.setName("OrdersProcessingSubscription");
name = store.subscriptions().create(Order.class, options);
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 managing the subscription task on the server-side. Once chosen, that node will be the only node to manage the subscription.
There is an enterprise license level feature that supports 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 manage the data subscription task.
Nevertheless, there is an option to manually decide which node will be responsible for managing the subscription task.
Provide the tag of the node you wish to be responsible in the MentorNode
property as follows:
SubscriptionCreationOptions options = new SubscriptionCreationOptions();
options.setMentorNode("D");
name = store.subscriptions().create(Order.class, options);
Manually setting the node can help choose a more suitable server based on factors such as resources, client proximity, or other considerations.