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.

# $first N
<a name="firstN"></a>

Nouveau depuis la version 8.0.1.

L'`$firstN`opérateur d'Amazon DocumentDB renvoie les N premiers éléments. Lorsqu'il est utilisé comme accumulateur dans une `$group` étape, il renvoie un tableau des N premières valeurs de chaque groupe. Lorsqu'il est utilisé comme opérateur d'expression de tableau, il renvoie les N premiers éléments d'un tableau.

**Paramètres**
+ `input`: expression qui renvoie au champ ou au tableau à partir duquel les valeurs doivent être renvoyées.
+ `n`: entier positif qui indique le nombre de valeurs à renvoyer. Lorsqu'il est utilisé comme accumulateur dans une `$group` étape, il `n` peut également s'agir d'une expression, à condition qu'elle soit résolue en un entier positif en fonction du `_id` champ de groupe.

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

L'exemple suivant montre comment utiliser l'`$firstN`accumulateur pour récupérer les deux premières quantités pour chaque article lors de l'agrégation.

**Note**  
`$firstN`sélectionne les valeurs dans l'ordre dans lequel les documents arrivent sur `$group` scène. Pour renvoyer les N premières valeurs pour un ordre spécifique (par exemple, par date ou score), ajoutez une `$sort` étape avant`$group`.

**Créez des exemples de documents **

```
db.sales.insertMany([
  { item: "abc", quantity: 10, date: ISODate("2023-01-01") },
  { item: "abc", quantity: 5, date: ISODate("2023-01-02") },
  { item: "abc", quantity: 8, date: ISODate("2023-01-03") },
  { item: "xyz", quantity: 15, date: ISODate("2023-01-01") },
  { item: "xyz", quantity: 7, date: ISODate("2023-01-02") },
  { item: "xyz", quantity: 3, date: ISODate("2023-01-03") }
]);
```

**Exemple de requête **

```
db.sales.aggregate([
  { $group: { _id: "$item", firstTwoQuantities: { $firstN: { input: "$quantity", n: 2 } } } }
]);
```

**Sortie**

```
[
  { "_id": "abc", "firstTwoQuantities": [10, 5] },
  { "_id": "xyz", "firstTwoQuantities": [15, 7] }
]
```

## Exemple d'utilisation d'expressions (MongoDB Shell)
<a name="firstN-expression-examples"></a>

L'`$firstN`opérateur peut également être utilisé comme expression au sein d'une `$project` étape pour renvoyer les N premiers éléments d'un champ de tableau.

**Créez des exemples de documents **

```
db.inventory.insertMany([
  { _id: 1, item: "abc", tags: ["red", "green", "blue", "yellow", "purple"] },
  { _id: 2, item: "xyz", tags: ["alpha", "beta", "gamma"] }
]);
```

**Exemple de requête **

```
db.inventory.aggregate([
  { $project: {
      firstThreeTags: { $firstN: { input: "$tags", n: 3 } }
    }}
]);
```

**Sortie**

```
[
  { "_id": 1, "firstThreeTags": ["red", "green", "blue"] },
  { "_id": 2, "firstThreeTags": ["alpha", "beta", "gamma"] }
]
```

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

Pour afficher un exemple de code d'utilisation de l'`$firstN`accumulateur, choisissez l'onglet correspondant à la langue que vous souhaitez utiliser. Les exemples suivants montrent à la fois l'utilisation de l'accumulateur (in`$group`) et l'utilisation de l'expression (in`$project`) :

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

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

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

  try {
    await client.connect();
    const db = client.db('test');

    // Accumulator usage: first N values per group
    const sales = db.collection('sales');
    const accumulatorResult = await sales.aggregate([
      { $group: { _id: "$item", firstTwoQuantities: { $firstN: { input: "$quantity", n: 2 } } } }
    ]).toArray();
    console.log('Accumulator result:', accumulatorResult);

    // Expression usage: first N elements of an array field
    const inventory = db.collection('inventory');
    const expressionResult = await inventory.aggregate([
      { $project: { firstThreeTags: { $firstN: { input: "$tags", n: 3 } } } }
    ]).toArray();
    console.log('Expression result:', expressionResult);

  } finally {
    await 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')

    try:
        db = client['test']

        # Accumulator usage: first N values per group
        sales = db['sales']
        accumulator_result = list(sales.aggregate([
            { '$group': { '_id': '$item', 'firstTwoQuantities': { '$firstN': { 'input': '$quantity', 'n': 2 } } } }
        ]))
        print('Accumulator result:', accumulator_result)

        # Expression usage: first N elements of an array field
        inventory = db['inventory']
        expression_result = list(inventory.aggregate([
            { '$project': { 'firstThreeTags': { '$firstN': { 'input': '$tags', 'n': 3 } } } }
        ]))
        print('Expression result:', expression_result)

    finally:
        client.close()

example()
```

------