Skip to content

Commit 282344b

Browse files
mayaraman19mayaraman19
authored
DOCSP-42762: Indexes (#74)
1 parent ca9a84d commit 282344b

File tree

4 files changed

+347
-1
lines changed

4 files changed

+347
-1
lines changed

‎source/data-modeling.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ Model Your Data
1919
Field Behaviors </data-modeling/field-behaviors>
2020
Inheritance </data-modeling/inheritance>
2121
Document Validation </data-modeling/validation>
22+
Optimize Queries With Indexes </data-modeling/indexes>
2223

2324
In this section, you can learn how to model data in {+odm+}.
2425

@@ -36,3 +37,6 @@ In this section, you can learn how to model data in {+odm+}.
3637

3738
- :ref:`mongoid-modeling-validation`: Learn how to create document
3839
validation rules for your model classes.
40+
41+
- :ref:`mongoid-optimize-queries-with-indexes`: Learn how to create and manage
42+
indexes for your model classes.

‎source/data-modeling/indexes.txt‎

Lines changed: 219 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
1+
.. _mongoid-optimize-queries-with-indexes:
2+
3+
=============================
4+
Optimize Queries With Indexes
5+
=============================
6+
7+
.. default-domain:: mongodb
8+
9+
.. facet::
10+
:name: genre
11+
:values: reference
12+
13+
.. meta::
14+
:keywords: code example, odm, optimization, efficiency, Atlas search
15+
16+
.. contents:: On this page
17+
:local:
18+
:backlinks: none
19+
:depth: 3
20+
:class: singlecol
21+
22+
Overview
23+
--------
24+
25+
In this guide, you can learn how to use **indexes** with {+odm+}. Indexes can
26+
improve the efficiency of queries by limiting the number of documents MongoDB
27+
needs to scan. If your application is repeatedly running queries
28+
on certain fields, you can create an index on those fields to improve query
29+
performance.
30+
31+
The following sections in this guide describe how to declare and create different
32+
types of indexes using {+odm+}. The examples use the ``Restaurant`` model, which
33+
maps to the ``restaurants`` collection in the ``sample_restaurants`` database.
34+
To learn how to connect to this database
35+
and collection using {+odm+}, see the :ref:`mongoid-quick-start-rails` or
36+
:ref:`mongoid-quick-start-sinatra` guides.
37+
38+
Declare and Create an Index
39+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
40+
41+
When using {+odm+}, you can declare your index using the ``index`` macro and
42+
then create it using the ``create_indexes`` command.
43+
44+
The following code example shows how to declare and create an ascending index
45+
named ``cuisine_index`` on the ``cuisine`` field in the ``Restaurant`` class:
46+
47+
.. literalinclude:: /includes/data-modeling/indexes.rb
48+
:language: ruby
49+
:emphasize-lines: 8, 11
50+
:start-after: start create index
51+
:end-before: end create index
52+
53+
The ``index`` macro defines the index you want to create and the ``create_indexes``
54+
command creates it in the ``restaurants`` collection.
55+
56+
When defining an index, the first hash object contains the field you want to
57+
index and its direction. ``1`` represents an ascending index, and ``-1`` represents a
58+
descending index. The second hash object contains index options. To learn more
59+
about index options, see the :ref:`mongoid-indexes-api-documentation` section.
60+
61+
Aliases and Declaring Indexes
62+
+++++++++++++++++++++++++++++
63+
64+
You can use aliased field names in index definitions. For example, the following
65+
code creates an index on the ``b`` field, which is an alias of the ``borough``
66+
field:
67+
68+
.. literalinclude:: /includes/data-modeling/indexes.rb
69+
:language: ruby
70+
:start-after: start create alias index
71+
:end-before: end create alias index
72+
73+
Create an Index on Embedded Document Fields
74+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
75+
76+
You can define an index on embedded document fields. The following code example
77+
shows how to declare an ascending index on the ``street`` field, which is embedded
78+
within the ``address`` field in the ``Restaurant`` model.
79+
80+
.. literalinclude:: /includes/data-modeling/indexes.rb
81+
:language: ruby
82+
:start-after: start create embedded index
83+
:end-before: end create embedded index
84+
85+
Create a Compound Index
86+
~~~~~~~~~~~~~~~~~~~~~~~
87+
88+
You can define a compound index on multiple fields. The following code example
89+
shows how to declare a compound index that is ascending on the ``borough``
90+
field and descending on the ``name`` field.
91+
92+
.. literalinclude:: /includes/data-modeling/indexes.rb
93+
:language: ruby
94+
:start-after: start create compound index
95+
:end-before: end create compound index
96+
97+
Create a Geospatial Index
98+
~~~~~~~~~~~~~~~~~~~~~~~~~
99+
100+
You can define a 2dsphere index on fields that contain GeoJSON objects or
101+
coordinate pairs.
102+
The following example defines a 2dsphere index on a field that contains GeoJSON
103+
objects:
104+
105+
.. literalinclude:: /includes/data-modeling/indexes.rb
106+
:language: ruby
107+
:start-after: start create 2dsphere index
108+
:end-before: end create 2dsphere index
109+
110+
For more information on 2dsphere indexes, see the :manual:`2dsphere </core/indexes/index-types/geospatial/2dsphere/>`
111+
guide in the MongoDB {+server-manual+}.
112+
113+
For more information on the GeoJSON type, see the :manual:`GeoJSON Objects </reference/geojson/>`
114+
guide in the MongoDB {+server-manual+}.
115+
116+
Create a Sparse Index
117+
~~~~~~~~~~~~~~~~~~~~~
118+
119+
You can define a sparse index on fields that are not present in all documents.
120+
The following code example defines a sparse index on the ``borough`` field:
121+
122+
.. literalinclude:: /includes/data-modeling/indexes.rb
123+
:language: ruby
124+
:start-after: start create sparse index
125+
:end-before: end create sparse index
126+
127+
For more information on sparse indexes, see the :manual:`Sparse Indexes </core/index-sparse/>`
128+
guide in the MongoDB {+server-manual+}.
129+
130+
Create Multiple Indexes
131+
~~~~~~~~~~~~~~~~~~~~~~~
132+
133+
You can define multiple indexes within your model and create them using a single
134+
``create_indexes`` call. The following example shows how to create multiple
135+
indexes at the same time:
136+
137+
.. literalinclude:: /includes/data-modeling/indexes.rb
138+
:language: ruby
139+
:start-after: start create multiple indexes
140+
:end-before: end create multiple indexes
141+
142+
Drop Indexes
143+
~~~~~~~~~~~~
144+
145+
You can drop all indexes in your collection. The following example drops all
146+
indexes in the ``Restaurant`` model:
147+
148+
.. literalinclude:: /includes/data-modeling/indexes.rb
149+
:language: ruby
150+
:start-after: start drop indexes
151+
:end-before: end drop indexes
152+
153+
.. note:: Default Index
154+
155+
MongoDB creates a default index on the ``_id`` field during the
156+
creation of a collection. This index prevents clients from inserting
157+
two documents with the same values for the ``_id`` field. You cannot
158+
drop this index.
159+
160+
Atlas Search Indexes
161+
~~~~~~~~~~~~~~~~~~~~
162+
163+
You can declare and manage Atlas Search indexes using {+odm+}.
164+
165+
To declare a search index, use the ``search_index`` macro within your model. To
166+
create the search indexes declared within a model, use the ``create_search_indexes``
167+
command. The following code example shows how to declare and create an Atlas
168+
Search index named ``my_search_index``.
169+
The index is on the ``name`` and ``cuisine`` fields and is dynamic.
170+
171+
.. literalinclude:: /includes/data-modeling/indexes.rb
172+
:language: ruby
173+
:start-after: start create atlas search index
174+
:end-before: end create atlas search index
175+
176+
To learn more about the syntax for creating an Atlas Search index, see
177+
the :atlas:`Create an Atlas Search Index </atlas-search/create-index/#std-label-ref-create-index>`
178+
guide in the MongoDB Atlas documentation.
179+
180+
Remove an Atlas Search Index
181+
++++++++++++++++++++++++++++
182+
183+
To remove an Atlas Search index, use the ``remove_search_indexes`` command. The
184+
following code example shows how to remove an Atlas Search index from the
185+
``restaurants`` collection:
186+
187+
.. literalinclude:: /includes/data-modeling/indexes.rb
188+
:language: ruby
189+
:start-after: start remove atlas search index
190+
:end-before: end remove atlas search index
191+
192+
List Atlas Search Indexes
193+
+++++++++++++++++++++++++
194+
195+
You can enumerate through all Atlas Search indexes in your collection
196+
by using the ``search_indexes`` command. The following example enumerates through
197+
all Atlas Search indexes in the ``restaurants`` collection and prints out their
198+
information:
199+
200+
.. literalinclude:: /includes/data-modeling/indexes.rb
201+
:language: ruby
202+
:start-after: start list atlas search index
203+
:end-before: end list atlas search index
204+
205+
.. _mongoid-indexes-api-documentation:
206+
207+
API Documentation
208+
-----------------
209+
210+
To learn more about using indexes in {+odm+}, see the
211+
`Mongoid::Indexable::ClassMethods <{+api-root+}/Indexable/ClassMethods.html>`__
212+
documentation.
213+
214+
To learn more about index options, see the `Mongoid::Indexable::Validators::Options
215+
<{+api-root+}/Indexable/Validators/Options.html>`__ documentation.
216+
217+
To learn more about using Atlas Search indexes in {+odm+}, see the
218+
`Mongoid::SearchIndexable::ClassMethods <{+api-root+}/SearchIndexable/ClassMethods.html>`__
219+
documentation.

‎source/includes/data-modeling/indexes.rb‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# start create index
2+
class Restaurant
3+
include Mongoid::Document
4+
5+
field :name, type: String
6+
field :cuisine, type: String
7+
field :borough, type: String
8+
9+
index({ cuisine: 1}, { name: "cuisine_index", unique: false })
10+
end
11+
12+
Restaurant.create_indexes
13+
# end create index
14+
15+
# start create alias index
16+
class Restaurant
17+
include Mongoid::Document
18+
19+
field :borough, as: :b
20+
21+
index({ b: 1}, { name: "borough_index" })
22+
end
23+
# end create alias index
24+
25+
# start create embedded index
26+
class Address
27+
include Mongoid::Document
28+
29+
field :street, type: String
30+
end
31+
32+
class Restaurant
33+
include Mongoid::Document
34+
35+
embeds_many :addresses
36+
index({"addresses.street": 1})
37+
end
38+
# end create embedded index
39+
40+
# start create compound index
41+
class Restaurant
42+
include Mongoid::Document
43+
44+
field :name, type: String
45+
field :borough, type: String
46+
47+
index({borough: 1, name: -1}, { name: "compound_index"})
48+
end
49+
# end create compound index
50+
51+
# start create 2dsphere index
52+
class Restaurant
53+
include Mongoid::Document
54+
55+
field :location, type: Array
56+
57+
index({location: "2dsphere"}, { name: "location_index"})
58+
end
59+
# end create 2dsphere index
60+
61+
# start create sparse index
62+
class Restaurant
63+
include Mongoid::Document
64+
65+
field :name, type: String
66+
field :cuisine, type: String
67+
field :borough, type: String
68+
69+
index({ borough: 1}, { sparse: true })
70+
end
71+
# end create sparse index
72+
73+
# start create multiple indexes
74+
class Restaurant
75+
include Mongoid::Document
76+
77+
field :name, type: String
78+
field :cuisine, type: String
79+
field :borough, type: String
80+
81+
index({ name: 1})
82+
index({ cuisine: -1})
83+
end
84+
85+
Restaurant.create_indexes
86+
# end create multiple indexes
87+
88+
# start drop indexes
89+
Restaurant.remove_indexes
90+
# end drop indexes
91+
92+
# start create atlas search index
93+
class Restaurant
94+
include Mongoid::Document
95+
96+
field :name, type: String
97+
field :cuisine, type: String
98+
field :borough, type: String
99+
100+
search_index :my_search_index,
101+
mappings: {
102+
fields: {
103+
name: {
104+
type: "string"
105+
},
106+
cuisine: {
107+
type: "string"
108+
}
109+
},
110+
dynamic: true
111+
}
112+
end
113+
114+
Restaurant.create_search_indexes
115+
# end create atlas search index
116+
117+
# start remove atlas search index
118+
Restaurant.remove_search_indexes
119+
# end remove atlas search index
120+
121+
#start list atlas search index
122+
Restaurant.search_indexes.each { |index| puts index }
123+
# end list atlas search index

‎source/reference/indexes.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -276,4 +276,4 @@ explicitly requiring ``mongoid``:
276276
# Rakefile
277277

278278
require 'bundler/setup'
279-
load 'mongoid/tasks/database.rake'
279+
load 'mongoid/tasks/database.rake'

0 commit comments

Comments
 (0)