Navigation

Index Management

Specifying Indexes

You can define indexes on documents using the index macro. Provide the key for the index along with a direction. Additional options can be supplied in the second options hash parameter:

class Person
  include Mongoid::Document
  field :ssn

  index({ ssn: 1 }, { unique: true, name: "ssn_index" })
end

You can define indexes on embedded document fields as well:

class Person
  include Mongoid::Document
  embeds_many :addresses
  index "addresses.street" => 1
end

You can index on multiple fields and provide direction:

class Person
  include Mongoid::Document
  field :first_name
  field :last_name

  index({ first_name: 1, last_name: 1 }, { unique: true })
end

Indexes can be sparse:

class Person
  include Mongoid::Document
  field :ssn

  index({ ssn: -1 }, { sparse: true })
end

For geospatial indexes, make sure the field being indexed is of type Array:

class Person
  include Mongoid::Document
  field :location, type: Array

  index({ location: "2d" }, { min: -200, max: 200 })
end

Indexes can be scoped to a specific database:

class Person
  include Mongoid::Document
  field :ssn
  index({ ssn: 1 }, { database: "users", unique: true, background: true })
end

You may use aliased field names in index definitions. Field aliases will also be resolved on the following options: partial_filter_expression, weights, wildcard_projection.

class Person
  include Mongoid::Document
  field :a, as: :age
  index({ age: 1 }, { partial_filter_expression: { age: { '$gte' => 20 } })
end

Note

The expansion of field name aliases in index options such as partial_filter_expression is performed according to the behavior of MongoDB server 6.0. Future server versions may change how they interpret these options, and Mongoid’s functionality may not support such changes.

Mongoid can define indexes on “foreign key” fields for associations. This only works on the association macro that the foreign key is stored on:

class Comment
  include Mongoid::Document
  belongs_to :post, index: true
  has_and_belongs_to_many :preferences, index: true
end

Deprecated: In MongoDB 4.0 and earlier, users could control whether to build indexes in the foreground (blocking) or background (non-blocking, but less efficient) using the background option.

class Person
  include Mongoid::Document
  field :ssn
  index({ ssn: 1 }, { unique: true, background: true })
end

The default value of background is controlled by Mongoid’s background_indexing configuration option.

The background option has no effect as of MongoDB 4.2.

Index Management Rake Tasks

When you want to create the indexes in the database, use the provided db:mongoid:create_indexes Rake task:

$ rake db:mongoid:create_indexes

Mongoid also provides a Rake task to delete all secondary indexes.

$ rake db:mongoid:remove_indexes

Note: the output of these Rake tasks goes to the default logger configured by Rails. This is usually a file like log/development.log and not standard output.

These create/remove indexes commands also works for just one model by running in Rails console:

# Create indexes for Model
Model.create_indexes

# Remove indexes for Model
Model.remove_indexes

Telling Mongoid Where to Look For Models

For non-Rails applications, Mongoid’s rake tasks will look for models in ./app/models and ./lib/models. For Rails, Mongoid will look in ./app/models (or wherever you’ve configured Rails to look for models). If your models are in another location, you will need to tell Mongoid where to look for them with Mongoid.model_paths=. You can do this by setting it in your application’s Rakefile:

# Rakefile

# keep the defaults, but add more paths to look for models
Mongoid.model_paths += [ "./src/models", "./lib/documents" ]

# or, override the defaults entirely
Mongoid.model_paths = [ "./src/models", "./lib/documents" ]

Make sure that these paths are in your application’s load path, as well. For example:

# Rakefile

$LOAD_PATHS.concat [ "./src/models", "./lib/documents" ]

Using Rake Tasks With Non-Rails Applications

Mongoid’s Rake tasks are automatically loaded in Rails applications using Mongoid. When using Mongoid with a non-Rails application, these tasks must be loaded manually:

# Rakefile

require 'mongoid'
load 'mongoid/tasks/database.rake'

If your application uses Bundler, you can require bundler/setup instead of explicitly requiring mongoid:

# Rakefile

require 'bundler/setup'
load 'mongoid/tasks/database.rake'