Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

Introduction

RESTHeart manages aggregation operations: both aggregation pipelines and map reduce functions are supported.

...

Info

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.

...

aggrs is an array of pipeline or mapReduce objects.

aggragation pipeline metadata object format

Code Block
languagejs
themeMidnight
titlepipeline object format
{
	"type":"pipeline",
	"uri": <uri>,
	"stages": [
		"<stage_1>",
		"<stage_2>",
		...
	]
}

...

Info

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

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

Code Block
languagejs
themeMidnight
titlemapReduce object format
{
   	"type":"mapReduce",
	"uri":"<uri>",
	"map": "<map_function>",
	"reduce": "<reduce_function>",
	"query": "<query>"
}

...

PropertyDescriptionMandatory
typefor aggregation pipeline operations is "mapReduce"yes
urispecifies the URI when the operation is bound under /<db>/<collection>/_aggrs path.yes
map

the map function

For more information refer to https://docs.mongodb.org/manual/core/map-reduce/

yes
reducethe reduce functionyes
querythe filter queryno

Examples

The following requests upsert a collection  defining two aggregation operations:

...

Code Block
languagejs
GET /db/ao_test
 
HTTP/1.1 200 OK
...
{
    "_links": {
        ...,
        "test_ap": {
            "href": "/db/ao_test/_aggrs/test_ap"
        }, 
        "test_mr": {
            "href": "/db/ao_test/_aggrs/test_mr"
        }
    },
    ....
}

Passing variables to aggregation operations

The query parameter avars allows to pass variables to the aggregation operations.

...

Code Block
GET /test/ao_test/_aggrs/test_ap?avars={"n":1}

HTTP/1.1 200 OK
...

Variables in stages or query

Variables can be used in aggregation pipeline stages and map reduce query as follows:

...

Code Block
languagejs
{
  "query": { "name": { "$var": "n" } },
  ...
}

Variables in map or reduce functions

Variables are passed also to map and reduce javascript functions where the variable $vars can be used. For instance:

...