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. This way 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 definitions.

Stream definition format

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

Property Description Mandatory

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 Aggregation Pipeline on MongoDb documentation.	yes

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 Aggregation Pipeline on MongoDb documentation.

yes

Note	Stages take as input Change Events instead of the documents. 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).

Optional Stages

The aggregation of the stream can include optional stages. These optional stages are only executed when one or more variables are specified.

For a more comprehensive understanding of how to use optional stages, please refer to the Aggregation documentation.

Escaped stage properties

MongoDB (up to v5) does not allow to store fields with names starting with $ or containing dots (.).

To store stages with dollar prefixed operators or use the dot notation, 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