/
cursor.max.txt
175 lines (114 loc) · 5.21 KB
/
cursor.max.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
============
cursor.max()
============
.. default-domain:: mongodb
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol
Definition
----------
.. method:: cursor.max()
Specifies the *exclusive* upper bound for a specific index in order
to constrain the results of
:method:`~db.collection.find()`. :method:`~cursor.max()` provides a
way to specify an upper bound on compound key indexes.
The :method:`~cursor.max()` method has the following parameter:
.. list-table::
:header-rows: 1
:widths: 20 20 80
* - Parameter
- Type
- Description
* - ``indexBounds``
- document
- The exclusive upper bound for the index keys.
The ``indexBounds`` parameter has the following prototype form:
.. code-block:: javascript
{ field1: <max value>, field2: <max value2> ... fieldN:<max valueN> }
The fields correspond to *all* the keys of a particular index *in
order*. You can explicitly specify the particular index with the
:method:`~cursor.hint()` method. Otherwise, :binary:`~bin.mongod`
selects the index using the fields in the ``indexBounds``; however,
if multiple indexes exist on same fields with different sort
orders, the selection of the index may be ambiguous.
.. seealso:: :method:`~cursor.min()`.
:method:`~cursor.max()` exists primarily to support the
:binary:`~bin.mongos` (sharding) process, and is a shell wrapper around the query
modifier :operator:`$max`.
.. include:: /includes/extracts/mongo-shell-deprecated-meta-operator-max.rst
Behavior
--------
Interaction with Index Selection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Because :method:`~cursor.max()` requires an index on a field,
and forces the query to use this index, you may prefer the
:query:`$lt` operator for the query if possible. Consider the
following example:
.. code-block:: javascript
db.products.find( { _id: 7 } ).max( { price: 1.39 } )
The query will use the index on the ``price`` field, even if
the index on ``_id`` may be better.
Index Bounds
~~~~~~~~~~~~
If you use :method:`~cursor.max()` with :method:`~cursor.min()` to
specify a range:
- the index bounds specified in :method:`~cursor.min()` and
:method:`~cursor.max()` must both refer to the keys of the same index.
- the bound specified by :method:`~cursor.max()` must be greater than
the bound specified by :method:`~cursor.min()`.
.. versionchanged:: 3.4.16
``max()`` without ``min()``
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/fact-query-min-max.rst
Example
-------
This example assumes a collection named ``products`` that holds the
following documents:
.. code-block:: javascript
{ "_id" : 6, "item" : "apple", "type" : "cortland", "price" : 1.29 }
{ "_id" : 2, "item" : "apple", "type" : "fuji", "price" : 1.99 }
{ "_id" : 1, "item" : "apple", "type" : "honey crisp", "price" : 1.99 }
{ "_id" : 3, "item" : "apple", "type" : "jonagold", "price" : 1.29 }
{ "_id" : 4, "item" : "apple", "type" : "jonathan", "price" : 1.29 }
{ "_id" : 5, "item" : "apple", "type" : "mcintosh", "price" : 1.29 }
{ "_id" : 7, "item" : "orange", "type" : "cara cara", "price" : 2.99 }
{ "_id" : 10, "item" : "orange", "type" : "navel", "price" : 1.39 }
{ "_id" : 9, "item" : "orange", "type" : "satsuma", "price" : 1.99 }
{ "_id" : 8, "item" : "orange", "type" : "valencia", "price" : 0.99 }
The collection has the following indexes:
.. code-block:: javascript
{ "_id" : 1 }
{ "item" : 1, "type" : 1 }
{ "item" : 1, "type" : -1 }
{ "price" : 1 }
- Using the ordering of ``{ item: 1, type: 1 }`` index,
:method:`~cursor.max()` limits the query to the documents
that are below the bound of ``item`` equal to ``apple`` and
``type`` equal to ``jonagold``:
.. code-block:: javascript
db.products.find().max( { item: 'apple', type: 'jonagold' } ).hint( { item: 1, type: 1 } )
The query returns the following documents:
.. code-block:: javascript
{ "_id" : 6, "item" : "apple", "type" : "cortland", "price" : 1.29 }
{ "_id" : 2, "item" : "apple", "type" : "fuji", "price" : 1.99 }
{ "_id" : 1, "item" : "apple", "type" : "honey crisp", "price" : 1.99 }
If the query did not explicitly specify the index with the
:method:`~cursor.hint()` method, it is ambiguous as to
whether :binary:`~bin.mongod` would select the ``{ item: 1, type: 1
}`` index ordering or the ``{ item: 1, type: -1 }`` index ordering.
- Using the ordering of the index ``{ price: 1 }``, :method:`~cursor.max()` limits the query to the documents that are below
the index key bound of ``price`` equal to ``1.99`` and
:method:`~cursor.min()` limits the query to the documents
that are at or above the index key bound of ``price`` equal to
``1.39``:
.. note::
.. versionchanged:: 3.4.16
The bound specified by :method:`~cursor.max()` must be greater
than the bound specified by :method:`~cursor.min()`.
.. code-block:: javascript
db.products.find().min( { price: 1.39 } ).max( { price: 1.99 } ).hint( { price: 1 } )
The query returns the following documents:
.. code-block:: javascript
{ "_id" : 10, "item" : "orange", "type" : "navel", "price" : 1.39 }