Skip to content

Commit 77fa232

Browse files
mcmorisimcmorisi
committed
DOCSP-41142: Work with Indexes + Single Field Indexes (#14)
(cherry picked from commit 12ef143)
1 parent 41acb2d commit 77fa232

File tree

6 files changed

+281
-9
lines changed

6 files changed

+281
-9
lines changed

‎snooty.toml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,8 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv",
88

99
toc_landing_pages = [
1010
"/read",
11-
"/indexes"
11+
"/indexes",
12+
"work-with-indexes",
1213
]
1314

1415
[constants]

‎source/includes/indexes/indexes.kt

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
import com.mongodb.ConnectionString
2+
import com.mongodb.MongoClientSettings
3+
import com.mongodb.client.model.Indexes
4+
import com.mongodb.client.model.Filters
5+
import com.mongodb.client.model.Sorts
6+
import com.mongodb.kotlin.client.MongoClient
7+
import org.bson.codecs.pojo.annotations.BsonId
8+
import org.bson.types.ObjectId
9+
10+
// start-movie-class
11+
data class Movie(
12+
@BsonId
13+
val id: ObjectId,
14+
val title: String? = "",
15+
val genre: String? = "",
16+
val cast: List<String>? = null,
17+
val plot: String? = "",
18+
)
19+
// end-movie-class
20+
21+
fun main() {
22+
val uri = "<connection string URI>"
23+
24+
val settings = MongoClientSettings.builder()
25+
.applyConnectionString(ConnectionString(uri))
26+
.retryWrites(true)
27+
.build()
28+
29+
val mongoClient = MongoClient.create(settings)
30+
val database = mongoClient.getDatabase("sample_mflix")
31+
val collection = database.getCollection<Movie>("movies")
32+
33+
// start-remove-index
34+
collection.dropIndex("_title_")
35+
// end-remove-index
36+
37+
// start-remove-all-indexes
38+
collection.dropIndexes()
39+
// end-remove-all-indexes
40+
41+
// start-index-single
42+
collection.createIndex(Indexes.ascending(Movie::title.name))
43+
// end-index-single
44+
45+
// start-index-single-query
46+
val filter = Filters.eq(Movie::title.name, "Batman")
47+
val sort = Sorts.ascending(Movie::title.name)
48+
val results = collection.find(filter).sort(sort)
49+
50+
results.forEach { result ->
51+
println(result)
52+
}
53+
// end-index-single-query
54+
}

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ fun main() {
2222
val collection = database.getCollection<Document>("<collection name>")
2323

2424
// start-single-field
25-
collection.createIndex(Indexes.ascending("<field name"))
25+
collection.createIndex(Indexes.ascending("<field name>"))
2626
// end-single-field
2727

2828
// start-compound

‎source/indexes.txt

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -18,12 +18,11 @@ Optimize Queries by Using Indexes
1818
:description: Learn how to use indexes by using the MongoDB Kotlin Sync driver.
1919
:keywords: query, optimization, efficiency, usage example, code example
2020

21-
.. TODO
22-
.. .. toctree::
23-
.. :titlesonly:
24-
.. :maxdepth: 1
21+
.. toctree::
22+
:titlesonly:
23+
:maxdepth: 1
2524

26-
.. /work-with-indexes
25+
/work-with-indexes
2726

2827
Overview
2928
--------
@@ -65,8 +64,7 @@ The following example creates an ascending index on the specified field:
6564
:copyable:
6665
:dedent:
6766

68-
.. TODO: To learn more about single field indexes, see the
69-
.. :ref:`kotlin-sync-single-field-index` guide.
67+
To learn more about single field indexes, see the :ref:`kotlin-sync-single-field-index` guide.
7068

7169
Compound Index
7270
--------------

‎source/indexes/single-field-index.txt

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
.. _kotlin-sync-single-field-index:
2+
3+
====================
4+
Single-Field Indexes
5+
====================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: index, query, optimization, efficiency
19+
20+
Overview
21+
--------
22+
23+
:manual:`Single-field indexes </core/index-single/>` are indexes with a reference to a
24+
single field within a collection's documents. They improve single field query and sort
25+
performance, and support :manual:`TTL Indexes </core/index-ttl>` that automatically remove
26+
documents from a collection after a certain amount of time or at a specific clock time.
27+
28+
When creating a single-field index, you must specify the following:
29+
30+
- The field on which to create the index
31+
- The sort order for the indexed values (ascending or descending)
32+
33+
.. note::
34+
35+
The ``_id_`` index is an example of a single-field index. This index is automatically
36+
created on the ``_id`` field when a new collection is created.
37+
38+
Sample Data
39+
~~~~~~~~~~~
40+
41+
The examples in this guide use the ``movies`` collection in the ``sample_mflix``
42+
database from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
43+
free MongoDB Atlas cluster and load the sample datasets, see the
44+
:atlas:`Get Started with Atlas </getting-started>` guide.
45+
46+
The following {+language+} data class models the documents in this collection:
47+
48+
.. literalinclude:: /includes/indexes/indexes.kt
49+
:start-after: start-movie-class
50+
:end-before: end-movie-class
51+
:language: kotlin
52+
:copyable:
53+
54+
Create Single-Field Index
55+
-------------------------
56+
57+
The following example creates an index in ascending order on the ``title`` field:
58+
59+
.. literalinclude:: /includes/indexes/indexes.kt
60+
:start-after: start-index-single
61+
:end-before: end-index-single
62+
:language: kotlin
63+
:copyable:
64+
:dedent:
65+
66+
The following is an example of a query that is covered by the index created in the preceding code example:
67+
68+
.. io-code-block::
69+
:copyable: true
70+
71+
.. input:: /includes/indexes/indexes.kt
72+
:start-after: start-index-single-query
73+
:end-before: end-index-single-query
74+
:language: kotlin
75+
:dedent:
76+
77+
.. output::
78+
:visible: false
79+
80+
Movie(id=573a1398f29313caabceb515, title=Batman, ...)
81+
82+
Additional Information
83+
----------------------
84+
85+
To learn more about single-field indexes, see :manual:`Single Field Indexes </core/index-single>`
86+
in the {+mdb-server+} manual.
87+
88+
API Documentation
89+
~~~~~~~~~~~~~~~~~
90+
91+
To learn more about any of the methods or types discussed in this
92+
guide, see the following API Documentation:
93+
94+
- `find() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/find.html>`__
95+
- `filter() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/filter.html>`__
96+
- `sort() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-find-iterable/sort.html>`__

‎source/work-with-indexes.txt

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
.. _kotlin-sync-work-with-indexes:
2+
3+
=================
4+
Work with Indexes
5+
=================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: query, optimization, efficiency
19+
20+
.. toctree::
21+
22+
/indexes/single-field-index.txt
23+
24+
Overview
25+
--------
26+
27+
In this guide, you can learn how to use **indexes** with the {+driver-short+}.
28+
Indexes can improve the efficiency of queries and add functionality to querying and
29+
storing documents.
30+
31+
Without indexes, MongoDB must scan every document in a collection to find the
32+
documents that match each query. These collection scans are slow and can negatively affect
33+
the performance of your application. However, if an appropriate index exists for a query,
34+
MongoDB can use the index to limit the documents it must inspect.
35+
36+
Operational Considerations
37+
~~~~~~~~~~~~~~~~~~~~~~~~~~
38+
39+
To improve query performance, build indexes on fields that appear often in
40+
your application's queries and operations that return sorted results. Each
41+
index that you add consumes disk space and memory when active, so we recommend
42+
that you track index memory and disk usage for capacity planning. In addition,
43+
when a write operation updates an indexed field, MongoDB updates the related
44+
index, which can negatively impact performance for write operations.
45+
46+
You can use :manual:`wildcard indexes </core/index-wildcard/>` in your MongoDB application
47+
to query against fields whose names are not known in advance or are arbitrary. Wildcard
48+
indexes are not designed to replace workload-based index planning.
49+
50+
For more information about designing your data model and choosing indexes appropriate for your application, see the
51+
:manual:`Data Modeling and Indexes </core/data-model-operations/#indexes>` guide
52+
in the {+mdb-server+} manual.
53+
54+
Sample Data
55+
~~~~~~~~~~~
56+
57+
The examples in this guide use the ``movies`` collection in the ``sample_mflix``
58+
database from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
59+
free MongoDB Atlas cluster and load the sample datasets, see the
60+
:atlas:`Get Started with Atlas </getting-started>` guide.
61+
62+
Create an Index
63+
---------------
64+
65+
MongoDB supports several different index types to help query your data.
66+
The following pages describe the most common index types and provide sample
67+
code for creating each index type.
68+
69+
- :ref:`kotlin-sync-single-field-index`
70+
71+
.. TODO: - :ref:`kotlin-sync-compound-index`
72+
.. TODO: - :ref:`kotlin-sync-atlas-search-index`
73+
74+
Remove an Index
75+
---------------
76+
77+
You can remove any unused index except the default unique index on the
78+
``_id`` field.
79+
80+
The following sections show how to remove a single index or how to remove all
81+
indexes in a collection.
82+
83+
Delete a Single Index
84+
~~~~~~~~~~~~~~~~~~~~~
85+
86+
Pass an index name to the ``dropIndex()`` method to remove an index from a collection.
87+
88+
The following example removes an index with the name ``"_title_"`` from the ``movies``
89+
collection:
90+
91+
.. literalinclude:: /includes/indexes/indexes.kt
92+
:language: kotlin
93+
:start-after: start-remove-index
94+
:end-before: end-remove-index
95+
:dedent:
96+
97+
.. note::
98+
99+
You cannot remove a single field from a compound text index. You must
100+
drop the entire index and create a new one to update the indexed
101+
fields.
102+
103+
Delete All Indexes
104+
~~~~~~~~~~~~~~~~~~
105+
106+
You can drop all indexes by calling the ``dropIndexes()`` method on your collection:
107+
108+
.. literalinclude:: /includes/indexes/indexes.kt
109+
:language: kotlin
110+
:start-after: start-remove-all-indexes
111+
:end-before: end-remove-all-indexes
112+
:dedent:
113+
114+
API Documentation
115+
~~~~~~~~~~~~~~~~~
116+
117+
To learn more about any of the methods or types discussed in this
118+
guide, see the following API documentation:
119+
120+
- `createIndex() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/create-index.html>`__
121+
- `createIndexes() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/create-indexes.html>`__
122+
- `dropIndex() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/drop-index.html>`__
123+
- `dropIndexes() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/drop-indexes.html>`__

0 commit comments

Comments
 (0)