Create and Update Subscription API

• In this page:
  • Create subscription
  • SubscriptionCreationOptions<T>
  • SubscriptionCreationOptions
  • Update subscription
  • SubscriptionUpdateOptions
  • Subscription query

Create subscription

Subscriptions can be created using the following Create methods available through the Subscriptions property of the DocumentStore.

string Create(SubscriptionCreationOptions options,
            string database = null);

string Create<T>(SubscriptionCreationOptions options = null,
               string database = null);

string Create<T>(SubscriptionCreationOptions<T> options,
               string database = null);

string Create<T>(Expression<Func<T, bool>> predicate = null,
               PredicateSubscriptionCreationOptions options = null,
               string database = null);

Task<string> CreateAsync(SubscriptionCreationOptions options,
                       string database = null,
                       CancellationToken token = default);

public Task<string> CreateAsync<T>(SubscriptionCreationOptions options = null,
                                 string database = null,
                                 CancellationToken token = default);

Task<string> CreateAsync<T>(SubscriptionCreationOptions<T> options,
                          string database = null,
                          CancellationToken token = default);

Task<string> CreateAsync<T>(Expression<Func<T, bool>> predicate = null,
                          PredicateSubscriptionCreationOptions options = null,
                          string database = null,
                          CancellationToken token = default);

Parameter	Type	Description
predicate	Expression<Func<T, bool>>	An optional lambda expression that returns a boolean. This predicate defines the filter criteria for the subscription documents.
options	SubscriptionCreationOptions<T>	Contains subscription creation options. See SubscriptionCreationOptions<T>
options	SubscriptionCreationOptions	Contains subscription creation options - non-generic version. See SubscriptionCreationOptions
database	string	The name of the database where the subscription task will be created. If null, the default database configured in the DocumentStore will be used.
token	CancellationToken	Cancellation token used in to halt the subscription creation process.

Return value	Description
string	The name of the created data subscription. If the name was provided in SubscriptionCreationOptions, it will be returned. Otherwise, a unique name will be generated by server.

SubscriptionCreationOptions<T>

A generic version of the subscription creation options object.

public class SubscriptionCreationOptions<T>
{
  public string Name { get; set; }
  public Expression<Func<T, bool>> Filter { get; set; }
  public Expression<Func<T, object>> Projection { get; set; }
  public Action<ISubscriptionIncludeBuilder<T>> Includes { get; set; }
  public string ChangeVector { get; set; }
  public bool Disabled { get; set; }
  public string MentorNode { get; set; }
  public bool PinToMentorNode { get; set; }
  public ArchivedDataProcessingBehavior? ArchivedDataProcessingBehavior { get; set; }
}

Member	Type	Description
<T>	type	Type of object from which the collection of documents managed by the subscription will be derived.
Name	string	User defined name for the subscription. The name must be unique in the database.
Filter	Expression<Func<T, bool>>	Lambda expression defining the filter logic for the subscription. Will be translated to a JavaScript function.
Projection	Expression<Func<T, object>>	Lambda expression defining the projection that will be sent by the subscription for each matching document. Will be translated to a JavaScript function.
Includes	Action<ISubscriptionIncludeBuilder<T>>	An action that defines include clauses for the subscription. Included documents and/or included counters will be part of the batch sent by the subscription. Include methods can be chained.
ChangeVector	string	Allows to define a change vector from which the subscription will start processing. Useful for ad-hoc processes that need to process only recent changes. In such cases, you can set the field to "LastDocument" to start processing from the latest document in the collection.
MentorNode	string	Allows to define a specific node in the cluster to handle the subscription. Useful when you prefer a specific server due to its stronger hardware, closer geographic proximity to clients, or other reasons.

SubscriptionCreationOptions

A non-generic version of the subscription creation options object.

Member	Type	Description
Name	string	User defined name for the subscription. The name must be unique in the database.
Query	string	RQL query that defines the subscription. This RQL comes with additional support to JavaScript functions inside the where clause and special semantics for subscriptions on documents revisions.
ChangeVector	string	Allows to define a change vector from which the subscription will start processing. Useful for ad-hoc processes that need to process only recent changes. In such cases, you can set the field to "LastDocument" to start processing from the latest document in the collection.
MentorNode	string	Allows to define a specific node in the cluster to handle the subscription. Useful when you prefer a specific server due to its stronger hardware, closer geographic proximity to clients, or other reasons.

Update subscription

Existing subscriptions can be modified using the following Update methods available through the Subscriptions property of the DocumentStore.

string Update(SubscriptionUpdateOptions options, string database = null);

Task<string> UpdateAsync(SubscriptionUpdateOptions options, string database = null,
                  CancellationToken token = default);

Parameter	Type	Description
options	SubscriptionUpdateOptions	The subscription update options object. See SubscriptionUpdateOptions
database	string	The name of the database where the subscription task resides. If null, the default database configured in the DocumentStore will be used.
token	CancellationToken	Cancellation token used to halt the update process.

Return value	Description
string	The name of the updated data subscription.

SubscriptionUpdateOptions

SubscriptionUpdateOptions inherits from SubscriptionCreationOptions and adds two additional fields:

public class SubscriptionUpdateOptions : SubscriptionCreationOptions
{
  public long? Id { get; set; }
  public bool CreateNew { get; set; }
}

Parameter	Type	Description
Id	long?	The unique ID that was assigned to the subscription by the server at creation time. You can retrieve it by getting the subscription status. When updating, the Id can be used instead of the Name field, and takes precedence over it. This allows you to modify the subscription's name: provide the Id and submit a new name in the Name field.
CreateNew	bool	Determines the behavior when the subscription you wish to update does Not exist. true - a new subscription is created with the provided option parameters. false - an exception will be thrown. Default: false

Subscription query

All subscriptions are eventually translated to an RQL-like statement. These statements have the following parts:

• Functions definition part, like in ordinary RQL. Those functions can contain any JavaScript code, and also supports load and include operations.

• From statement, defining the documents source, ex: from Orders. The from statement can only address collections, therefore, indexes are not supported.

• Where statement describing the criteria according to which it will be decided to either send the documents to the worker or not. Those statements support either RQL like equality operations (=, ==) ,
  plain JavaScript expressions or declared function calls, allowing to perform complex filtering logic.
  The subscriptions RQL does not support any of the known RQL searching keywords.

• Select statement, that defines the projection to be performed. The select statements can contain function calls, allowing complex transformations.

• Include statement allowing to define include path in document.

Keywords

Although subscription's query syntax has an RQL-like structure, it supports only the declare, select and where keywords, usage of all other RQL keywords is not supported.
Usage of JavaScript ES5 syntax is supported.

Paths

Paths in subscriptions RQL statements are treated as JavaScript indirections and not like regular RQL paths.
It means that a query that in RQL would look like:

from Orders as o
where o.Lines[].Product = "products/1-A"

Will look like that in subscriptions RQL:

declare function filterLines(doc, productId)
{
    if (!!doc.Lines){
        return doc.Lines.filter(x=>x.Product == productId).length >0;
    }
    return false;
}

from Orders as o
where filterLines(o, "products/1-A")

Revisions

To define a data subscription that sends document revisions to the client,
you must first configure revisions for the specific collection managed by the subscription.

The subscription should be defined in a special way:

• In case of the generic API, the SubscriptionCreationOptions<> generic parameter should be of the generic type Revision<>, while it's generic parameter correlates to the collection to be processed. Ex: new SubscriptionCreationOptions<Revision<Order>>()
• For RQL syntax, concatenate the (Revisions = true) clause to the collection being queried.
  For example: From Orders(Revisions = true) as o