Change streams

The "streams" collection metadata

In RESTHeart, not only documents but also databases and collections have properties. Some properties are metadata, i.e. they have a special meaning for RESTheart that influences its behavior.

The collection metadata property streams allows to declare change streams that client can watch for to be aware about changes to documents and bind them to given URI.

Change streams need to be defined as collection metadata. It is not possible to define a stream via a query parameter and this is by design: clients are not able to open up arbitrary change streams but only those defined (and tested) by the developers.

streams is an array of stream objects.

Stream metadata object format

stream object format

{
    "uri": <uri>,
    "stages": [
        "<stage_1>",
        "<stage_2>",
        ...
    ]
}

Property Description Mandatory

uri specifies the URI when the stream is bound under the path /<db>/<collection>/_streams yes

Property	Description	Mandatory
uri	specifies the URI when the stream is bound under the path `/<db>/<collection>/_streams`	yes
stages	the MongoDB aggregation pipeline stages. For more information refer to https://docs.mongodb.org/manual/core/aggregation-pipeline/	yes

stages

the MongoDB aggregation pipeline stages.

For more information refer to https://docs.mongodb.org/manual/core/aggregation-pipeline/

yes

Notes:

Only a subset of aggregation pipeline stages are allowed for this features. Check MongoDB’s documentation for further informations.
Stages takes as input Change Events instead of the documents themselves. For example, the modified version of a document after a PATCH request is present at event.fullDocument property of the stages input event. (See examples).

Escape stage properties informations

MongoDB does not allow to store fields with names starting with $ or containing dots (.), see Restrictions on Field Names on MongoDB’s documentation.

In order to allow storing stages with dollar prefixed operators or using the dot notation (to refer to properties of subdocuments), RESTHeart automatically and transparently escapes the properties keys as follows:

the $ prefix is "underscore escaped", e.g. $exists is stored as _$exists
if the dot notation has to be used in a key name, dots are replaced with :: e.g. SD.prop is stored as SD::prop

Note	RESTHeart escapes them automatically.