Docs Menu
Docs Home
/
MongoDB Manual
/ / /

$tsIncrement (aggregation)

On this page

  • Definition
  • Behavior
  • Examples
$tsIncrement

New in version 5.1.

Returns the incrementing ordinal from a timestamp as a long.

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

$tsIncrement syntax:

{ $tsIncrement: <expression> }

The expression must resolve to a timestamp.

Tip

See also:

$tsIncrement returns:

  • Null if the input expression evaluates to null or refers to a field that is missing.

  • An error if the input expression does not evaluate to a timestamp.

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

db.stockSales.insertMany( [
{ _id: 0, symbol: "MDB", saleTimestamp: Timestamp(1622731060, 1) },
{ _id: 1, symbol: "MDB", saleTimestamp: Timestamp(1622731060, 2) },
{ _id: 2, symbol: "MSFT", saleTimestamp: Timestamp(1714124193, 1) },
{ _id: 3, symbol: "MSFT", saleTimestamp: Timestamp(1714124193, 2) },
{ _id: 4, symbol: "MSFT", 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")
}

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:

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.

Back

$toUUID