create

Definition

• create
• Explicitly creates a collection or view.

Note

The view created by this command does not refer to materializedviews. For discussion of on-demand materialized views, see$merge instead.

create has the following form:

Starting in MongoDB 4.2

MongoDB removes the MMAPv1 storage engine and the MMAPv1 specificoption flags for create.

{
  create: <collection or view name>,
  capped: <true|false>,
  autoIndexId: <true|false>,
  size: <max_size>,
  max: <max_documents>,
  storageEngine: <document>,
  validator: <document>,
  validationLevel: <string>,
  validationAction: <string>,
  indexOptionDefaults: <document>,
  viewOn: <source>,                   // Added in MongoDB 3.4
  pipeline: <pipeline>,               // Added in MongoDB 3.4
  collation: <document>,              // Added in MongoDB 3.4
  writeConcern: <document>
}

create has the following fields:

FieldTypeDescriptioncreatestringThe name of the new collection or view. SeeNaming Restrictions.cappedbooleanOptional. To create a capped collection,specify true. If you specify true, you must also set a maximumsize in the size field.autoIndexIdbooleanOptional. Specify false to disable the automatic creation of an index on the_id field.

Important

Starting in MongoDB 4.0, you cannot set the option autoIndexIdto false when creating collections in databases other than thelocal database.

Deprecated since version 3.2.

sizeintegerOptional. Specify a maximum size in bytes for a capped collection. Once acapped collection reaches its maximum size, MongoDB removes the olderdocuments to make space for the new documents. The size field isrequired for capped collections and ignored for other collections.maxintegerOptional. The maximum number of documents allowed in the capped collection. Thesize limit takes precedence over this limit. If a cappedcollection reaches the size limit before it reaches the maximumnumber of documents, MongoDB removes old documents. If you prefer touse the max limit, ensure that the size limit, which isrequired for a capped collection, is sufficient to contain themaximum number of documents.storageEnginedocumentOptional. Available for the WiredTiger storage engine only.

New in version 3.0.

Allows users to specify configuration to the storage engine on aper-collection basis when creating a collection. The value of thestorageEngine option should take the following form:

{ <storage-engine-name>: <options> }

Storage engine configuration specified when creating collections arevalidated and logged to the oplog during replication tosupport replica sets with members that use different storageengines.validatordocumentOptional. Allows users to specify validation rules or expressions for the collection. For more information,see Schema Validation.

New in version 3.2.

The validator option takes a document that specifies thevalidation rules or expressions. You can specify the expressions usingthe same operators as the query operatorswith the exception of $geoNear, $near,$nearSphere, $text, and $where.

Note

• Validation occurs during updates and inserts. Existingdocuments 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.validationLevelstringOptional. Determines how strictly MongoDB applies thevalidation rules to existing documents during an update.

New in version 3.2.

validationLevelDescription"off"No validation for inserts or updates."strict"Default Apply validation rules to all inserts and allupdates."moderate"Apply validation rules to inserts and to updates on existing _valid_documents. Do not apply rules to updates on existing _invalid_documents.

validationActionstringOptional. Determines whether to error on invalid documents or just warnabout the violations but allow invalid documents to be inserted.

New in version 3.2.

Important

Validation of documents only applies to those documents asdetermined by the validationLevel.

validationActionDescription"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 failsvalidation, the write operation logs the validation failure.

indexOptionDefaultsdocumentOptional. Allows users to specify a default configuration for indexes whencreating a collection.

The indexOptionDefaults option accepts a storageEnginedocument, which should take the following form:

{ <storage-engine-name>: <options> }

Storage engine configuration specified when creating indexes arevalidated and logged to the oplog during replication tosupport replica sets with members that use different storageengines.

New in version 3.2.

viewOnstringThe name of the source collection or view from which to create theview. The name is not the full namespace of the collection orview; i.e. does not include the database name and implies the samedatabase as the view to create. You must create views in the samedatabase as the source collection.

See also db.createView().

New in version 3.4.

pipelinearrayAn array that consists of the aggregation pipeline stage(s). create creates the view byapplying the specified pipeline to the viewOn collection or view.

The view definition pipeline cannotinclude the $out or the $merge stage. If the view definition includesnested pipeline (e.g. the view definition includes$lookup or $facet stage), thisrestriction applies to the nested pipelinesas well.

The view definition is public; i.e. db.getCollectionInfos()and explain operations on the view will include the pipeline thatdefines the view. As such, avoid referring directly to sensitive fieldsand values in view definitions.

See also db.createView().

New in version 3.4.

collationSpecifies the default collation for thecollection or the view.

Collation allows users to specifylanguage-specific rules for string comparison, such as rules forlettercase and accent marks.

The collation option has the following syntax:

