DOCSP-41142: Work with Indexes + Single Field Indexes

snooty.toml

@@ -8,7 +8,8 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv",
 
 toc_landing_pages = [
     "/read",
-    "/indexes"
+    "/indexes",
+    "work-with-indexes",
 ]
 
 sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"

source/includes/indexes/indexes.kt

@@ -0,0 +1,54 @@
+import com.mongodb.ConnectionString
+import com.mongodb.MongoClientSettings
+import com.mongodb.client.model.Indexes
+import com.mongodb.client.model.Filters
+import com.mongodb.client.model.Sorts
+import com.mongodb.kotlin.client.MongoClient
+import org.bson.codecs.pojo.annotations.BsonId
+import org.bson.types.ObjectId
+
+// start-movie-class
+data class Movie(
+    @BsonId
+    val id: ObjectId,
+    val title: String? = "",
+    val genre: String? = "",
+    val cast: List<String>? = null,
+    val plot: String? = "",
+)
+// end-movie-class
+
+fun main() {
+    val uri = "<connection string URI>"
+
+    val settings = MongoClientSettings.builder()
+        .applyConnectionString(ConnectionString(uri))
+        .retryWrites(true)
+        .build()
+
+    val mongoClient = MongoClient.create(settings)
+    val database = mongoClient.getDatabase("sample_mflix")
+    val collection = database.getCollection<Movie>("movies")
+
+    // start-remove-index
+    collection.dropIndex("_title_")
+    // end-remove-index
+
+    // start-remove-all-indexes
+    collection.dropIndexes()
+    // end-remove-all-indexes
+
+    // start-index-single
+    collection.createIndex(Indexes.ascending(Movie::title.name))
+    // end-index-single
+
+    // start-index-single-query
+    val filter = Filters.eq(Movie::title.name, "Batman")
+    val sort = Sorts.ascending(Movie::title.name)
+    val results = collection.find(filter).sort(sort)
+
+    results.forEach { result ->
+        println(result)
+    }
+    // end-index-single-query
+}

source/includes/usage-examples/index-code-examples.kt

