Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

# $facet
<a name="facet"></a>

Nouveau depuis la version 8.0.2.

La phase `$facet` d'agrégation d'Amazon DocumentDB traite plusieurs pipelines d'agrégation au cours d'une seule étape sur le même ensemble de documents d'entrée. Chaque champ de sortie définit son propre pipeline, et chaque pipeline reçoit les mêmes documents d'entrée. Cela vous permet de calculer plusieurs agrégations indépendantes, telles que des comptages, des regroupements et des statistiques récapitulatives, dans une seule requête au lieu d'exécuter la collecte via plusieurs requêtes distinctes.

Chaque sous-pipeline fonctionne indépendamment et produit un tableau de documents qui est stocké dans le champ de sortie correspondant. Étant donné que les sous-pipelines ne partagent pas l'état, la sortie d'un pipeline n'affecte pas un autre.

**Syntaxe**

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

**Paramètres**
+ `outputField`(obligatoire) : nom d'un champ de sortie contenant le tableau de résultats du pipeline d'agrégation associé. Vous pouvez spécifier un ou plusieurs champs de sortie. Chaque champ de sortie correspond à un tableau d'étapes du pipeline d'agrégation qui est appliqué aux documents d'entrée.

**Sortie**

L'`$facet`étape renvoie un seul document. Chaque champ de sortie que vous spécifiez contient un tableau de documents produits par le sous-pipeline correspondant.

**Limites**
+ Un `$facet` sous-pipeline ne peut pas inclure les étapes suivantes : `$changeStream``$collStats`,, `$facet` (l'imbrication n'est pas autorisée) `$geoNear` `$indexStats``$listSearchIndexes`,`$merge`,,`$out`, `$planCacheStats` `$search``$searchMeta`, et. `$vectorSearch`
+ Le document renvoyé par la `$facet` scène doit rester dans la limite de taille du document BSON de 16 Mo.
+ Une `$sort` étape qui précède une `$facet` étape ne peut pas déterminer l'ordre d'un accumulateur sensible à l'ordre (`$first``$last`,`$push`,`$firstN`,`$lastN`, ou`$mergeObjects`) dans une `$bucketAuto` étape `$group``$bucket`, ou lorsque cet ordre devrait être appliqué au-delà de la limite. `$facet` Cela s'applique que l'étape de regroupement se trouve à l'intérieur d'un `$facet` sous-pipeline ou après l'`$facet`étape. Dans ce cas, Amazon DocumentDB renvoie une erreur au lieu d'exécuter le pipeline. Pour commander un tel accumulateur, placez l'`$sort`étage à l'intérieur du `$facet` sous-pipeline, juste avant l'étape de regroupement. Order-insensitive les accumulateurs, tels que`$sum`,`$min`, et `$max``$count`, ne sont pas affectés.

## Exemple (MongoDB Shell)
<a name="facet-examples"></a>

L'exemple suivant montre comment utiliser le `$facet` stage pour calculer plusieurs agrégations sur les mêmes données de vente dans une seule requête.

**Créez des exemples de documents **

```
db.sales.insertMany([
  { item: "abc", price: 10, quantity: 2, date: new Date("2020-09-01") },
  { item: "def", price: 20, quantity: 1, date: new Date("2020-10-01") },
  { item: "ghi", price: 5, quantity: 3, date: new Date("2020-11-01") },
  { item: "jkl", price: 15, quantity: 2, date: new Date("2020-12-01") },
  { item: "abc", price: 25, quantity: 1, date: new Date("2021-01-01") }
]);
```

**Exemple de requête **

La commande suivante permet `$facet` de calculer, en une seule étape, la quantité totale vendue par article, les statistiques de prix globales et le nombre total de documents :

```
db.sales.aggregate([
  {
    $facet: {
      "totalByItem": [
        { $group: { _id: "$item", totalQuantity: { $sum: "$quantity" } } }
      ],
      "priceStats": [
        { $group: { _id: null, avgPrice: { $avg: "$price" }, maxPrice: { $max: "$price" } } }
      ],
      "documentCount": [
        { $count: "total" }
      ]
    }
  }
])
```

**Sortie**

La commande renvoie le résultat suivant :

```
[
  {
    totalByItem: [
      { _id: "abc", totalQuantity: 3 },
      { _id: "def", totalQuantity: 1 },
      { _id: "ghi", totalQuantity: 3 },
      { _id: "jkl", totalQuantity: 2 }
    ],
    priceStats: [
      { _id: null, avgPrice: 15, maxPrice: 25 }
    ],
    documentCount: [
      { total: 5 }
    ]
  }
]
```

## Exemples de code
<a name="facet-code"></a>

Pour afficher un exemple de code d'utilisation de la `$facet` commande, choisissez l'onglet correspondant à la langue que vous souhaitez utiliser :

------
#### [ Node.js ]

```
const { MongoClient } = require('mongodb');

async function example() {
  const client = await MongoClient.connect('mongodb://<username>:<password>@<cluster-endpoint>:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false');
  const db = client.db('test');
  const sales = db.collection('sales');

  const result = await sales.aggregate([
    {
      $facet: {
        "totalByItem": [
          { $group: { _id: "$item", totalQuantity: { $sum: "$quantity" } } }
        ],
        "priceStats": [
          { $group: { _id: null, avgPrice: { $avg: "$price" }, maxPrice: { $max: "$price" } } }
        ],
        "documentCount": [
          { $count: "total" }
        ]
      }
    }
  ]).toArray();

  console.log(result);
  client.close();
}

example();
```

------
#### [ Python ]

```
from pymongo import MongoClient

def example():
    client = MongoClient('mongodb://<username>:<password>@<cluster-endpoint>:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false')
    db = client['test']
    sales = db['sales']

    result = list(sales.aggregate([
        {
            '$facet': {
                'totalByItem': [
                    {'$group': {'_id': '$item', 'totalQuantity': {'$sum': '$quantity'}}}
                ],
                'priceStats': [
                    {'$group': {'_id': None, 'avgPrice': {'$avg': '$price'}, 'maxPrice': {'$max': '$price'}}}
                ],
                'documentCount': [
                    {'$count': 'total'}
                ]
            }
        }
    ]))

    print(result)
    client.close()

example()
```

------