db.createCollection() (original) (raw)

db.createCollection(name, options)

Creates a new collection. For views, see db.createView().

Because MongoDB creates a collection implicitly when the collection is first referenced in a command, this method is used primarily for creating new collections that use specific options. For example, you use db.createCollection() to create a:

• Capped collection.
• Clustered collection.
• New collection that uses schema validation.

db.createCollection() is a wrapper around the database command create.

This method is available in deployments hosted in the following environments:

• MongoDB 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, seeUnsupported Commands.

• MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
• MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

The db.createCollection() method has the following prototype form:

db.createCollection( <name>,

    {

      capped: <boolean>,

      timeseries: {                  // Added in MongoDB 5.0

         timeField: <string>,        // required for time series collections

         metaField: <string>,

         granularity: <string>,

         bucketMaxSpanSeconds: <number>,  // Added in MongoDB 6.3

         bucketRoundingSeconds: <number>  // Added in MongoDB 6.3

      },

      expireAfterSeconds: <number>,

      clusteredIndex: <document>,  // Added in MongoDB 5.3

      changeStreamPreAndPostImages: <document>,  // Added in MongoDB 6.0

      size: <number>,

      max: <number>,

      storageEngine: <document>,

      validator: <document>,

      validationLevel: <string>,

      validationAction: <string>,

      indexOptionDefaults: <document>,

      viewOn: <string>,

      pipeline: <pipeline>,

      collation: <document>,

      writeConcern: <document>

    }

  )

The db.createCollection() method has the following parameters:

The options document contains the following fields:

If the deployment enforcesauthentication/authorization,db.createCollection() requires the following privileges:

A user with the readWrite built in role on the database has the required privileges to run the listed operations. Eithercreate a user with the required role or grant the role to an existing user.

db.createCollection() has the following behavior:

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 untildb.createCollection() releases the lock. 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.

You can create collections and indexes inside a distributed transaction if the transaction is not a cross-shard write transaction.

To use db.createCollection() in a transaction, the transaction must use read concern "local". If you specify a read concern level other than "local", the transaction fails.

See also:

If you run db.createCollection() with the same name and options as an existing collection or view, db.createCollection() returns success.

Capped collections have maximum size or document counts that prevent them from growing beyond maximum thresholds. All capped collections must specify a maximum size and may also specify a maximum document count. MongoDB removes older documents if a collection reaches the maximum size limit before it reaches the maximum document count. Consider the following example:

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 for more information about capped collections.

To create a time series collection that captures weather data for the past 24 hours, issue this command:

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:

db.createCollection(

    "weather24h",

    {

       timeseries: {

          timeField: "timestamp",

          metaField: "data",

          bucketMaxSpanSeconds: "3600",

          bucketRoundingSeconds: "3600"

       },

       expireAfterSeconds: 86400

    }

)

The following db.createCollection() example adds aclustered collection named stocks:

db.createCollection(

   "stocks",

   { clusteredIndex: { "key": { _id: 1 }, "unique": true, "name": "stocks clustered key" } }

)

In the example, 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.

Starting in MongoDB 6.0, you can use change stream events 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 usingdb.createCollection(), create, orcollMod.

The following example creates a collection that haschangeStreamPreAndPostImages enabled:

db.createCollection(

   "temperatureSensor",

   { changeStreamPreAndPostImages: { enabled: true } }

);

Pre- and post-images are not available for a change stream event 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 inexpireAfterSeconds.
  • The following example sets expireAfterSeconds to 100seconds on an entire cluster:

  use admin  
  db.runCommand( {  
     setClusterParameter:  
        { changeStreamOptions: {  
           preAndPostImages: { expireAfterSeconds: 100 }  
        } }  
  } )  

  • The following example returns the current changeStreamOptionssettings, including expireAfterSeconds:

  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.
  • 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 if other change stream event fields likeupdateDescription are not large.
  • Request only post-images in the change stream output for documents up to 16 mebibytes if other change stream event fields likeupdateDescription 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 torequired or whenAvailable in db.collection.watch(). To request a post-image, you set fullDocument using the same method.
• Pre-images are written to the config.system.preimagescollection.
  • The config.system.preimages collection may become large. To limit the collection size, you can set expireAfterSecondstime for the pre-images as shown earlier.
  • 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, you must disablechangeStreamPreAndPostImages for each collection using the collMod command before you can downgrade to an earlier MongoDB version.

See also:

• For change stream events and output, seeChange Events.
• To watch a collection for changes, seedb.collection.watch().
• For complete examples with the change stream output, seeChange Streams with Document Pre- and Post-Images.

Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.

You can specify collation at the collection orview level. For example, the following operation creates a collection, specifying a collation for the collection (See Collation Document for descriptions of the collation fields):

db.createCollection( "myColl", { collation: { locale: "fr" } } );

This collation will be used by indexes and operations that support collation unless they explicitly specify a different collation. For example, insert the following documents into myColl:

{ _id: 1, category: "café" }

{ _id: 2, category: "cafe" }

{ _id: 3, category: "cafE" }

The following operation uses the collection's collation:

db.myColl.find().sort( { category: 1 } )

The operation returns documents in the following order:

{ "_id" : 2, "category" : "cafe" }

{ "_id" : 3, "category" : "cafE" }

{ "_id" : 1, "category" : "café" }

The same operation on a collection that uses simple binary collation (i.e. no specific collation set) returns documents in the following order:

{ "_id" : 3, "category" : "cafE" }

{ "_id" : 2, "category" : "cafe" }

{ "_id" : 1, "category" : "café" }

See also:

You can specify collection-specific storage engine configuration options when you create a collection withdb.createCollection(). Consider the following operation:

db.createCollection(

   "users",

   { storageEngine: { wiredTiger: { configString: "<option>=<setting>" } } }

)

This operation creates a new collection named users with a specific configuration string that MongoDB will pass to thewiredTiger storage engine.

For example, to specify the zlib compressor for file blocks in theusers collection, set the block_compressor option with the following command:

db.createCollection(

   "users",

   { storageEngine: { wiredTiger: { configString: "block_compressor=zlib" } } }

)

Starting in MongoDB 7.2, you can't specify wiredTiger storage engine encryption options when you create a collection withdb.createCollection(). To configure encryption for the WiredTiger storage engine, see Encryption at Rest.