$tsIncrement (aggregation)

Obtain the Incrementing Ordinal from a Timestamp Field

Create a stockSales collection that contains company stock financial market sales:

db.stockSales.insertMany( [
   { _id: 0, symbol: "ABC", saleTimestamp: Timestamp(1622731060, 1) },
   { _id: 1, symbol: "ABC", saleTimestamp: Timestamp(1622731060, 2) },
   { _id: 2, symbol: "DEF", saleTimestamp: Timestamp(1714124193, 1) },
   { _id: 3, symbol: "DEF", saleTimestamp: Timestamp(1714124193, 2) },
   { _id: 4, symbol: "DEF", saleTimestamp: Timestamp(1714124193, 3) }
] )

In the timestamp constructor, the:

• First value is the number of seconds after the Unix epoch.

• Second value is the incrementing ordinal. When multiple events happen within the same second, the incrementing ordinal uniquely identifies each event.

The following example uses $tsIncrement in a $project stage to return the incrementing ordinal from the stock sales saleTimestamp field:

db.stockSales.aggregate( [
   {
      $project:
      {
         _id: 0, saleTimestamp: 1, saleIncrement: { $tsIncrement: "$saleTimestamp" }
      }
   }
] )

In the example, $project only includes the saleTimestamp and saleIncrement fields as shown in the following output:

{
  saleTimestamp: Timestamp({ t: 1622731060, i: 1 }),
  saleIncrement: Long("1")
},
{
  saleTimestamp: Timestamp({ t: 1622731060, i: 2 }),
  saleIncrement: Long("2")
},
{
  saleTimestamp: Timestamp({ t: 1714124193, i: 1 }),
  saleIncrement: Long("1")
},
{
  saleTimestamp: Timestamp({ t: 1714124193, i: 2 }),
  saleIncrement: Long("2")
},
{
  saleTimestamp: Timestamp({ t: 1714124193, i: 3 }),
  saleIncrement: Long("3")
}

Use $tsIncrement in a Change Stream Cursor to Monitor Collection Changes

The example in this section uses $tsIncrement in a change stream cursor to return every other change made to a collection in the same second of time.

Create a change stream cursor on a collection named cakeSales that you will see later in this section:

cakeSalesCursor = db.cakeSales.watch( [
   {
      $match: {
         $expr: {
            $eq: [
               { $mod: [ { $tsIncrement: "$clusterTime" } , 2 ] },
               0
            ]
         }
      }
   }
] )

In the example, the:

• db.collection.watch() method creates a change stream cursor for the cakeSales collection and stores the cursor in cakeSalesCursor.

• $match stage filters the documents to those returned by the $expr operator.

• $expr operator:

  • Applies $mod 2 to the $clusterTime variable's incrementing ordinal returned by $tsIncrement.

    $clusterTime is the timestamp from the oplog entry when the cakeSales collection is modified. See Command Response.

  • Compares the returned value from $mod to 0 using $eq.

Create a cakeSales collection that contains cake sales in the states of California (CA) and Washington (WA):

db.cakeSales.insertMany( [
   { _id: 0, type: "chocolate", orderDate: new Date("2020-05-18T14:10:30Z"),
     state: "CA", price: 13, quantity: 120 },
   { _id: 1, type: "chocolate", orderDate: new Date("2021-03-20T11:30:05Z"),
     state: "WA", price: 14, quantity: 140 },
   { _id: 2, type: "vanilla", orderDate: new Date("2021-01-11T06:31:15Z"),
     state: "CA", price: 12, quantity: 145 },
   { _id: 3, type: "vanilla", orderDate: new Date("2020-02-08T13:13:23Z"),
     state: "WA", price: 13, quantity: 104 },
   { _id: 4, type: "strawberry", orderDate: new Date("2019-05-18T16:09:01Z"),
     state: "CA", price: 41, quantity: 162 },
   { _id: 5, type: "strawberry", orderDate: new Date("2019-01-08T06:12:03Z"),
     state: "WA", price: 43, quantity: 134 }
] )

To monitor the cakeSales collection changes, use cakeSalesCursor. For example, to obtain the next document from cakeSalesCursor, use the next() method:

cakeSalesCursor.next()

Depending on the second when the documents were added to cakeSales, the output from cakeSalesCursor.next() varies. For example, the document additions might span more than one second.

The following cakeSalesCursor.next() example output shows the insert details for the first document added to the cakeSales collection. Notice the incrementing ordinal i is 2 in the clusterTime field.

_id: {
  _data: '82613A4F25000000022B022C0100296E5A100454C5BFAF538C47AB950614F43889BE00461E5F696400290004'
},
operationType: 'insert',
clusterTime: Timestamp({ t: 1631211301, i: 2 }),
fullDocument: {
  _id: 0,
  type: 'chocolate',
  orderDate: ISODate("2020-05-18T14:10:30.000Z"),
  state: 'CA',
  price: 13,
  quantity: 120
},
ns: { db: 'test', coll: 'cakeSales' },
documentKey: { _id: 0 }

Running cakeSalesCursor.next() again returns the cakeSales document for which the clusterTime incrementing ordinal i is 4, omitting the document where i is 3.