Skip to content

Commit db7bf96

Browse files
lindseymoorelindseymoore
authored
DOCSP-45202 Index Overview (#112)
* DOCSP-45202 Index Overview * edits * fix ref * atlas search updates * small fix * add api section, edit atlas search examples * edits * tech review
1 parent 1a70647 commit db7bf96

File tree

4 files changed

+380
-3
lines changed

4 files changed

+380
-3
lines changed

‎source/includes/indexes/index-code-examples.rb‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
require 'mongo'
2+
3+
# Replace the placeholders with your credentials
4+
uri = "<connection string>"
5+
6+
# Sets the server_api field of the options object to Stable API version 1
7+
options = { server_api: { version: '1' }}
8+
9+
# Creates a new client and connects to the server
10+
client = Mongo::Client.new(uri, options)
11+
12+
database = client.use('<database name>')
13+
collection = database[:<collection name>]
14+
15+
# Single Field
16+
# start-index-single
17+
collection.indexes.create_one({ <field name>: 1 })
18+
# end-index-single
19+
20+
# Compound
21+
# start-index-compound
22+
collection.indexes.create_one({ <field name 1>: -1, <field name 2>: 1 })
23+
# end-index-compound
24+
25+
# Multikey
26+
# start-index-multikey
27+
collection.indexes.create_one({ <field name>: 1 })
28+
# end-index-multikey
29+
30+
# Geospatial
31+
# start-index-geospatial
32+
collection.indexes.create_one({ <GeoJSON field name>: '2dsphere' })
33+
# end-index-geospatial
34+
35+
# Atlas Search
36+
37+
# Create Search Index
38+
# start-create-search-index
39+
index_definition = {
40+
mappings: {
41+
dynamic: false,
42+
fields: {
43+
<field name>: { type: '<field type>' }
44+
}
45+
}
46+
}
47+
collection.search_indexes.create_one(index_definition, name: '<index name>')
48+
# end-create-search-index
49+
50+
# List Search Indexes
51+
# start-list-search-indexes
52+
puts collection.search_indexes.collect(&:to_json)
53+
# end-list-search-indexes
54+
55+
# Update Search Indexes
56+
#start-update-search-indexes
57+
updated_definition = {
58+
mappings: {
59+
dynamic: false,
60+
fields: { <updated field name>: { type: '<updated field type>' } }
61+
}
62+
}
63+
64+
collection.search_indexes.update_one(updated_definition, name: '<index name>')
65+
#end-update-search-indexes
66+
67+
# Delete Search Index
68+
# start-drop-search-index
69+
collection.search_indexes.drop_one(name: '<index name>')
70+
# end-drop-search-index
71+
72+
# Text Index
73+
# start-text
74+
collection.indexes.create_one({ <field name>: 'text' })
75+
# end-text
76+
77+
# Create Many
78+
# start-index-create-many
79+
collection.indexes.create_many([
80+
{ key: { <field name 1>: 1 } },
81+
{ key: { <field name 2>: -1 } },
82+
])
83+
# end-index-create-many
84+
85+
# Delete an Index
86+
# start-drop-single-index
87+
collection.indexes.drop_one( '<index name>' )
88+
# end-drop-single-index
89+
90+
# Drops all indexes in the collection.
91+
# start-drop-all-index
92+
collection.indexes.drop_all
93+
# end-drop-all-index
94+
95+
# List an Index
96+
# start-list-indexes
97+
puts collection.indexes.collect(&:to_json)
98+
# end-list-indexes
99+
100+
client.close

‎source/includes/indexes/index-starter-code.rb‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
require 'mongo'
2+
3+
# Replace the placeholders with your credentials
4+
uri = "<connection string>"
5+
6+
# Sets the server_api field of the options object to Stable API version 1
7+
options = { server_api: { version: "1" }}
8+
9+
# Creates a new client and connect to the server
10+
client = Mongo::Client.new(uri, options)
11+
12+
database = client.use('<database name>')
13+
collection = database[:<collection name>]
14+
15+
# Start example code here
16+
17+
# End example code here
18+
19+
client.close

‎source/indexes.txt‎

Lines changed: 260 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Optimize Queries by Using Indexes
1515
:values: reference
1616

1717
.. meta::
18-
:description: Learn how to use indexes by using the MongoDB Scala Driver.
18+
:description: Learn how to use indexes by using the MongoDB Ruby Driver.
1919
:keywords: query, optimization, efficiency, usage example, code example
2020

2121
.. toctree::
@@ -33,4 +33,262 @@ Overview
3333
On this page, you can see copyable code examples that show how to manage
3434
different types of indexes by using the {+driver-long+}.
3535

36-
.. TODO
36+
To use an example from this page, copy the code example into the sample
37+
application or your own application. Be sure to replace all placeholders in the
38+
code examples, such as ``<connection string>``, with the relevant values for
39+
your MongoDB deployment.
40+
41+
Sample Application
42+
~~~~~~~~~~~~~~~~~~
43+
44+
You can use the following sample application to test the code on this page. To
45+
use the sample application, perform the following steps:
46+
47+
1. Ensure you have the {+driver-short+} installed in your project. See the
48+
:ref:`ruby-quick-start-download-and-install` guide to learn more.
49+
50+
#. Copy the following code and paste it into a new ``.rb`` file.
51+
52+
#. Copy a code example from this page and paste it on the specified lines in the
53+
file.
54+
55+
.. literalinclude:: /includes/indexes/index-starter-code.rb
56+
:language: ruby
57+
:emphasize-lines: 15-17
58+
59+
Single Field Index
60+
------------------
61+
62+
The following example creates an ascending index on the specified field:
63+
64+
.. literalinclude:: /includes/indexes/index-code-examples.rb
65+
:language: ruby
66+
:start-after: start-index-single
67+
:end-before: end-index-single
68+
69+
To learn more about single field indexes, see the :ref:`ruby-single-field-index`
70+
guide.
71+
72+
Compound Index
73+
--------------
74+
75+
The following example creates a compound index on the two specified fields.
76+
77+
.. literalinclude:: /includes/indexes/index-code-examples.rb
78+
:language: ruby
79+
:start-after: start-index-compound
80+
:end-before: end-index-compound
81+
82+
To learn more about compound indexes, see the :ref:`ruby-compound-index` guide.
83+
84+
Multikey Index
85+
--------------
86+
87+
The following example creates a multikey index on the specified array-valued field:
88+
89+
.. literalinclude:: /includes/indexes/index-code-examples.rb
90+
:language: ruby
91+
:start-after: start-index-multikey
92+
:end-before: end-index-multikey
93+
94+
To learn more about multikey indexes, see the :ref:`ruby-multikey-index` guide.
95+
96+
Geospatial Index
97+
----------------
98+
99+
The following example creates a 2dsphere index on the specified field that
100+
contains GeoJSON objects:
101+
102+
.. literalinclude:: /includes/indexes/index-code-examples.rb
103+
:language: ruby
104+
:start-after: start-index-geospatial
105+
:end-before: end-index-geospatial
106+
107+
For more information on 2dsphere indexes, see the
108+
:manual:`2dsphere Indexes </core/indexes/index-types/geospatial/2dsphere/>`
109+
guide in the {+mdb-server+} manual.
110+
111+
For more information about the GeoJSON type, see the
112+
:manual:`GeoJSON Objects </reference/geojson/>` guide in
113+
the {+mdb-server+} manual.
114+
115+
Atlas Search Index Management
116+
-----------------------------
117+
118+
The following sections contain code examples that describe how to manage
119+
Atlas Search indexes.
120+
121+
To learn more about search indexes, see the :ref:`ruby-atlas-search-index` guide.
122+
123+
Create Search Index
124+
~~~~~~~~~~~~~~~~~~~
125+
126+
The following example creates an Atlas Search index on the specified field:
127+
128+
.. literalinclude:: /includes/indexes/index-code-examples.rb
129+
:language: ruby
130+
:start-after: start-create-search-index
131+
:end-before: end-create-search-index
132+
:dedent:
133+
134+
List Search Indexes
135+
~~~~~~~~~~~~~~~~~~~
136+
137+
The following example prints a list of Atlas Search indexes in the specified
138+
collection:
139+
140+
.. literalinclude:: /includes/indexes/index-code-examples.rb
141+
:language: ruby
142+
:start-after: start-list-search-indexes
143+
:end-before: end-list-search-indexes
144+
:dedent:
145+
146+
Update Search Indexes
147+
~~~~~~~~~~~~~~~~~~~~~
148+
149+
The following example updates an existing Atlas Search index with the specified
150+
new index definition:
151+
152+
.. literalinclude:: /includes/indexes/index-code-examples.rb
153+
:language: ruby
154+
:start-after: start-update-search-indexes
155+
:end-before: end-update-search-indexes
156+
:dedent:
157+
158+
Delete Search Indexes
159+
~~~~~~~~~~~~~~~~~~~~~
160+
161+
The following example deletes an Atlas Search index with the specified name:
162+
163+
.. literalinclude:: /includes/indexes/index-code-examples.rb
164+
:language: ruby
165+
:start-after: start-drop-search-index
166+
:end-before: end-drop-search-index
167+
:dedent:
168+
169+
Text Index
170+
----------
171+
172+
The following example creates a text index on the specified string field:
173+
174+
.. literalinclude:: /includes/indexes/index-code-examples.rb
175+
:start-after: start-text
176+
:end-before: end-text
177+
:language: ruby
178+
:dedent:
179+
180+
.. TODO: To learn more about text indexes, see the :ref:`ruby-text-index`
181+
.. guide.
182+
183+
Create Many Indexes
184+
-------------------
185+
186+
The following example creates multiple indexes on the given array of index specifications:
187+
188+
.. literalinclude:: /includes/indexes/index-code-examples.rb
189+
:start-after: start-index-create-many
190+
:end-before: end-index-create-many
191+
:language: ruby
192+
:dedent:
193+
194+
Drop Index
195+
----------
196+
197+
The following example deletes an index with the specified name:
198+
199+
.. literalinclude:: /includes/indexes/index-code-examples.rb
200+
:language: ruby
201+
:start-after: start-drop-single-index
202+
:end-before: end-drop-single-index
203+
204+
The following example shows how to delete all indexes in a collection:
205+
206+
.. literalinclude:: /includes/indexes/index-code-examples.rb
207+
:language: ruby
208+
:start-after: start-drop-all-index
209+
:end-before: end-drop-all-index
210+
211+
List Indexes
212+
------------
213+
214+
The following example prints a list of all indexes in the specified
215+
collection:
216+
217+
.. literalinclude:: /includes/indexes/index-code-examples.rb
218+
:language: ruby
219+
:start-after: start-list-indexes
220+
:end-before: end-list-indexes
221+
:dedent:
222+
223+
Index Options
224+
-------------
225+
226+
The following is a full list of the available options you can add
227+
when creating indexes. These options mirror the options supported by the
228+
``createIndex`` command. For more information, see the :manual:`createIndex command
229+
</reference/method/db.collection.createIndex/>` in the {+mdb-server+} manual.
230+
231+
.. list-table::
232+
:header-rows: 1
233+
:widths: 40 80
234+
235+
* - Option
236+
- Description
237+
* - ``:background``
238+
- Either ``true`` or ``false``. Tells the index to be created in the background.
239+
* - ``:expire_after``
240+
- Number of seconds to expire documents in the collection after.
241+
* - ``:name``
242+
- The name of the index.
243+
* - ``:sparse``
244+
- Whether the index should be sparse or not, either ``true`` or ``false``.
245+
* - ``:storage_engine``
246+
- The name of the storage engine for this particular index.
247+
* - ``:version``
248+
- The index format version to use.
249+
* - ``:default_language``
250+
- The default language of text indexes.
251+
* - ``:language_override``
252+
- The field name to use when overriding the default language.
253+
* - ``:text_version``
254+
- The version format for text index storage.
255+
* - ``:weights``
256+
- A document specifying fields and weights in text search.
257+
* - ``:sphere_version``
258+
- The 2d sphere index version.
259+
* - ``:bits``
260+
- Sets the maximum boundary for latitude and longitude in the 2d index.
261+
* - ``:max``
262+
- Maximum boundary for latitude and longitude in the 2d index.
263+
* - ``:min``
264+
- Minimum boundary for latitude and longitude in the 2d index.
265+
* - ``:bucket_size``
266+
- The number of units within which to group the location values in a geo haystack index.
267+
* - ``:partial_filter_expression``
268+
- A filter for a partial index.
269+
* - ``:hidden``
270+
- A Boolean specifying whether the index should be hidden; a hidden index
271+
is one that exists on the collection but will not be used by the query planner.
272+
* - ``:commit-quorum``
273+
- Specify how many data-bearing members of a replica set, including the primary, must
274+
complete the index builds successfully before the primary marks the indexes as ready.
275+
Potential values are:
276+
277+
- integer from 0 to the number of members of the replica set
278+
- ``“majority”`` indicating that a majority of data bearing nodes must vote
279+
- ``“votingMembers”`` which means that all voting data bearing nodes must vote
280+
281+
For more information, see :manual:`commitQuorom
282+
</reference/method/db.collection.createIndex/#std-label-createIndex-method-commitQuorum>`
283+
in the {+mdb-server+} manual.
284+
285+
API Documentation
286+
-----------------
287+
288+
To learn more about the methods or objects used in this guide, see the following
289+
API documentation:
290+
291+
- `indexes <{+api-root+}/Mongo/Collection.html#indexes-instance_method>`__
292+
- `create_one <{+api-root+}/Mongo/Index/View.html#create_one-instance_method>`__
293+
- `drop_one <{+api-root+}/Mongo/Index/View.html#drop_one-instance_method>`__
294+
- `drop_all <{+api-root+}/Mongo/Index/View.html#drop_all-instance_method>`__

0 commit comments

Comments
 (0)