===========
Collections
===========

MongoDB stores documents in collections. If a collection does not
exist, MongoDB creates the collection when you first store data for
that collection.

You can also explicitly create a collection with various options,
such as setting the maximum size or the documentation validation rules.

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.

To create a :manual:`capped collection </core/capped-collections/>` ,
use the ``createCollection`` method and specify ``'capped' : true``.

.. code-block:: js

   const { MongoClient } = require('mongodb');

   // Connection URL
   const url = 'mongodb://localhost:27017';

   // Create a new MongoClient
   const client = new MongoClient(url);

   async function main(client) {
     const db = client.db('test');
     await db.createCollection('myCollection', {
       capped: true,
       size: 100000,
       max: 5000
     });
     console.log('Collection created.');
   }

   // Function to connect to the server and run your code
   async function run() {
     try {
       // Connect the client to the server
       await client.connect();
       console.log('Connected successfully to server');

       await main(client);
     } finally {
       // Ensures that the client will close when you finish/error
       await client.close();
     }
   }

   // Runs your code
   run();

Document Validation
-------------------

Collections with :manual:`validation </core/schema-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:: js

   async function main(client) {
     const db = client.db('test');
     await db.createCollection('myCollection', {
       validator: {
         $or: [
           { phone: { $type: 'string' } },
           { email: { $regex: /@mongodb\.com$/ } },
           { status: { $in: ['Unknown', 'Incomplete'] } }
         ]
       }
     });
     console.log('Collection created.');
   }