Python Driver Examples

PyMongo is the recommended Python driver for working with MongoDB. Here’s the compatibility breakdown:

Here are the recommended versions of each driver to use with a specific version of MongoDB:

Python Driver	MongoDB 2.4	MongoDB 2.6	MongoDB 3.0
3.0	✓	✓	✓
2.8	✓	✓	✓

Here are the recommended driver versions to use with each version of Python:

Python Driver	Python 2.7, PyPy	Python 3.1	Python 3.2, PyPy3	Python 3.3	Python 3.4
3.0	✓		✓	✓	✓
2.8	✓	✓	✓	✓	✓

Installation

Installation is simple and uses the expected pip command:

$ sudo pip install pymongo

However you can also install it using setuptools:

$ sudo easy_install pymongo

Then you can import it like anything else:

from pymongo import MongoClient

Example document

Here’s the example document we’ll be using:

{
    "start": "2015-09-02T22:46:30.782Z",
    "end": "2016-09-02T22:46:30.782Z",
    "location": "Texas",
    "official_game": false,
    "winner": "Javi",
    "players": [
        {
            "name": "Javi",
            "decks": [
                "Dinosaurs",
                "Plants"
            ],
            "points": 24,
            "place": 1
        },
        {
            "name": "Seth",
            "decks": [
                "Spies",
                "Zombies"
            ],
            "points": 20,
            "place": 2
        },
        {
            "name": "Dave",
            "decks": [
                "Steampunk",
                "Wizard"
            ],
            "points": 20,
            "place": 2
        },
        {
            "name": "Castro",
            "decks": [
                "Shapeshifters",
                "Ninjas"
            ],
            "points": 18,
            "place": 4
        }
    ]
}

Connecting

Warning

When connecting using the MongoDB URI, we highly recommend avoiding usernames or passwords with an @ symbol inside. This can break the URI parsing and cause failures when trying to connect.

Connecting to a replica set:

import pymongo

settings = {
    'host': 'dfw-c9-1.objectrocket.com:12345,dfw-c9-0.objectrocket.com:37143',
    'database': 'YOUR_DATABASE_NAME',
    'username': 'YOUR_USERNAME',
    'password': 'YOUR_PASSWORD',
    'options': 'replicaSet=c74b5276378ed3bd70cba37a3ac45fea'
}

try:
    conn = pymongo.MongoClient("mongodb://{username}:{password}@{host}/{database}?{options}".format(**settings))
    collectionNames = conn[settings.database].collection_names()
    print "Connected"
    print "Collection Names", collectionNames
    conn.close()
except Exception as ex:
    print "Error:", ex
    exit('Failed to connect, terminating.')

Connecting to a sharded instance with a write concern of 1:

import pymongo

settings = {
    'host': 'iad-mongos0.objectrocket.com:12345/example_db',
    'database': 'YOUR_DATABASE_NAME',
    'username': 'YOUR_USERNAME',
    'password': 'YOUR_PASSWORD',
    'options': 'w=1'
}

try:
    conn = pymongo.MongoClient("mongodb://{username}:{password}@{host}/{database}?{options}".format(**settings))
    collectionNames = conn[settings.database].collection_names()
    print "Connected"
    print "Collection Names", collectionNames
    conn.close()
except Exception as ex:
    print "Error:", ex
    exit('Failed to connect, terminating.')

Connecting to a sharded instance using SSL:

Make sure to change the port number when using an SSL connection.

import pymongo

settings = {
    'host': 'iad-mongos0.objectrocket.com:12345',
    'database': 'YOUR_DATABASE_NAME',
    'username': 'YOUR_USERNAME',
    'password': 'YOUR_PASSWORD',
    'options': 'ssl=true'
}

try:
    conn = pymongo.MongoClient("mongodb://{username}:{password}@{host}/{database}?{options}".format(**settings))
    collectionNames = conn[settings.database].collection_names()
    print "Connected"
    print "Collection Names", collectionNames
    conn.close()
except Exception as ex:
    print "Error:", ex
    exit('Failed to connect, terminating.')

Creating a document

Creating and inserting a document:

import pymongo
from datetime import datetime

settings = {
    'host': 'iad-mongos0.objectrocket.com:12345',
    'database': 'YOUR_DATABASE_NAME',
    'collection': 'YOUR_COLLECTION_NAME',
    'username': 'YOUR_USERNAME',
    'password': 'YOUR_PASSWORD',
    'options': 'w=1'
}

