identity map

The identity map in Mongoid is a current aid to assist with excessive database queries in relations, and is necessary for eager loading to work. It's functionality will be extended in future releases.

To enable the identity map, simply change the configuration option in your mongoid.yml.

identity_map_enabled: true

When a document is now loaded from the database, is is automatically added to the identity map by it's class and id. Subsequent request for that document by it's id will not hit the database, but rather pull the document back from the identity map itself. It's primary function in this capacity is to aid in cutting down queries for belongs_to relations when iterating over the parents.

access

You can access documents in the map directly via the get method. It requires the class of the document you want and an id.

Mongoid::IdentityMap.get(Person, id)

Note in future releases the Mongoid finders will hook directly into the map so you don't have to access it directly.

the unit of work

To prevent database objects from becoming stale, the documents in the identity map should only exist in a single unit of work, which is usually a single request to the application.

rails

No extra work is needed for Rails users, Mongoid will automatically clear out the identity map after each request.

sinatra

You can require the Mongoid identity map middleware in your application to clear out the map with each request:

use Rack::Mongoid::Middleware::IdentityMap

non rack based applications

For users not using rack based apps, you will need to wrap your requests or application defined unit of work in a Mongoid.unit_of_work block:

Mongoid.unit_of_work do
  Person.create(title: "Grand Poobah")
end

testing

If you have the identity map enabled in your application, you should set up a global hook to clear out the map before each test so the test suite does not create memory bloat. For example in RSpec in spec_helper.rb.

RSpec.configure do |config|
  config.before(:each) { Mongoid::IdentityMap.clear }
end