@@ -22,7 +22,7 @@ fun main() {
     val collection = database.getCollection<Document>("<collection name>")
 
     // start-single-field
-    collection.createIndex(Indexes.ascending("<field name"))
+    collection.createIndex(Indexes.ascending("<field name>"))
     // end-single-field
 
     // start-compound

source/indexes.txt

@@ -18,12 +18,11 @@ Optimize Queries by Using Indexes
    :description: Learn how to use indexes by using the MongoDB Kotlin Sync driver.
    :keywords: query, optimization, efficiency, usage example, code example
 
-.. TODO
-.. .. toctree::
-..    :titlesonly:
-..    :maxdepth: 1
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
 
-..    /work-with-indexes
+   /work-with-indexes
 
 Overview
 --------
@@ -65,8 +64,7 @@ The following example creates an ascending index on the specified field:
    :copyable:
    :dedent:
 
-.. TODO: To learn more about single field indexes, see the
-.. :ref:`kotlin-sync-single-field-index` guide.
+To learn more about single field indexes, see the :ref:`kotlin-sync-single-field-index` guide.
 
 Compound Index
 --------------

source/indexes/single-field-index.txt

@@ -0,0 +1,96 @@
+.. _kotlin-sync-single-field-index:
+
+====================
+Single-Field Indexes
+====================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: index, query, optimization, efficiency
+
+Overview
+--------
+
+: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.
+
+When creating a single-field index, you must specify the following:
+
+- The field on which to create the index
+- The sort order for the indexed values (ascending or descending)
+
+.. 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.
+
+Sample Data
+~~~~~~~~~~~
+
+The examples in this guide use the ``movies`` collection in the ``sample_mflix``
+database from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
+free MongoDB Atlas cluster and load the sample datasets, see the
+:atlas:`Get Started with Atlas </getting-started>` guide.
+
+The following {+language+} data class models the documents in this collection:
+
+.. literalinclude:: /includes/indexes/indexes.kt
+   :start-after: start-movie-class
+   :end-before: end-movie-class
+   :language: kotlin
+   :copyable:
+
+Create Single-Field Index
+-------------------------
+
+The following example creates an index in ascending order on the ``title`` field:
+
+.. literalinclude:: /includes/indexes/indexes.kt
+   :start-after: start-index-single
+   :end-before: end-index-single
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+The following is an example of a query that is covered by the index created in the preceding code example:
+
+.. io-code-block::
+   :copyable: true
+
+   .. input:: /includes/indexes/indexes.kt
+      :start-after: start-index-single-query
+      :end-before: end-index-single-query
+      :language: kotlin
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      Movie(id=573a1398f29313caabceb515, title=Batman, ...)
+
+Additional Information
+----------------------
+
+To learn more about single-field indexes, see :manual:`Single Field Indexes </core/index-single>`
+in the {+mdb-server+} manual.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about any of the methods or types discussed in this
+guide, see the following API Documentation:
+
+- `find() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/find.html>`__
+- `filter() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/filter.html>`__
+- `sort() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/sort.html>`__

source/work-with-indexes.txt

@@ -0,0 +1,123 @@
+.. _kotlin-sync-work-with-indexes:
+
+=================
+Work with Indexes
+=================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: query, optimization, efficiency
+
+.. toctree::
+
+   /indexes/single-field-index.txt
+
+Overview
+--------
+
+In this guide, you can learn how to use **indexes** with the {+driver-short+}.
+Indexes can improve the efficiency of queries and add functionality to querying and
+storing documents.
+
+Without indexes, MongoDB must scan every document in a collection to find the
+documents that match each query. These collection scans are slow and can negatively affect
+the performance of your application. However, if an appropriate index exists for a query,
+MongoDB can use the index to limit the documents it must inspect.
+
+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 we recommend
+that you track index memory and disk usage for capacity planning. In addition,
+when a write operation updates an indexed field, MongoDB updates the related
+index, which can negatively impact performance for write operations.
+
+You can use :manual:`wildcard indexes </core/index-wildcard/>` in your MongoDB application
+to query against fields whose names are not known in advance or are arbitrary. Wildcard
+indexes are not designed to replace workload-based index planning.
+
+For more information about designing your data model and choosing indexes appropriate for your application, see the
+:manual:`Data Modeling and Indexes </core/data-model-operations/#indexes>` guide
+in the {+mdb-server+} manual.
+
+Sample Data
+~~~~~~~~~~~
+
+The examples in this guide use the ``movies`` collection in the ``sample_mflix``
+database from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
+free MongoDB Atlas cluster and load the sample datasets, see the
+:atlas:`Get Started with Atlas </getting-started>` guide.
+
+Create an Index
+---------------
+
+MongoDB supports several different index types to help query your data.
+The following pages describe the most common index types and provide sample
+code for creating each index type.
+
+- :ref:`kotlin-sync-single-field-index`
+
+.. TODO: - :ref:`kotlin-sync-compound-index`
+.. TODO: - :ref:`kotlin-sync-atlas-search-index`
+
+Remove an Index
+---------------
+
+You can remove any unused index except the default unique index on the
+``_id`` field.
+
+The following sections show how to remove a single index or how to remove all
+indexes in a collection.
+
+Delete a Single Index
+~~~~~~~~~~~~~~~~~~~~~
+
+Pass an index name to the ``dropIndex()`` method to remove an index from a collection.
+
+The following example removes an index with the name ``"_title_"`` from the ``movies``
+collection:
+
+.. literalinclude:: /includes/indexes/indexes.kt
+   :language: kotlin
+   :start-after: start-remove-index
+   :end-before: end-remove-index
+   :dedent:
+
+.. note::
+
+   You cannot remove a single field from a compound text index. You must
+   drop the entire index and create a new one to update the indexed
+   fields.
+
+Delete All Indexes
+~~~~~~~~~~~~~~~~~~
+
+You can drop all indexes by calling the ``dropIndexes()`` method on your collection:
+
+.. literalinclude:: /includes/indexes/indexes.kt
+   :language: kotlin
+   :start-after: start-remove-all-indexes
+   :end-before: end-remove-all-indexes
+   :dedent:
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about any of the methods or types discussed in this
+guide, see the following API documentation:
+
+- `createIndex() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/create-index.html>`__
+- `createIndexes() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/create-indexes.html>`__
+- `dropIndex() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/drop-index.html>`__
+- `dropIndexes() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/drop-indexes.html>`__