RESTHeart 3.0 is the latest stable version.
RESTHeart manages aggregation operations: both aggregation pipelines and map reduce functions are supported.
"Aggregations operations process data records and return computed results. Aggregation operations group values from multiple documents together, and can perform a variety of operations on the grouped data to return a single result."
In both cases only inline output type is supported, i.e. no result is written to the DB server.
The aggrs collection metadata
In RESTHeart, not only documents but also dbs 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
aggrs allows to declare aggregation operations and bind them to given URI.
Aggregation operations need to be defined as collection metadata. It is not possible to execute an aggregation via a query parameter and this is by design: clients are not able to execute arbitrary aggregation operations but only those defined (and tested) by the developers.
aggrs is an array of pipeline or mapReduce objects.
aggragation pipeline metadata object format
|type||for aggregation pipeline operations is "pipeline"||yes|
|uri||specifies the URI when the operation is bound under the path ||yes|
the MongoDB aggregation pipeline stages.
For more information refer to https://docs.mongodb.org/manual/core/aggregation-pipeline/
MongoDB does not allow to store fields with names starting with $ or containing dots (.), see Restrictions on Field Names on MongoDB 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.
$existsis stored as
- if the dot notation has to be used in a key name, dots are replaced with :: e.g.
SD.propis stored as
In RESTHeart 1.x, these escapes are not managed automatically: the developer had to explicitly use them; starting from version 2.0 this is not needed anymore.
mapReduce metadata object format
|type||for aggregation pipeline operations is "mapReduce"||yes|
|uri||specifies the URI when the operation is bound under /<db>/<collection>/_aggrs path.||yes|
the map function
For more information refer to https://docs.mongodb.org/manual/core/map-reduce/
|reduce||the reduce function||yes|
|query||the filter query||no|
The following requests upsert a collection defining two aggregation operations:
- aggregation operation test_ap bound at
- map reduce operation test_mr bound at
Note between the
_links collection property the URIs of the aggregation operations.
Passing variables to aggregation operations
The query parameter
avars allows to pass variables to the aggregation operations.
For example, the previous example aggregations both use a variable named "n". If the variable is not passed via the
avars qparam, the request fails.
Passing the variable n, the request succeeds:
Variables in stages or query
Variables can be used in aggregation pipeline stages and map reduce query as follows:
In case of map reduce operation previous example, the variable was used to filter the documents to have the name property matching the variable n:
Variables in map or reduce functions
$vars can be used. For instance:
Note the map function;
JSON.parse($vars) allows to access the variables passed with the query parameter