===========
Quick Start
===========
This guide will show you how to set up a simple application using Node.js and MongoDB. Its scope is only how to set up the driver and perform the simple CRUD operations.

Create the package.json file
----------------------------

First, create a directory where your application will live.

.. code-block:: sh

   mkdir myproject
   cd myproject

Enter the following command and answer the questions to create the initial structure for your new project:

.. code-block:: sh

   npm init

Next, install the driver dependency.

.. code-block:: sh

   npm install mongodb --save

You should see **NPM** download a lot of files. Once it's done you'll find all the downloaded packages under the **node_modules** directory.

Start a MongoDB Server
----------------------

For complete MongoDB installation instructions, see `the manual <https://docs.mongodb.org/manual/installation/>`_.


#. Download the right MongoDB version from `MongoDB <https://www.mongodb.org/downloads>`_
#. Create a database directory (in this case under **/data**\ ).
#. Install and start a ``mongod`` process.

.. code-block:: sh

   mongod --dbpath=/data

You should see the **mongod** process start up and print some status information.

Connect to MongoDB
------------------

Create a new **app.js** file and add the following code to try out some basic CRUD
operations using the MongoDB driver.

Add code to connect to the server and the database **myproject**\ :

.. literalinclude:: /includes/basic-connection.js
    :language: js

Run your app from the command line with:

.. code-block:: sh

   node app.js

The application should print **Connected successfully to server** to the console.

Insert a Document
-----------------

Add to **app.js** the following function which uses the **insertMany**
method to add three documents to the **documents** collection.  

.. code-block:: js

   async function insertDocuments(db) {
     // Get the documents collection
     const collection = db.collection('documents');
     // Insert some documents
     const result = await collection.insertMany([{ a: 1 }, { a: 2 }, { a: 3 }]);
    
     assert.equal(3, result.result.n);
     assert.equal(3, result.ops.length);
     console.log('Inserted 3 documents into the collection');
     return result;
   }

The **insert** command returns an object with the following fields:

* **result** Contains the result document from MongoDB
* **ops** Contains the documents inserted with added **_id** fields
* **connection** Contains the connection used to perform the insert

Add the ``insertDocuments`` method to your app:

.. code-block:: js

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

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

   // Database Name
   const dbName = 'myproject';
   const client = new MongoClient(url, { useNewUrlParser: true });

   // Use connect method to connect to the server
   client.connect().then(async function() {
     console.log("Connected successfully to server");
     const db = client.db(dbName);

     try {
       await insertDocuments(db);
     } finally {
       await client.close();
     }
   });

Run the updated **app.js** file:

.. code-block:: sh

   node app.js

The operation returns the following output:

.. code-block:: sh

   Connected successfully to server
   Inserted 3 documents into the collection

Find All Documents
------------------

Add a query that returns all the documents.

.. code-block:: js

   async function findDocuments(db) {
     // Get the documents collection
     const collection = db.collection('documents');   
     // Find some documents
     const docs = await collection.find({}).toArray();
     console.log("Found the following records");
     console.log(docs);   
     return docs;
   }

This query returns all the documents in the **documents** collection.
Add the ``findDocuments`` method to your app:

.. code-block:: js

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

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

   // Database Name
   const dbName = 'myproject';
   const client = new MongoClient(url, { useNewUrlParser: true });

   // Use connect method to connect to the server
   client.connect().then(async function() {
     console.log("Connected successfully to server");
     const db = client.db(dbName);

     try {
       await insertDocuments(db);
       await findDocuments(db);
     } finally {
       await client.close();
     }
   });

Find Documents with a Query Filter
----------------------------------

Add a query filter to find only documents which meet the query criteria.

.. code-block:: js

   async function findDocuments(db) {
     // Get the documents collection
     const collection = db.collection('documents');   
     // Find some documents
     const docs = await collection.find({'a': 3}).toArray();
     console.log("Found the following records");
     console.log(docs);   
     return docs;
   }

Only the documents which match ``'a' : 3`` should be returned.

Update a document
-----------------

The following operation updates a document in the **documents** collection.

.. code-block:: js

   async function updateDocuments(db) {
     // Get the documents collection
     const collection = db.collection('documents');
     // Update document where a is 2, set b equal to 1
     const result = await collection.updateOne({ a : 2 }, { $set: { b : 1 } });
     assert.equal(1, result.result.n);
     console.log("Updated the document with the field a equal to 2");

     return result;
   }

The method updates the first document where the field **a** is equal to **2** by adding a new field **b** to the document set to **1**.
Add the ``updateDocuments`` method to your app:

.. code-block:: js

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

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

   // Database Name
   const dbName = 'myproject';
   const client = new MongoClient(url, { useNewUrlParser: true });

   // Use connect method to connect to the server
   client.connect().then(async function() {
     console.log("Connected successfully to server");
     const db = client.db(dbName);

     try {
       await insertDocuments(db);
       await updateDocuments(db);
     } finally {
       await client.close();
     }
   });

Remove a document
-----------------

Remove the document where the field **a** is equal to **3**.

.. code-block:: js

   async function removeDocument(db) {
     // Get the documents collection
     const collection = db.collection('documents');

     // Delete document where a is 3
     const result = await collection.deleteOne({ a : 3 });
     assert.equal(1, result.result.n);
     console.log("Removed the document with the field a equal to 3");

     return result;
   }

Add the ``removeDocument`` method to your app:

.. code-block:: js

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

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

   // Database Name
   const dbName = 'myproject';
   const client = new MongoClient(url, { useNewUrlParser: true });

   // Use connect method to connect to the server
   client.connect().then(async function() {
     console.log("Connected successfully to server");
     const db = client.db(dbName);

     try {
       await insertDocuments(db);
       await updateDocuments(db);
       await removeDocuments(db);
     } finally {
       await client.close();
     }
   });

Index a Collection
------------------

`Indexes <https://docs.mongodb.org/manual/indexes/>`_ can improve your application's
performance. The following function creates an index on the **a** field in the
**documents** collection.

.. code-block:: js

   async function indexCollection(db) {
     const results = await db.collection('documents').createIndex({ a: 1 });
     console.log(results);
     return results;
   }

Add the ``indexCollection`` method to your app:

.. code-block:: js

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

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

   // Database Name
   const dbName = 'myproject';
   const client = new MongoClient(url, { useNewUrlParser: true });

   // Use connect method to connect to the server
   client.connect().then(async function() {
     console.log("Connected successfully to server");
     const db = client.db(dbName);

     try {
       await insertDocuments(db);
       await indexCollection(db);
     } finally {
       await client.close();
     }
   });