/ /

$facet (etapa de agregación)

Definición

$facet

Procesa múltiples canalizaciones de agregación dentro de una sola etapa en el mismo conjunto de documentos de entrada. Cada sub-pipeline tiene su propio campo en el documento de salida donde sus resultados se almacenan como un arreglo de documentos.

La etapa $facet le permite crear agregaciones multifacéticas que caracterizan los datos a través de múltiples dimensiones, o facetas, dentro de una única etapa de agregación. Las agregaciones multifacéticas ofrecen múltiples filtros y categorizaciones para orientar la exploración y el análisis de datos. Los minoristas suelen utilizar el facetado para acotar los resultados de búsqueda creando filtros en función del precio del producto, el fabricante, el tamaño, etc.

Los documentos de entrada se pasan a la fase $facet sólo una vez, permitiendo realizar varias agregaciones en el mismo conjunto de documentos de entrada.

Compatibilidad

Puedes usar $facet para implementaciones alojadas en los siguientes entornos:

MongoDB Atlas: El servicio totalmente administrado para implementaciones de MongoDB en la nube.

MongoDB Enterprise: La versión basada en suscripción y autogestionada de MongoDB
MongoDB Community: La versión de MongoDB con código fuente disponible, de uso gratuito y autogestionada.

Sintaxis

La etapa $facet tiene la siguiente forma:

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

Especifica el nombre del campo de salida para cada pipeline especificado.

Considerations

A medida que se ejecuta cada etapa en un $facet, el documento resultante está limitado a 100 megabytes. Ten en cuenta que la bandera allowDiskUse no afecta el límite de tamaño de 100 megabytes, ya que $facet no puede volcarse en el disco.

El documento de salida final está sujeto al límite de tamaño de documento BSON de 16 mebibytes. Si se superan los 16 mebibytes, la agregación genera un error.

Tip

Límites de la canalización de agregación

Comportamiento

Las etapas de agregación relacionadas con facetas categorizan y agrupan los documentos entrantes. Especifica cualquiera de las siguientes etapas relacionadas con facetas dentro de los diferentes sub-pipelines $facet <stage> para realizar una agregación multifacética:

Otras etapas de agregación también pueden usarse con $facet con las siguientes excepciones:

Cada sub-pipeline dentro de $facet recibe exactamente el mismo conjunto de documentos de entrada. Estas sub-pipelines son completamente independientes entre sí y el arreglo de documentos generado por cada una se almacena en campos separados en el documento de salida. La salida de un sub-pipeline no puede usarse como entrada para un sub-pipeline diferente dentro de la misma etapa $facet. Si se requieren agregaciones adicionales, añade etapas adicionales después de $facet y especifica el nombre del campo, <outputField>, de la salida deseada del sub-pipeline.

Uso del índice

El orden del pipeline determina cómo la etapa $facet utiliza los índices.

Si la etapa $facet es la primera etapa de un pipeline, la etapa realizará un COLLSCAN. La etapa $facet no utiliza índices si es la primera etapa en el pipeline.
Si la etapa $facet llega más adelante en el pipeline y las etapas anteriores han utilizado índices, $facet no activará un COLLSCAN durante la ejecución.

Por ejemplo, $match o $sort etapas que vienen antes de una etapa $facet pueden hacer uso de índices y el $facet no activará un COLLSCAN.

Para obtener sugerencias de optimización, consulta: Optimización de la canalización de agregación.

Ejemplos

Los ejemplos de esta página utilizan datos del conjunto de datos sample_mflix. Para obtener más información sobre cómo cargar este conjunto de datos en la implementación autogestionada de MongoDB, consultar Cargar el conjunto de datos de muestra. Si realizó alguna modificación en las bases de datos de muestra, es posible que deba descartar y volver a crear las bases de datos para ejecutar los ejemplos de esta página.

La siguiente pipeline de agregación utiliza la colección movies para categorizar películas en múltiples dimensions. Un $match escenario limita el input a películas con una duración superior a 1,000 minutos. La etapa $facet ejecuta tres sub-pipelines en paralelo usando $sortByCount, $bucket y $bucketAuto. MongoDB recupera los documents de input de la colección movies solo una vez, al inicio de la operación:

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

Los ejemplos de C# de esta página utilizan la base de datos sample_mflix de los conjuntos de datos de ejemplo de Atlas. Para aprender a crear un clúster gratuito de MongoDB Atlas y cargar los conjuntos de datos de ejemplo, consulte la sección «Primeros pasos» en la documentación del controlador MongoDB.NET/C#.

La siguiente clase Movie modela los documentos en la colección 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; }
}

Para usar el controlador MongoDB.NET/C# para agregar una etapa $facet a una canalización de agregación, llame al método UnionWith() en un objeto PipelineDefinition.

El siguiente ejemplo crea una etapa del pipeline que ejecuta dos agregaciones paralelas. La primera agregación distribuye los documentos entrantes en cinco grupos por el valor de su campo Runtime. La segunda agregación cuenta cada valor en el campo Rated y devuelve el recuento de cada valor, limitado a los cinco valores principales.

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

Los ejemplos de Node.js de esta página utilizan la base de datos sample_mflix de los conjuntos de datos de ejemplo de Atlas. Para aprender a crear un clúster gratuito de MongoDB Atlas y cargar los conjuntos de datos de ejemplo, consulte la sección «Primeros pasos» en la documentación del controlador de MongoDB para Node.js.

Para utilizar el controlador de MongoDB Node.js para agregar una etapa de $facet a una canalización de agregación, utilice el Operador $facet en un objeto de canalización.

El siguiente ejemplo crea una etapa del pipeline que ejecuta dos agregaciones paralelas. La primera agregación distribuye los documentos entrantes en cinco grupos según el valor de su campo runtime utilizando la etapa $bucketAuto. La segunda agregación cuenta cada valor en el campo rated y devuelve el recuento de los cinco valores principales utilizando las etapas $sortByCount y $limit. A continuación, el ejemplo ejecuta la canalización de agregación:

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

Obtén más información

Para obtener más información sobre las etapas relacionadas del pipeline, consulta las guías $bucketAuto, $sortByCount y $limit.

Volver

$documents

$fill