$first (aggregation)

On this page

Definition

Syntax
Behaviors
Examples

This version of the documentation is archived and no longer supported. View the current documentation to learn how to upgrade your version of MongoDB.

Definition

$first

Returns the value that results from applying an expression to the first document in a group of documents that share the same group by key. Only meaningful when documents are in a defined order.

$first is only available in the $group stage.

Syntax

$first syntax:

{ $first: <expression> }

Behaviors

Defining Document Order

To define the document order for $first in a pipeline stage, add a preceding $sort stage.

Array Operator

If the expression resolves to an array:

When using $first in a $group stage, the output value depends on the order of the documents coming into pipeline. To guarantee a defined order, the $group pipeline stage should follow a $sort stage.

Missing Values

Documents in a group may be missing fields or may have fields with missing values.

If there are no documents from the prior pipeline stage, the $group stage returns nothing.
If the field that the $first accumulator is processing is missing, $first returns null.

For more information, see the Missing Data example later in this topic.

Examples

Use in `$group` Stage

Create the sales collection:

db.sales.insertMany( [
   { "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-01-01T08:00:00Z") },
   { "_id" : 2, "item" : "jkl", "price" : 20, "quantity" : 1, "date" : ISODate("2014-02-03T09:00:00Z") },
   { "_id" : 3, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2014-02-03T09:05:00Z") },
   { "_id" : 4, "item" : "abc", "price" : 10, "quantity" : 10, "date" : ISODate("2014-02-15T08:00:00Z") },
   { "_id" : 5, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2014-02-15T09:05:00Z") },
   { "_id" : 6, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2014-02-15T12:05:10Z") },
   { "_id" : 7, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2014-02-15T14:12:12Z") }
] )

Grouping the documents by the item field, the following operation uses the $first accumulator to return the first sales date for each item:

db.sales.aggregate(
   [
     { $sort: { item: 1, date: 1 } },
     {
       $group:
         {
           _id: "$item",
           firstSale: { $first: "$date" }
         }
     }
   ]
)

The operation returns the following results:

[
   { _id: 'jkl', firstSale: ISODate("2014-02-03T09:00:00.000Z") },
   { _id: 'xyz', firstSale: ISODate("2014-02-03T09:05:00.000Z") },
   { _id: 'abc', firstSale: ISODate("2014-01-01T08:00:00.000Z") }
]

Missing Data

Some documents in the badData collection are missing fields, other documents are missing values.

Create the badData collection:

db.badData.insertMany( [
   { "_id": 1, "price": 6, "quantity": 6 },
   { "_id": 2, "item": "album", "price": 5 , "quantity": 5  },
   { "_id": 7, "item": "tape", "price": 6, "quantity": 6 },
   { "_id": 8, "price": 5, "quantity": 5  },
   { "_id": 9, "item": "album", "price": 3, "quantity": '' },
   { "_id": 10, "item": "tape", "price": 3, "quantity":  4 },
   { "_id": 12, "item": "cd", "price": 7  }
] )

Query the badData collection, grouping the output on the item field:

db.badData.aggregate( [
   { $sort: { item: 1, price: 1 } },
   { $group:
      {
         _id: "$item",
         inStock: { $first: "$quantity" }
      }
   }
] )

The $sort stage orders the documents and passes them to the $group stage.

[
  { _id: null, inStock: 5 },
  { _id: 'album', inStock: '' },
  { _id: 'cd', inStock: null },
  { _id: 'tape', inStock: 4 }
]

$first selects the first document from each output group:

The _id: null group is included.
When the accumulator field, $quantity in this example, is missing, $first returns null.

Back

$filter (aggregation)

$first (array operator)