adding reference indexes back

Author: mayaraman19

source/reference/indexes.txt

@@ -0,0 +1,278 @@
+.. _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
+
+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``.
+
+.. code-block:: ruby
+
+    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:
+
+.. 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>`_.
+
+
+Specifying Search Indexes on MongoDB Atlas
+==========================================
+
+If your application is connected to MongoDB Atlas, you can declare and manage
+search indexes on your models. (This feature is only available on MongoDB
+Atlas.)
+
+To declare a search index, use the ``search_index`` macro in your model:
+
+.. code-block:: ruby
+
+    class Message
+      include Mongoid::Document
+
+      search_index { ... }
+      search_index :named_index, { ... }
+    end
+
+Search indexes may be given an explicit name; this is necessary if you have
+more than one search index on a model.
+
+
+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
+
+Managing Search Indexes on MongoDB Atlas
+----------------------------------------
+
+If you have defined search indexes on your model, there are rake tasks available
+for creating and removing those search indexes:
+
+.. code-block:: bash
+
+    $ rake db:mongoid:create_search_indexes
+    $ rake db:mongoid:remove_search_indexes
+
+By default, creating search indexes will wait for the indexes to be created,
+which can take quite some time. If you want to simply let the database create
+the indexes in the background, you can set the ``WAIT_FOR_SEARCH_INDEXES``
+environment variable to 0, like this:
+
+.. code-block:: bash
+
+    $ rake WAIT_FOR_SEARCH_INDEXES=0 db:mongoid:create_search_indexes
+
+Note that the task for removing search indexes will remove all search indexes
+from all models, and should be used with caution.
+
+You can also add and remove search indexes for a single model by invoking the
+following in a Rails console:
+
+.. code-block:: ruby
+
+    # Create all defined search indexes on the model; this will return
+    # immediately and the indexes will be created in the background.
+    Model.create_search_indexes
+
+    # Remove all search indexes from the model
+    Model.remove_search_indexes
+
+    # Enumerate all search indexes on the model
+    Model.search_indexes.each { |index| ... }
+
+
+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:
+
+.. code-block:: ruby
+
+    # 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:
+
+.. code-block:: ruby
+
+    # 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:
+
+.. code-block:: ruby
+
+    # Rakefile
+
+    require 'mongoid'
+    load 'mongoid/tasks/database.rake'
+
+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'