diff --git a/snooty.toml b/snooty.toml index 77be8b46..7f974e88 100644 --- a/snooty.toml +++ b/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/" diff --git a/source/includes/indexes/indexes.kt b/source/includes/indexes/indexes.kt new file mode 100644 index 00000000..e1d776f8 --- /dev/null +++ b/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? = null, + val plot: String? = "", +) +// end-movie-class + +fun main() { + val 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("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 +} diff --git a/source/includes/usage-examples/index-code-examples.kt b/source/includes/usage-examples/index-code-examples.kt index b97f2c0e..43db624d 100644 --- a/source/includes/usage-examples/index-code-examples.kt +++ b/source/includes/usage-examples/index-code-examples.kt @@ -22,7 +22,7 @@ fun main() { val collection = database.getCollection("") // start-single-field - collection.createIndex(Indexes.ascending("")) // end-single-field // start-compound diff --git a/source/indexes.txt b/source/indexes.txt index 94e6674f..078da717 100644 --- a/source/indexes.txt +++ b/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 -------------- diff --git a/source/indexes/single-field-index.txt b/source/indexes/single-field-index.txt new file mode 100644 index 00000000..cbbe894d --- /dev/null +++ b/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 ` 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 ` 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 `. To learn how to create a +free MongoDB Atlas cluster and load the sample datasets, see the +:atlas:`Get Started with Atlas ` 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 ` +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>`__ \ No newline at end of file diff --git a/source/work-with-indexes.txt b/source/work-with-indexes.txt new file mode 100644 index 00000000..053b7704 --- /dev/null +++ b/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 ` 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 ` 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 `. To learn how to create a +free MongoDB Atlas cluster and load the sample datasets, see the +:atlas:`Get Started with Atlas ` 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>`__