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

<!--
Tab options on this page. Append to the .md URL to filter:
  ?tabs=<id,...>   select specific tabs (e.g. ?tabs=nodejs,shell)
  ?allTabs=true    include every tab
  (no param)       default: one tab per tabset

Available tabs:
  drivers: shell, csharp, nodejs
-->

# $changeStream (aggregation stage)

## Definition

Returns a [Change Stream](https://www.mongodb.com/docs/manual/changestreams.md#std-label-changeStreams) cursor on a collection, a database, or an entire cluster. Must be used as the first stage in an aggregation pipeline.

The [`$changeStream`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/changestream.md#mongodb-pipeline-pipe.-changeStream) stage has the following syntax:

```text
{
  $changeStream: {
    allChangesForCluster: <boolean>,
    fullDocument: <string>,
    fullDocumentBeforeChange: <string>,
    ignoreRemovedShards: <boolean>,
    resumeAfter: <document>
    showExpandedEvents: <boolean>,
    startAfter: <document>
    startAtOperationTime: <timestamp>
  }
}
```

| Parameter | Description |
| --- | --- |
| `allChangesForCluster` | Optional: Sets whether the change stream should include all changes in the cluster. May only be opened on the `admin` database. |
| `fullDocument` | Optional: Specifies whether change notifications include a copy of the full document when modified by `update` operations. `default`: Change notifications do not include the full document for `update` operations.; `required`: Change notifications includes a copy of the modified document as it appeared immediately after the change. If the document cannot be found, the change stream throws an error.To use this option, you must first use the [`collMod`](https://www.mongodb.com/docs/manual/reference/command/collmod.md#mongodb-dbcommand-dbcmd.collMod) command to enable the `changeStreamPreAndPostImages` option.**New in version 6.0**; `updateLookup`: Change notifications includes a copy of the document modified by the change.  This document is the current majority-committed document or `null` if it no longer exists.; `whenAvailable`: Change notification includes a copy of the modified document as it appeared immediately after the change or `null` if the document is unavailable.To use this option, you must first use the [`collMod`](https://www.mongodb.com/docs/manual/reference/command/collmod.md#mongodb-dbcommand-dbcmd.collMod) command to enable the `changeStreamPreAndPostImages` option.**New in version 6.0** In the case of partial updates, the change notification also provides a description of the change. |
| `fullDocumentBeforeChange` | Include the full document from before the change. This field accepts the following values: `off`: Disables inclusion of the document from before the change.; `whenAvailable`: Includes document from before the change. The query does not fail if the unmodified document is not available.; `required`: Includes document from before the change. The query fails if the unmodified document is not available. |
| `resumeAfter` | Optional. Specifies a [resume token](https://www.mongodb.com/docs/manual/changestreams.md#std-label-change-stream-resume) as the logical starting point for the change stream. Cannot be used to resume the change stream after an [`invalidate`](https://www.mongodb.com/docs/manual/reference/change-events/invalidate.md#mongodb-data-invalidate) event. `resumeAfter` is mutually exclusive with `startAfter` and `startAtOperationTime`. |
| `showExpandedEvents` | Specifies whether to include additional change events, such as such as DDL and index operations. **New in version 6.0** |
| `startAfter` | Optional. Specifies a [resume token](https://www.mongodb.com/docs/manual/changestreams.md#std-label-change-stream-resume) as the logical starting point for the change stream. Unlike `resumeAfter`, `startAfter` can resume notifications after an [`invalidate`](https://www.mongodb.com/docs/manual/reference/change-events/invalidate.md#mongodb-data-invalidate) event by creating a new change stream. `startAfter` is mutually exclusive with `resumeAfter` and `startAtOperationTime`. |
| `startAtOperationTime` | Specifies a time as the logical starting point for the change stream. Cannot be used with `resumeAfter` or `startAfter` fields. |

## Stable API Support

Change streams are included in [Stable API](https://www.mongodb.com/docs/manual/reference/stable-api.md#std-label-stable-api) V1. However, the [showExpandedEvents](https://www.mongodb.com/docs/manual/reference/change-events.md#std-label-change-streams-expanded-events) option is not included in Stable API V1.

## Examples

### MongoDB Shell

To create a change stream cursor using the aggregation stage, run the [`aggregate`](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#mongodb-dbcommand-dbcmd.aggregate) command.

```javascript
var cur = db.names.aggregate( [
   { $changeStream: {} }
] )
```

To open the cursor, run `cur`.

When the change stream detects a change, the `next()` method returns a change event notification. For example, after running `cur.next()`, MongoDB returns a document similar to the following:

```json
{
   "_id": {
      _data: "8262E2EE54000000022B022C0100296E5A100448E5E3DD01364019AE8FE8C6859527E046645F6964006462E2EE54C8756C0D5CF6F0720004"
   },
   "operationType": "insert",
   "clusterTime": Timestamp({ t: 1659039316, i: 2 }),
   "wallTime": ISODate("2022-07-28T20:15:16.148Z"),
   "fullDocument": {
      "_id": ObjectId("62e2ee54c8756c0d5cf6f072"),
      "name": "Walker Percy"
   },
   "ns": {
      "db": "test",
      "coll": "names"
   },
   "documentKey": { _id: ObjectId("62e2ee54c8756c0d5cf6f072") }
}
```

## Learn More

For more information on change stream notifications, see [Change Events.](https://www.mongodb.com/docs/manual/reference/change-events.md#std-label-change-events)

To learn more about related pipeline stages, see the [`$changeStreamSplitLargeEvent`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/changestreamsplitlargeevent.md#mongodb-pipeline-pipe.-changeStreamSplitLargeEvent) guide.