Aggregate.project

1. Interface Description

Function: Aggregation stage. Passes specified fields to the next pipeline. These fields can be either existing fields or newly computed fields.

Syntax: project({ <field>:<expression> })

2. Input Parameters

Field expressions can have the following formats:

Format	Description
<field>: <1 or true>	Specifies to include an existing field
_id: <0 or false>	Excludes the _id field
<field>: <expression>	Adds a new field or resets an existing field
<field>: <0 or false>	Excludes a field (if you exclude a non-_id field, you cannot use other expressions in this project)

Notes

Specifying Included Fields

• The _id field is included in the output by default. For any other fields to appear in the output, they must be explicitly specified in project.
• If you specify including a field that does not exist, project will ignore this field and will not add it to the output document.

Specifying Excluded Fields

• If you specify excluding a field in project, all other fields will be included in the output;
• If you exclude a non-_id field, you cannot use other expressions in this project;

Adding a New Field or Resetting an Existing Field

You can use special expressions to add new fields or reset existing fields.

Multilevel Nested Fields

Sometimes, when fields are deeply nested, we can use dot notation:

"contact.phone.number": <1 or 0 or expression>

You can also directly use a nested format:

contact: { phone: { number: <1 or 0 or expression> } }

3. Response

Parameter	Type	Required	Description
-	Aggregate	Yes	Aggregation object

4. Sample Code

Suppose we have a collection articles containing the following documents:

{
  "_id": 666,
  "title": "This is title",
  "author": "Nobody",
  "isbn": "123456789",
  "introduction": "......"
}

Specifying Certain Fields to Include

The following code uses project to make the output include only the _id, title, and author fields:

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

const db = app.database();
const { gt, sum } = db.command.aggregate;

exports.main = async (event, context) => {
  const res = await db
    .collection("articles")
    .aggregate()
    .project({
      title: 1,
      author: 1,
    })
    .end();
  console.log(res.data);
};

The output is as follows:

{ "_id" : 666, "title" : "This is title", "author" : "Nobody" }

Exclude the _id Field from the Output

The _id` field is included in the output by default. If you do not want it, you can specify to exclude it:

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

const db = app.database();
const { gt, sum } = db.command.aggregate;

exports.main = async (event, context) => {
  const res = await db
    .collection("articles")
    .aggregate()
    .project({
      _id: 0, // Specifies to exclude the _id field
      title: 1,
      author: 1,
    })
    .end();
  console.log(res.data);
};

The output is as follows:

{ "title" : "This is title", "author" : "Nobody" }

Exclude a Specific Non-_id Field

We can also specify to exclude a particular non-_id field from the output, so that all other fields are included:

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

const db = app.database();
const { gt, sum } = db.command.aggregate;

exports.main = async (event, context) => {
  const res = await db
    .collection("articles")
    .aggregate()
    .project({
      isbn: 0, // Specifies to exclude the isbn field
    })
    .end();
  console.log(res.data);
};

The output is as follows, which lacks the isbn field compared to the input:

{
  "_id": 666,
  "title": "This is title",
  "author": "Nobody",
  "introduction": "......"
}

Adding a Computed New Field

Suppose we have a collection students containing the following documents:

{
  "_id": 1,
  "name": "Xiao Ming",
  "scores": {
    "chinese": 80,
    "math": 90,
    "english": 70
  }
}

In the following code, we use project to add a new field totalScore in the output:

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

const db = app.database();
const { gt, sum } = db.command.aggregate;

exports.main = async (event, context) => {
  const res = await db
    .collection("students")
    .aggregate()
    .project({
      _id: 0,
      name: 1,
      totalScore: sum(["$scores.chinese", "$scores.math", "$scores.english"]),
    })
    .end();
  console.log(res.data);
};

Output:

{ "name": "Xiao Ming", "totalScore": 240 }

Adding a New Array Field

Suppose we have a collection points containing the following documents:

{ "_id": 1, "x": 1, "y": 1 }
{ "_id": 2, "x": 2, "y": 2 }
{ "_id": 3, "x": 3, "y": 3 }

In the following code, we use project to place the fields x and y into a new array field coordinate:

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

const db = app.database();
const { gt, sum } = db.command.aggregate;

exports.main = async (event, context) => {
  const res = await db
    .collection("points")
    .aggregate()
    .project({
      coordinate: ["$x", "$y"],
    })
    .end();
  console.log(res.data);
};

The output is as follows:

{ "_id": 1, "coordinate": [1, 1] }
{ "_id": 2, "coordinate": [2, 2] }
{ "_id": 3, "coordinate": [3, 3] }