aggregate

Updated pdexter 2023-12-12

Aggregation in Formbird allows you to retrieve data in a format similar to MongoDB's aggregation framework. This functionality can be utilized through the REST API or within DataService in rulesets. To understand more about MongoDB's aggregation framework, you can refer to the official MongoDB documentation on aggregation.

Syntax

ft3.aggregate( query, user-id )

.then( callback-function(data) {...} )

.catch( error-handler-function(e) {...} )

Example Usage

Server Rulesets

const query = {
  startPipeline: {
    "$match": {
      "systemHeader.keyIds": { "$exists": true }
    }
  },
  endPipeline: {
    "$group": {
      "_id": "$systemHeader.systemType",
      "count": { "$sum": 1 }
    }
  }
};

ft3.aggregate(query, ntf.userId)
.then(data => {
    // process the returned data
})
.catch(err => {
    // handle error
});

StartPipeline

The startPipeline parameter initiates the aggregation process. This stage typically includes filtering and selection operations to narrow down the dataset. It is crucial for setting the conditions and criteria for the data to be processed.

Common operations in startPipeline:

• $match: Filters documents based on specified criteria.
• $project: Selects and reshapes fields.
• $limit: Limits the number of documents in the pipeline.

Access Control: The Formbird platform performs access checks on documents after the startPipeline stage, ensuring that only authorized data progresses to the endPipeline stage. This step is critical for maintaining data security and integrity within the system.

EndPipeline

The endPipeline parameter concludes the aggregation process. It is typically used for grouping and summarizing the data. This stage involves performing aggregation operations on the dataset refined by the startPipeline.

Common operations in endPipeline:

• $group: Groups documents by specified fields and calculates aggregate values.
• $sort: Sorts documents in the pipeline.
• $count: Counts the number of documents in the pipeline.

This bifurcation into startPipeline and endPipeline ensures that the aggregation process is secure, efficient, and adheres to the necessary data access protocols.