.. _indexes:

****************
Index Management
****************

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol

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:

.. code-block:: ruby

    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:

.. code-block:: ruby

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

You can index on multiple fields and provide direction:

.. code-block:: ruby

    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:

.. code-block:: ruby

    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:

.. code-block:: ruby

    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:

.. code-block:: ruby

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

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

.. code-block:: ruby

    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.

.. code-block:: ruby

    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`` :ref:`configuration option <configuration-options>`.

The ``background`` option has `no effect as of MongoDB 4.2
<https://www.mongodb.com/docs/manual/core/index-creation/#comparison-to-foreground-and-background-builds>`_.


Index Management Rake Tasks
===========================

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

.. code-block:: bash

    $ rake db:mongoid:create_indexes

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

.. code-block:: bash

    $ 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:

.. code-block:: ruby

    # Create indexes for Model
    Model.create_indexes

    # Remove indexes for Model
    Model.remove_indexes

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. This can be achieved by loading them in the Rakefile and
providing an ``:environment`` task to load your application's models:

.. code-block:: ruby

    # Rakefile

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

    task :environment do
      # Require/load your application's models here
    end

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

.. code-block:: ruby

    # Rakefile

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

    task :environment do
      # Require/load your application's models here
    end