Introduction to MongoDB

W. H. Bell

October 25, 2023

1 Introduction

MongoDB is a NoSQL database that allows documents to be stored in BSON (Binary JavaScript Object
Notation) format. Documents can be inserted using JavaScript Object Notation (JSON). JavaScript
can be used to define a schema and query documents that are present in MongoDB.

MongoDB provides interfaces for several programming languages, as well as a mongo shell.
Details of the interfaces are given at https://api.mongodb.com/. In this document, the Python
programming interface is discussed. The Python programming interface is documented at
https://api.mongodb.com/python/current/tutorial.html.

2 Typesetting and spaces

A fixed width font is used for commands or source code. To aid the reader, a small bucket character
is used to indicate spaces in commands or source code. This character should be replaced with
a space when the command or source code is entered. An example of the bucket that is used to
indicate spaces is demonstrated in Listing 1, where there is a single space between the command and
argument.

Listing 1: Demonstrating the bucket character used to indicate spaces in source code and commands.
command ␣ argument

3 Assumptions

It is assumed that these exercises are being run on a Linux PC in the Computer and Information
Sciences labs. However, these exercises can be run on another Linux installation, provided the
MongoDB python client pymongo has been installed an a MongoDB server is accessible. They can
also be run on Windows or OSX, where the commands to change directories have to be updated as
needed.

Introduction to MongoDB Page 1 of 11

This document includes Bash Linux commands to clone a software repository and change directory. A
separate sheet of Bash Linux commands is provided to Computer and Information Sciences students.
It is assumed that the reader is either familiar with these commands or has access to the reference
document.

The commands that are given in this document have been tested with MongoDB server version 5.0.
They may work with other recent versions of MongoDB.

4 Server connection details

These exercises can be run using a MongoDB server on the local PC or using a remote MongoDB
server. If a remote MongoDB server is used, then the connection details must be provided by setting
environment variables as demonstrated in Listing 2, where server name, username, password and
db name should be replaced by the corresponding connection values. These variables must be set in
the terminal window where the Python example programs are run. If the environment variables are not
set, the default values from Table 1 are used.

Listing 2: Setting connection Bash environment variables.

export ␣ MONGODB_SERVER = server_name
export ␣ MONGODB_USERNAME = username
export ␣ MONGODB_PASSWD = password
export ␣ MONGODB_DB = db_name

Table 1: Default settings for environment variables.

Variable Default/Action
MONGODB SERVER localhost
MONGODB USERNAME No authentication.
MONGODB PASSWD No authentication.
MONGODB DB test

The environment variables are read by the functions that are defined in mongo connect.py. The
functions in mongo connect.py are used to connect to the MongoDB database server and select a
database.

Introduction to MongoDB Page 2 of 11

5 Exercises

1. Open a terminal window.

2. Clone the exercises repository by typing the command that is given in Listing 3 on one line.

Listing 3: Cloning the MongoDB exercises.

git ␣ clone ␣ https :// gitlab . cis . strath . ac . uk / gxb20157 / introduction - to -
mongodb . git

3. Change directory to the python folder by typing the command given in Listing 4.

Listing 4: Changing directory to the python directory.

cd ␣ introduction - to - mongodb / python

4. Set the environment variables as discussed in Section 4.

5. Test the connection to the MongoDB server by running the command given in Listing 5. If
the client successfully connects to the MongoDB server, the program will print “Successfully
connected to MongoDB server.”

Listing 5: Testing the connection to the MongoDB server.

./ test_connection . py

6. List the databases that are available by typing the command given in Listing 6.

Listing 6: Listing available MongoDB databases.

./ list_databases . py

7. Create a database by typing the command that is given in Listing 7.

Listing 7: Running a Python program to create a database.

./ create_database . py

The contents of create database.py are given in Listing 8. This Python program opens a client
connection to the MongoDB server. It creates a database using the value in the MONGODB DB
environment variable or the default name ’test’ if the environment variable has not been set.
Line 8 either creates the database or forms a connection to it, if it already exists. A collection is
created in a similar manner as a database. A document is defined as a Python dictionary at Line
14 and 15. Finally, the Python dictionary is passed to the function insert one to insert it into the
database.

If a collection is created, but it does not contain at least one document it will not be saved to the
MongoDB server. Likewise, if a database does not contain at least one collection, it will not be
saved to the MongoDB server.