example_doc = {
    "start": datetime.utcnow(),
    "end": datetime(2015, 8, 22, 16, 22, 38),
    "location": "Texas",
    "official_game": False,
    "winner": "Javi",
    "players": [
        {
            "name": "Javi",
            "decks": [
                "Dinosaurs",
                "Plants"
            ],
            "points": 24,
            "place": 1
        },
        {
            "name": "Seth",
            "decks": [
                "Spies",
                "Zombies"
            ],
            "points": 20,
            "place": 2
        },
        {
            "name": "Dave",
            "decks": [
                "Steampunk",
                "Wizard"
            ],
            "points": 20,
            "place": 2
        },
        {
            "name": "Castro",
            "decks": [
                "Shapeshifters",
                "Ninjas"
            ],
            "points": 18,
            "place": 4
        }
    ]
}

try:
    conn = pymongo.MongoClient("mongodb://{username}:{password}@{host}/{database}?{options}".format(**settings))
    db = conn[settings.database]
    collection = db[settings.collection]
    doc_id = collection.insert_one(example_doc).inserted_id
    print "Here is the _id of the doc I inserted: %s." % doc_id
    conn.close()
except Exception as ex:
    print "Error:", ex
    exit('Failed to connect, terminating.')

Output from above:

$ ipython pymongo_example.py
Here is the _id of the doc I inserted: 55ce1520f643f056fd1c9887.

Reading documents

Finding a document with a specific field:

import pymongo
from pprint import pprint

settings = {
    'host': 'iad-mongos0.objectrocket.com:12345',
    'database': 'YOUR_DATABASE_NAME',
    'collection': 'YOUR_COLLECTION_NAME',
    'username': 'YOUR_USERNAME',
    'password': 'YOUR_PASSWORD',
    'options': 'w=1'
}

try:
    conn = pymongo.MongoClient("mongodb://{username}:{password}@{host}/{database}?{options}".format(**settings))
    db = conn[settings.database]
    collection = db[settings.collection]
    results = collection.find_one({"winner" : "Javi"})
    print "Here is a doc: "
    pprint(results)
    conn.close()
except Exception as ex:
    print "Error:", ex
    exit('Failed to connect, terminating.')

Output from above:

Here is a doc:
{u'_id': ObjectId('55ce1520f643f056fd1c9887'),
 u'end': datetime.datetime(2015, 8, 22, 16, 22, 38),
 u'location': u'Texas',
 u'official_game': False,
 u'players': [{u'decks': [u'Dinosaurs', u'Plants'],
               u'name': u'Javi',
               u'place': 1,
               u'points': 24},
              {u'decks': [u'Spies', u'Zombies'],
               u'name': u'Seth',
               u'place': 2,
               u'points': 20},
              {u'decks': [u'Steampunk', u'Wizard'],
               u'name': u'Dave',
               u'place': 2,
               u'points': 20},
              {u'decks': [u'Shapeshifters', u'Ninjas'],
               u'name': u'Castro',
               u'place': 4,
               u'points': 18}],
 u'start': datetime.datetime(2015, 8, 14, 16, 19, 44, 868000),
 u'winner': u'Javi'}

Updating a document

Updating a document:

import pymongo
from pprint import pprint

settings = {
    'host': 'iad-mongos0.objectrocket.com:12345',
    'database': 'YOUR_DATABASE_NAME',
    'collection': 'YOUR_COLLECTION_NAME',
    'username': 'YOUR_USERNAME',
    'password': 'YOUR_PASSWORD',
    'options': 'w=1'
}

try:
    conn = pymongo.MongoClient("mongodb://{username}:{password}@{host}/{database}?{options}".format(**settings))
    db = conn.example_db
    collection = db[settings.collection]
    results = collection.find_one({"winner" : "Javi"})
    print "Here is the original doc: "
    pprint(results)

    update_doc = collection.update_one({"winner" : "Javi"},{"$set": {"winner" : "Seth"}})
    updated_doc = collection.find_one({"winner" : "Seth"})
    print "Here is how many documents I found: "
    pprint(update_doc.matched_count)
    print "Here is the new doc: "
    pprint(updated_doc)

    conn.close()
