create.txt

======
create
======

.. default-domain:: mongodb

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

Definition
----------

.. dbcommand:: create

   Explicitly creates a collection. :dbcommand:`create` has the
   following form:

   .. code-block:: javascript

      { create: <collection_name>,
        capped: <true|false>,
        autoIndexId: <true|false>,
        size: <max_size>,
        max: <max_documents>,
        flags: <0|1>
      }

   :dbcommand:`create` has the following fields:


   .. list-table::
      :header-rows: 1
      :widths: 20 20 80
   
      * - Field
   
        - Type
   
        - Description
   
      * - ``create``
   
        - string
   
        - The name of the new collection.
          
          
   
      * - ``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. Before 2.2, the default value for ``autoIndexId``
          was ``false``.
          
          
   
      * - ``size``
   
        - integer
   
        - Optional. The maximum size for the capped collection. Once a capped collection
          reaches its maximum size, MongoDB overwrites older old documents
          with new documents. The ``size`` field is required for capped
          collections.
          
          
   
      * - ``max``
   
        - integer
   
        - Optional. The maximum number of documents to keep in the capped collection. The
          ``size`` limit takes precedence over this limit. If a capped
          collection reaches its maximum size before it reaches the maximum
          number of documents, MongoDB removes old documents. If you use this
          limit, ensure that the ``size`` limit is sufficient to contain the
          documents limit.
          
          
   
      * - ``flags``
   
        - integer
   
        - Optional. .. versionadded:: 2.6
          
          Set to ``0`` to disable the :collflag:`usePowerOf2Sizes` allocation
          strategy for this collection, or ``1`` to enable
          :collflag:`usePowerOf2Sizes`. Defaults to ``1`` unless the
          :parameter:`newCollectionsUsePowerOf2Sizes` parameter is set to
          ``false``.
          
          
   


   For more information on the ``autoIndexId`` field in versions before
   2.2, see :ref:`2.2-id-indexes-capped-collections`.

   The :method:`db.createCollection()` method wraps the
   :dbcommand:`create` command.

Considerations
--------------

The :dbcommand:`create` command obtains a write lock on the
affected database and will block other operations until it has
completed. The write lock for this operation is typically short
lived. However, allocations for large capped collections may take
longer.

Example
-------

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

.. code-block:: javascript

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