Pipeline Aggregation

Pipeline aggregation allows for querying, aggregating, and transforming data in multiple stages in real-time through a single API request. While query arguments allow for making simple, single-stage queries through the API, pipelines allow for more complex searches, aggregations and transformations.

To leverage pipeline aggregation via the API, simply pass a pipeline query argument with the request. The pipeline query argument is an array of pipeline stages that execute in order. Each stage transforms the result set and passes it on to the next stage in the pipeline.

?pipeline=[{ stage1 },{ stage2 }, { stage3 }, ...]

In the below example, the pipeline contains two stages. The first is a $match stage. This filters the result set to all accounts create on or after 2015-01-01T00:00:00.000Z. Then that set of results is passed onto the $group stage which counts all of the accounts in the result set and finally returns a count result. For all available stages, see Pipeline Stages

Pipeline Request

GET /accounts?pipeline=[{"$match": {"created": {"$gte": "2015-01-01T00:00:00.000Z"}}}, {"$group": {"_id": null, "count": {"$count": "_id"}}}]

Pipeline Result

{
    "data": [
        {
            "count": 24
        }
    ],
    "hasMore": false,
    "object": "list"
}

Pipeline Stages

Name	Description	Example
$group	A JSON object containing an _id property (required) and 0 or more property groupings.	{"$group": {"_id": null, "count": {"$count": "_id"}}}
$limit	An integer representing the number of results to return.	{"$limit": 100}
$match	A JSON object containing operators and expressions used to limit the search results.	{"$match": {"$and": [{"created": {"$gt": "2015-01-01T00:00:00.000Z"}}, {"created": {"$lt": "2015-06-01T00:00:00.000Z"}}]}}
$project	A JSON object that specifies existing properties or new properties to pass along to the next stage in the pipeline.	{"$project",{"_id": 1, "name": 1}}
$skip	An integer representing the number of results to skip. Useful for paging where mapping or groupings have been applied, or where search the search criteria cannot be paged using unique fields.	{"$skip": 10}
$sort	A JSON object containing one or more properties, the values of which must be 1 for ascending and -1 for descending.	{"$sort": {"_id": -1}}
$unwind	Accepts a property name and deconstructs an array into a single property in multiple documents.	{"$unwind": roles}