Aggregate.addFields

1. Interface Description

Function: Aggregation stage. Adds new fields to the output records. After the addFields aggregation stage, all output records will include the fields specified by addFields in addition to the input fields.

Syntax: addFields({<new field>: <expression>})

Notes:

addFields is equivalent to a project stage that specifies all existing fields and the newly added fields. addFields can specify multiple new fields, where the value of each new field is determined by the expression used. If a specified new field has the same name as an existing field, the new field's value will overwrite the existing field's value. Note that addFields cannot be used to add elements to array fields.

2. Input Parameters

Parameter	Type	Required	Description
key(new field)	expression	Required	aggregate expression

3. Response

Parameter	Type	Required	Description
-	Aggregate	Yes	Aggregation object

4. Sample Code

Example 1: Applying addFields Twice Consecutively

Suppose the collection scores contains the following records:

{
  _id: 1,
  student: "Maya",
  homework: [ 10, 5, 10 ],
  quiz: [ 10, 8 ],
  extraCredit: 0
}
{
  _id: 2,
  student: "Ryan",
  homework: [ 5, 6, 5 ],
  quiz: [ 8, 8 ],
  extraCredit: 8
}

Apply addFields twice: first to add two fields representing the sum of homework and quiz respectively, then to add another field calculating the sum based on these two previous sums.

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("scores")
    .aggregate()
    .addFields({
      totalHomework: $.sum("$homework"),
      totalQuiz: $.sum("$quiz"),
    })
    .addFields({
      totalScore: $.add(["$totalHomework", "$totalQuiz", "$extraCredit"]),
    })
    .end();
  console.log(res.data);
};

The returned result is as follows:

{
  "_id" : 1,
  "student" : "Maya",
  "homework" : [ 10, 5, 10 ],
  "quiz" : [ 10, 8 ],
  "extraCredit" : 0,
  "totalHomework" : 25,
  "totalQuiz" : 18,
  "totalScore" : 43
}
{
  "_id" : 2,
  "student" : "Ryan",
  "homework" : [ 5, 6, 5 ],
  "quiz" : [ 8, 8 ],
  "extraCredit" : 8,
  "totalHomework" : 16,
  "totalQuiz" : 16,
  "totalScore" : 40
}

Example 2: Adding Fields in Nested Records

Fields can be added in nested records using dot notation. Suppose the vehicles collection contains the following records:

{ _id: 1, type: "car", specs: { doors: 4, wheels: 4 } }
{ _id: 2, type: "motorcycle", specs: { doors: 0, wheels: 2 } }
{ _id: 3, type: "jet ski" }

The following operation can be used to add a new field fuel_type under the specs field, setting its value to the fixed string unleaded:

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("vehicles")
    .aggregate()
    .addFields({
      "spec.fuel_type": "unleaded",
    })
    .end();
  console.log(res.data);
};

The returned result is as follows:

{ _id: 1, type: "car",
   specs: { doors: 4, wheels: 4, fuel_type: "unleaded" } }
{ _id: 2, type: "motorcycle",
   specs: { doors: 0, wheels: 2, fuel_type: "unleaded" } }
{ _id: 3, type: "jet ski",
   specs: { fuel_type: "unleaded" } }

Example 3: Setting a Field Value to Another Field

You can set a field's value to another field's value by using a string expression formed by $ followed by the field name.

Using the same collection example as above, the following operation can be used to add a field vehicle_type, setting its value to that of the type field:

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("vehicles")
    .aggregate()
    .addFields({
      vehicle_type: "$type",
    })
    .end();
  console.log(res.data);
};

The returned result is as follows:

{ _id: 1, type: "car", vehicle_type: "car",
   specs: { doors: 4, wheels: 4, fuel_type: "unleaded" } }
{ _id: 2, type: "motorcycle", vehicle_type: "motorcycle",
   specs: { doors: 0, wheels: 2, fuel_type: "unleaded" } }
{ _id: 3, type: "jet ski", vehicle_type: "jet ski",
   specs: { fuel_type: "unleaded" } }