Introduction to MongoDB Page 3 of 11

 Listing 8: The file create database.py.
1 # !/ usr / bin / env ␣ python3
2 import ␣ mongo_connect
3
4 # ␣ Get ␣ a ␣ client ␣ connection ␣ to ␣ the ␣ MongoDB ␣ database .
5 client ␣ = ␣ mongo_connect . get_client ()
6
7 # ␣ Create ␣ a ␣ connection ␣ to ␣ the ␣ database .
8 db ␣ = ␣ client [ mongo_connect . ge t_data base_n ame () ]
9
10 # ␣ Create ␣ a ␣ collection .
11 customers ␣ = ␣ db [ ’ Customers ’]
12
13 # ␣ Create ␣ a ␣ document , ␣ which ␣ is ␣ a ␣ Python ␣ dictionary .
14 customer ␣ = ␣ { " CustomerId " : ␣ " 1 " ,
15 ␣ ␣ ␣ ␣ ␣ ␣ ␣ ␣ ␣ ␣ ␣ ␣ " CustomerName " : ␣ " Barry ␣ Rayner " }
16
17 # ␣ Insert ␣ the ␣ document ␣ into ␣ the ␣ collection .
18 id ␣ = ␣ customers . insert_one ( customer )

8. At the Bash prompt, execute the script read database.py in a similar manner as Listing 7.

The contents of read database.py are given in Listing 9. This Python program opens a client
connection to the MongoDB server and gets a connection to the database. It loops over the
collection names in the database, printing each collection name. If the ’Customers’ collection
does not exist, an error message is printed and the program stops. If the “Customers” collection
does exist, then each document from the collection is printed. The find function is used at Line
23 without arguments, selecting all documents and fields within the collection.

Introduction to MongoDB Page 4 of 11

 Listing 9: The file read database.py.
1 # !/ usr / bin / env ␣ python3
2 import ␣ mongo_connect
3 import ␣ pprint
4 import ␣ sys
5
6 # ␣ Create ␣ a ␣ client ␣ connection ␣ to ␣ the ␣ MongoDB ␣ database .
7 client ␣ = ␣ mongo_connect . get_client ()
8
9 # ␣ Get ␣ a ␣ connection ␣ to ␣ the ␣ database .
10 db ␣ = ␣ client [ mongo_connect . ge t_data base_n ame () ]
11
12 # ␣ Read ␣ the ␣ available ␣ collection ␣ names .
13 print ( " >>␣ Available ␣ collections : " )
14 for ␣ collection_name ␣ in ␣ db . l i s t _ c o l l e c t i o n _ n a m e s () :
15 ␣ ␣ ␣ ␣ print ( collection_name )
16
17 if ␣ " Customers " ␣ not ␣ in ␣ db . l i s t _ c o l l e c t i o n _ n a m e s () :
18 ␣ ␣ ␣ ␣ print ( " !! ␣ Error : ␣ the ␣ customers ␣ collection ␣ was ␣ not ␣ found . " )
19 ␣ ␣ ␣ ␣ sys . exit (1)
20
21 # ␣ Print ␣ all ␣ available ␣ documents .
22 print ( " >>␣ Documents ␣ in ␣ the ␣ \" Customers \" ␣ collection : " )
23 for ␣ document ␣ in ␣ db [ " Customers " ]. find () :
24 ␣ ␣ ␣ ␣ pprint . pprint ( document )

9. Add another document to MongoDB. First, try to add a document to the ’Customers’ collection.
Then try to add another collection to the database.
10. Run the drop database.py program, in a similar manner as Listing 7.
11. Run the planets database.py program, in a similar manner as Listing 7.

The contents of planets database.py are given in Listing 10. This program creates a database
and a ’OrbitData’ collection. It reads JSON data from a text file named’planets.json’ and
inserts these data into MongoDB.

The first section of the ’planets.json’ file is given in Listing 11. This file contains a list, where
each element is a dictionary. The Python program reads these data into a list that contains
dictionaries as its elements. The insert many function is called at Line 20 to insert these data
into the MongoDB database.

Introduction to MongoDB Page 5 of 11

 Listing 10: The file planets database.py.
