> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# $tsIncrement  (expression operator)

## Definition

**New in version 5.1**

Returns the incrementing ordinal from a [timestamp](https://www.mongodb.com/docs/manual/reference/bson-types.md#std-label-document-bson-type-timestamp) as a [`long`.](https://www.mongodb.com/docs/manual/reference/mongodb-extended-json-v1.md#mongodb-bsontype-data_numberlong)

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

[`$tsIncrement`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/tsincrement.md#mongodb-expression-exp.-tsIncrement) syntax:

```none
{ $tsIncrement: <expression> }
```

The [expression](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions) must resolve to a [timestamp.](https://www.mongodb.com/docs/manual/reference/bson-types.md#std-label-document-bson-type-timestamp)

**See also:**

- [Expressions](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions)

- [MongoDB BSON Types](https://www.mongodb.com/docs/manual/reference/bson-types.md#std-label-bson-types)

- [`$tsSecond`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/tssecond.md#mongodb-expression-exp.-tsSecond)

## Behavior

[`$tsIncrement`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/tsincrement.md#mongodb-expression-exp.-tsIncrement) returns:

- `Null` if the input [expression](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions) evaluates to `null` or refers to a field that is missing.

- An error if the input [expression](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions) does not evaluate to a [timestamp.](https://www.mongodb.com/docs/manual/reference/bson-types.md#std-label-document-bson-type-timestamp)

## Examples

### Obtain the Incrementing Ordinal from a Timestamp Field

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

```javascript
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](https://www.mongodb.com/docs/manual/reference/bson-types.md#std-label-document-bson-type-timestamp) constructor, the:

- First value is the number of seconds after the [Unix epoch.](https://en.wikipedia.org/wiki/Unix_time)

- 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`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/tsincrement.md#mongodb-expression-exp.-tsIncrement) in a [`$project`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project) stage to return the incrementing ordinal from the stock sales `saleTimestamp` field:

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

In the example, [`$project`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project) only includes the `saleTimestamp` and `saleIncrement` fields as shown in the following output:

```javascript
{
  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`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/tsincrement.md#mongodb-expression-exp.-tsIncrement) in a [change stream cursor](https://www.mongodb.com/docs/manual/changestreams.md#std-label-changeStreams) to return every other change made to a collection in the same second of time.

Create a [change stream cursor](https://www.mongodb.com/docs/manual/changestreams.md#std-label-changeStreams) on a collection named `cakeSales` that you will see later in this section:

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

In the example, the:

- [`db.collection.watch()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.watch.md#mongodb-method-db.collection.watch) method creates a [change stream cursor](https://www.mongodb.com/docs/manual/changestreams.md#std-label-changeStreams) for the `cakeSales` collection and stores the cursor in `cakeSalesCursor`.

- [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) stage filters the documents to those returned by the [`$expr`](https://www.mongodb.com/docs/manual/reference/operator/query/expr.md#mongodb-query-op.-expr) operator.

- [`$expr`](https://www.mongodb.com/docs/manual/reference/operator/query/expr.md#mongodb-query-op.-expr) operator:

  - Applies [`$mod`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/mod.md#mongodb-expression-exp.-mod) `2` to the `$clusterTime` variable's incrementing ordinal returned by [`$tsIncrement`.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/tsincrement.md#mongodb-expression-exp.-tsIncrement)

    `$clusterTime` is the timestamp from the [oplog](https://www.mongodb.com/docs/manual/core/replica-set-oplog.md#std-label-replica-set-oplog) entry when the `cakeSales` collection is modified. See [Command Response.](https://www.mongodb.com/docs/manual/reference/method/db.runcommand.md#std-label-command-response)

  - Compares the returned value from [`$mod`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/mod.md#mongodb-expression-exp.-mod) to `0` using [`$eq`.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/eq.md#mongodb-expression-exp.-eq)

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

```javascript
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()`](https://www.mongodb.com/docs/manual/reference/method/cursor.next.md#mongodb-method-cursor.next) method:

```javascript
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.

```javascript
_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`.