Data Subscriptions: Creation API Overview
In this page:
Subscription creation overloads summary
Subscription Creation Options
Subscription query
Create and CreateForRevisions overloads summary
Subscription creation is accessible through DocumentStore
's subscriptions
property, of type DocumentSubscriptions
:
store.subscriptions.create(clazz, [database]);
store.subscriptions.create(options, [database]);
store.subscriptions.createForRevisions(clazz, [database]);
store.subscriptions.createForRevisions(options, [database]);
Parameters | ||
---|---|---|
documentType | class | Subscription item class |
options | object | Contains subscription creation options |
id | string | User defined name of the subscription: allows to have a human readable identification of a subscription. The name must be unique in the database. |
query | string | Required. RQL query that describes the subscription. That RQL comes with additional support to javascript clause inside the 'Where' statement and special semantics for subscriptions on documents revisions. |
changeVector | string | Allows to define a change vector, from which the subscription will start processing. It might be useful for ad-hoc processes that need to process only recent changes in data, for that specific use, the field may receive a special value: "LastDocument", that will take the latest change vector in the machine. |
mentorNode | string | Allows to define a specific node in the cluster that we want to treat the subscription. That's useful in cases when one server is preffered over other, either because of stronger hardware or closer geographic proximity to clients etc. |
documentType | class | Subscription item class |
database | string | Name of database to create a data subscription. If null , default database configured in DocumentStore will be used. |
Return value | |
---|---|
string |
Created data subscription name. If Name was provided in SubscriptionCreationOptions, it will be returned, otherwise, a unique name will be generated by server. |
Subscription query
-
Functions definition part, like in ordinary RQL. Those functions can contain any javascript code, and also supports
load
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 supports 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
In order to define a data subscription that uses documents revisions, there first has to be revisions configured for the specific collection.
The subscription should be defined in a special way:
-
In case of the generic API, use method
createForRevisions()
instead ofcreate()
-
For RQL syntax, the
(Revisions = true)
statement should be concatenated to the collection to be queries. Ex:From orders(Revisions = true) as o