diff --git a/source/faq/indexes.txt b/source/faq/indexes.txt index d8c9773347a..1c44ab5e08d 100644 --- a/source/faq/indexes.txt +++ b/source/faq/indexes.txt @@ -116,3 +116,12 @@ The :operator:`$ne` and :operator:`$nin` operators are not selective. See :ref:`index-selectivity`. If you need to use these, it is often best to make sure that an additional, more selective criterion is part of the query. + +.. _faq-index-min-max: + +Can I use index keys to constrain query matches? +------------------------------------------------ + +You can use the :method:`min() ` and the :method:`max() +` methods to constrain the results of the cursor returned +from :method:`find() ` by using the index keys. diff --git a/source/reference/method/cursor.max.txt b/source/reference/method/cursor.max.txt new file mode 100644 index 00000000000..649c6363f9d --- /dev/null +++ b/source/reference/method/cursor.max.txt @@ -0,0 +1,127 @@ +============ +cursor.max() +============ + +.. default-domain:: mongodb + +.. method:: cursor.max() + + The :method:`max() ` method specifies the *exclusive* + upper bound for a specific index in order to constrain the results + of :method:`find() `. :method:`max() + ` provides a way to specify an upper bound on compound + key indexes. + + :method:`max() ` takes the following parameter: + + :param document indexbounds: + + Specifies the exclusive upper bound for the index keys. The + ``indexbounds`` parameter has the following prototype form: + + .. code-block:: javascript + + { field1: , field2: ... fieldN:} + + The fields correspond to *all* the keys of a particular index + *in order*. You can explicitly specify the particular index + with the :method:`hint() ` method. Otherwise, + :program:`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. + + Consider the following examples of :method:`max() `: + + The examples assume a collection ``products`` with 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 four 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:`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:`hint() ` method, it is ambiguous as to + whether :program:`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:`max() + ` limits the query to the documents that are below + the index key bound of ``price`` equal to ``1.99`` and + :method:`min() ` limits the query to the documents + that are at or above the index key bound of ``price`` equal to + ``1.39``: + + .. 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" : 6, "item" : "apple", "type" : "cortland", "price" : 1.29 } + { "_id" : 4, "item" : "apple", "type" : "jonathan", "price" : 1.29 } + { "_id" : 5, "item" : "apple", "type" : "mcintosh", "price" : 1.29 } + { "_id" : 3, "item" : "apple", "type" : "jonagold", "price" : 1.29 } + { "_id" : 10, "item" : "orange", "type" : "navel", "price" : 1.39 } + + .. note:: + + - Because :method:`max() ` requires a corresponding + index as well as enforces the use of that index, it may be + preferable to use the :operator:`$lt` operator in 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. + + - :method:`max() ` exists primarily to support the + :program:`mongos` (sharding) process. + + - If you use :method:`max() ` with :method:`min() + ` to specify a range, the index bounds specified + in :method:`min() ` and :method:`max() + ` must both refer to the keys of the same index. + + - :method:`max() ` is a shell wrapper around the + special operator :operator:`$max`. + diff --git a/source/reference/method/cursor.min.txt b/source/reference/method/cursor.min.txt new file mode 100644 index 00000000000..089fbec9752 --- /dev/null +++ b/source/reference/method/cursor.min.txt @@ -0,0 +1,130 @@ +============ +cursor.min() +============ + +.. default-domain:: mongodb + +.. method:: cursor.min() + + The :method:`min() ` method specifies the *inclusive* + lower bound for a specific index in order to constrain the results + of :method:`find() `. :method:`min() + ` provides a way to specify lower bounds on compound + key indexes. + + :method:`min() ` takes the following parameter: + + :param document indexbounds: + + Specifies the inclusive lower bound for the index keys. The + ``indexbounds`` parameter has the following prototype form: + + .. code-block:: javascript + + { field1: , field2: ... fieldN:} + + The fields correspond to *all* the keys of a particular index + *in order*. You can explicitly specify the particular index + with the :method:`hint() ` method. Otherwise, + :program:`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. + + Consider the following examples of :method:`min() `: + + The examples assume a collection ``products`` with 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 four 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:`min() ` limits the query to the documents + that are at or above the index key bound of ``item`` equal to + ``apple`` and ``type`` equal to ``jonagold``: + + .. code-block:: javascript + + db.products.find().min( { item: 'apple', type: 'jonagold' } ).hint( { item: 1, type: 1 } ) + + + The query returns the following documents: + + .. code-block:: javascript + + { "_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 } + + If the query did not explicitly specify the index with the + :method:`hint() ` method, it is ambiguous as to + whether :program:`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:`min() + ` limits the query to the documents that are at or + above the index key bound of ``price`` equal to ``1.39`` and + :method:`max() ` limits the query to the documents + that are below the index key bound of ``price`` equal to ``1.99``: + + .. 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" : 6, "item" : "apple", "type" : "cortland", "price" : 1.29 } + { "_id" : 4, "item" : "apple", "type" : "jonathan", "price" : 1.29 } + { "_id" : 5, "item" : "apple", "type" : "mcintosh", "price" : 1.29 } + { "_id" : 3, "item" : "apple", "type" : "jonagold", "price" : 1.29 } + { "_id" : 10, "item" : "orange", "type" : "navel", "price" : 1.39 } + + .. note:: + + - Because :method:`min() ` requires a corresponding + index as well as enforces the use of that index, it may be + preferable to use the :operator:`$gte` operator in the query if + possible. Consider the following example: + + .. code-block:: javascript + + db.products.find( { _id: 7 } ).min( { price: 1.39 } ) + + The query will use the index on the ``price`` field, even if + the index on ``_id`` may be better. + + - :method:`min() ` exists primarily to support the + :program:`mongos` (sharding) process. + + - If you use :method:`min() ` with :method:`max() + ` to specify a range, the index bounds specified + in :method:`min() ` and :method:`max() + ` must both refer to the keys of the same index. + + - :method:`min() ` is a shell wrapper around the + special operator :operator:`$min`.