DOCSP-9555: indexes (#55)

* DOCSP-9555: indexes

* addressing nits

* more clarity

* test comment delimit

* adding more rst comments

* code block formatting

* more formatting

* clarify that indexes support other operations

* wording

* indexes in toc tree

* more nits

* fixing extlinks

* formatting fixes

* clarifications

* imports

* monospace field names

* monospace field names

Author: terakilobyte

source/fundamentals.txt

@@ -14,12 +14,12 @@ Fundamentals
    /fundamentals/databases-collections
    /fundamentals/data-formats
    /fundamentals/crud
+   /fundamentals/indexes
    /fundamentals/aggregation
 
 
 ..
   /fundamentals/builders
-  /fundamentals/indexes
   /fundamentals/collations
   /fundamentals/csfle
   /fundamentals/gridfs

source/fundamentals/indexes.txt

@@ -0,0 +1,373 @@
+=======
+Indexes
+=======
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. common-content-begin
+
+Overview
+--------
+
+Indexes support the efficient execution of queries in MongoDB. Without indexes, MongoDB must scan *every* document in a
+collection (a **collection scan**) to find the documents that match each query. These collection scans are slow and can
+negatively affect the performance of your application. If an appropriate index exists for a query, MongoDB can use the
+index to limit the number of documents it must inspect.
+
+Indexes also:
+
+- allow efficient sorting
+- enable special capabilities like :ref:`geospatial <geo-indexes>` search
+- allow adding constraints to ensure a field value is :ref:`unique <unique-indexes>`
+- and :manual:`more </indexes/>`
+
+.. tip::
+
+   Indexes are also used by update operations when finding the document(s) to update, delete operations when finding the
+   document(s) to delete, and by :manual:`certain stages </core/aggregation-pipeline/#pipeline-operators-and-indexes>` in
+   the aggregation framework.
+
+Query Coverage and Performance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When you execute a query against MongoDB, your command can include various elements:
+
+- query criteria that specify field(s) and value(s) you are looking for
+- options that affect the query's execution (e.g. read concern)
+- projection criteria to specify the fields MongoDB should return (optional)
+- sort criteria to specify the order documents will be returned from MongoDB (optional)
+
+When all the fields specified in the query, projection, and sort are in the same index, MongoDB returns results directly
+from the index, also called a **covered query**.
+
+.. important:: Sort Order
+
+   Sort criteria must match or invert the order of the index.
+
+   Consider an index on the field ``name`` in ascending order (A-Z), ``age`` in descending order (9-0):
+
+   .. code-block:: none
+      :copyable: false
+
+      name_1_age_-1
+
+   MongoDB would use this index when you sort your data by either:
+
+   - ``name`` ascending, ``age`` descending
+   - ``name`` descending, ``age`` ascending
+
+   Specifying a sort order of ``name`` and :guilabel:`age` ascending or :guilabel:`name` and ``age``
+   descending would require an in-memory sort.
+
+For additional information on how to ensure your index covers your query criteria and projection, see the MongoDB manual
+articles on :manual:`query coverage </core/query-optimization/#read-operations-covered-query>`.
+
+Operational Considerations
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To improve query performance, build indexes on fields that appear often in your application's queries and operations
+that return sorted results. Each index that you add consumes disk space and memory when active so you should track index
+memory and disk usage for capacity planning. In addition, when a write operation updates an indexed field, MongoDB also
+has to update the related index.
+
+Since MongoDB supports dynamic schemas, applications can query against fields whose names cannot be known in advance or
+are arbitrary. MongoDB 4.2 introduced :manual:`wildcard indexes </core/index-wildcard/>` to help support these queries.
+Wildcard indexes are not designed to replace workload-based index planning.
+
+For more information on designing your data model and choosing indexes appropriate for your application, see the MongoDB
+server documentation on :manual:`Indexing Strategies </applications/indexes>` and
+:manual:`Data Modeling and Indexes </core/data-model-operations/#data-model-indexes>`.
+
+Index Types
+-----------
+
+MongoDB supports a number of different index types to support querying your data. The following sections describe the
+most common index types and provide sample code for creating each index type. For a full list of index types, see
+:manual:`Indexes </indexes/>`.
+
+.. common-content-end
+
+.. driver-content-begin
+
+.. tip::
+
+   The MongoDB Java Driver provides the :java-core-api:`Indexes </com/mongodb/client/model/Indexes.html>` class that
+   includes static factory methods to create index specification documents for different MongoDB Index key types.
+
+The following examples use the
+:java-sync-api:`createIndex </com/mongodb/client/MongoCollection.html#createIndex(org.bson.conversions.Bson,com.mongodb.client.model.IndexOptions)>`
+to create various indexes, and the following setup:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/IndexPage.java
+   :language: java
+   :dedent:
+   :start-after: begin imports
+   :end-before: end imports
+
+
+.. literalinclude:: /includes/fundamentals/code-snippets/IndexPage.java
+   :language: java
+   :dedent:
+   :start-after: begin declaration
+   :end-before: end declaration
+
+.. driver-content-end
+
+.. common-content-begin
+
+Single Field and Compound Indexes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Single Field Indexes
+++++++++++++++++++++
+
+:manual:`Single field indexes </core/index-single/>` are indexes with a reference to a single field within a collection's
+documents. They improve single field query and sort performance, and support :manual:`TTL Indexes </core/index-ttl>` that
+automatically remove documents from a collection after a certain amount of time or at a specific clock time.
+
+
+.. note::
+
+   The ``_id_`` index is an example of a single field index. This index is automatically created on the ``_id`` field
+   when a new collection is created.
+
+The following example creates an index in ascending order on the ``title`` field:
+
+.. common-content-end
+
+.. driver-content-begin
+.. literalinclude:: /includes/fundamentals/code-snippets/IndexPage.java
+   :language: java
+   :dedent:
+   :start-after: begin single index
+   :end-before: end single index
+.. driver-content-end
+
+The following is an example of a query that would be covered by the index created above:
+
+.. driver-content-begin
+.. literalinclude:: /includes/fundamentals/code-snippets/IndexPage.java
+   :language: java
+   :dedent:
+   :start-after: begin covered single query
+   :end-before: end covered single query
+.. driver-content-end
+
+.. common-content-begin
+
+See the MongoDB server manual section on :manual:`single field indexes </core/index-single>` for more information.
+
+Compound Indexes
+++++++++++++++++
+
+:manual:`Compound </core/index-compound/>` indexes hold references to multiple fields within a collection's documents,
+improving query and sort performance.
+
+.. tip::
+
+   Read more about compound indexes, **index prefixes**, and sort order :manual:`here </core/index-compound/#prefixes>`.
+
+The following example creates a compound index on the ``type`` and ``rated`` fields:
+
+.. common-content-end
+
+.. driver-content-begin
+
+.. literalinclude:: /includes/fundamentals/code-snippets/IndexPage.java
+   :language: java
+   :dedent:
+   :start-after: begin compound index
+   :end-before: end compound index
+
+The following is an example of a query that would be covered by the index created above:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/IndexPage.java
+   :language: java
+   :dedent:
+   :start-after: begin covered compound query
+   :end-before: end covered compound query
+.. driver-content-end
+
+.. common-content-begin
+
+See the MongoDB server manual section on :manual:`Compound indexes </core/index-compound>` for more information.
+
+Multikey Indexes (Indexes on Array Fields)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Multikey indexes** are indexes that improve performance for queries that specify a field with an index that contains
+an array value. You can define a multikey index using the same syntax as a single field or compound index.
+
+The following example creates a compound, multikey index on the ``rated`, ``genres`` (an array of
+Strings), and ``title`` fields:
+
+.. common-content-end
+.. driver-content-begin
+.. literalinclude:: /includes/fundamentals/code-snippets/IndexPage.java
+   :language: java
+   :dedent:
+   :start-after: begin multikey index
+   :end-before: end multikey index
+
+The following is an example of a query that would be covered by the index created above:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/IndexPage.java
+   :language: java
+   :dedent:
+   :start-after: begin covered multikey query
+   :end-before: end covered multikey query
+.. driver-content-end
+
+.. common-content-begin
+
+Multikey indexes behave differently from non-multikey indexes in terms of query coverage, index bound computation, and
+sort behavior. For a full explanation of multikey indexes, including a discussion of their behavior and limitations,
+refer to the :manual:`Multikey Indexes page </core/index-multikey>` in the MongoDB manual.
+
+Text Indexes
+~~~~~~~~~~~~
+
+**Text indexes** support text search queries on string content. These indexes can include any field whose value is a
+string or an array of string elements. MongoDB supports text search for various languages. You can specify the default
+language as an option when creating the index.
+
+.. tip::
+
+   Text indexes differ from the more powerful :atlas:`Atlas full text search indexes </atlas-search/>` Atlas users
+   should use Atlas search.
+
+.. warning::
+
+   Collections are limited to one text index. Keep in mind that a text index can cover multiple fields.
+
+.. common-content-end
+
+.. driver-content-begin
+
+The following example creates a text index on the ``plot`` field:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/IndexPage.java
+   :language: java
+   :dedent:
+   :start-after: begin text index
+   :end-before: end text index
+
+The following is an example of a query that would use the index created above. Note that the ``sort`` is
+omitted because text indexes do not contain sort order.
+
+.. literalinclude:: /includes/fundamentals/code-snippets/IndexPage.java
+   :language: java
+   :dedent:
+   :start-after: begin text query
+   :end-before: end text query
+
+.. driver-content-end
+.. common-content-begin
+
+For a full explanation of text search with MongoDB, refer to :manual:`Text Indexes </core/index-text>` in the MongoDB
+manual.
+
+Geospatial Indexes
+~~~~~~~~~~~~~~~~~~
+
+.. _geo-indexes:
+
+MongoDB supports queries of geospatial coordinate data using **2dsphere indexes**. With a 2dsphere index, you can query
+the geospatial data for inclusion, intersection, and proximity. For more information on querying geospatial data, see
+:manual:`Geospatial Queries </geospatial-queries/>`.
+
+To create a 2dsphere index, you must specify a field that contains only **GeoJSON objects**. For more details on this
+type, see the MongoDB server manual page on :manual:`GeoJSON objects </reference/geojson>`.
+
+The ``location.geo` field in following sample document from the ``theaters`` collection in the ``sample_mflix```
+database is a GeoJSON Point object that describes the coordinates of the theater:
+
+.. code-block:: javascript
+
+   {
+      "_id" : ObjectId("59a47286cfa9a3a73e51e75c"),
+      "theaterId" : 104,
+      "location" : {
+         "address" : {
+            "street1" : "5000 W 147th St",
+            "city" : "Hawthorne",
+            "state" : "CA",
+            "zipcode" : "90250"
+         },
+         "geo" : {
+            "type" : "Point",
+            "coordinates" : [
+               -118.36559,
+               33.897167
+            ]
+         }
+      }
+   }
+
+The following example creates a ``2dsphere`` index on the ``location.geo`` field:
+
+.. warning::
+
+   Attemping to create a geospatial index on a field that is covered by a geospatial index will result in an error.
+
+.. common-content-end
+.. driver-content-begin
+
+.. literalinclude:: /includes/fundamentals/code-snippets/IndexPage.java
+   :language: java
+   :dedent:
+   :start-after: begin geospatial index
+   :end-before: end geospatial index
+
+The following is an example of a geospatial query using the "location.geo" index.
+
+.. literalinclude:: /includes/fundamentals/code-snippets/IndexPage.java
+   :language: java
+   :dedent:
+   :start-after: begin geospatial query
+   :end-before: end geospatial query
+
+.. driver-content-end
+.. common-content-begin
+
+MongoDB also supports ``2d`` indexes for calculating distances on a Euclidean plane and for working with the "legacy
+coordinate pairs" syntax used in MongoDB 2.2 and earlier. See the :manual:`Geospatial Queries page </geospatial-queries>`
+in the MongoDB server manual for more further information.
+
+Unique Indexes
+~~~~~~~~~~~~~~
+
+.. _unique-indexes:
+
+Unique indexes ensure that the indexed fields do not store duplicate values. By default, MongoDB creates a unique index
+on the ``_id`` field during the creation of a collection. To create a unique index, specify the field or combination of
+fields that you want to prevent duplication on and set the ``unique`` option to ``true``.
+
+The following example creates a unique, descending index on the ``theaterId`` field:
+
+.. common-content-end
+.. driver-content-begin
+
+.. literalinclude:: /includes/fundamentals/code-snippets/IndexPage.java
+   :language: java
+   :dedent:
+   :start-after: begin unique index
+   :end-before: end unique index
+
+.. warning::
+
+   Attempting to perform a write operation that stores a duplicate value that violates the unique index, the MongoDB
+   Java driver will raise a ``DuplicateKeyException``, and MongoDB will throw an error resembling the following:
+
+.. code-block:: none
+
+   E11000 duplicate key error index
+
+Refer to the :manual:`Unique Indexes page </core/index-unique>` in the MongoDB server manual for more information.
+.. driver-content-end