> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # db.createCollection() (mongosh method) ## Definition Creates a new collection. For [views](https://www.mongodb.com/docs/manual/core/views.md#std-label-views-landing-page), see [`db.createView()`.](https://www.mongodb.com/docs/manual/reference/method/db.createView.md#mongodb-method-db.createView) MongoDB creates a collection implicitly when you first reference it in a command. Use `db.createCollection()` primarily to create collections that use specific options, including: - [Capped collection.](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-capped-collection) - [Clustered collection.](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-clustered-collection) - New collection that uses [schema validation.](https://www.mongodb.com/docs/manual/core/schema-validation.md#std-label-schema-validation-overview) `db.createCollection()` is a wrapper around the database command [`create`.](https://www.mongodb.com/docs/manual/reference/command/create.md#mongodb-dbcommand-dbcmd.create) ## Compatibility This method is available in deployments hosted in the following environments: - [MongoDB Atlas](https://www.mongodb.com/docs/atlas): The fully managed service for MongoDB deployments in the cloud **Note:** This command is supported in all MongoDB Atlas clusters. For information on Atlas support for all commands, see [Unsupported Commands.](https://www.mongodb.com/docs/atlas/unsupported-commands/) - [MongoDB Enterprise](https://www.mongodb.com/docs/manual/administration/install-enterprise.md#std-label-install-mdb-enterprise): The subscription-based, self-managed version of MongoDB - [MongoDB Community](https://www.mongodb.com/docs/manual/administration/install-community.md#std-label-install-mdb-community-edition): The source-available, free-to-use, and self-managed version of MongoDB ## Syntax The `db.createCollection()` method has the following prototype form: ```javascript db.createCollection( , { capped: , timeseries: { // Added in MongoDB 5.0 timeField: , // required for time series collections metaField: , granularity: , bucketMaxSpanSeconds: , // Added in MongoDB 6.3 bucketRoundingSeconds: // Added in MongoDB 6.3 }, expireAfterSeconds: , clusteredIndex: , // Added in MongoDB 5.3 changeStreamPreAndPostImages: , // Added in MongoDB 6.0 size: , max: , storageEngine: , validator: , validationLevel: , validationAction: , indexOptionDefaults: , viewOn: , pipeline: , collation: , writeConcern: , encryptedFields: } ) ``` The `db.createCollection()` method has the following parameters: | Parameter | Type | Description | | --- | --- | --- | | `name` | string | The name of the collection to create. See [Naming Restrictions.](https://www.mongodb.com/docs/manual/reference/limits.md#std-label-restrictions-on-db-names) | | `options` | document | Optional. Configuration options for creating a: Capped collection; Clustered collection; View | The `options` document contains the following fields: | Field | Type | Description | | --- | --- | --- | | `capped` | boolean | Optional. To create a [capped collection](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-capped-collection), specify `true`. If you specify `true`, you must also set a maximum size in the `size` field. | | `timeseries.timeField` | string | Required when creating a [time series collection](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-time-series-collection). The name of the field which contains the date in each time series document. Documents in a time series collection must have a valid BSON date as the value for the `timeField`. | | `timeseries.metaField` | string | Optional. The name of the field which contains metadata in each time series document. The metadata in the specified field labels a unique series of documents. The metadata should rarely, if ever, change. The name of the specified field cannot be `_id` or the same as the `timeseries.timeField`. The field can be of any type except array. | | `timeseries.granularity` | string | Optional, do not use if setting `bucketRoundingSeconds` and `bucketMaxSpanSeconds`. Possible values are `seconds` (default), `minutes`, and `hours`. Set `granularity` to the value that most closely matches the time between consecutive incoming timestamps. This improves performance by optimizing how MongoDB internally stores data in the collection. For more information on granularity and bucket intervals, see [Set Granularity for Time Series Data.](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-granularity.md#std-label-timeseries-granularity) | | `timeseries.bucketMaxSpanSeconds` | integer | Optional, used with `bucketRoundingSeconds` as an alternative to `granularity`. Sets the maximum time between timestamps in the same bucket. Possible values are 1-31536000. If you set `bucketMaxSpanSeconds`, you must set `bucketRoundingSeconds` to the same value. To downgrade below MongoDB 6.3, you must either modify the collection to use the corresponding `granularity` value, or drop the collection. For details, see [`collMod`.](https://www.mongodb.com/docs/manual/reference/command/collMod.md#mongodb-dbcommand-dbcmd.collMod) | | `timeseries.bucketRoundingSeconds` | integer | Optional, used with `bucketMaxSpanSeconds` as an alternative to `granularity`. Sets the number of seconds to round down by when MongoDB sets the minimum timestamp for a new bucket. Must be equal to `bucketMaxSpanSeconds`. For example, setting both parameters to `1800` rounds new buckets down to the nearest 30 minutes. If a document with a time of `2023-03-27T18:24:35Z` does not fit an existing bucket, MongoDB creates a new bucket with a minimum time of `2023-03-27T18:00:00Z` and a maximum time of `2023-03-27T18:30:00Z`. | | `expireAfterSeconds` | number | Optional. Specifies the seconds after which documents in a [time series collection](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-time-series-collection) or [clustered collection](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-clustered-collection) expire. MongoDB deletes expired documents automatically. For clustered collections, the documents are deleted automatically based on the clustered index key `_id` and the values must be date types. See [TTL Indexes.](https://www.mongodb.com/docs/manual/core/index-ttl.md#std-label-index-feature-ttl) | | `clusteredIndex` | document | Starting in MongoDB 5.3, you can create a collection with a **clustered index**. Clustered indexes are stored in the same [WiredTiger](https://www.mongodb.com/docs/manual/core/wiredtiger.md#std-label-storage-wiredtiger) file as the collection. The resulting collection is called a [clustered collection.](https://www.mongodb.com/docs/manual/core/clustered-collections.md#std-label-clustered-collections) The `clusteredIndex` field has the following syntax: `clusteredIndex: { key: , unique: , name: }` `key`Required. The clustered index key field. Must be set to `{ _id: 1 }`. The default value for the `_id` field is an automatically generated unique [object identifier](https://www.mongodb.com/docs/manual/reference/bson-types.md#std-label-objectid), but you can set your own [clustered index key values.](https://www.mongodb.com/docs/manual/core/clustered-collections.md#std-label-clustered-collections-clustered-index-key-values)`unique`Required. Must be set to `true`. A unique index indicates the collection will not accept inserted or updated documents where the clustered index key value matches an existing value in the index.`name`Optional. A name that uniquely identifies the clustered index. **New in version 5.3** | | `changeStreamPreAndPostImages` | document | Optional. Starting in MongoDB 6.0, you can use [change stream events](https://www.mongodb.com/docs/manual/reference/change-events.md#std-label-change-stream-output) to output the version of a document before and after changes (the document pre- and post-images): The pre-image is the document before it was replaced, updated, or deleted. There is no pre-image for an inserted document.; The post-image is the document after it was inserted, replaced, or updated. There is no post-image for a deleted document.; Enable `changeStreamPreAndPostImages` for a collection using [`db.createCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.createCollection.md#mongodb-method-db.createCollection), [`create`](https://www.mongodb.com/docs/manual/reference/command/create.md#mongodb-dbcommand-dbcmd.create), or [`collMod`](https://www.mongodb.com/docs/manual/reference/command/collMod.md#mongodb-dbcommand-dbcmd.collMod). For example, when using the `collMod` command:`db.runCommand( { collMod: , changeStreamPreAndPostImages: { enabled: true } } )` To check the current `changeStreamPreAndPostImages` setting for a collection, run [`db.getCollectionInfos()`:](https://www.mongodb.com/docs/manual/reference/method/db.getCollectionInfos.md#mongodb-method-db.getCollectionInfos) `db.getCollectionInfos( { name: "" } )[0].options.changeStreamPreAndPostImages` **Output:** `{ changeStreamPreAndPostImages: { enabled: true } }` `changeStreamPreAndPostImages` has the following syntax: `changeStreamPreAndPostImages: { enabled: }` To enable change stream pre- and post-images for the collection, set `enabled` to `true`. For complete examples with the change stream output, see [Change Streams with Document Pre- and Post-Images.](https://www.mongodb.com/docs/manual/reference/method/db.collection.watch.md#std-label-db.collection.watch-change-streams-pre-and-post-images-example) For a `db.createCollection()` example on this page, see [Create a Collection with Change Stream Pre- and Post-Images for Documents.](https://www.mongodb.com/docs/manual/reference/method/db.createCollection.md#std-label-createCollection-change-stream-pre-and-post-images-example) **New in version 6.0** | | `size` | number | Optional. Specify a maximum size in bytes for a capped collection. Once a capped collection reaches its maximum size, MongoDB removes the older documents to make space for the new documents. The `size` field is required for capped collections and ignored for other collections. | | `max` | number | Optional. The maximum number of documents allowed in the capped collection. The `size` limit takes precedence over this limit. If a capped collection reaches the `size` limit before it reaches the maximum number of documents, MongoDB removes old documents. If you prefer to use the `max` limit, ensure that the `size` limit, which is required for a capped collection, is sufficient to contain the maximum number of documents. | | `storageEngine` | document | Optional. Available for the WiredTiger storage engine only. Specifies storage engine configuration on a per-collection basis. The value of the `storageEngine` option takes the following form: `{ : }` Storage engine configuration specified when creating collections are validated and logged to the [oplog](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-oplog) during replication to support replica sets with members that use different storage engines. Starting in MongoDB 7.2, you can't specify `wiredTiger` storage engine encryption options when you create a collection with [`db.createCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.createCollection.md#mongodb-method-db.createCollection). To configure encryption for the WiredTiger storage engine, see [Encryption at Rest.](https://www.mongodb.com/docs/manual/core/security-encryption-at-rest.md#std-label-security-encryption-at-rest) For details, see [Specify Storage Engine Options.](https://www.mongodb.com/docs/manual/reference/method/db.createCollection.md#std-label-create-collection-storage-engine-options) | | `validator` | document | Optional. Specifies [validation rules or expressions](https://www.mongodb.com/docs/manual/core/schema-validation.md#std-label-schema-validation-overview) for the collection. The `validator` option takes a document that specifies the validation rules or expressions. You can specify the expressions using the same operators as the [query operators](https://www.mongodb.com/docs/manual/reference/mql/query-predicates.md#std-label-query-selectors) except for [`$near`](https://www.mongodb.com/docs/manual/reference/operator/query/near.md#mongodb-query-op.-near), [`$nearSphere`](https://www.mongodb.com/docs/manual/reference/operator/query/nearSphere.md#mongodb-query-op.-nearSphere), [`$text`](https://www.mongodb.com/docs/manual/reference/operator/query/text.md#mongodb-query-op.-text), and [`$where`.](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) To learn how to create a collection with schema validation, see [Specify JSON Schema Validation.](https://www.mongodb.com/docs/manual/core/schema-validation/specify-json-schema.md#std-label-schema-validation-json) | | `validationLevel` | string | Optional. Determines how strictly MongoDB applies the validation rules to existing documents during an update. `"off"`No validation for inserts or updates.`"strict"`**Default** Apply validation rules to all inserts and all updates.`"moderate"`Apply validation rules to inserts and to updates on existing *valid* documents. Do not apply rules to updates on existing *invalid* documents. To see an example that uses `validationLevel`, see [Specify Validation Level for Existing Documents.](https://www.mongodb.com/docs/manual/core/schema-validation/specify-validation-level.md#std-label-schema-specify-validation-level) | | `validationAction` | string | Optional. Determines whether to `error` on invalid documents or just `warn` about the violations but allow invalid documents to be inserted. IMPORTANT: Validation of documents only applies to those documents as determined by the `validationLevel`. To see an example that uses `validationAction`, see [Choose How to Handle Invalid Documents.](https://www.mongodb.com/docs/manual/core/schema-validation/handle-invalid-documents.md#std-label-schema-validation-handle-invalid-docs) | | `indexOptionDefaults` | document | Optional. Specifies a default configuration for indexes in the collection. The `indexOptionDefaults` option accepts a `storageEngine` document, which should take the following form: `{ : }` Storage engine configuration specified when creating indexes are validated and logged to the [oplog](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-oplog) during replication to support replica sets with members that use different storage engines. | | `viewOn` | string | The name of the source collection or view from which to create a view. For details, see [`db.createView()`.](https://www.mongodb.com/docs/manual/reference/method/db.createView.md#mongodb-method-db.createView) | | `pipeline` | array | An array that consists of the [aggregation pipeline stage(s)](https://www.mongodb.com/docs/manual/core/aggregation-pipeline.md#std-label-aggregation-pipeline). [`db.createView()`](https://www.mongodb.com/docs/manual/reference/method/db.createView.md#mongodb-method-db.createView) creates a view by applying the specified `pipeline` to the `viewOn` collection or view. For details, see [`db.createView()`.](https://www.mongodb.com/docs/manual/reference/method/db.createView.md#mongodb-method-db.createView) | | `collation` | document | Specifies the default [collation](https://www.mongodb.com/docs/manual/reference/collation.md#std-label-collation) for the collection. [Collation](https://www.mongodb.com/docs/manual/reference/collation.md#std-label-collation) allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. The collation option has the following syntax: `collation: { locale: , caseLevel: , caseFirst: , strength: , numericOrdering: , alternate: , maxVariable: , backwards: }` When specifying collation, the `locale` field is mandatory; all other collation fields are optional. For descriptions of the fields, see [Collation Document.](https://www.mongodb.com/docs/manual/reference/collation.md#std-label-collation-document-fields) If you specify a collation at the collection level: Indexes on that collection will be created with that collation unless the index creation operation explicitly specify a different collation.; Operations on that collection use the collection's default collation unless they explicitly specify a different collation.You cannot specify multiple collations for an operation. For example, you cannot specify different collations per field, or if performing a find with a sort, you cannot use one collation for the find and another for the sort. If no collation is specified for the collection or for the operations, MongoDB uses the simple binary comparison used in prior versions for string comparisons. For a collection, you can only specify the collation during the collection creation. Once set, you cannot modify the collection's default collation. For an example, see [Specify Collation.](https://www.mongodb.com/docs/manual/reference/method/db.createCollection.md#std-label-createCollection-collation-example) | | `writeConcern` | document | Optional. A document that expresses the [write concern](https://www.mongodb.com/docs/manual/reference/write-concern.md#std-label-write-concern) for the operation. Omit to use the default write concern. When issued on a sharded cluster, [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) converts the [write concern](https://www.mongodb.com/docs/manual/reference/write-concern.md#std-label-write-concern) of the [`create`](https://www.mongodb.com/docs/manual/reference/command/create.md#mongodb-dbcommand-dbcmd.create) command and its helper [`db.createCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.createCollection.md#mongodb-method-db.createCollection) to [`"majority"`.](https://www.mongodb.com/docs/manual/reference/write-concern.md#mongodb-writeconcern-writeconcern.-majority-) | | `encryptedFields` | document | Optional. A document that configures [Queryable Encryption](https://www.mongodb.com/docs/manual/core/queryable-encryption.md#std-label-qe-manual-feature-qe) for the collection being created. To use encrypted fields in a collection, specify a new configuration option. You must have permissions to create and modify a collection to set this configuration during collection creation. After you create a collection, the `encryptedFields` value is immutable. The configuration includes a list of fields and their corresponding key identifiers, types, and supported queries. `encryptedFieldsConfig = { "fields": [ { "keyId": UUID, // required "path": String, // path to field, required "bsonType": "string" | "int" ..., // required "queries": // optional [ { "queryType": "equality" }, ] } ] }` For a helper that creates an encrypted collection, see [`db.createEncryptedCollection()`.](https://www.mongodb.com/docs/manual/reference/method/db.createEncryptedCollection.md#mongodb-method-db.createEncryptedCollection) For details, see [Queryable Encryption Tutorials.](https://www.mongodb.com/docs/manual/core/queryable-encryption/tutorials.md#std-label-qe-tutorials) | ## Access Control If the deployment enforces [authentication/authorization](https://www.mongodb.com/docs/manual/core/authentication.md#std-label-authentication), [`db.createCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.createCollection.md#mongodb-method-db.createCollection) requires the following privileges: | Task | Required Privileges | | --- | --- | | Create a non-capped collection | [`createCollection`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-createCollection) on the database, **or** [`insert`](https://www.mongodb.com/docs/manual/reference/change-events/insert.md#mongodb-data-insert) on the collection to create | | Create a [capped collection](https://www.mongodb.com/docs/manual/core/capped-collections.md#std-label-manual-capped-collection) | [`convertToCapped`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-convertToCapped) for the collection [`createCollection`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-createCollection) on the database | | Create a [view](https://www.mongodb.com/docs/manual/core/views.md#std-label-views-landing-page) | [`createCollection`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-createCollection) on the database. However, if the user has the [`createCollection`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-createCollection) on the database *and* [`find`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-find) on the view to create, the user must *also* have the following additional permissions: [`find`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-find) on the source collection or view.; [`find`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-find) on any other collections or views referenced in the `pipeline`, if any. | A user with the [`readWrite`](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#mongodb-authrole-readWrite) built in role on the database has the required privileges to run the listed operations. Either [create a user](https://www.mongodb.com/docs/manual/tutorial/create-users.md#std-label-create-users) with the required role or [grant the role to an existing user.](https://www.mongodb.com/docs/manual/tutorial/manage-users-and-roles.md#std-label-modify-existing-user-access) ## Behavior ### Resource Locking [`db.createCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.createCollection.md#mongodb-method-db.createCollection) obtains an exclusive lock on the specified collection or view for the duration of the operation. All subsequent operations on the collection must wait until [`db.createCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.createCollection.md#mongodb-method-db.createCollection) releases the lock. [`db.createCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.createCollection.md#mongodb-method-db.createCollection) typically holds this lock for a short time. Creating a view requires obtaining an additional exclusive lock on the `system.views` collection in the database. This lock blocks creation or modification of views in the database until the command completes. ### Transactions You can create collections and indexes inside a [distributed transaction](https://www.mongodb.com/docs/manual/core/transactions.md#std-label-transactions-create-collections-indexes) if the transaction is not a cross-shard write transaction. To use `db.createCollection()` in a transaction, the transaction must use read concern [`"local"`](https://www.mongodb.com/docs/manual/reference/read-concern-local.md#mongodb-readconcern-readconcern.-local-). If you specify a read concern level other than [`"local"`](https://www.mongodb.com/docs/manual/reference/read-concern-local.md#mongodb-readconcern-readconcern.-local-), the transaction fails. **See also:** [Create Collections and Indexes in a Transaction](https://www.mongodb.com/docs/manual/core/transactions.md#std-label-transactions-create-collections-indexes) ### Collection or View with Same Name and Options If you run `db.createCollection()` with the same name and options as an existing collection or view, `db.createCollection()` returns success. ## Examples ### Create a Capped Collection Capped collections have a maximum size and, optionally, a maximum document count. When a capped collection reaches its maximum size, MongoDB removes older documents to make room for new ones. The following example creates a capped collection named `log`: ```javascript db.createCollection("log", { capped : true, size : 5242880, max : 5000 } ) ``` This command creates a collection named `log` with a maximum size of 5 megabytes and a maximum of 5000 documents. See [Capped Collections](https://www.mongodb.com/docs/manual/core/capped-collections.md#std-label-manual-capped-collection) for more information about capped collections. ### Create a Time Series Collection To create a [time series collection](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-time-series-collection) that captures weather data for the past 24 hours, issue this command: ```javascript db.createCollection( "weather24h", { timeseries: { timeField: "timestamp", metaField: "data", granularity: "hours" }, expireAfterSeconds: 86400 } ) ``` Alternately, to create the same collection but limit each bucket to timestamp values within the same hour, issue this command: ```javascript db.createCollection( "weather24h", { timeseries: { timeField: "timestamp", metaField: "data", bucketMaxSpanSeconds: 3600, bucketRoundingSeconds: 3600 }, expireAfterSeconds: 86400 } ) ``` ### Create a Clustered Collection The following [`db.createCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.createCollection.md#mongodb-method-db.createCollection) example adds a [clustered collection](https://www.mongodb.com/docs/manual/core/clustered-collections.md#std-label-clustered-collections) named `stocks`: ```javascript db.createCollection( "stocks", { clusteredIndex: { "key": { _id: 1 }, "unique": true, "name": "stocks clustered key" } } ) ``` In the example, [clusteredIndex](https://www.mongodb.com/docs/manual/reference/method/db.createCollection.md#std-label-db.createCollection.clusteredIndex) specifies: - `"key": { _id: 1 }`, which sets the clustered index key to the `_id` field. - `"unique": true`, which indicates the clustered index key value must be unique. - `"name": "stocks clustered key"`, which sets the clustered index name. ### Create a Collection with Change Stream Pre- and Post-Images for Documents Starting in MongoDB 6.0, you can use [change stream events](https://www.mongodb.com/docs/manual/reference/change-events.md#std-label-change-stream-output) to output the version of a document before and after changes (the document pre- and post-images): - The pre-image is the document before it was replaced, updated, or deleted. There is no pre-image for an inserted document. - The post-image is the document after it was inserted, replaced, or updated. There is no post-image for a deleted document. - Enable `changeStreamPreAndPostImages` for a collection using [`db.createCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.createCollection.md#mongodb-method-db.createCollection), [`create`](https://www.mongodb.com/docs/manual/reference/command/create.md#mongodb-dbcommand-dbcmd.create), or [`collMod`](https://www.mongodb.com/docs/manual/reference/command/collMod.md#mongodb-dbcommand-dbcmd.collMod). For example, when using the `collMod` command: ```javascript db.runCommand( { collMod: , changeStreamPreAndPostImages: { enabled: true } } ) ``` To check the current `changeStreamPreAndPostImages` setting for a collection, run [`db.getCollectionInfos()`:](https://www.mongodb.com/docs/manual/reference/method/db.getCollectionInfos.md#mongodb-method-db.getCollectionInfos) ```javascript db.getCollectionInfos( { name: "" } )[0].options.changeStreamPreAndPostImages ``` **Output:** ```javascript { changeStreamPreAndPostImages: { enabled: true } } ``` The following example creates a collection that has [changeStreamPreAndPostImages](https://www.mongodb.com/docs/manual/reference/method/db.createCollection.md#std-label-db.createCollection.changeStreamPreAndPostImages) enabled: ```javascript db.createCollection( "temperatureSensor", { changeStreamPreAndPostImages: { enabled: true } } ); ``` Pre- and post-images are not available for a [change stream event](https://www.mongodb.com/docs/manual/reference/change-events.md#std-label-change-stream-output) if the images were: - Not enabled on the collection at the time of a document update or delete operation. - Removed after the pre- and post-image retention time set in `expireAfterSeconds`. - The following example sets `expireAfterSeconds` to `100` seconds on an entire cluster: ```javascript use admin db.runCommand( { setClusterParameter: { changeStreamOptions: { preAndPostImages: { expireAfterSeconds: 100 } } } } ) ``` **Note:** The [`setClusterParameter`](https://www.mongodb.com/docs/manual/reference/command/setClusterParameter.md#mongodb-dbcommand-dbcmd.setClusterParameter) command is not supported in MongoDB Atlas clusters. For information on Atlas support for all commands, see [Unsupported Commands in Atlas.](https://www.mongodb.com/docs/atlas/unsupported-commands.md#std-label-unsupported-commands) - The following example returns the current `changeStreamOptions` settings, including `expireAfterSeconds`: ```javascript db.adminCommand( { getClusterParameter: "changeStreamOptions" } ) ``` - Setting `expireAfterSeconds` to `off` uses the default retention policy: pre- and post-images are retained until the corresponding change stream events are removed from the [oplog.](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-oplog) - If a change stream event is removed from the oplog, then the corresponding pre- and post-images are also deleted regardless of the `expireAfterSeconds` pre- and post-image retention time. Additional considerations: - Enabling pre- and post-images consumes storage space and adds processing time. Only enable pre- and post-images if you need them. - Limit the change stream event size to less than 16 mebibytes. To limit the event size, you can: - Limit the document size to 8 megabytes. You can request pre- and post-images simultaneously in the [change stream output](https://www.mongodb.com/docs/manual/reference/change-events.md#std-label-change-stream-output) if other change stream event fields like `updateDescription` are not large. - Request only post-images in the change stream output for documents up to 16 mebibytes if other change stream event fields like `updateDescription` are not large. - Request only pre-images in the change stream output for documents up to 16 mebibytes if: - document updates affect only a small fraction of the document structure or content, *and* - do not cause a `replace` change event. A `replace` event always includes the post-image. - To request a pre-image, you set `fullDocumentBeforeChange` to `required` or `whenAvailable` in [`db.collection.watch()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.watch.md#mongodb-method-db.collection.watch). To request a post-image, you set `fullDocument` using the same method. - Pre-images are written to the [`config.system.preimages`](https://www.mongodb.com/docs/manual/reference/system-collections.md#mongodb-data-config.system.preimages) collection. - The `config.system.preimages` collection may become large. To limit the collection size, you can set `expireAfterSeconds` time for the pre-images as shown earlier. - To monitor the size of `config.system.preimages`, connect to a shard node on a sharded cluster or a [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) node on a replica set. Then, run the following commands: ```javascript use config db.system.preimages.totalSize() db.system.preimages.stats() ``` **Note:** You must have the [`collStats`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-collStats) privilege action on the `config.system.preimages` collection to run these commands. To run these commands on an MongoDB Atlas deployment, you must have the [`atlasAdmin`](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#mongodb-atlasrole-atlasAdmin) role. - Pre-images are removed asynchronously by a background process. **Important: Backward-Incompatible Feature** Starting in MongoDB 6.0, if you are using document pre- and post-images for [change streams](https://www.mongodb.com/docs/manual/reference/change-events.md#std-label-change-stream-output), you must disable [changeStreamPreAndPostImages](https://www.mongodb.com/docs/manual/reference/command/collMod.md#std-label-collMod-change-stream-pre-and-post-images) for each collection using the [`collMod`](https://www.mongodb.com/docs/manual/reference/command/collMod.md#mongodb-dbcommand-dbcmd.collMod) command before you can downgrade to an earlier MongoDB version. **See also:** - For change stream events and output, see [Change Stream Events.](https://www.mongodb.com/docs/manual/reference/change-events.md#std-label-change-stream-output) - To watch a collection for changes, see [`db.collection.watch()`.](https://www.mongodb.com/docs/manual/reference/method/db.collection.watch.md#mongodb-method-db.collection.watch) - For complete examples with the change stream output, see [Change Streams with Document Pre- and Post-Images.](https://www.mongodb.com/docs/manual/reference/method/db.collection.watch.md#std-label-db.collection.watch-change-streams-pre-and-post-images-example) ### Specify Collation [Collation](https://www.mongodb.com/docs/manual/reference/collation.md#std-label-collation) allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. You can specify [collation](https://www.mongodb.com/docs/manual/reference/collation.md#std-label-collation) at the collection or [view](https://www.mongodb.com/docs/manual/core/views.md#std-label-views-landing-page) level. For example, the following operation creates a collection, specifying a collation for the collection (See [Collation Document](https://www.mongodb.com/docs/manual/reference/collation.md#std-label-collation-document-fields) for descriptions of the collation fields): ```javascript db.createCollection( "myColl", { collation: { locale: "fr" } } ); ``` This collation is used by indexes and operations that support collation unless they explicitly specify a different collation. For example, insert the following documents into `myColl`: ```javascript { _id: 1, category: "café" } { _id: 2, category: "cafe" } { _id: 3, category: "cafE" } ``` The following operation uses the collection's collation: ```javascript db.myColl.find().sort( { category: 1 } ) ``` The operation returns documents in the following order: ```javascript { "_id" : 2, "category" : "cafe" } { "_id" : 3, "category" : "cafE" } { "_id" : 1, "category" : "café" } ``` The same operation on a collection that uses binary collation (that is, no specific collation set) returns documents in the following order: ```javascript { "_id" : 3, "category" : "cafE" } { "_id" : 2, "category" : "cafe" } { "_id" : 1, "category" : "café" } ``` **See also:** [Create a View with Default Collation](https://www.mongodb.com/docs/manual/core/views/specify-collation.md#std-label-create-view-w-collation) ### Specify Storage Engine Options You can specify collection-specific storage engine configuration options when you create a collection with `db.createCollection()`. ```javascript db.createCollection( "users", { storageEngine: { wiredTiger: { configString: "