Manipulating Documents

Now that we are able to find out the available collections, let’s take a look at the following commands, which are used for manipulating the documents:

• Insert
• Update
• Remove

Simple data retrieval

Before we actually start with these operations, let’s look at how to query the database in the simplest terms, as this method will be used as an example in upcoming chapters.

The MongoDB shell offers the ability to query for data; this is mainly achieved by using the db.<collection>.find() method.

The db.collection.find() will retrieve all the documents in a given collection (actually, the top 20). For more information, please see the full chapter on how to find and project data in MongoDB.

Inserting a document

There are several ways to insert data into a MongoDB collection.

Table 3: Methods of document creation

The goal in the following example is to add a new user in the users collection.

As we have seen, it’s fairly easy to insert a simple document representing the user.

Figure 20: Inserting a user.

Using a single line vs multiline when specifying a JSON string doesn’t really make any difference. The important point is to close the function with the right parenthesis. As soon as the document is inserted, the MongoDB shell informs us with the number of affected rows in the form of WriteResult ({ “nInserted”: 1 }).

Just to prove that we have inserted two users, we can call db.users.count(), which will return the count of documents currently present in the users collection.

It is also possible to insert more than one document at a time, by using an array of JSON documents and passing this as a parameter to the insert function. In JSON, brackets [  ] are used to specify an array of objects.

Figure 21: Inserting multiple documents into a collection.

It’s also possible to use the db.users.save() to insert a new document into the collection. In reality, the save() command can be used both for inserting or updating documents.

If a document does not exist with the specified _id value, the save() method performs an insert with the specified fields in the document; otherwise, an update is performed, replacing all fields in the existing record with the fields from the document.

Let’s see an example of how to use the save() command to insert data into a collection. It’s pretty much straightforward, and it looks very similar to the previous examples.

Figure 22: Inserting data into a collection by using save().

Document primary key

When we retrieved the item from the users collection, you might have noticed that there is a field called _id, which we did not explicitly mention when we inserted the document.

As in any database, MongoDB provides a way of handling the primary keys for the documents. Documents stored in a collection require a unique _id field that acts as a primary key. We can explicitly set the value of the _id; alternatively, the database will assign one by default. MongoDB uses the ObjectId type as the default to store the value for the _id field; however, the _id field may contain values of any BSON data type, other than an array.

The ObjectId is a BSON type, and its value consists of 12 bytes, where the first four bytes are a timestamp that reflect the ObjectId’s creation, specifically:

• a 4-byte value representing the seconds since the Unix epoch
• a 3-byte machine identifier
• a 2-byte process ID
• a 3-byte counter, starting with a random value

So, it’s a very good candidate for a unique value. Let’s look at a small example on how to force our own primary key:

Code Listing 20: Inserting user data by forcing the primary key

Assigning an _id is as easy as handling any other attribute. As you can see in Figure 23, duplicate primary keys will be avoided.

Figure 23: Duplicate primary keys not allowed.

Updating a document

MongoDB allows you to change existing documents in the following ways:

• Update the value of an existing field.
• Change the document by adding or removing attributes (fields).
• Replace the document entirely.

To manipulate the documents, MongoDB mainly offers three different flavors of the update() methods to be performed at the collection level.

Table 4: MongoDB document update methods

Updating a value of an existing attribute

The following seems to be the most obvious operation to perform, so let’s try to change the firstname of a user in the users collection. In order to do this, let’s just create a new user with a simpler _id, by running the following command:

Code Listing 21: Creating a user with a fixed primary key

Once the user is in the collection, we can quickly query the collection and check if the user has been properly inserted by running the find() method. The find() method will return the full list of items in the collection.

Code Listing 22: Searching for user data (basic usage)

You should be able to see the user with the primary key _id = 1.

In order to change the firstname of the user, we can use the following command:

Code Listing 23: Update user's firstname

The first parameter (in red) represents the filter that will be applied to items with the update, a bit like a WHERE clause when updating records in the RDBMS.

The second parameter (in blue) defines the operation to be performed. In our case, we use the operator $set in order to set the value of the firstname.

If the field we are passing is not in the document, it will be automatically created. If we would like to add the age of the user, then it becomes as simple as:

Code Listing 24: Updating user's age

On the command line, you should see something similar to the following:

Figure 24: Applying the update methods.

To give an idea of which parameters the update() method supports, let’s take a look at the general method signature:

Code Listing 25: Collection update method signature

Table 5: Update method's options

Update operators

There are quite a few update operators that can be used to manipulate values. We have already seen the usage of the $set operator, which performs the change on the document by setting the value explicitly, but there are others:

Table 6: Update operators

If we are dealing with an array of items (a collection of items), then there are several more operators, including:

Table 7: Update operators for arrays

For the full list of available operators, please visit the official MongoDB documentation or check the available options directly in the MongoDB shell with the following command:

Code Listing 26: Use of help on a collection

Also, check the method signatures for the these update methods.

Deleting a document

In a very similar way as it happens for updates, MongoDB offers various ways for deleting documents. The methods follow pretty much the same principle.

Table 8: Data removal methods

Let’s demonstrate a deletion of a single document by using the deleteOne method. The signature of the deleteOne method is as follows. It accepts the filter and the writeConcern as discussed previously. WriteConcern is not mandatory, and if not specified, will take the default values.

Code Listing 27: DeleteOne method signature

Let’s assume we already have an entry in the users table, and we try to delete it. This might look like the following:

Figure 25: Deleting a document.

What is interesting here is the filter part, where we specify the document to be deleted. In our case, this is directly the primary key, _id = 1.