********
Indexing
********

.. default-domain:: mongodb

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

The driver provides the ability to create, drop and view
:manual:`indexes</indexes/>` on a collection through the ``indexes`` attribute:

.. code-block:: ruby

  client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music')
  client[:bands].indexes
  # => #<Mongo::Index::View:0x000055e2822b9318 @collection=#<Mongo::Collection:0x660 namespace=music.bands>, @batch_size=nil, @options={}>


Creating Indexes
================

Indexes can be created one at a time, or several can be created in a single
operation. When creating multiple indexes on MongoDB 3.0 and later, the indexes
are created in parallel; on earlier versions they are created sequentially.

To create a single index, use ``indexes#create_one``, passing the key
specification as the first argument and options as the second argument:

.. code-block:: ruby

  client[:bands].indexes.create_one(genre: 1)

  client[:bands].indexes.create_one(
    { name: 1 },
    unique: true, expire_after: 120,
  )

To create multiple indexes, use ``indexes#create_many`` which accepts an array
of index specifications. Unlike ``create_one``, each index specification
is a hash with the ``key`` key mapped to the key specification and the
options being specified on the top level.

.. code-block:: ruby

  client[:bands].indexes.create_many([
    { key: { genre: 1 } },
    { key: { name: 1 }, unique: true, expire_after: 120 },
  ])

.. _index-options:

The following is a full list of the available options that can be added
when creating indexes. These options mirror the options supported by the
:manual:`createIndex command</reference/method/db.collection.createIndex/>`.

.. list-table::
   :header-rows: 1
   :widths: 40 80

   * - Option
     - Description
   * - ``:background``
     - Either ``true`` or ``false``. Tells the index to be created in the background.
   * - ``:expire_after``
     - Number of seconds to expire documents in the collection after.
   * - ``:name``
     - The name of the index.
   * - ``:sparse``
     - Whether the index should be sparse or not, either ``true`` or ``false``.
   * - ``:storage_engine``
     - The name of the storage engine for this particular index.
   * - ``:version``
     - The index format version to use.
   * - ``:default_language``
     - The default language of text indexes.
   * - ``:language_override``
     - The field name to use when overriding the default language.
   * - ``:text_version``
     - The version format for text index storage.
   * - ``:weights``
     - A document specifying fields and weights in text search.
   * - ``:sphere_version``
     - The 2d sphere index version.
   * - ``:bits``
     - Sets the maximum boundary for latitude and longitude in the 2d index.
   * - ``:max``
     - Maximum boundary for latitude and longitude in the 2d index.
   * - ``:min``
     - Minimum boundary for latitude and longitude in the 2d index.
   * - ``:bucket_size``
     - The number of units within which to group the location values in a geo haystack index.
   * - ``:partial_filter_expression``
     - A filter for a partial index.
   * - ``:hidden``
     - A Boolean specifying whether the index should be hidden; a hidden index 
       is one that exists on the collection but will not be used by the query planner.

The :commit_quorum option
-------------------------
On MongoDB server versions 4.4 and newer, the ``:commit_quorum`` option may be
specified on index creation. This option differs from other index options in that
it determines server behavior during index creation, rather than determining
the behavior of an individual index.

The ``:commit_quorum`` option specifies how many voting, data-bearing members
of a replica set must complete the index build before the index is ready.
Possible values are integers (0 to the number of voting, data-bearing members
of the replica set), "majority", or "votingMembers".

To specify ``:commit_quorum`` when creating one index, add another option
to the second argument of the ``indexes#create_one`` method:

.. code-block:: ruby

  client[:bands].indexes.create_one(
    { name: 1 },
    unique: true, expire_after: 120, commit_quorum: 'majority'
  )

To specify create options when creating multiple indexes, add a Hash specifying
``:commit_quorum`` as a final element to the Array of indexes passed to
``indexes#create_many``. Note that this Hash MUST be the final element in the
Array.

.. code-block:: ruby

  client[:bands].indexes.create_many([
    { key: { genre: 1 } },
    { key: { name: 1 }, unique: true, expire_after: 120 },
    { commit_quorum: 'majority' },
  ])

Dropping Indexes
================

To drop an index, call ``indexes#drop_one`` or ``indexes#drop_all``.

.. code-block:: ruby

  # Drops the name_1 index.
  client[:bands].indexes.drop_one( 'name_1' )

  # Drops all indexes in the collection.
  client[:bands].indexes.drop_all


Listing Indexes
===============

To list the indexes, iterate the ``indexes`` object:

.. code-block:: ruby

  client[:bands].indexes.each do |index_spec|
    p index_spec
    # {"v"=>2, "key"=>{"_id"=>1}, "name"=>"_id_"}
    # {"v"=>2, "key"=>{"genre"=>1}, "name"=>"genre_1"}
    # {"v"=>2, "unique"=>true, "key"=>{"name"=>1}, "name"=>"name_1",
    #  "expireAfterSeconds"=>120}
  end

Each iteration returns an index specification as returned by the
:manual:`listIndexes</reference/command/listIndexes/>` command.

.. note::

  The shape and contents of the index specifications returned by this method
  may change from one version of MongoDB to another.