Aggregate

Aggregate HTTP Interface

The Learning Locker Aggregate HTTP interface utilises the Mongo aggregation API and is only available for allowed collections. The Aggregate HTTP Interface is more advanced than the xAPI HTTP interface and allows you to access MongoDB's powerful Aggregation API for more custom filtration of documents.

Allowed Collections

This interface can be used to aggregate on multiple allowed only collections. To check whether a collection is allowed for aggregation or not, we use a regular expression. You can specify your own rule using AGGREGATE_API_ALLOWED_COLLECTIONS environment variable with ^rollup default value that means that by default you can aggregate on collections that prefixed with "rollup" word.

Request Setup

When using this interface, you must additionally supply your Basic Auth details with each request in the Authorization header. Your Basic Auth details can be found under Settings > Clients. The interface can be passed options via a JSON object in the request body (described in the table below). The collection property is required. The collection is a string that determines the collection name used to execute the aggregation on. The other properties are optional.

Name

Description

Default Value

Name

Description

Default Value

pipeline

Array containing a pipeline of stages for documents to pass through before being output from the interface.

[]

(in this case, you'll get records from the desired collection without any transformations)

skip

Number that specifies a number of records that should be skipped from the beginning. This parameter will be transformed into $skip aggregation stage and executed at the very end.

0

limit

Number that specifies a number of records that will be cut from the final results. This parameter will be transformed into $limit aggregation stage and executed at the very end.

10000

maxTimeMS

Number that specifies the time limit for the query in Mongo.

0

(if nothing else was set to MAX_TIME_MS environment variable)

batchSize

Specifies the number of documents to return in each batch of the response from the MongoDB instance. Defaults to 100

100

hint

Specifies a Mongo collection index to use instead of the chosen index selected during the query planner stage. We recommend only using this parameter in the rare cases when Mongo isn’t choosing the best index during the initial query planner stage.

desiredIndexName

Example

A simple request to this interface using all of the available parameters looks like the request below.

1 2 3 4 5 6 7 8 9 10 11 12 POST http://www.example.org/api/aggregate Authorization: Basic YOUR_BASIC_AUTH Content-Type: application/json; charset=utf-8 { "collection": "rollupUniqueVerbsByPlatformDaily", "pipeline": [], "skip": 0, "limit": 1, "maxTimeMs": 100, "batchSize": 100 }

A response to this valid request will return a 200 response like the response below, where the JSON encoded body contains several keys.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 { "result": [ { "_id" : "111aaa1111a111111aa11111", "organisationId" : "111aaa1111a111111aa11111", "organisationName" : [ "My amazing org" ], "lrsId" : "111aaa1111a111111aa11111", "lrsName" : [ "My awesome store" ], "clientId" : "111aaa1111a111111aa11111", "clientName" : [ "My incredible client" ], "platform" : "Some Cool Platform", "verb" : "http://adlnet.gov/expapi/verbs/scored", "count" : 200, "date" : "2017-08-01T00:00:00Z", "storedDate" : "2017-08-01T00:00:00Z" } ], "startedAt": "2020-04-03 14:17:30.924+03:00", "completedAt": "2020-04-03 14:17:30.943+03:00" }

Pipeline Stages

So far we've only seen the limit and project stages, however, there are many other stages available in Mongo. The common stages are listed in the table below.

Name

Description

Name

Description

project

Reshapes the records from the previous stage of the pipeline for the next stage.

match

Filters the records from the previous stage of the pipeline for the next stage.

limit

Limits the number of records from the previous stage of the pipeline for the next stage.

skip

Skips a number of records from the previous stage of the pipeline for the next stage.

group

Groups records by a specified identifier from the previous stage of the pipeline for the next stage.

sort

Sorts the records from the previous stage of the pipeline for the next stage.

 

Learning Locker and the Squirrel logo are trademark of Learning Pool 2020 | Learning Locker is licensed under GPL 3.0.