How to Create a Data Subscription

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.
  const subscriptionName = await documentStore.subscriptions.create({
      query: "from Orders"
  });

• For more complex subscription creation scenarios, see the these examples.

• A subscription also can be modified after it has been created, see update existing subscription.

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).

const subscriptionName = await store.subscriptions.create({
    query: "from Orders",
    // Set a custom name for the subscription 
    name: "OrdersProcessingSubscription"
});

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:

const subscriptionName = await store.subscriptions.create({
    query: "from Orders",
    // Set a responsible node for the subscritpion 
    mentorNode: "D"
});

Manually setting the node can help choose a more suitable server based on factors such as resources, client proximity, or other considerations.