Skip to content

Commit da9e2be

Browse files
author
Sam Kleinman
committed
merge: DOCS-671
2 parents 4853df9 + 9842c6d commit da9e2be

File tree

3 files changed

+266
-0
lines changed

3 files changed

+266
-0
lines changed

‎source/faq/indexes.txt

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,3 +116,12 @@ The :operator:`$ne` and :operator:`$nin` operators are not selective.
116116
See :ref:`index-selectivity`. If you need to use these,
117117
it is often best to make sure that an additional, more selective
118118
criterion is part of the query.
119+
120+
.. _faq-index-min-max:
121+
122+
Can I use index keys to constrain query matches?
123+
------------------------------------------------
124+
125+
You can use the :method:`min() <cursor.min()>` and the :method:`max()
126+
<cursor.max()>` methods to constrain the results of the cursor returned
127+
from :method:`find() <db.collection.find()>` by using the index keys.

‎source/reference/method/cursor.max.txt

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
============
2+
cursor.max()
3+
============
4+
5+
.. default-domain:: mongodb
6+
7+
.. method:: cursor.max()
8+
9+
The :method:`max() <cursor.max()>` method specifies the *exclusive*
10+
upper bound for a specific index in order to constrain the results
11+
of :method:`find() <db.collection.find()>`. :method:`max()
12+
<cursor.max()>` provides a way to specify an upper bound on compound
13+
key indexes.
14+
15+
:method:`max() <cursor.max()>` takes the following parameter:
16+
17+
:param document indexbounds:
18+
19+
Specifies the exclusive upper bound for the index keys. The
20+
``indexbounds`` parameter has the following prototype form:
21+
22+
.. code-block:: javascript
23+
24+
{ field1: <max value>, field2: <max value2> ... fieldN:<max valueN>}
25+
26+
The fields correspond to *all* the keys of a particular index
27+
*in order*. You can explicitly specify the particular index
28+
with the :method:`hint() <cursor.hint()>` method. Otherwise,
29+
:program:`mongod` selects the index using the fields in the
30+
``indexbounds``; however, if multiple indexes exist on same
31+
fields with different sort orders, the selection of the index
32+
may be ambiguous.
33+
34+
Consider the following examples of :method:`max() <cursor.max()>`:
35+
36+
The examples assume a collection ``products`` with the following documents:
37+
38+
.. code-block:: javascript
39+
40+
{ "_id" : 6, "item" : "apple", "type" : "cortland", "price" : 1.29 }
41+
{ "_id" : 2, "item" : "apple", "type" : "fuji", "price" : 1.99 }
42+
{ "_id" : 1, "item" : "apple", "type" : "honey crisp", "price" : 1.99 }
43+
{ "_id" : 3, "item" : "apple", "type" : "jonagold", "price" : 1.29 }
44+
{ "_id" : 4, "item" : "apple", "type" : "jonathan", "price" : 1.29 }
45+
{ "_id" : 5, "item" : "apple", "type" : "mcintosh", "price" : 1.29 }
46+
{ "_id" : 7, "item" : "orange", "type" : "cara cara", "price" : 2.99 }
47+
{ "_id" : 10, "item" : "orange", "type" : "navel", "price" : 1.39 }
48+
{ "_id" : 9, "item" : "orange", "type" : "satsuma", "price" : 1.99 }
49+
{ "_id" : 8, "item" : "orange", "type" : "valencia", "price" : 0.99 }
50+
51+
The collection has the following four indexes:
52+
53+
.. code-block:: javascript
54+
55+
{ "_id" : 1 }
56+
{ "item" : 1, "type" : 1 }
57+
{ "item" : 1, "type" : -1 }
58+
{ "price" : 1 }
59+
60+
- Using the ordering of ``{ item: 1, type: 1 }`` index,
61+
:method:`max() <cursor.max()>` limits the query to the documents
62+
that are below the bound of ``item`` equal to ``apple`` and
63+
``type`` equal to ``jonagold``:
64+
65+
.. code-block:: javascript
66+
67+
db.products.find().max( { item: 'apple', type: 'jonagold' } ).hint( { item: 1, type: 1 } )
68+
69+
The query returns the following documents:
70+
71+
.. code-block:: javascript
72+
73+
{ "_id" : 6, "item" : "apple", "type" : "cortland", "price" : 1.29 }
74+
{ "_id" : 2, "item" : "apple", "type" : "fuji", "price" : 1.99 }
75+
{ "_id" : 1, "item" : "apple", "type" : "honey crisp", "price" : 1.99 }
76+
77+
If the query did not explicitly specify the index with the
78+
:method:`hint() <cursor.hint()>` method, it is ambiguous as to
79+
whether :program:`mongod` would select the ``{ item: 1, type: 1
80+
}`` index ordering or the ``{ item: 1, type: -1 }`` index ordering.
81+
82+
- Using the ordering of the index ``{ price: 1 }``, :method:`max()
83+
<cursor.max()>` limits the query to the documents that are below
84+
the index key bound of ``price`` equal to ``1.99`` and
85+
:method:`min() <cursor.min()>` limits the query to the documents
86+
that are at or above the index key bound of ``price`` equal to
87+
``1.39``:
88+
89+
.. code-block:: javascript
90+
91+
db.products.find().min( { price: 1.39 } ).max( { price: 1.99 } ).hint( { price: 1 } )
92+
93+
The query returns the following documents:
94+
95+
.. code-block:: javascript
96+
97+
{ "_id" : 6, "item" : "apple", "type" : "cortland", "price" : 1.29 }
98+
{ "_id" : 4, "item" : "apple", "type" : "jonathan", "price" : 1.29 }
99+
{ "_id" : 5, "item" : "apple", "type" : "mcintosh", "price" : 1.29 }
100+
{ "_id" : 3, "item" : "apple", "type" : "jonagold", "price" : 1.29 }
101+
{ "_id" : 10, "item" : "orange", "type" : "navel", "price" : 1.39 }
102+
103+
.. note::
104+
105+
- Because :method:`max() <cursor.max()>` requires a corresponding
106+
index as well as enforces the use of that index, it may be
107+
preferable to use the :operator:`$lt` operator in the query if
108+
possible. Consider the following example:
109+
110+
.. code-block:: javascript
111+
112+
db.products.find( { _id: 7 } ).max( { price: 1.39 } )
113+
114+
The query will use the index on the ``price`` field, even if
115+
the index on ``_id`` may be better.
116+
117+
- :method:`max() <cursor.max()>` exists primarily to support the
118+
:program:`mongos` (sharding) process.
119+
120+
- If you use :method:`max() <cursor.max()>` with :method:`min()
121+
<cursor.min()>` to specify a range, the index bounds specified
122+
in :method:`min() <cursor.min()>` and :method:`max()
123+
<cursor.max()>` must both refer to the keys of the same index.
124+
125+
- :method:`max() <cursor.max()>` is a shell wrapper around the
126+
special operator :operator:`$max`.
127+

