Mongo Mapper




Find one or more documents by their _id.

# works with string representation of object id

# or with actual object id

# also works with array of ids or multiple arguments
Patient.find(['4da32870c198a73ca3000001', '4da32870c198a73ca3000002'])
Patient.find('4da32870c198a73ca3000001', '4da32870c198a73ca3000002')


Get all of the documents in a query as an array. Works with options or criteria.

Patient.all(:last_name => 'Johnson', :order => :last_name.asc)


Get all of the documents in a query one at a time and pass them to the given block. Works with options or criteria.

Patient.find_each(:last_name => "Johnson") do |document|
  # do something with document


Get the first document in a query. Naturally, this makes the most sense when you have also provided a means of sorting.

Patient.first(:order => :created_at.desc)
Patient.first(:email => '')


Get the last document in a query. Naturally, this makes the most sense when you have also provided a means of sorting.

Patient.last(:order => :created_at.asc)


Paginate the query.

  :order    => :created_at.asc,
  :per_page => 25,
  :page     => 3,


Mongo has rich support for dynamic queries. MongoMapper uses Plucky to construct query proxy objects that only retrieve data from Mongo when needed. This allows a query to be composed of several conditions before being evaluated.


Use where to specify your query criteria.

patients = Patient.where(:first_name => "John", :last_name => "Johnson")


Sometimes you know you are loading objects for a very specific purpose–maybe to show a few fields on the UI. You can limit the number of fields returned with data filled in as follows:

query = Patient.where(:last_name => "Johnson").
        fields(:last_name, :gender).all
#=> [#<Patient created_at: nil, updated_at: nil, _id: BSON::ObjectId('4d140b878951a202ae000002'), gender: "M", last_name: "Johnson", first_name: nil>]

Note that all the other attributes in your model will be nil (or set to their default value). Therefore, if you call a method that makes use of all the attributes–like to_json–then keep in mind that the values will be nil, and you will need to emit only those fields:

query.to_json(:only => [:last_name, :gender])
#=> "[{\"last_name\":\"Johnson\",\"gender\":\"M\"}]"


Instead of returning an array of complete documents, you may want to merely check to see how many exist.

patients = Patient.where( :last_name.gte => 'A', => 'B' ).count
#=> 1803

sort, order

You can choose to sort the documents by various keys, ascending (default) or descending.


Patient.where(:updated_at.gte => 3.days.ago).sort(:updated_at.desc)


You can limit the number of documents returned by the query.

patients = Patient.sort(:last_name).limit(10)

skip, offset

Skip is used to return a list of documents beyond the number that are requested to be skipped.

patients = Patient.sort(:last_name).limit(10).skip(10)


Mongo supports quite a few conditional operators. You can use these directly in your MongoMapper queries.

User.where(:age => {:$gt => 21, :$lt => 30})

MongoMapper also provides shorthand for most of these operators.

User.where( => 21)

See MongoDB’s documentation on conditional operators.

Destroying documents

MongoMapper provides 2 methods for destroying/deleting documents and 2 methods for removing/destroying all documents.


Destroy a single or multiple document(s) by providing ID (s) or tne instance of a document

# Destroy a single user with the given ID

# Destroys two user with given ids
User.destroy("50a210d2f7aa6006d2000001", "50a21153f7aa6006d2000002")

# Delete an instance
u = User.create(:name => cow)


Destroy all or multiple documents from given matching criteria Warning: You can loose all your data if you call this at the wrong time.

# Destroy every user in the collection

# Destroys user with a given name
User.destroy_all(:name => "George")


Delete document(s) from given ID (s) or the delete an instance of a document. Callbacks are NOT triggered.

Usage is identical to destroy


Delete multiple or all documents. Callbacks are NOT triggered.

Usage is identical to destroy_all

MongoDB Querying Documentation

Fork me on GitHub