Permalink
Fetching contributors…
Cannot retrieve contributors at this time
225 lines (155 sloc) 6.87 KB
=====================
db.createCollection()
=====================
.. default-domain:: mongodb
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol
Definition
----------
.. method:: db.createCollection(name, options)
.. versionchanged:: 3.4
Added support for:
- Creation of views (see also :method:`db.createView()`).
- Collation.
Creates a new collection or :doc:`view </core/views>`.
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>`. :method:`db.createCollection()` is also
used to pre-allocate space for an ordinary collection.
:method:`db.createCollection()` is a wrapper around the database
command :dbcommand:`create`.
The :method:`db.createCollection()` method has the following prototype form:
.. code-block:: javascript
db.createCollection(<name>, { capped: <boolean>,
autoIndexId: <boolean>,
size: <number>,
max: <number>,
storageEngine: <document>,
validator: <document>,
validationLevel: <string>,
validationAction: <string>,
indexOptionDefaults: <document>,
viewOn: <string>,
pipeline: <pipeline>,
collation: <document> } )
The :method:`db.createCollection()` method has the following parameters:
.. include:: /includes/apiargs/method-db.createCollection-param.rst
The ``options`` document contains the following fields:
.. include:: /includes/apiargs/method-db.createCollection-options-param.rst
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.
The following command simply pre-allocates a 2-gigabyte, uncapped
collection named ``people``:
.. code-block:: javascript
db.createCollection("people", { size: 2147483648 } )
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.
.. _createCollection-collation-example:
Specify Collation
~~~~~~~~~~~~~~~~~
.. include:: /includes/extracts/collation-versionadded.rst
You can specify :ref:`collation <collation>` at the collection or
:ref:`view <3.4-reference-views>` level. For example, the following
operation creates a collection, specifying a collation for the
collection (See :ref:`collation-document-fields` for descriptions of
the collation fields):
.. code-block:: javascript
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``:
.. code-block:: javascript
{ _id: 1, category: "café" }
{ _id: 2, category: "cafe" }
{ _id: 3, category: "cafE" }
The following operation uses the collection's collation:
.. code-block:: javascript
db.myColl.find().sort( { category: 1 } )
The operation returns documents in the following order:
.. code-block:: javascript
{ "_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:
.. code-block:: javascript
{ "_id" : 3, "category" : "cafE" }
{ "_id" : 2, "category" : "cafe" }
{ "_id" : 1, "category" : "café" }
.. seealso:: :ref:`create-view-w-collation`
.. _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.