‎source/reference/method/cursor.min.txt

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
============
2+
cursor.min()
3+
============
4+
5+
.. default-domain:: mongodb
6+
7+
.. method:: cursor.min()
8+
9+
The :method:`min() <cursor.min()>` method specifies the *inclusive*
10+
lower bound for a specific index in order to constrain the results
11+
of :method:`find() <db.collection.find()>`. :method:`min()
12+
<cursor.min()>` provides a way to specify lower bounds on compound
13+
key indexes.
14+
15+
:method:`min() <cursor.min()>` takes the following parameter:
16+
17+
:param document indexbounds:
18+
19+
Specifies the inclusive lower bound for the index keys. The
20+
``indexbounds`` parameter has the following prototype form:
21+
22+
.. code-block:: javascript
23+
24+
{ field1: <min value>, field2: <min value2> ... fieldN:<min valueN>}
25+
26+
The fields correspond to *all* the keys of a particular index
27+
*in order*. You can explicitly specify the particular index
28+
with the :method:`hint() <cursor.hint()>` method. Otherwise,
29+
:program:`mongod` selects the index using the fields in the
30+
``indexbounds``; however, if multiple indexes exist on same
31+
fields with different sort orders, the selection of the index
32+
may be ambiguous.
33+
34+
Consider the following examples of :method:`min() <cursor.min()>`:
35+
36+
The examples assume a collection ``products`` with the following documents:
37+
38+
.. code-block:: javascript
39+
40+
{ "_id" : 6, "item" : "apple", "type" : "cortland", "price" : 1.29 }
41+
{ "_id" : 2, "item" : "apple", "type" : "fuji", "price" : 1.99 }
42+
{ "_id" : 1, "item" : "apple", "type" : "honey crisp", "price" : 1.99 }
43+
{ "_id" : 3, "item" : "apple", "type" : "jonagold", "price" : 1.29 }
44+
{ "_id" : 4, "item" : "apple", "type" : "jonathan", "price" : 1.29 }
45+
{ "_id" : 5, "item" : "apple", "type" : "mcintosh", "price" : 1.29 }
46+
{ "_id" : 7, "item" : "orange", "type" : "cara cara", "price" : 2.99 }
47+
{ "_id" : 10, "item" : "orange", "type" : "navel", "price" : 1.39 }
48+
{ "_id" : 9, "item" : "orange", "type" : "satsuma", "price" : 1.99 }
49+
{ "_id" : 8, "item" : "orange", "type" : "valencia", "price" : 0.99 }
50+
51+
The collection has the following four indexes:
52+
53+
.. code-block:: javascript
54+
55+
{ "_id" : 1 }
56+
{ "item" : 1, "type" : 1 }
57+
{ "item" : 1, "type" : -1 }
58+
{ "price" : 1 }
59+
60+
- Using the ordering of ``{ item: 1, type: 1 }`` index,
61+
:method:`min() <cursor.min()>` limits the query to the documents
62+
that are at or above the index key bound of ``item`` equal to
63+
``apple`` and ``type`` equal to ``jonagold``:
64+
65+
.. code-block:: javascript
66+
67+
db.products.find().min( { item: 'apple', type: 'jonagold' } ).hint( { item: 1, type: 1 } )
68+
69+
70+
The query returns the following documents:
71+
72+
.. code-block:: javascript
73+
74+
{ "_id" : 3, "item" : "apple", "type" : "jonagold", "price" : 1.29 }
75+
{ "_id" : 4, "item" : "apple", "type" : "jonathan", "price" : 1.29 }
76+
{ "_id" : 5, "item" : "apple", "type" : "mcintosh", "price" : 1.29 }
77+
{ "_id" : 7, "item" : "orange", "type" : "cara cara", "price" : 2.99 }
78+
{ "_id" : 10, "item" : "orange", "type" : "navel", "price" : 1.39 }
79+
{ "_id" : 9, "item" : "orange", "type" : "satsuma", "price" : 1.99 }
80+
{ "_id" : 8, "item" : "orange", "type" : "valencia", "price" : 0.99 }
81+
82+
If the query did not explicitly specify the index with the
83+
:method:`hint() <cursor.hint()>` method, it is ambiguous as to
84+
whether :program:`mongod` would select the ``{ item: 1, type: 1
85+
}`` index ordering or the ``{ item: 1, type: -1 }`` index ordering.
86+
87+
- Using the ordering of the index ``{ price: 1 }``, :method:`min()
88+
<cursor.min()>` limits the query to the documents that are at or
89+
above the index key bound of ``price`` equal to ``1.39`` and
90+
:method:`max() <cursor.max()>` limits the query to the documents
91+
that are below the index key bound of ``price`` equal to ``1.99``:
92+
93+
.. code-block:: javascript
94+
95+
db.products.find().min( { price: 1.39 } ).max( { price: 1.99 } ).hint( { price: 1 } )
96+
97+
The query returns the following documents:
98+
99+
.. code-block:: javascript
100+
101+
{ "_id" : 6, "item" : "apple", "type" : "cortland", "price" : 1.29 }
102+
{ "_id" : 4, "item" : "apple", "type" : "jonathan", "price" : 1.29 }
103+
{ "_id" : 5, "item" : "apple", "type" : "mcintosh", "price" : 1.29 }
104+
{ "_id" : 3, "item" : "apple", "type" : "jonagold", "price" : 1.29 }
105+
{ "_id" : 10, "item" : "orange", "type" : "navel", "price" : 1.39 }
106+
107+
.. note::
108+
109+
- Because :method:`min() <cursor.min()>` requires a corresponding
110+
index as well as enforces the use of that index, it may be
111+
preferable to use the :operator:`$gte` operator in the query if
112+
possible. Consider the following example:
113+
114+
.. code-block:: javascript
115+
116+
db.products.find( { _id: 7 } ).min( { price: 1.39 } )
117+
118+
The query will use the index on the ``price`` field, even if
119+
the index on ``_id`` may be better.
120+
121+
- :method:`min() <cursor.min()>` exists primarily to support the
122+
:program:`mongos` (sharding) process.
123+
124+
- If you use :method:`min() <cursor.min()>` with :method:`max()
125+
<cursor.max()>` to specify a range, the index bounds specified
126+
in :method:`min() <cursor.min()>` and :method:`max()
127+
<cursor.max()>` must both refer to the keys of the same index.
128+
129+
- :method:`min() <cursor.min()>` is a shell wrapper around the
130+
special operator :operator:`$min`.

0 commit comments

Comments
 (0)