1 # !/ usr / bin / env python3
2 import json
3 import mongo_connect
4
5 # Get a client connection to the MongoDB database .
6 client = mongo_connect . get_client ()
7
8 # Create a connection to the database .
9 db = client [ mongo_connect . ge t_data base_n ame () ]
10
11 # Create a collection .
12 orbit_data = db [ ’ OrbitData ’]
13
14 # Load data from a JSON file .
15 input_file = open ( " planets . json " )
16 json_data = json . load ( input_file )
17 input_file . close ()
18
19 # Insert the documents into the collection .
20 result = orbit_data . insert_many ( json_data )

Listing 11: The first 24 lines of the file planets.json.

1 [
2 {
3 " name " : " Mercury " ,
4 " Mass (10^{24} kg ) " : 0.33 ,
5 " Diameter ( km ) " : 4879.0 ,
6 " Density ( kg / m ^{3}) " : 5427.0 ,
7 " Gravity ( m / s ^{2}) " : 3.7 ,
8 " Escape Velocity ( km / s ) " : 4.3 ,
9 " Rotation Period ( hours ) " : 1407.6 ,
10 " Length of Day ( hours ) " : 4222.6 ,
11 " Distance from Sun (10^{6} km ) " : 57.9 ,
12 " Perihelion (10^{6} km ) " : 46.0 ,
13 " Aphelion (10^{6} km ) " : 69.8 ,
14 " Orbital Period ( days ) " : 88.0 ,
15 " Orbital Velocity ( km / s ) " : 47.4 ,
16 " Orbital Inclination ( degrees ) " : 7.0 ,
17 " Orbital Eccentricity " : 0.205 ,
18 " Obliquity to Orbit ( degrees ) " : 0.034 ,
19 " Mean Temperature ( C ) " : 167.0 ,
20 " Surface Pressure ( bars ) " : 0.0 ,

Introduction to MongoDB Page 6 of 11

 21 " Number of Moons " : 0.0 ,
22 " Ring System ? " : " No " ,
23 " Global Magnetic Field ? " : " Yes "
24 },

12. Run the select planet.py program, in a similar manner as Listing 7.

The contents of select planet.py are given in Listing 12. This Python program prints the names
of the collections and then checks if the ’orbit data’ collection is present. If the ’OrbitData’
collection is present, it prints the names of each of the planets and the complete document for
Pluto.

The find function at Line 26 includes two arguments, which are each given within {} parentheses.
The first pair of {} parentheses is empty. This is the condition, which is optional. Since the
condition is empty, all documents are considered. The second argument is {’name’:1, ’ id’:0
}. The second argument is a list of document fields that should be considered. The format is the
field name, a colon and the position number. Setting the position number to zero for the id field
causes it not to be printed.

The find one function at Line 32 includes a condition that the field ’name’ must be equal to
’Pluto’. Since the list of fields to be considered is omitted, all fields are returned.

Listing 12: The file select planet.py.

1 # !/ usr / bin / env python3
2 import mongo_connect
3 import pprint
4 import sys
5
6 # Create a client connection to the MongoDB database .
7 client = mongo_connect . get_client ()
8
9 # Get a connection to the database .
10 db = client [ mongo_connect . ge t_data base_n ame () ]
11
12 # Read the available collection names .
13 print ( " >> Available collections : " )
14 for collection_name in db . l i s t _ c o l l e c t i o n _ n a m e s () :
15 print ( collection_name )
16 print ()
17
18 if " OrbitData " not in db . l i s t _ c o l l e c t i o n _ n a m e s () :
19 print ( " !! Error : the \" OrbitData \" collection was not found . " )
20 sys . exit (1)

Introduction to MongoDB Page 7 of 11

 21
22 orbit_data = db [ " OrbitData " ]
23
24 # Print the names of the planets .
25 print ( " >> The names of the planets : " )
26 for planet in orbit_data . find ({} , { ’ name ’: 1 , ’ _id ’: 0}) :
27 print ( planet )
28 print ()
29
30 # Print the data for Pluto
31 print ( " >> The data for Pluto : " )
32 planet = orbit_data . find_one ({ ’ name ’: ’ Pluto ’ })
33 pprint . pprint ( planet )

13. Run the planets with moons.py program, in a similar manner as Listing 7.

The contents of planets with moons.py are given in Listing 13. This program reads data from
the ’OrbitData’ collection. The find function at Line 25 is used to list the names of the planets
and their number of moons. The find function at Line 32 contains two arguments. The text $gt
implies greater than. Therefore, the condition is that the selected documents must have more
than zero moons. The second argument is used to print the planet name and number of moons.
Finally, the sort function is used to sort the documents by the number of moons.

Listing 13: The file planets with moons.py.

1 # !/ usr / bin / env python3
2 import mongo_connect
3 import sys
4
5 # Create a client connection to the MongoDB database .
6 client = mongo_connect . get_client ()
7
8 # Get a connection to the database .
9 db = client [ mongo_connect . ge t_data base_n ame () ]
10
11 # Read the available collection names .
12 print ( " >> Available collections : " )
13 for collection_name in db . l i s t _ c o l l e c t i o n _ n a m e s () :
14 print ( collection_name )
15 print ()
16
17 if " OrbitData " not in db . l i s t _ c o l l e c t i o n _ n a m e s () :
18 print ( " !! Error : the \" OrbitData \" collection was not found . " )
19 sys . exit (1)

Introduction to MongoDB Page 8 of 11

 20
21 orbit_data = db [ " OrbitData " ]
22
23 # Print the names of the planets .
24 print ( " >> The names of the planets : " )
25 for planet in orbit_data . find ({} , { ’ name ’: 1 , ’ Number of Moons ’: 2 , ’
_id ’: 0}) :
26 print ( planet )
27 print ()
28
29
30 # Print planets with moons .
31 print ( " >> Planets with moons : " )
32 for planet in orbit_data . find ({ ’ Number of Moons ’: { ’ $ gt ’: 0}} ,
33 { ’ name ’: 1 , ’ Number of Moons ’: 2 , ’ _id ’
: 0}
34 ) . sort ( ’ Number of Moons ’) :
35 print ( planet )
36 print ()

The comparison query operators are provided in Table 2 for reference. These operators should
be used within double or single quotes when implemented in Python with pymongo.

Table 2: Comparison query operators.

Operator Name
$eq Matches values that are equal to a specified value
$gt Matches values that are greater than a specified value
$gte Matches values that are greater than or equal to a specified value
$in Matches any of the values specified in an array
$lt Matches values that are less than a specified value
$lte Matches values that are less than or equal to a specified value
$ne Matches all values that are not equal to a specified value
$nin Matches none of the values specified in an array

Introduction to MongoDB Page 9 of 11

 14. Select planets by another document field.
15. Order planets by their mass.
16. Run the drop database.py program, in a similar manner as Listing 7.
17. Run the index database.py program, in a similar manner as Listing 7.

The contents of index database.py are given in Listing 14. This program creates a database
and a ’Customers’ collection. Before any documents are added, an index is defined at Line 15.
This index requires that CustomerName entries are unique within the collection. A customer is
defined at Line 18 and inserted at Line 23. If the insert operation fails, the program prints the
warning message at Line 26.

Listing 14: The file index database.py.

1 # !/ usr / bin / env python3
2 import pymongo
3 import mongo_connect
4
5 # Get a client connection to the MongoDB database .
6 client = mongo_connect . get_client ()
7
8 # Create a connection to the database .
9 db = client [ mongo_connect . ge t_data base_n ame () ]
10
11 # Create a collection .
12 customers = db [ ’ Customers ’]
13
14 # Create an index to require unique names .
15 customers . create_index ([( ’ CustomerName ’ , pymongo . ASCENDING ) ] , unique =
True )
16
17 # Create a document , which is a Python dictionary .
18 customer = { " CustomerId " : " 1 " ,
19 " CustomerName " : " Barry Rayner " }
20
21 # Insert the document into the collection .
22 try :
23 id = customers . insert_one ( customer )
24 print ( " Inserted : " + str ( customer ) )
25 except pymongo . errors . Du plicat eKeyEr ror :
26 print ( " Warning : could not insert the customer document . " )

18. Run the index database.py program, in a similar manner as Listing 7. What happened the
second time that the program was run?

Introduction to MongoDB Page 10 of 11

 19. Run the script drop database.py and then index database.py in a similar manner as Listing 7.
What happens this time?
20. Run the drop database.py program, in a similar manner as Listing 7.

The MongoDB condition and selection of document data is similar to the functionality that is defined
with SQL where and select clauses and a relational database. MongoDB will also allow a schema to
be defined for document validation.

Introduction to MongoDB Page 11 of 11