Skip to main content

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:

FormatDescription
<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​

ParameterTypeRequiredDescription
-AggregateYesAggregation 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] }