Skip to content

Commit 77b5ab5

Browse files
rustagirrustagir
authored
Merge pull request #9 from rustagir/DOCSP-37797-indexes
DOCSP-37797: indexes tutorial
2 parents 8432025 + f65b22c commit 77b5ab5

File tree

3 files changed

+264
-0
lines changed

3 files changed

+264
-0
lines changed

‎.github/pull_request_template.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22

33
[PR Reviewing Guidelines](https://github.com/mongodb/docs-java-rs/blob/master/REVIEWING.md)
44

5+
**Note: this is part of a consolidation effort, so your review should
6+
not address style guide issues or phrasing unless there are errors**
7+
58
JIRA - <https://jira.mongodb.org/browse/DOCSP-NNNNN>
69
Staging - <https://docs-mongodbcom-staging.corp.mongodb.com/drivers/docsworker-xlarge/NNNNN/>
710

‎source/tutorials.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,5 @@ Tutorials
88

99
/tutorials/connect/
1010
/tutorials/db-coll/
11+
/tutorials/indexes/
1112

‎source/tutorials/indexes.txt

Lines changed: 260 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,260 @@
1+
.. _javars-indexes:
2+
3+
==============
4+
Create Indexes
5+
==============
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
Indexes support the efficient execution of queries in MongoDB. To
14+
create an index on a field or fields, pass an index specification
15+
document to the ``MongoCollection.createIndex()`` method.
16+
17+
The {+driver-short+} provides the ``Indexes`` class that includes
18+
static factory methods to create index specification documents for the
19+
various MongoDB index key types. To learn more about index types, see
20+
:manual:`Indexes </indexes/>` in the Server manual.
21+
22+
.. note::
23+
24+
MongoDB only creates an index if an index of the same specification
25+
does not already exist.
26+
27+
Prerequisites
28+
-------------
29+
30+
You must include the following import statements in your program to run the
31+
code examples in this guide:
32+
33+
.. code-block:: java
34+
35+
import com.mongodb.reactivestreams.client.MongoClient;
36+
import com.mongodb.reactivestreams.client.MongoClients;
37+
import com.mongodb.reactivestreams.client.MongoDatabase;
38+
import com.mongodb.reactivestreams.client.MongoCollection;
39+
import org.bson.Document;
40+
41+
import com.mongodb.client.model.Indexes;
42+
import com.mongodb.client.model.IndexOptions;
43+
import com.mongodb.client.model.Filters;
44+
45+
.. important::
46+
47+
This guide uses the ``Subscriber`` implementations, which are
48+
described in the :ref:`Quick Start Primer <javars-primer>`.
49+
50+
Connect to a MongoDB Deployment
51+
-------------------------------
52+
53+
First, connect to a MongoDB deployment and declare and define
54+
``MongoDatabase`` and ``MongoCollection`` instances.
55+
56+
The following code connects to a standalone
57+
MongoDB deployment running on ``localhost`` on port ``27017``. Then, it
58+
defines the ``database`` variable to refer to the ``test`` database and
59+
the ``collection`` variable to refer to the ``restaurants`` collection:
60+
61+
.. code-block:: java
62+
63+
MongoClient mongoClient = MongoClients.create();
64+
MongoDatabase database = mongoClient.getDatabase("test");
65+
MongoCollection<Document> collection = database.getCollection("restaurants");
66+
67+
To learn more about connecting to MongoDB deployments,
68+
see the :ref:`javars-connect` tutorial.
69+
70+
Ascending Index
71+
---------------
72+
73+
To create a specification for an ascending index, use the
74+
``Indexes.ascending()`` static helper method.
75+
76+
Single Ascending Index
77+
~~~~~~~~~~~~~~~~~~~~~~
78+
79+
The following example creates an ascending index on the ``name`` field:
80+
81+
.. code-block:: java
82+
83+
collection.createIndex(Indexes.ascending("name"))
84+
.subscribe(new PrintToStringSubscriber<String>());
85+
86+
Compound Ascending Index
87+
~~~~~~~~~~~~~~~~~~~~~~~~
88+
89+
The following example creates an ascending compound index on the
90+
``stars`` field and the ``name`` field:
91+
92+
.. code-block:: java
93+
94+
collection.createIndex(Indexes.ascending("stars", "name"))
95+
.subscribe(new PrintToStringSubscriber<String>());
96+
97+
To view an alternative way to create a compound index, see the :ref:`Compound
98+
Indexes <javars-compound-indexes>` section.
99+
100+
Descending Index
101+
----------------
102+
103+
To create a specification of a descending index, use the
104+
``Indexes.descending()`` static helper method.
105+
106+
Single Descending Key Index
107+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
108+
109+
The following example creates a descending index on the ``stars`` field:
110+
111+
.. code-block:: java
112+
113+
collection.createIndex(Indexes.descending("stars"))
114+
.subscribe(new PrintToStringSubscriber<String>());
115+
116+
Compound Descending Key Index
117+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
118+
119+
The following example creates a descending compound index on the
120+
``stars`` field and the ``name`` field:
121+
122+
.. code-block:: java
123+
124+
collection.createIndex(Indexes.descending("stars", "name"))
125+
.subscribe(new PrintToStringSubscriber<String>());
126+
127+
To view an alternative way to create a compound index, see the :ref:`Compound
128+
Indexes <javars-compound-indexes>` section.
129+
130+
.. _javars-compound-indexes:
131+
132+
Compound Indexes
133+
----------------
134+
135+
To create a specification for a compound index, use the
136+
``Indexes.compoundIndex()`` static helper method.
137+
138+
.. note::
139+
140+
To create a specification for a compound index where all the keys are
141+
ascending, you can use the ``ascending()`` method. To create a
142+
specification for a compound index where all the keys are descending,
143+
you can use the ``descending()`` method.
144+
145+
The following example creates a compound index on the ``stars`` field
146+
in descending order and the ``name`` field in ascending order:
147+
148+
.. code-block:: java
149+
150+
collection.createIndex(
151+
Indexes.compoundIndex(Indexes.descending("stars"),
152+
Indexes.ascending("name"))
153+
).subscribe(new PrintToStringSubscriber<String>());
154+
155+
Text Indexes
156+
------------
157+
158+
MongoDB provides text indexes to support text search of string
159+
content. Text indexes can include any field whose value is a string or
160+
an array of string elements. To create a specification for a text
161+
index, use the ``Indexes.text()`` static helper method.
162+
163+
The following example creates a text index on the ``name`` field:
164+
165+
.. code-block:: java
166+
167+
collection.createIndex(Indexes.text("name"))
168+
.subscribe(new PrintToStringSubscriber<String>());
169+
170+
Hashed Index
171+
------------
172+
173+
To create a specification for a hashed index index, use the
174+
``Indexes.hashed()`` static helper method.
175+
176+
The following example creates a hashed index on the ``_id`` field:
177+
178+
.. code-block:: java
179+
180+
collection.createIndex(Indexes.hashed("_id"))
181+
.subscribe(new PrintToStringSubscriber<String>());
182+
183+
Geospatial Indexes
184+
------------------
185+
186+
To support geospatial queries, MongoDB supports various geospatial
187+
indexes.
188+
189+
2dsphere
190+
~~~~~~~~
191+
192+
To create a specification for a ``2dsphere`` index, use the
193+
``Indexes.geo2dsphere()`` static helper method.
194+
195+
The following example creates a ``2dsphere`` index on the
196+
``contact.location`` field:
197+
198+
.. code-block:: java
199+
200+
collection.createIndex(Indexes.geo2dsphere("contact.location"))
201+
.subscribe(new PrintToStringSubscriber<String>());
202+
203+
IndexOptions
204+
------------
205+
206+
In addition to the index specification document, the
207+
``createIndex()`` method can take an index options document, that
208+
directs the driver to create unique indexes or partial indexes.
209+
210+
The driver provides the ``IndexOptions`` class to specify various
211+
index options.
212+
213+
Add the following import statement to your code to create an
214+
``IndexOptions`` instance.
215+
216+
.. code-block:: java
217+
218+
import com.mongodb.client.model.IndexOptions;
219+
220+
Unique Index
221+
~~~~~~~~~~~~
222+
223+
The following code specifies the ``unique(true)`` option to create a
224+
unique index on the ``name`` and ``stars`` fields:
225+
226+
.. code-block:: java
227+
228+
IndexOptions indexOptions = new IndexOptions().unique(true);
229+
collection.createIndex(Indexes.ascending("name", "stars"), indexOptions)
230+
.subscribe(new PrintToStringSubscriber<String>());
231+
232+
Partial Index
233+
~~~~~~~~~~~~~
234+
235+
To create a partial index, include the ``partialFilterExpression`` index
236+
option.
237+
238+
The following example creates a partial index on documents in which the
239+
value of the ``status`` field is ``"A"``.
240+
241+
.. code-block:: java
242+
243+
IndexOptions partialFilterIndexOptions = new IndexOptions()
244+
.partialFilterExpression(Filters.exists("contact.email"));
245+
collection.createIndex(
246+
Indexes.descending("name", "stars"), partialFilterIndexOptions)
247+
.subscribe(new PrintToStringSubscriber<String>());
248+
249+
Get a List of Indexes on a Collection
250+
-------------------------------------
251+
252+
Use the ``listIndexes()`` method to get a list of indexes. The following code
253+
lists the indexes on the collection:
254+
255+
.. code-block:: java
256+
257+
collection.listIndexes().subscribe(new PrintDocumentSubscriber());
258+
259+
To learn about other index options, see :manual:`Index Properties
260+
</core/indexes/index-properties/>` in the Server manual.

0 commit comments

Comments
 (0)