Using Variables

Passing variables to change stream

The aggregation stages of the change stream can use variables, as in the following example:

{
    "uri": "mine",
    "stages": [
        { "$match": { "fullDocument::name": { "$var": "n" } } }
    ]
}

The $match stage uses the variable n, specified as { "$var": "n" }.

The client can pass the variable using the avar query parameter.

GET /messages/_streams/mine?avars={"n":"Andrea"} HTTP/1.1

In case of the change stream mine described in the examples, the variable n is used to restrict notifications only to changes on documents with the property name matching it.

Predefined variables

The change stream aggregation can use predefined variables, as in the following example:

{
    "uri": "mine",
    "stages": [
        { "$match": { "fullDocument::name": { "$var": "@user._id" } } }
    ]
}

The $match stage uses the predefined variable @user._id, specified as { "$var": "@user._id" }.

Note	the predefined variables are resolved server side, i.e. the client does not need to pass the variable and the server will resolve it, making sure its value is trusted. In the example, the `name` property is matched against the user id of the authenticated user.

Refer to Aggregation documentation page for more information.

Security considerations

By default RESTHeart makes sure that the variables passed as query parameters don’t contains MongoDB operators.

This behavior is required to protect data from undesirable malicious query injection.

Even though is highly discouraged, is possible to disable this check by editing the following property in the restheart.yml configuration file.

## Security

# Check if aggregation variables use operators.
# Allowing operators in aggregation variables is risky
# because requester can inject operators modifying the query

aggregation-check-operators: true