WebSocket & SSE

Using Variables

RESTHeart Ulabase
Important
A variable in a stage changes the pipeline, and each different pipeline opens its own MongoDB cursor. A stream filtered in its stages therefore opens one change stream per distinct set of bound values. To serve many clients from one cursor, keep the stages fixed and put the variable in notify_when, which is evaluated per client on the shared cursor. A client binds a variable in the same way in both cases, as described here.

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" }.

Since 9.9.0, the client passes the variable as a plain query parameter named after it:

GET /messages/_streams/mine?n=Andrea HTTP/1.1

With the change stream mine of the examples, the client receives only the changes to the documents whose name is the value of n.

A value that parses as JSON is read as JSON: ?opts={"a":1} binds opts to that object, and ?tags=[1,2,3] binds tags to that array. Any other value is a string: ?n=Andrea binds n to "Andrea". Aggregations and change streams bind variables in the same way: see Passing Variables.

Legacy: the avars Query Parameter

Before 9.9.0, all variables had to be bundled into a single JSON object passed via the avars query parameter:

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

This form is still supported. A request can use both forms. When a variable is given both ways, the avars value wins.

Dot Notation support for $var

$var reads a nested property of a variable with the dot notation.

For example, a client passes ?options={"name":"Andrea"}, or avars={"options":{"name":"Andrea"}} in the legacy form. A stage reads the nested property name like this:

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

{ "$var": "options.name" } is the property name of the variable options: here, Andrea.

Variables with Default Values

A variable can have a default value, used when the client does not bind it: { "$var": ["n", "Andrea"] }. See Variables with default values in the aggregations page.

Predefined variables

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

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

The $match stage uses the predefined variable @user.sub, specified as { "$var": "@user.sub" }, and matches it against the document’s owner.

Note
The server resolves the predefined variables. The client does not pass them, and a value it sends for one, such as ?avars={"@user.sub": "someone-else"}, is ignored. The stream stays scoped to the connected caller.
Note
A predefined variable has a different value for each caller, so a stage that uses one opens a cursor per caller, like any other stage variable. Use it where the events of one user must be kept from the others. For a selection among events that every client may see, use notify_when, which shares one cursor.
Important
Use the name the caller’s account carries. @user.sub identifies a caller authenticated with a JWT, @user._id one authenticated against MongoDB users, @user.userid one from the file realm: see Identifying the caller. A variable the account does not carry is unresolved. Since 9.8.2 an unresolved variable fails the request with variable not bound. Before, it was bound to null, which matched every document without that field.

The list of the predefined variables is in the aggregations page.

Security considerations

The variables of a change stream are values, as in aggregations. With aggregation-check-operators enabled, the default:

  • a value with a MongoDB operator, a key starting with $, gets 400. The check covers every value in avars and, since v9.17, each plain query parameter that a stage or notify_when reads with $var or $ifvar;

  • since v9.17, a string starting with $ is bound as {"$literal": value} where MongoDB would read it as a field path or as a variable. In a $match stage outside $expr it is left as it is.

mongo:
  aggregation-check-operators: true

Setting it to false lets the client change the query through a variable, and is strongly discouraged. See Operator Injection Protection for the details and the examples.