mongodb/mongo-ruby-driver

********************
Atlas Search Indexes
********************

.. default-domain:: mongodb

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

If you are using a database hosted by MongoDB Atlas, the driver provides the
ability to create, drop and view `Atlas search indexes <https://www.mongodb.com/docs/atlas/atlas-search/>`_
on a collection through the ``search_indexes`` attribute:

.. code-block:: ruby

  client = Mongo::Client.new(your_atlas_uri, database: 'music')
  client[:bands].search_indexes
  # => #<Mongo::SearchIndex::View:0x000055e2822b9318 @collection=#<Mongo::Collection:0x660 namespace=music.bands> ...>


Creating Search Indexes
=======================

Search indexes can be created one at a time, or several can be created in
parallel in a single operation.

To create a single index, use ``search_indexes#create_one``, passing the index
definition as the first argument, and an optional name for the index as the
second argument.

.. code-block:: ruby

  client[:bands].search_indexes.create_one({ dynamic: true })

  client[:bands].search_indexes.create_one(
    {
      dynamic: false,
      fields: {
        name: { type: 'string', analyzer: 'lucene.simple' }
      }
    },
    'band-name-index'
  )

To create multiple indexes, use ``search_indexes#create_many`` which accepts
an array of index specifications. Unlike ``create_one``, each index
specification is a hash with at least a ``definition`` key, which
defines the index. Each has may also specify a ``name`` key, to name
the index.

.. code-block:: ruby

  client[:bands].search_indexes.create_many([
    { definition: { dynamic: true } },
    { name: 'band-name-index,
      definition: {
        dynamic: false,
        fields: {
          name: { type: 'string', analyzer: 'lucene.simple' }
        }
      }
    },
  ])

Note that whether you call ``create_one`` or ``create_many``, the
method will return immediately, before the indexes are created. The
indexes are then created in the background, asynchronously.


Update Search Indexes
=====================

You can programmatically update an Atlas search index. For example, you
might do this to change the analyzer used, or to provide an explicit field
mapping, instead of a dynamic one. To do this, use the ``search_indexes#update_one``
method:

.. code-block:: ruby

  client[:bands].search_indexes.update_one(new_definition, id: index_id)

  client[:bands].search_indexes.update_one(new_definition, name: index_name)

Indexes may be identified by either id, or name, but you must specify one
or the other. The new index definition must be a complete definition--it will
take precedence as specified over the existing definition.

To get the id or name of an index that you wish to update, you can
`list the search indexes <#listing-search-indexes>`_.


Dropping Search Indexes
=======================

To drop Atlas search indexes, call ``search_indexes#drop_one`` and
provide either the ``id`` or the ``name`` of the index you wish to
drop.

.. code-block:: ruby

  client[:bands].search_indexes.drop_one(id: index_id)

  client[:bands].search_indexes.drop_one(name: index_name)

In either case, the method will return immediately and the index will
be dropped in the background, asynchronously.

To get the id or name of an index that you wish to drop, you can
`list the search indexes <#listing-search-indexes>`_.


Listing Search Indexes
======================

To list the available search indexes, iterate over the
``search_indexes`` object:

.. code-block:: ruby

  client[:bands].search_indexes.each do |index_spec|
    p index_spec['id']
    p index_spec['name']
    p index_spec['status']
    p index_spec['queryable']
    p index_spec['latestDefinition']
  end