$分面（Facet）（聚合阶段）

定义

$facet

在单个阶段内处理同一组输入文档上的多个聚合管道。每个子管道在输出文档中都有自己的字段，其结果存储为文档数组。

$facet 阶段支持创建多分面聚合，能够在单个聚合阶段跨多个维度或分面描述数据特征。多分面聚合提供多个过滤器和分类方式来指导数据浏览和分析。零售商通常利用分面来创建产品价格、制造商、尺寸等过滤器以缩小搜索结果范围。

输入文档仅传递到 $facet 阶段一次，从而可以对同一组输入文档进行各种聚合。

兼容性

可以使用 $facet 查找托管在以下环境中的部署：

MongoDB Atlas：用于云中 MongoDB 部署的完全托管服务

MongoDB Enterprise：基于订阅、自我管理的 MongoDB 版本
MongoDB Community：源代码可用、免费使用且可自行管理的 MongoDB 版本

语法

$facet 阶段具有以下形式：

{ $facet:    {      <outputField1>: [ <stage1>, <stage2>, ... ],      <outputField2>: [ <stage1>, <stage2>, ... ],      ...
    }}

为每个指定管道指定输出字段名称。

Considerations

执行 $facet 中的每个阶段时，生成的文档限制为 100 MB。请注意，allowDiskUse 标记不会影响 100 MB 的大小限制，因为 $facet 不会溢出到磁盘。

如果 $facet 阶段构造的 document 大小超过 100 兆字节限制，MongoDB将返回ExceededMemoryLimit 错误。

最终输出文档受 16 MiB 的 BSON 文档大小限制。如果超过 16 MiB，此聚合会产生错误。

提示

聚合管道限制

行为

与分面相关的聚合阶段对传入文档进行分类和分组。在不同的 $facet 子管道的 <stage> 中指定以下任何与分面相关的阶段，以执行多分面聚合：

其他聚合阶段也可以与 $facet 一起使用，但以下情况除外：

$facet 内的每个子管道都会被传递完全相同的输入文档集。这些子管道彼此完全独立，每个子管道输出的文档数组都存储在输出文档的单独字段中。在同一 $facet 阶段中，一个子管道的输出不能用作另一子管道的输入。如需进一步聚合，请在 $facet 之后添加附加阶段，并指定所需子管道输出的字段名 <outputField>。

索引使用

管道顺序决定了 $facet 阶段使用索引的方式。

如果 $facet 阶段是管道中的第一个阶段，则该阶段将执行 COLLSCAN。如果 $facet 阶段是管道中的第一个阶段，则不使用索引。
如果 $facet 阶段出现在管道中较晚的阶段，并且较早的阶段已使用索引，则 $facet 在执行期间不会触发 COLLSCAN。

例如，在 $facet 阶段之前的 $match 或 $sort 阶段可以使用索引，而 $facet 不会触发 COLLSCAN。

有关优化建议，请参阅聚合管道优化。

示例

本页上的示例使用来自 sample_mflix 数据集的数据。有关如何将此数据集加载到您的自管理 MongoDB 部署中的详细信息，请参阅加载示例数据集。如果您对示例数据库进行了任何修改，您可能需要删除并重新创建数据库，才能运行此页面上的示例。

以下聚合管道使用 movies集合在多个dimensions对电影进行分类。$match 阶段将 input 限制为运行时间大于 1 000 分钟的电影。$facet 阶段使用 $sortByCount、$bucket 和 $bucketAuto 并行运行三个子管道。MongoDB仅在操作开始时从 movies集合中获取input document一次：

db.movies.aggregate( [  { $match: { runtime: { $gt: 1000 } } },  {    $facet: {      "categorizedByGenres": [        { $unwind: "$genres" },        { $sortByCount: "$genres" }      ],      "categorizedByRuntime": [        {          $bucket: {            groupBy: "$runtime",            boundaries: [ 1000, 1200, 1400 ],            default: "Other",            output: {              "count": { $sum: 1 },              "titles": { $push: "$title" }            }          }        }      ],      "categorizedByYear(Auto)": [        {          $bucketAuto: {            groupBy: "$year",            buckets: 4          }        }      ]    }  }] )

