Aggregate.bucket

1. Interface Description

Function: Aggregation Stage. Divides input records into different groups based on given conditions and boundaries, with each group being a bucket.

Disclaimer:

bucket({ groupBy: <expression>, boundaries: [<lowerbound1>, <lowerbound2>, ...], default: <literal>, output: { <output1>: <accumulator expr>, ... <outputN>: <accumulator expr> } })

Notes:

Each group is output as a record, containing an _id field with the value of the lower bound and a count field with the value of the number of records in the group. count is output by default when output is not specified.

bucket is output only when there is at least one record in the group.

To use bucket, at least one of the following conditions must be met; otherwise, an error will be thrown:

• For every input record, the value obtained by applying the groupBy expression must be within boundaries.
• Specify a default value that is outside boundaries or has a different type than the values in boundaries.

2. Input Parameters

Parameter	Type	Required	Description
groupBy	expression	Yes	The field is detailed below
boundaries	Array	Yes	The field is detailed below
default	any	No	The field is detailed below
output	Object	No	The field is detailed below

groupBy is an expression used to determine grouping, applied to each input record. You can use a $ prefix followed by the field path to group as the expression. Unless a default value is specified with default, each record must contain the specified field, and the field value must be within the range specified by boundaries.

boundaries is an array where each element represents the lower bound of a group. At least two boundary values must be specified. The array values must be of the same type and in ascending order.

default is optional. When specified, records that do not fall into any group will be placed into a default group, where the _id of this group is determined by default. The value of default must be less than the minimum value in boundaries or greater than or equal to its maximum value. The value of default can be of a different type than the elements in boundaries.

output is optional, used to determine which fields, in addition to _id, the output records should contain. The value of each field must be specified using an accumulator expression. When output is specified, the default count is not output by default and must be manually specified:

output: {
  count: $.sum(1),
  ...
  <outputN>: <accumulator expr>
}

3. Response

Parameter	Type	Required	Description
-	Aggregate	Yes	Aggregation object

4. Sample Code

Suppose the collection items contains the following records:

{
  _id: "1",
  price: 10
}
{
  _id: "2",
  price: 50
}
{
  _id: "3",
  price: 20
}
{
  _id: "4",
  price: 80
}
{
  _id: "5",
  price: 200
}

Group the above records, categorizing [0, 50) into one group, [50, 100) into another group, and others into a separate group:

const tcb = require("@cloudbase/node-sdk");
const app = tcb.init({
  env: "xxx",
});

const db = app.database();
const $ = db.command.aggregate;

exports.main = async (event, context) => {
  const res = await db
    .collection("items")
    .aggregate()
    .bucket({
      groupBy: "$price",
      boundaries: [0, 50, 100],
      default: "other",
      output: {
        count: $.sum(),
        ids: $.push("$_id"),
      },
    })
    .end();
  console.log(res.data);
};

The returned result is as follows:

[
  {
    "_id": 0,
    "count": 2,
    "ids": [
      "1",
      "3"
    ]
  },
  {
    "_id": 50,
    "count": 2,
    "ids": [
      "2",
      "4"
    ]
  },
  {
    "_id": "other",
    "count": 1,
    "ids": [
      "5"
    ]
  }
]