Basic Usage

Simon offers a lot of flexibility in how you interact with the database.

All of the examples below utilize the User model defined in Quickstart, so if you haven’t already done that, you want to check it out first.


At the heart of retrieving documents are three methods: all(), find(), and get().

Use all() to retrieve all documents from the users collection.

users = Users.all()

Often times it will be necessary to filter the documents coming back. To do so, use find(). It takes a series of named parameters that represent keys in the documents and the values to match against.

To find all documents whose name field has a value of Simon:

users = Users.find(name='Simon')

To find all documents whose name field has a value of Simon and whose company field has a value of My Company:

internal_users = Users.find(name='Simon', company='My Company')

If you were to execute these queries using the mongo Shell, they would look like:

users = db.users.find({name: 'Simon'})

internal_users = db.users.find({name: 'Simon', company: 'My Company'})

At this point, no real information would have been returned from the database. Utilizing the cursor behavior built into PyMongo, documents will only be transferred from the database when they are requested. This is done by interacting with the result of find() like you would with any other iterable such as a list.

for user in users:
    print 'A document was just loaded from the users collection'

Documents can also be loaded through slicing, although this will cause all documents in, as well as prior to, the slice to be loaded.

first_user = users[0]
# the first user has been loaded

fourth_users = users[3]
# the first four users have been loaded

all_users = users[:]
# all users have been loaded

More advanced uses are covered in Querying.


The main way to save a document using Simon is with save(). Calling it on an instance with a new document will insert the document. The document will be given an ObjectId by the database, which will then be associated with the instance.

user = User(name='Simon')  # insert

Calling save() on an instance with an existing document will update the document. This will replace what’s in the database with the one associated with the instance. = ''  # update

The equivalent queries in the mongo Shell would be:

db.users.insert({name: 'Simon'})

db.users.update({_id: ObjectId(...)}, {email: ''})

More advanced uses are covered in Saving.


If you don’t want a document anymore, removing it from the database is simply a matter of calling delete().


Be careful as this will raise a TypeError if you try to delete a document that was never saved.

If you were to execute this query directly in mongo Shell, it would look like:

db.users.remove({_id: ObjectId(...)})

At the time of this writing there appears to be no way to set the justOne parameter to true using PyMongo. If you decide to remove the unique constraint from the _id field, bad things could happen when you use delete().

Table Of Contents

Previous topic


Next topic

The QuerySet Class

This Page

Fork me on GitHub