> 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
-->

# $changeStreamSplitLargeEvent (aggregation stage)

## Definition

*New in MongoDB 7.0 (and 6.0.9).*

If a [change stream](https://www.mongodb.com/docs/manual/changestreams.md#std-label-changeStreams) has large events that exceed 16 MB, a `BSONObjectTooLarge` exception is returned. Starting in MongoDB 7.0 (and 6.0.9), you can use a `$changeStreamSplitLargeEvent` stage to split the events into smaller fragments.

You should only use `$changeStreamSplitLargeEvent` when strictly necessary. For example, if your application requires full document pre- or post-images, and generates large events that exceed 16 MB, use `$changeStreamSplitLargeEvent`.

Before you decide to use `$changeStreamSplitLargeEvent`, you should first try to reduce the change event size. For example:

- Don't request document pre- or post-images unless your application requires them. This generates `fullDocument` and `fullDocumentBeforeChange` fields in more cases, which are typically the largest objects in a change event.

- Use a [`$project`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project) stage to include only the fields necessary for your application. This reduces the change event size and avoids the additional time to split large events into fragments. This allows more change events to be returned in each batch.

You can only have one `$changeStreamSplitLargeEvent` stage in your pipeline, and it must be the last stage. You can only use `$changeStreamSplitLargeEvent` in a `$changeStream` pipeline.

`$changeStreamSplitLargeEvent` syntax:

```javascript
{
  $changeStreamSplitLargeEvent: {}
}
```

## Behavior

`$changeStreamSplitLargeEvent` splits events that exceed 16 MB into fragments and returns the fragments sequentially using the change stream cursor.

The fragments are split so that the maximum number of fields are returned in the first fragment. This ensures the event context is returned as quickly as possible.

When the change event is split, only the size of top-level fields are used. `$changeStreamSplitLargeEvent` does not recursively process or split subdocuments. For example, if you use a `$project` stage to create a change event with a single field that is 20 MB in size, the event is not split and the stage returns an error.

Each fragment has a resume token. A stream that is resumed using a fragment's token will either:

- Begin a new stream from the subsequent fragment.

- Start at the next event if resuming from the final fragment in the sequence.

Each fragment for an event includes a `splitEvent` document:

```javascript
splitEvent: {
   fragment: <int>,
   of: <int>
}
```

The following table describes the fields.

| Field | Description |
| --- | --- |
| `fragment` | Fragment index, starting at 1. |
| `of` | Total number of fragments for the event. |

## Examples

### MongoDB Shell

The example scenario in this section shows the use of `$changeStreamSplitLargeEvent` with a new collection named `myCollection`.

Create `myCollection` and insert one document with just under 16 MB of data:

```javascript
db.myCollection.insertOne(
   { _id: 0, largeField: "a".repeat( 16 * 1024 * 1024 - 1024 ) }
)
```

`largeField` contains the repeated letter `a`.

Enable [changeStreamPreAndPostImages](https://www.mongodb.com/docs/manual/reference/command/collmod.md#std-label-collMod-change-stream-pre-and-post-images) for `myCollection`, which allows a change stream to retrieve a document as it was before an update (pre-image) and after an update (post-image):

```javascript
db.runCommand( {
   collMod: "myCollection",
   changeStreamPreAndPostImages: { enabled: true }
} )
```

Create a change stream cursor to monitor changes to `myCollection` using [`db.collection.watch()`:](https://www.mongodb.com/docs/manual/reference/method/db.collection.watch.md#mongodb-method-db.collection.watch)

```javascript
myChangeStreamCursor = db.myCollection.watch(
   [ { $changeStreamSplitLargeEvent: {} } ],
   { fullDocument: "required", fullDocumentBeforeChange: "required" }
)
```

For the change stream event:

- `fullDocument: "required"` includes the document post-image.

- `fullDocumentBeforeChange: "required"` includes the document pre-image.

For details, see [`$changeStream`.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/changestream.md#mongodb-pipeline-pipe.-changeStream)

Update the document in `myCollection`, which also produces a change stream event with the document pre- and post-images:

```javascript
db.myCollection.updateOne(
   { _id: 0 },
   { $set: { largeField: "b".repeat( 16 * 1024 * 1024 - 1024 ) } }
)
```

`largeField` now contains the repeated letter `b`.

Retrieve the fragments from `myChangeStreamCursor` using the [`next()`](https://www.mongodb.com/docs/manual/reference/method/cursor.next.md#mongodb-method-cursor.next) method and store the fragments in objects named `firstFragment`, `secondFragment`, and `thirdFragment`:

```javascript
const firstFragment = myChangeStreamCursor.next()
const secondFragment = myChangeStreamCursor.next()
const thirdFragment = myChangeStreamCursor.next()
```

Show `firstFragment.splitEvent`:

```javascript
firstFragment.splitEvent
```

Output with the fragment details:

```javascript
splitEvent: { fragment: 1, of: 3 }
```

Similarly, `secondFragment.splitEvent` and `thirdFragment.splitEvent` return:

```javascript
splitEvent: { fragment: 2, of: 3 }
splitEvent: { fragment: 3, of: 3 }
```

To examine the object keys for `firstFragment`:

```javascript
Object.keys( firstFragment )
```

Output:

```javascript
[
   '_id',
   'splitEvent',
   'wallTime',
   'clusterTime',
   'operationType',
   'documentKey',
   'ns',
   'fullDocument'
]
```

To examine the size in bytes for `firstFragment.fullDocument`:

```javascript
bsonsize( firstFragment.fullDocument )
```

Output:

```javascript
16776223
```

`secondFragment` contains the `fullDocumentBeforeChange` pre-image, which is approximately 16 MB in size. The following example shows the object keys for `secondFragment`:

```javascript
Object.keys( secondFragment )
```

Output:

```javascript
[ '_id', 'splitEvent', 'fullDocumentBeforeChange' ]
```

`thirdFragment` contains the `updateDescription` field, which is approximately 16 MB in size. The following example shows the object keys for `thirdFragment`:

```javascript
Object.keys( thirdFragment )
```

Output:

```javascript
[ '_id', 'splitEvent', 'updateDescription' ]
```

## 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 [`$changeStream`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/changestream.md#mongodb-pipeline-pipe.-changeStream) guide.