except Exception as ex:
    print "Error:", ex
    exit('Failed to connect, terminating.')

Output from above:

$ ipython update_doc.py
Here is the original doc:
{u'_id': ObjectId('55ce1d01f643f05a6ca695d4'),
 u'end': datetime.datetime(2015, 8, 22, 16, 22, 38),
 u'location': u'Texas',
 u'official_game': False,
 u'players': [{u'decks': [u'Dinosaurs', u'Plants'],
               u'name': u'Javi',
               u'place': 1,
               u'points': 24},
              {u'decks': [u'Spies', u'Zombies'],
               u'name': u'Seth',
               u'place': 2,
               u'points': 20},
              {u'decks': [u'Steampunk', u'Wizard'],
               u'name': u'Dave',
               u'place': 2,
               u'points': 20},
              {u'decks': [u'Shapeshifters', u'Ninjas'],
               u'name': u'Castro',
               u'place': 4,
               u'points': 18}],
 u'start': datetime.datetime(2015, 8, 14, 16, 53, 21, 950000),
 u'winner': u'Javi'}
Here is how many documents I found:
1
Here is the new doc:
{u'_id': ObjectId('55ce1d01f643f05a6ca695d4'),
 u'end': datetime.datetime(2015, 8, 22, 16, 22, 38),
 u'location': u'Texas',
 u'official_game': False,
 u'players': [{u'decks': [u'Dinosaurs', u'Plants'],
               u'name': u'Javi',
               u'place': 1,
               u'points': 24},
              {u'decks': [u'Spies', u'Zombies'],
               u'name': u'Seth',
               u'place': 2,
               u'points': 20},
              {u'decks': [u'Steampunk', u'Wizard'],
               u'name': u'Dave',
               u'place': 2,
               u'points': 20},
              {u'decks': [u'Shapeshifters', u'Ninjas'],
               u'name': u'Castro',
               u'place': 4,
               u'points': 18}],
 u'start': datetime.datetime(2015, 8, 14, 16, 53, 21, 950000),
 u'winner': u'Seth'}

Deleting a document

Deleting a document:

import pymongo
from pprint import pprint

settings = {
    'host': 'iad-mongos0.objectrocket.com:12345',
    'database': 'YOUR_DATABASE_NAME',
    'collection': 'YOUR_COLLECTION_NAME',
    'username': 'YOUR_USERNAME',
    'password': 'YOUR_PASSWORD',
    'options': 'w=1'
}

try:
    conn = pymongo.MongoClient("mongodb://{username}:{password}@{host}/{database}?{options}".format(**settings))
    db = conn.example_db
    collection = db[settings.collection]
    results = collection.find_one({"winner" : "Seth"})
    print "Here is the doc I found: "
    pprint(results)

    deleted = collection.delete_one({"winner" : "Seth"})
    print "Here is how many documents I deleted: "
    pprint(deleted.deleted_count)

    conn.close()
except Exception as ex:
    print "Error:", ex
    exit('Failed to connect, terminating.')

Output from above:

$ ipython delete_doc.py
Here is the doc I found:
{u'_id': ObjectId('55ce1d01f643f05a6ca695d4'),
 u'end': datetime.datetime(2015, 8, 22, 16, 22, 38),
 u'location': u'Texas',
 u'official_game': False,
 u'players': [{u'decks': [u'Dinosaurs', u'Plants'],
               u'name': u'Javi',
               u'place': 1,
               u'points': 24},
              {u'decks': [u'Spies', u'Zombies'],
               u'name': u'Seth',
               u'place': 2,
               u'points': 20},
              {u'decks': [u'Steampunk', u'Wizard'],
               u'name': u'Dave',
               u'place': 2,
               u'points': 20},
              {u'decks': [u'Shapeshifters', u'Ninjas'],
               u'name': u'Castro',
               u'place': 4,
               u'points': 18}],
 u'start': datetime.datetime(2015, 8, 14, 16, 53, 21, 950000),
 u'winner': u'Seth'}
Here is how many documents I deleted:
1

Additional reading

If you need more help with PyMongo, links to official documentation are below:

• PyMongo Github
• MongoDB Python Driver documentation
• MongoDB Python Driver Tutorial
• Getting Started with MongoDB (Python Edition)

As always, if you have any questions, please don’t hesitate to reach out to our support team!