db.createCollection.txt

=====================
db.createCollection()
=====================

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

Definition
----------

.. method:: db.createCollection(name, options)

   Creates a new collection explicitly.

   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
   :method:`db.createCollection()` to create a :term:`capped collection
   <capped collection>`, or to create a new collection that uses
   :doc:`document validation </core/document-validation>`.

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

   .. versionchanged:: 3.2

   .. code-block:: javascript

      db.createCollection(<name>, { capped: <boolean>,
                                    autoIndexId: <boolean>,
                                    size: <number>,
                                    max: <number>,
                                    storageEngine: <document>,
                                    validator: <document>,
                                    validationLevel: <string>,
                                    validationAction: <string>,
                                    indexOptionDefaults: <document> } )

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


   .. list-table::
      :header-rows: 1
      :widths: 20 20 80
   
      * - Parameter
   
        - Type
   
        - Description
   
      * - ``name``
   
        - string
   
        - The name of the collection to create.
          
          
   
      * - ``options``
   
        - document
   
        - Optional. Configuration options for creating a capped collection or for
          preallocating space in a new collection.
          
          
   


   The ``options`` document creates a capped collection, preallocates
   space in a new ordinary collection, or specifies :doc:`document validation
   </core/document-validation>` criteria. The ``options`` document contains
   the following fields:


   .. list-table::
      :header-rows: 1
      :widths: 20 20 80
   
      * - Field
   
        - Type
   
        - Description
   
      * - ``capped``
   
        - boolean
   
        - Optional. To create a :term:`capped collection`,
          specify ``true``. If you specify ``true``, you must also set a maximum
          size in the ``size`` field.
          
          
   
      * - ``autoIndexId``
   
        - boolean
   
        - Optional. Specify ``false`` to disable the automatic creation of an index on the
          ``_id`` field.
          
          .. important::
          
             For replica sets, do not set ``autoIndexId`` to ``false``.
          
          .. deprecated:: 3.2
             The ``autoIndexId`` option will be removed in version 3.4.
          
          
   
      * - ``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.
          
          
   
      * - ``usePowerOf2Sizes``
   
        - boolean
   
        - Optional. Available for the MMAPv1 storage engine only.
          
          .. deprecated:: 3.0
          
             For the MMAPv1 storage engine, all collections use the :ref:`power
             of 2 sizes allocation <power-of-2-allocation>` unless the
             ``noPadding`` option is ``true``. The ``usePowerOf2Sizes`` option
             does not affect the allocation strategy.
          
          
   
      * - ``noPadding``
   
        - boolean
   
        - Optional. Available for the MMAPv1 storage engine only.
          
          .. versionadded:: 3.0
          
             ``noPadding`` flag disables the :ref:`power of 2 sizes allocation
             <power-of-2-allocation>` for the collection. With ``noPadding``
             flag set to true, the allocation strategy does not include
             additional space to accommodate document growth, as such, document
             growth will result in new allocation. Use for collections with
             workloads that are insert-only or in-place updates (such as
             incrementing counters).
          
             Defaults to ``false``.
          
          .. warning::
          
             Do not set ``noPadding`` if the workload includes removes or any
             updates that may cause documents to grow. For more information,
             see :ref:`exact-fit-allocation`.
          
          
   
      * - ``storageEngine``
   
        - document
   
        - Optional. Available for the WiredTiger storage engine only.
          
          .. versionadded:: 3.0
          
          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:
          
          .. code-block:: javascript
          
             { <storage-engine-name>: <options> }
          
          Storage engine configuration specified when creating collections are
          validated and logged to the :term:`oplog` during replication to
          support replica sets with members that use different storage
          engines.
          
          
   
      * - ``validator``
   
        - document
   
        - Optional. Allows users to specify :doc:`validation rules or expressions
          </core/document-validation>` for the collection. For more information,
          see :doc:`/core/document-validation`.
          
          .. versionadded:: 3.2
          
          The ``validator`` option takes a document that specifies the
          validation rules or expressions. You can specify the expressions using
          the same operators as the :ref:`query operators <query-selectors>`
          with the exception of :query:`$geoNear`, :query:`$near`,
          :query:`$nearSphere`, :query:`$text`, and :query:`$where`.
          
          .. note::
          
             - 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.
          
          .. versionadded:: 3.2
          
          .. include:: /includes/extracts/table-validationLevel-values.rst
          
          
   
      * - ``validationAction``
   
        - string
   
        - Optional. Determines whether to ``error`` on invalid documents or just ``warn``
          about the violations but allow invalid documents to be inserted.
          
          .. versionadded:: 3.2
          
          .. important::
          
             Validation of documents only applies to those documents as
             determined by the ``validationLevel``.
          
          .. include:: /includes/extracts/table-validationAction-values.rst
          
          
   
      * - ``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:
          
          .. code-block:: javascript
          
             { <storage-engine-name>: <options> }
          
          Storage engine configuration specified when creating indexes are
          validated and logged to the :term:`oplog` during replication to
          support replica sets with members that use different storage
          engines.
          
          .. versionadded:: 3.2
          
          
   


   :method:`db.createCollection()` is a wrapper around the database
   command :dbcommand:`create`.

Examples
--------

Create a Capped Collection
~~~~~~~~~~~~~~~~~~~~~~~~~~

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:

.. code-block:: 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 :doc:`/core/capped-collections` for more
information about capped collections.

Create a Collection with Document Validation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 3.2

Collections with validation compare each inserted or updated document
against the criteria specified in the ``validator`` option. Depending
on the ``validationLevel`` and ``validationAction``, MongoDB either
returns a warning, or refuses to insert or update the document if it
fails to meet the specified criteria.

The following example creates a ``contacts`` collection with a validator
that specifies that inserted or updated documents should match at least
one of three following conditions:

- the ``phone`` field is a string
- the ``email`` field matches the regular expression
- the ``status`` field is either ``Unknown`` or ``Incomplete``.

.. code-block:: javascript

   db.createCollection( "contacts",
      {
         validator: { $or:
            [
               { phone: { $type: "string" } },
               { email: { $regex: /@mongodb\.com$/ } },
               { status: { $in: [ "Unknown", "Incomplete" ] } }
            ]
         }
      }
   )

With the validator in place, the following insert operation fails validation:

.. code-block:: javascript

   db.contacts.insert( { name: "Amanda", status: "Updated" } )

The method returns the error in the ``WriteResult``:

.. code-block:: javascript

   WriteResult({
      "nInserted" : 0,
      "writeError" : {
         "code" : 121,
         "errmsg" : "Document failed validation"
      }
   })

For more information, see :doc:`/core/document-validation`. To view the
validation specifications for a collection, use the
:method:`db.getCollectionInfos()` method.

.. _create-collection-storage-engine-options:

Specify Storage Engine Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 3.0

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

.. code-block:: javascript

   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 the
``wiredTiger`` storage engine. See the :wtdocs:`WiredTiger documentation of
collection level options </struct_w_t___s_e_s_s_i_o_n.html>`
for specific ``wiredTiger`` options.