Database Manual / Reference / Query Language / Aggregation Stages

$documents (aggregation stage)（聚合阶段）

Definition定义

$documents

New in version 6.0.在版本6.0中新增。

Returns literal documents from input values.从输入值返回文字文档。

Syntax语法

The $documents stage has the following form:$documents阶段具有以下形式：

{ $documents: <expression> }

Limitations局限性

  • You can only use $documents in a database-level aggregation pipeline.您只能在数据库级聚合管道中使用$documents。
  • You must use $documents as the first stage of an aggregation pipeline.您必须将$documents用作聚合管道的第一阶段。

See below for usage examples.请参阅下面的用法示例。

Behavior行为

$documents accepts any valid expression that resolves to an array of objects. This includes:接受解析为对象数组的任何有效表达式。这包括：

  • system variables, such as 系统变量，例如$$NOW or 或$$SEARCH_META
  • $let expressions表达式
  • variables in scope from $lookup expressions$lookup表达式范围内的变量

Expressions that do not resolve to a current document, like $myField or $$ROOT, will result in an error.未解析为当前文档的表达式，如$myField或$$ROOT，将导致错误。

Examples示例

MongoDB Shell

Test a Pipeline Stage测试管道阶段

Create testing and debugging data for a pipeline stage without creating test collections.为管道阶段创建测试和调试数据，而不创建测试集合。

db.aggregate(
   [
      { $documents: [ { x: 10 }, { x: 2 }, { x: 5 } ] },
      { $bucketAuto: { groupBy: "$x", buckets: 4 } }
   ]
)

The aggregation expression does not specify a collection. It uses the input data in the highlighted $documents stage as input to the $bucketAuto stage.聚合表达式未指定集合。它使用突出显示的$documents阶段中的输入数据作为$bucketAuto阶段的输入。

[
  { _id: { min: 2, max: 5 }, count: 1 },
  { _id: { min: 5, max: 10 }, count: 1 },
  { _id: { min: 10, max: 10 }, count: 1 }
]

Use a $documents Stage in a $lookup Stage在$lookup阶段中使用$documents阶段

Correlate documents in a collection with other data using $documents to modify $lookup output.使用$documents将集合中的文档与其他数据相关联，以修改$lookup输出。

Create the locations collection.创建locations集合。

db.locations.insertMany(
   [
      { zip: 94301, name: "Palo Alto" },
      { zip: 10019, name: "New York" }
   ]
 )

Use $documents as a data source to transform the documents.使用$documents作为数据源来转换文档。

db.locations.aggregate(
   [
      { $match: {} },
      { $lookup:
         {
            localField: "zip",
            foreignField: "zip_id",
            as: "city_state",
            pipeline:
              [
                 { $documents:
                    [
                       { zip_id: 94301, name: "Palo Alto, CA" },
                       { zip_id: 10019, name: "New York, NY" }
                    ]
                 }
              ]
         }
      }
   ]
 )

The output correlates the data in the locations collection with the values in the $documents pipeline stage.输出将locations集合中的数据与$documents管道阶段中的值相关联。

[
   {
      _id: ObjectId("618949d60f7bfd5f5689490d"),
      zip: 94301,
      name: 'Palo Alto',
      city_state: [ { zip_id: 94301, name: 'Palo Alto, CA' } ]
   },
   {
      _id: ObjectId("618949d60f7bfd5f5689490e"),
      zip: 10019,
      name: 'New York',
      city_state: [ { zip_id: 10019, name: 'New York, NY' } ]
   }
]
  • The zip field corresponds to the zip_id fieldzip（邮编）字段对应于zip_id字段
  • The as parameter creates a new output fieldas参数创建一个新的输出字段
C#

To use the MongoDB .NET/C# driver to add a $documents stage to an aggregation pipeline, call the Documents() method on a PipelineDefinition object.要使用MongoDB NET/C#驱动程序将$documents阶段添加到聚合管道中，请在PipelineDefinition对象上调用Documents()方法。

The following example creates a pipeline stage that creates three documents:以下示例创建了一个管道阶段，该阶段创建了三个文档：

var documentArray = new[]
{
    new BsonDocument {{ "title", "The Shawshank Redemption" }},
    new BsonDocument {{ "title", "Back to the Future" }},
    new BsonDocument {{ "title", "Jurassic Park" }},
};

var pipeline = new EmptyPipelineDefinition<NoPipelineInput>()
    .Documents(documentArray);
Node.js

To use the MongoDB Node.js driver to add a $documents stage to an aggregation pipeline, use the $documents operator in a pipeline object.要使用MongoDB Node.js驱动程序向聚合管道添加$documents阶段，请在管道对象中使用$documents运算符。

The following example creates a pipeline stage that creates three documents. The example then runs the aggregation pipeline:以下示例创建了一个创建三个文档的管道阶段。然后，该示例运行聚合管道：

const pipeline = [
  {
    $documents: [
      { "title": "The Shawshank Redemption" },
      { "title": "Back to the Future" },
      { "title": "Jurassic Park" }
    ]
  }
];

const cursor = collection.aggregate(pipeline);
return cursor;

Learn More了解更多

For details on subqueries using the $lookup syntax, see Correlated Subqueries Using Concise Syntax.有关使用$lookup语法的子查询的详细信息，请参阅使用简明语法的相关子查询。