> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # create (database command) ## Definition Explicitly creates a collection or view. **Note:** The view created by this command does not refer to materialized views. For discussion of on-demand materialized views, see [`$merge`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge.md#mongodb-pipeline-pipe.-merge) instead. ## Compatibility This command 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 `create` command has the following syntax: **Note:** MongoDB 6.3 adds the `bucketMaxSpanSeconds` and `bucketRoundingSeconds` parameters. To downgrade below 6.3, you must either drop all collections with these parameters, or modify them to use the corresponding `granularity`, if possible. For details see [`collMod`.](https://www.mongodb.com/docs/manual/reference/command/collMod.md#mongodb-dbcommand-dbcmd.collMod) ```javascript db.runCommand( { create: , capped: , timeseries: { timeField: , 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 autoIndexId: , size: , max: , storageEngine: , validator: , validationLevel: , validationAction: , indexOptionDefaults: , viewOn: , pipeline: , collation: , writeConcern: , encryptedFields: , comment: } ``` ### Command Fields The `create` command has the following fields: | Field | Type | Description | | --- | --- | --- | | `create` | string | The name of the new collection or view. See [Naming Restrictions](https://www.mongodb.com/docs/manual/reference/limits.md#std-label-restrictions-on-db-names). If you try to create a collection or view that already exists and you provide identical options for that existing collection or view, no action is taken and success is returned. | | `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 should be data that is used to label a unique series of documents. The metadata should rarely, if ever, change The name of the specified field may not be `_id` or the same as the `timeseries.timeField`. The field can be of any data type. Although the `metaField` field is optional, using metadata can improve query optimization. For example, MongoDB automatically [creates a compound index](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-secondary-index.md#std-label-timeseries-add-secondary-index) on the `metaField` and `timeField` fields for new collections. If you do not provide a value for this field, the data is bucketed solely based on time. | | `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` | integer | 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. | | `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 `create` example on this page, see [Create a Collection with Change Stream Pre- and Post-Images for Documents.](https://www.mongodb.com/docs/manual/reference/command/create.md#std-label-create-change-stream-pre-and-post-images-example) **New in version 6.0** | | `autoIndexId` | boolean | Optional. Specify `false` to disable the automatic creation of an index on the `_id` field. IMPORTANT: Starting in MongoDB 4.0, you cannot set `autoIndexId` to `false` when creating collections in databases other than the `local` database. **Deprecated since version 3.2** | | `size` | integer | 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` | integer | 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. Allows users to specify configuration to the storage engine on a per-collection basis when creating a collection. The value of the `storageEngine` option should take 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 more information, see [Specify Storage Engine Options.](https://www.mongodb.com/docs/manual/reference/command/create.md#std-label-create-command-collection-storage-engine-options) | | `validator` | document | Optional. Allows users to specify [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) Validation occurs during updates and inserts. Existing documents do not undergo validation checks until modification.; You cannot specify a validator for collections in the `admin`, `local`, and `config` databases.; You cannot specify a validator for `system.*` collections. | | `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. | | `validationAction` | string | Optional. Determines whether to `error` on invalid documents or just `warn` about the violations but allow invalid documents to be inserted. Validation of documents only applies to those documents as determined by the `validationLevel`. `"error"`**Default** Documents must pass validation before the write occurs. Otherwise, the write operation fails.`"warn"`Documents do not have to pass validation. If the document fails validation, the write operation logs the validation failure. | | `indexOptionDefaults` | document | Optional. Allows users to specify a default configuration for indexes when creating a 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 the view. The name is not the full namespace of the collection or view. It does not include the database name. You must create views in the same database as the source collection. See also [`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). `create` creates the view by applying the specified `pipeline` to the `viewOn` collection or view. A view definition `pipeline` cannot include the [`$out`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out.md#mongodb-pipeline-pipe.-out) or the [`$merge`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge.md#mongodb-pipeline-pipe.-merge) stage. This restriction also applies to embedded pipelines, such as pipelines used in [`$lookup`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup.md#mongodb-pipeline-pipe.-lookup) or [`$facet`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/facet.md#mongodb-pipeline-pipe.-facet) stages. The view definition is public; i.e. [`db.getCollectionInfos()`](https://www.mongodb.com/docs/manual/reference/method/db.getCollectionInfos.md#mongodb-method-db.getCollectionInfos) and `explain` operations on the view will include the pipeline that defines the view. As such, avoid referring directly to sensitive fields and values in view definitions. See also [`db.createView()`.](https://www.mongodb.com/docs/manual/reference/method/db.createView.md#mongodb-method-db.createView) | | `collation` | | Specifies the default [collation](https://www.mongodb.com/docs/manual/reference/collation.md#std-label-collation) for the collection or the view. [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 view, if no collation is specified, the view's default collation is the "basic" binary comparison collator. For a view on a collection, the view does not inherit the collection's collation settings. For a view on another view, the to be created view must specify the same collation settings. After you create the collection or the view, you cannot update its default collation. For an example that specifies the default collation during the creation of a collection, see [Specify Collation.](https://www.mongodb.com/docs/manual/reference/command/create.md#std-label-create-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 details, see [Queryable Encryption Tutorials.](https://www.mongodb.com/docs/manual/core/queryable-encryption/tutorials.md#std-label-qe-tutorials) | | `comment` | any | Optional. A user-provided comment to attach to this command. Once set, this comment appears alongside records of this command in the following locations: [mongod log messages](https://www.mongodb.com/docs/manual/reference/log-messages.md#std-label-log-messages-ref), in the `attr.command.cursor.comment` field.; [Database profiler](https://www.mongodb.com/docs/manual/reference/database-profiler.md#std-label-profiler) output, in the [`command.comment`](https://www.mongodb.com/docs/manual/reference/database-profiler.md#mongodb-data-system.profile.command) field.; [`currentOp`](https://www.mongodb.com/docs/manual/reference/command/currentOp.md#mongodb-dbcommand-dbcmd.currentOp) output, in the [`command.comment`](https://www.mongodb.com/docs/manual/reference/command/currentOp.md#mongodb-data-currentOp.command) field. A comment can be any valid [BSON type](https://www.mongodb.com/docs/manual/reference/bson-types.md#std-label-bson-types) (string, integer, object, array, etc). | The [`db.createCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.createCollection.md#mongodb-method-db.createCollection) method and the [`db.createView()`](https://www.mongodb.com/docs/manual/reference/method/db.createView.md#mongodb-method-db.createView) method wrap the `create` command. ## Behavior `create` has the following behavior: ### Resource Locking [`create`](https://www.mongodb.com/docs/manual/reference/command/create.md#mongodb-dbcommand-dbcmd.create) 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 [`create`](https://www.mongodb.com/docs/manual/reference/command/create.md#mongodb-dbcommand-dbcmd.create) releases the lock. [`create`](https://www.mongodb.com/docs/manual/reference/command/create.md#mongodb-dbcommand-dbcmd.create) 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 `create` 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 `create` with the same name and options as an existing collection or view, `create` returns success. ### Stable API **Changed in version 5.0** When using [Stable API](https://www.mongodb.com/docs/manual/reference/stable-api.md#std-label-stable-api) V1, all `create` command fields are supported except the following fields, which are not available in Stable API V1: - `autoIndexId` - `capped` - `indexOptionDefaults` - `max` - `size` - `storageEngine` ## Access Control If the deployment enforces [authentication/authorization](https://www.mongodb.com/docs/manual/core/authentication.md#std-label-authentication), [`create`](https://www.mongodb.com/docs/manual/reference/command/create.md#mongodb-dbcommand-dbcmd.create) 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) ## Examples ### Create a Capped Collection To create a [capped collection](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-capped-collection) limited to 64 kilobytes, issue the command in the following form: ```javascript db.runCommand( { create: "collection", capped: true, size: 64 * 1024 } ) ``` ### 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 } ) ``` **Note:** In this example `expireAfterSeconds` is specified as `86400` which means documents expire `86400` seconds after the `timestamp` value. See [Set up Automatic Removal for Time Series Collections (TTL).](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-automatic-removal.md#std-label-manual-timeseries-automatic-removal) ### Create a Clustered Collection The following [`create`](https://www.mongodb.com/docs/manual/reference/command/create.md#mongodb-dbcommand-dbcmd.create) example adds a [clustered collection](https://www.mongodb.com/docs/manual/core/clustered-collections.md#std-label-clustered-collections) named `products`: ```javascript db.runCommand( { create: "products", clusteredIndex: { "key": { _id: 1 }, "unique": true, "name": "products clustered key" } } ) ``` In the example, [clusteredIndex](https://www.mongodb.com/docs/manual/reference/command/create.md#std-label-create.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": "products 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/command/create.md#std-label-create.changeStreamPreAndPostImages) enabled: ```javascript db.runCommand( { create: "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) ### Create a View **Note:** The view created by this command does not refer to materialized views. For discussion of on-demand materialized views, see [`$merge`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge.md#mongodb-pipeline-pipe.-merge) instead. A view definition `pipeline` cannot include the [`$out`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out.md#mongodb-pipeline-pipe.-out) or the [`$merge`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge.md#mongodb-pipeline-pipe.-merge) stage. This restriction also applies to embedded pipelines, such as pipelines used in [`$lookup`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup.md#mongodb-pipeline-pipe.-lookup) or [`$facet`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/facet.md#mongodb-pipeline-pipe.-facet) stages. To create a [view](https://www.mongodb.com/docs/manual/core/views.md#std-label-views-landing-page) using the `create` command, use the following syntax: ```javascript db.runCommand( { create: , viewOn: , pipeline: } ) ``` or if specifying a collation: ```javascript db.runCommand( { create: , viewOn: , pipeline: , collation: } ) ``` For example, create a `survey` collection with the following documents: ```javascript db.survey.insertMany( [ { _id: 1, empNumber: "abc123", feedback: { management: 3, environment: 3 }, department: "A" }, { _id: 2, empNumber: "xyz987", feedback: { management: 2, environment: 3 }, department: "B" }, { _id: 3, empNumber: "ijk555", feedback: { management: 3, environment: 4 }, department: "A" } ] ) ``` The following operation creates a `managementRatings` view with the `_id`, `feedback.management`, and `department` fields: ```javascript db.runCommand ( { create: "managementFeedback", viewOn: "survey", pipeline: [ { $project: { "management": "$feedback.management", department: 1 } } ] } ) ``` **Important:** The view definition is public; i.e. [`db.getCollectionInfos()`](https://www.mongodb.com/docs/manual/reference/method/db.getCollectionInfos.md#mongodb-method-db.getCollectionInfos) and `explain` operations on the view will include the pipeline that defines the view. As such, avoid referring directly to sensitive fields and values in view definitions. **See also:** [`db.createView()`](https://www.mongodb.com/docs/manual/reference/method/db.createView.md#mongodb-method-db.createView) ### Specify Collation 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.runCommand ( { create: "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 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) - [Collation and Views](https://www.mongodb.com/docs/manual/reference/collation.md#std-label-ref-collation-and-views) ### Specify Storage Engine Options You can specify collection-specific storage engine configuration options when you create a collection with [`db.createCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.createCollection.md#mongodb-method-db.createCollection). Consider the following operation: ```javascript db.runCommand( { create: "users", storageEngine: { wiredTiger: { configString: "