Back to DocumentationMQL Documentation

$firstN

The `$firstN` operator returns the first N values in a group according to the group's sorting order. If no sorting order is specified, the order is undefined.

Syntax

{
  $firstN: {
    input: [listOfFields],
    sortBy: {
      <fieldName>: <sortOrder>
    },
    n: <numDocumentsToReturn>
  }
}

Parameters

listOfFieldsobjectrequired

The list of fields to be returned for the first N documents in the result set.

fieldNamestringrequired

The field to use for sorting the result set.

sortOrdernumberrequired

1 or -1. 1 implies ascending order while -1 implies descending order.

nnumberrequired

The number of documents to return from the top of the sorted result set.

Examples

Sample Data

{
  "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4",
  "name": "First Up Consultants | Beverage Shop",
  "sales": {
    "totalSales": 75670,
    "salesByCategory": [
      { "categoryName": "Wine Accessories", "totalSales": 34440 }
    ]
  }
}

Find first two stores by total sales

Get the top two stores by total sales using $firstN accumulator.

This query sorts stores by total sales in descending order and returns the first two.

Query:

db.stores.aggregate([
  {
    $sort: { "sales.totalSales": -1 }
  },
  {
    $group: {
      _id: null,
      topTwoStores: {
        $firstN: {
          n: 2,
          input: {
            storeId: "$_id",
            storeName: "$name",
            totalSales: "$sales.totalSales"
          }
        }
      }
    }
  }
])

Output:

[
  {
    "_id": null,
    "topTwoStores": [
      {
        "storeId": "ffe155dd-caa2-4ac1-8ec9-0342241a84a3",
        "storeName": "Lakeshore Retail | Electronics Stop",
        "totalSales": 399426
      },
      {
        "storeId": "cba62761-10f8-4379-9eea-a9006c667927",
        "storeName": "Fabrikam, Inc. | Electronics Nook",
        "totalSales": 374845
      }
    ]
  }
]

Find first three sales categories

Use $firstN as array expression to find the first three sales categories.

This query projects the first three categories from the salesByCategory array.

Query:

db.stores.aggregate([
  { $match: {"_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74"} },
  {
    $project: {
      name: 1,
      totalSales: "$sales.totalSales",
      firstThreeCategories: {
        $firstN: {
          input: "$sales.salesByCategory",
          n: 3
        }
      }
    }
  }
])

Output:

[
  {
    "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74",
    "name": "Proseware, Inc. | Home Entertainment Hub",
    "totalSales": 165000,
    "firstThreeCategories": [
      { "categoryName": "Sound Bars", "totalSales": 2120 },
      null,
      { "categoryName": "Game Controllers", "totalSales": 43522 }
    ]
  }
]

Related