[  {    categorizedByGenres: [      { _id: 'Sport', count: 1 },      { _id: 'Documentary', count: 1 },      { _id: 'Action', count: 1 },      { _id: 'Drama', count: 1 },      { _id: 'Adventure', count: 1 },      { _id: 'History', count: 1 }    ],    categorizedByRuntime: [      { _id: 1000, count: 1, titles: [ 'Baseball' ] },      { _id: 1200, count: 1, titles: [ 'Centennial' ] }    ],    'categorizedByYear(Auto)': [      { _id: { min: 1978, max: 1994 }, count: 1 },      { _id: { min: 1994, max: 1994 }, count: 1 }    ]  }]

本页上的C#示例使用Atlas示例数据集中的 sample_mflix数据库。要学习；了解如何创建免费的MongoDB Atlas 群集并加载示例数据集，请参阅MongoDB .NET/ C#驱动程序文档中的入门。

以下 Movie 类对 sample_mflix.movies 集合中的文档进行建模：

[BsonIgnoreExtraElements]public class Movie{    [BsonId]    public ObjectId Id { get; set; }    [BsonElement("title")]    public string Title { get; set; } = null!;    [BsonElement("year")]    public int? Year { get; set; }    [BsonElement("runtime")]    public int? Runtime { get; set; }    [BsonElement("rated")]    public string? Rated { get; set; }    [BsonElement("metacritic")]    public int Metacritic { get; set; }    [BsonElement("plot")]    public string? Plot { get; set; }    [BsonElement("type")]    public string? Type { get; set; }    [BsonElement("cast")]    public string[]? Cast { get; set; }    [BsonElement("directors")]    public string[]? Directors { get; set; }    [BsonElement("writers")]    public string[]? Writers { get; set; }    [BsonElement("imdb")]    public ImdbData? Imdb { get; set; }}

要使用MongoDB .NET/C# 驱动程序将 $facet 阶段添加到聚合管道，请对 PipelineDefinition 对象调用 UnionWith() 方法。

以下示例创建了一个执行两个并行聚合的管道阶段。第一个聚合根据传入文档的 Runtime字段值将其分成五组。第二个聚合对 Rated字段中的每个值进行计数，并返回每个值的计数，但仅限于前五个值。

var bucketPipeline = new EmptyPipelineDefinition<Movie>()    .BucketAuto(        groupBy: m => m.Runtime,        buckets: 5);var bucketFacet = AggregateFacet.Create(    name: "Runtimes",    pipeline: bucketPipeline);
var countLimitPipeline = new EmptyPipelineDefinition<Movie>()    .SortByCount(m => m.Rated)    .Limit(5);var countFacet = AggregateFacet.Create(    "Ratings", countLimitPipeline);
var pipeline = new EmptyPipelineDefinition<Movie>()    .Facet(bucketFacet, countFacet);

{  "Runtimes": [    { "_id": { "min": null, "max": 89 }, "count": 4574 },    { "_id": { "min": 89, "max": 97 }, "count": 4539 },    { "_id": { "min": 97, "max": 106 }, "count": 4502 },    { "_id": { "min": 106, "max": 121 }, "count": 4421 },    { "_id": { "min": 121, "max": 1256 }, "count": 3313 }  ],  "Ratings": [    { "_id": null, "count": 9894 },    { "_id": "R", "count": 5537 },    { "_id": "PG-13", "count": 2321 },    { "_id": "PG", "count": 1852 },    { "_id": "APPROVED", "count": 709 }  ]}

本页上的 Node.js 示例使用 Atlas 示例数据集中的 sample_mflix数据库。要学习如何创建免费的MongoDB Atlas 集群并加载示例数据集，请参阅MongoDB Node.js驱动程序文档中的入门。

要使用MongoDB Node.js驱动程序将 $facet 阶段添加到聚合管道，请在管道对象中使用 $facet操作符。

以下示例创建了一个执行两个并行聚合的管道阶段。第一个聚合使用$bucketAuto阶段根据 runtime字段的值将传入文档分为五组。第二个聚合对 rated字段中的每个值进行计数，并使用 $sortByCount 和 $limit 阶段返回前五个值的计数。然后，该示例运行聚合管道：

const pipeline = [  {    $facet: {      bucketPipeline: [        {          $bucketAuto: {            groupBy: "$runtime",            buckets: 5          }        }      ],      countLimit: [        { $sortByCount: "$rated" },        { $limit: 5 }      ]    }  }];
const cursor = collection.aggregate(pipeline);return cursor;

了解详情

要学习；了解有关相关管道阶段的更多信息，请参阅 $bucketAuto、$sortByCount 和 $limit 指南。