CRUD with the MongoDB Node.js SDK

Step one to querying your database is connecting to it, and thankfully Atlas makes this rather easy.

First, make sure the mongodb package is installed (whether you’re making queries from the client or the server). A simple npm install in your project directory does it:

npm install mongodb

Note that if you’re using TypeScript in your project you’ll need to use the driver’s definitions:

npm install -D @types/node

With the driver installed, you’ve only got a few steps left before you can write queries: configuring database access, figuring out your unique database URI, and creating an instance of the MongoDB client with it in your application.

Like other databases, MongoDB requires you to create a database user (not to be confused with the user on your Atlas account) to be registered for different access patterns. This makes things more secure as you can allocate individual permissions, see which users did what to which data, etc. To create a database user, head over to your “Database Access” tab under the “Security” section. Click “add a new database user” and you’ll be presented with a lot of options:

You can choose from types of auth, specific roles and privileges, and even restrict users to specific datasets.

Head over to the “Network Access” setting in that same security tab, and there you’ll be able to add a whitelisted IP address. The UI is pretty simple and allows for comments—and a sort of self-destruction feature:

Your connection URI is how MongoDB knows what cluster to connect to among a sea of Atlas instances. Here’s the basic structure:

You can find it by heading to your Atlas homepage, finding your database, and clicking “connect.”

Choose “Connect your application” and configure the driver and version. Since we’re using the Node SDK, we’ll choose “Node.js” and the most recent version (4.0 or later as of May 2022).

Copy that URI, and we’re ready for the final step. I usually trip up on the fine print: note that both the username/password and database are placeholders, and you’ll need to update them with your desired values. For simplicity’s sake, I personally like to remove everything after the final slash (the database name, and retry writes setting) and just deal with that in code. So then my simpler, final URI looks like:

We’ll just need to import that MongoDB client we installed, and instantiate it with the URI:

Make sure to put your database user’s username and password in those placeholders as well! And with that, you should be successfully connected to your Atlas cluster and ready to run some queries, which is what you came here for.

Retrieving basic, unaggregated data in MongoDB is done via the find() command.

To read data from MongoDB, we’ll first want to construct some sort of query that gives the database specific parameters around what we want. For example, let’s say we want to look at all listings with more than 2 bedrooms on Airbnb. Here’s the JavaScript we’d need:

Since we’re using async-await, all of these statements need to be nested in an async function; code examples from here on out won’t include that extra boilerplate, but keep in mind that you’ll need to run them inside of an async function. After some boilerplate for choosing our database and collection, we define a query that tells MongoDB we want any documents that match our criteria–more than 2 bedrooms–using the $gt or greater than operator. Note that we’ve chosen the findOne() method here, which returns just a single result that matches our query.

If we wanted to add multiple filter conditions to our query, that’s no problem:

Since MongoDB is NoSQL after all, some of these records have mismatching schemas. We can write a query that simply checks that a certain field exists:

Thankfully, our charming Ribeira duplex does indeed have some reviews.

There are seemingly endless ways to customize your queries: check out MongoDB’s full documentation here.

All the above examples use findOne() for simplicity, but chances are you want to run queries that have more than one result. When you run a regular old find() that returns multiple results, MongoDB gives them to you in a navigable cursor object. To preview the results, you can run a forEach loop and print each result:

You can easily convert the cursor to an array as well:

Or, if you want to get a count of total results:

Technically, this is actually bad practice: there’s a special type of query for counting the number of documents in a collection that circumvents the need for a cursor in the first place:

Working with cursors via the MongoDB Node.js driver can be a bit confusing, since the documentation is rather sparse and the MongoDB shell documentation explicitly says that those docs aren’t relevant to drivers. So Mongo, if you’re reading this, please take note.

You probably don’t need all of the fields from every document returned in each query. MongoDB allows you to specify which fields you want with projections:

Adding a field with a 1 means explicitly including it, and using a 0 explicitly excludes it. By default, every field gets returned, so use projections when you can to minimize the amount of data transfer.

The easiest way to sort query results is to attach a sort() method chained to your find() method. Here’s how you’d sort results by price, descending:

Replacing that -1 with 1 sorts results ascending. You can add multiple levels of sorting by adding new entries to that sort object, like so:

Now we have a better sense of how much these places actually cost with extra fees included.

By the way, if you’re doing both projections and sorts, it eventually gets simpler to just add a single configuration object to your query instead of chaining all of these methods together:

Keep in mind that you need to pass your query object before your options object.

There are two ways to add search to your read queries in MongoDB: for text and for geospatial data. I’m going to make the (hopefully) reasonable assumption that it’s probably text you’re most interested in. To text search in MongoDB, you first need to create an index on the text field that you want to search. Here’s how we’d create a text index for each listing’s name field:

Note that you can only create one text index per collection. So if we wanted to index multiple text fields, we’d do it like so:

That would mean that every text search would search both of these fields.

Once we’ve created our index, we can search for a specific word or set of words easily:

