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 avars 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.

Dot Notation support for `$var`

$var in RESTHeart change streams can utilize dot notation to access nested properties. This allows you to specify a complex variable structure and reference its components for more flexible filtering.

For example, if a client passes a variable as avar={"options": {"name": "Andrea"}}, you can access the nested property name using the dot notation within an aggregation stage, like this:

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

The $match stage in the previous example uses the dot notation in { "$var": "options.name" } to reference the nested property name, in this case Andrea.

By employing dot notation, you can work with structured and nested data effectively and make your change stream filtering more versatile and powerful.

Variables with Default Values

Variables can have a default value. This default value is used when the variable is not specified in the ?avar query parameter.

For more detailed information on using variables with default values, please refer to the Aggregation documentation.

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 contain 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