collation: {
   locale: <string>,
   caseLevel: <boolean>,
   caseFirst: <string>,
   strength: <int>,
   numericOrdering: <boolean>,
   alternate: <string>,
   maxVariable: <string>,
   backwards: <boolean>
}

When specifying collation, the locale field is mandatory; allother collation fields are optional. For descriptions of the fields,see Collation Document.

If you specify a collation at the collection level:

• Indexes on that collection will be created with that collation unlessthe index creation operation explicitly specify a different collation.

• Operations on that collection use the collection’s defaultcollation unless they explicitly specify a different collation.

You cannot specify multiple collations for an operation. Forexample, you cannot specify different collations per field, or ifperforming a find with a sort, you cannot use one collation for thefind and another for the sort.

If no collation is specified for the collection or for theoperations, MongoDB uses the simple binary comparison used in priorversions for string comparisons.

For a view, if no collation is specified, the view’s defaultcollation is the “simple” binary comparison collator. For a view ona collection, the view does not inherit the collection’s collationsettings. For a view on another view, the to be created view mustspecify the same collation settings.

After you create the collection or the view, you cannot update itsdefault collation.

For an example that specifies the default collation during thecreation of a collection, see Specify Collation.

New in version 3.4.

writeConcerndocumentOptional. A document that expresses the write concernfor the operation. Omit to use the default writeconcern.

When issued on a sharded cluster, mongos converts thewrite concern of thecreate command and its helperdb.createCollection() to "majority".

The db.createCollection() method and thedb.createView() method wrap the createcommand.

Behavior

Resource Locking

Changed in version 4.2.

create obtains an exclusive lock on thespecified collection or view for the duration of the operation. Allsubsequent operations on the collection must wait untilcreate releases the lock. create typically holdsthis lock for a short time.

Creating a view requires obtaining an additional exclusive lockon the system.views collection in the database. This lock blockscreation or modification of views in the database until the commandcompletes.

Prior to MongoDB 4.2, create obtained an exclusive lockon the parent database, blocking all operations on the database _and_all its collections until the operation completed.

Access Control

If the deployment enforcesauthentication/authorization,create requires the following privileges:

The readWrite built in role includes the requiredprivileges. Alternatively, you cancreate a custom role to supportcreate.

The following example uses the db.createUser() method tocreate a user in the admin database with the readWriterole on the inventory and employees database:

db.getSiblingDB("admin").createUser(
  {
    "user" : "createViewUser",
    "pwd" : "replaceThisWithASecurePassword",
    "roles" : [
      { "db" : "inventory", "role" : "readWrite" },
      { "db" : "employees", "role" : "readWrite" }
    ]
  }
)

The created user can execute create on the specified databases.For more examples of user creation, see Add Users.

Alternatively, you can add the required roles to an existing userusing db.grantRolesToUser(). For a tutorial on addingprivileges to an existing database user, seeModify Access for an Existing User.

Examples

Create a Capped Collection

To create a capped collection limited to 64 kilobytes, issuethe command in the following form:

db.runCommand( { create: "collection", capped: true, size: 64 * 1024 } )

Create a View

Note

The view created by this command does not refer to materializedviews. For discussion of on-demand materialized views, see$merge instead.

Changed in version 4.2.

The view definition pipeline cannotinclude the $out or the $merge stage. If the view definition includesnested pipeline (e.g. the view definition includes$lookup or $facet stage), thisrestriction applies to the nested pipelinesas well.

To create a view using the createcommand, use the following syntax:

db.runCommand( { create: <view>, viewOn: <source>, pipeline: <pipeline> } )

or if specifying a collation:

db.runCommand( { create: <view>, viewOn: <source>, pipeline: <pipeline>, collation: <collation> } )

For example, given a collection survey with the following documents:

{ _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:

db.runCommand ( {
   create: "managementFeedback",
   viewOn: "survey",
   pipeline: [ { $project: { "management": "$feedback.management", department: 1 } } ]
} )

Important

The view definition is public; i.e. db.getCollectionInfos()and explain operations on the view will include the pipeline thatdefines the view. As such, avoid referring directly to sensitive fieldsand values in view definitions.

See also

db.createView()

Specify Collation

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

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

This collation will be used by indexes and operations that supportcollation unless they explicitly specify a different collation. Forexample, 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

Create a View with Default Collation, Collation and Views

Specify Storage Engine Options

New in version 3.0.

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

db.runCommand( {
    create: "users",
    storageEngine: { wiredTiger: { configString: "<option>=<setting>" } }
} )

This operation creates a new collection named users with aspecific configuration string that MongoDB will pass to thewiredTiger storage engine. See the WiredTiger documentation ofcollection level optionsfor specific wiredTiger options.