There’s a lot more you can do than just text search: check out the docs to go deeper.

You’ve got 2 methods for inserting data into your MongoDB collection: insertOne() and insertMany(). In MongoDB, each document in a collection has a unique identifier, the _id. You can manage it yourself (set a specific one for each document), or allow MongoDB to do that behind the scenes for you. For this tutorial, we’ll assume the latter, which generally is best practice.

This is pretty basic. You just define the document you want to insert, and then, well, insert it.

MongoDB returns the _id of the newly inserted document by default.

The insertMany () method inserts multiple documents, one at a time, until your list of docs is exhausted or an exception occurs.

It’s worth couching some of this in catching logic to make sure that everything was inserted as planned. The main reason there would be an error is mismanaging the _id – if you provide IDs yourself and accidentally have duplicates, the insert will fail on the first duplicated ID.

Updating documents in MongoDB is perhaps surprisingly a lot more complex than inserting them. There are two main concepts to focus on:

A query so the database knows which document(s) to update
An update document to replace the existing one(s) with

There are a bunch of options for what you want the callback to be. An interesting option is the findOneAndUpdate() method, which returns the entire original or updated document.

In terms of what you can actually do to existing documents, there are a bunch of operators. The most popular one is $set which just replaces the entire document or field with a new value that you pass through. But you can also remove fields, perform atomic operations like adding and multiplying, or update a date to the current date (specific, I know).

Let’s say we want to update the name of a specific listing in our database (imagine this is tied to some sort of edit functionality in a user-facing UI). Here’s how we’d do that with updateOne(), including finding the document we need and then passing in a new value for the name:

Remember that the filter gets passed before the update document. Here we’re using $set to replace the old value for name with our new, slightly better one. The .matchedCount property of the result tells you how many documents matched that filter, which is important in cases where the filter you provided isn’t entirely unique. In our case, it was, so it returns 1. And since this is updateOne(), even if more than 1 result is matched, MongoDB will only actually perform the update on the first matched document.

We can remove a field with $unset:

A kind of funny thing here is that it doesn’t actually matter what value you put in your JSON object for the unset operation. It needs to be something, so the object is valid, but since you’re removing the specific field, the value itself doesn’t matter.

You can also upsert by adding an option to the query:

The options param gets passed last, after the filter and updated document.

Even though updateOne() may match multiple documents, it will only update one; whereas updateMany() allows you to update multiple documents at once. If we wanted to apply a uniform price increase to every cleaning fee on our Airbnb listings with more than 2 bedrooms, we could do the following:

Here we’re using the $inc update operator to increment the cleaning fee by $5. Damn inflation.

Remember that you can pass a custom callback to write functions in MongoDB. So if you want to log some information to the console about what happened with your multiple updates, you can do that:

If you have a document with a field that contains (or is) an array, updating that field requires some special syntax. This deserves its own section as it’s a bit more on the complex side.

In our sample Airbnb dataset, each listing has an array of reviews. Here’s what a single review object in one of those arrays looks like:

Our application team wants to build a feature that allows users to update their review comments on a specific listing. So we’ll need to craft a query that finds the user’s review in the array, and then updates just the comments field. First, let’s figure out our query for finding the array entry in question:

This query filters for the specific listing we want to look at, and pulls only the review with the name of our user. This is obviously an oversimplification–you’ll need to make sure that the query values actually return unique results, as there may be multiple listings with the same name, or reviews with the same reviewer name. We’re using normal dot notation to reference the reviewer_name field.

With our document specified, we can pass a new value for that comments value:

That $ is called the positional operator, and it tells MongoDB that in the case of multiple matching array elements, it should update only the first one. If you want to update all matching elements in the array, you can use the all positional operator ($[]):

There’s a lot more to cover here: check out the docs for a more in depth look.

If you can find a document, you can delete it:

As with other operations we’ve covered, deleteOne() deletes the first document that matches your condition, while deleteMany() deletes all documents that match your condition:

The bulkWrite() function allows you to batch lots of different write operations together in a sort of recipe instead of performing all of them separately. So if there are any workflows that you want to kick off when a user takes an action, you can batch them all together.

Let’s say we’re working on some functionality for handling when a user deletes a review that they’ve posted. In addition to deleting that review from the reviews array, we also need to decrement the number_of_reviews field, update the first_review and last_review timestamps, and change the review_scores object to match the new data. A lot to do! We could do all of these separately, or put them together into a single bulkWrite() call.

The first thing we’ll do is define that recipe of operations:

Note that there’s a special syntax for each operation (read more in the docs here). With our operations array defined, we can now pass it into a bulkWrite() call:

Now, all of these operations get performed with only one round trip to the database. Note that bulk writes in MongoDB are not equivalent to ACID transactions in a traditional database. You can work with transactions in MongoDB, but according to their official documentation, “80%-90% of applications that leverage the document model will not need to utilize transactions in MongoDB.” You can read more here.

Thoughts or comments? Get a discussion going on Twitter: we’re at @retool.