From 0e23384c5a2481ba5d02628e18d1d58987e7a31e Mon Sep 17 00:00:00 2001 From: kay Date: Wed, 31 Oct 2012 16:20:26 -0400 Subject: [PATCH 1/5] DOCS-671 min and max query specifiers --- source/reference/method/cursor.max.txt | 138 ++++++++++++++++++++++++ source/reference/method/cursor.min.txt | 144 +++++++++++++++++++++++++ 2 files changed, 282 insertions(+) create mode 100644 source/reference/method/cursor.max.txt create mode 100644 source/reference/method/cursor.min.txt diff --git a/source/reference/method/cursor.max.txt b/source/reference/method/cursor.max.txt new file mode 100644 index 00000000000..c99eecf8d41 --- /dev/null +++ b/source/reference/method/cursor.max.txt @@ -0,0 +1,138 @@ +============ +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 the :method:`find() ` method. The + :method:`max() ` method provides a straight-forward + way to specify an upper bound on multiple-key index. + + The :method:`max() ` method 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*. :program:`mongod` determines the index + using the fields in the ``indexbounds``; however, you can + explicitly specify the particular index with the + :method:`hint() ` method. + + .. note:: + + - The :method:`max() ` method exist primarily to + support the :program:`mongos` (sharding) process. + + - Because the :method:`max() ` method requires a + corresponding index, it may be preferable to use the + :operator:`$lt` operator in the query instead. + + - If you use :method:`max() ` method with the + :method:`min() ` method to specify a range, the + index bounds specified in :method:`min() ` method + and the :method:`max() ` method must both refer + to the keys of the same index. + + - The :method:`max() ` method is a shell wrapper + around the special operator :operator:`$max`. + + Consider the following example of the :method:`max() ` + method: + + The examples assume a collection ``contacts`` with the following documents: + + .. code-block:: javascript + + { "_id" : 1, "fname" : "ant", "lname" : "arctica" } + { "_id" : 2, "fname" : "bob", "lname" : "cat" } + { "_id" : 3, "fname" : "house", "lname" : "cat" } + { "_id" : 4, "fname" : "wild", "lname" : "cat" } + { "_id" : 7, "fname" : "big", "lname" : "dog" } + { "_id" : 5, "fname" : "ant", "lname" : "eater" } + { "_id" : 6, "fname" : "ant", "lname" : "elope" } + + The collection has the following three indexes: + + .. code-block:: javascript + + { "v" : 1, "key" : { "_id" : 1 }, "ns" : "test.contacts", "name" : "_id_" } + { "v" : 1, "key" : { "lname" : 1, "fname" : 1 }, "ns" : "test.contacts", "name" : "lname_1_fname_1" } + { "v" : 1, "key" : { "lname" : 1 }, "ns" : "test.contacts", "name" : "lname_1" } + + - Specify a lower, inclusive bounds for the index + ``lname_1_fname_1`` in the query execution. Using the ordering of + ``lname_1_fname_1``, the :method:`max() ` method + limits the query to the documents that are below the bound of + ``lname`` equal to ``dog`` and ``fname`` equal to ``big``: + + .. code-block:: javascript + + db.contacts.find().max( { lname: 'dog', fname: 'big' } ) + + The query returns the following documents: + + .. code-block:: javascript + + { "_id" : 1, "fname" : "ant", "lname" : "arctica" } + { "_id" : 2, "fname" : "bob", "lname" : "cat" } + { "_id" : 3, "fname" : "house", "lname" : "cat" } + { "_id" : 4, "fname" : "wild", "lname" : "cat" } + + The equivalent query with the :operator:`$lt` operator is: + + .. code-block:: javascript + + db.contacts.find( { lname: { $lt: 'dog' } } ) + + Note that the equivalent query with the :operator:`$lt` operator + is **not**: + + .. code-block:: javascript + + db.contacts.find( { lname: { $lt: 'dog' } , fname: { $lt: 'big' } } ) + + The query with the :operator:`$lt` operator returns only the + documents with both ``lname`` value less than ``dog`` **and** + ``fname`` value less than ``big``: + + .. code-block:: javascript + + { "_id" : 1, "fname" : "ant", "lname" : "arctica" } + + - Specify a range for the index ``lname_1`` in the query execution. + The :method:`min() ` method limits the query to the + documents that are at or above the index key bound of ``lname`` + equal to ``cat`` and the :method:`max() ` method + limits the query to the documents that are below the index key + bound of ``lname`` equal to ``eater``: + + .. code-block:: javascript + + db.contacts.find().min( { lname: 'cat' } ).max( { lname: 'eater' } ) + + The query returns the following documents: + + .. code-block:: javascript + + { "_id" : 3, "fname" : "house", "lname" : "cat" } + { "_id" : 2, "fname" : "bob", "lname" : "cat" } + { "_id" : 4, "fname" : "wild", "lname" : "cat" } + { "_id" : 7, "fname" : "big", "lname" : "dog" } + + The equivalent query with the :operator:`$gte` and the + :operator:`$lt` operators is: + + .. code-block:: javascript + + db.contacts.find( { lname: { $gte:'cat', $lt: 'eater' } } ) diff --git a/source/reference/method/cursor.min.txt b/source/reference/method/cursor.min.txt new file mode 100644 index 00000000000..88b403e1bc0 --- /dev/null +++ b/source/reference/method/cursor.min.txt @@ -0,0 +1,144 @@ +============ +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 the :method:`find() ` method. The + :method:`min() ` method provides a straight-forward + way to specify a lower bounds on multiple-key index. + + The :method:`min() ` method 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*. Otherwise, :program:`mongod` determines + the index using the fields in the ``indexbounds``; however, + you can explicitly specify the particular index with the + :method:`hint() ` method. + + .. note:: + + - The :method:`min() ` method exist primarily to + support the :program:`mongos` (sharding) process. + + - Because the :method:`min() ` method requires a + corresponding index, it may be preferable to use the + :operator:`$gte` operator in the query instead. + + - If you use :method:`min() ` method with the + :method:`max() ` method to specify a range, the + index bounds specified in :method:`min() ` method + and the :method:`max() ` method must both refer + to the keys of the same index. + + - The :method:`min() ` method is a shell wrapper + around the special operator :operator:`$min`. + + Consider the following example of the :method:`min() ` + method: + + The examples assume a collection ``contacts`` with the following documents: + + .. code-block:: javascript + + { "_id" : 1, "fname" : "ant", "lname" : "arctica" } + { "_id" : 2, "fname" : "bob", "lname" : "cat" } + { "_id" : 3, "fname" : "house", "lname" : "cat" } + { "_id" : 4, "fname" : "wild", "lname" : "cat" } + { "_id" : 7, "fname" : "big", "lname" : "dog" } + { "_id" : 5, "fname" : "ant", "lname" : "eater" } + { "_id" : 6, "fname" : "ant", "lname" : "elope" } + + The collection has the following three indexes: + + .. code-block:: javascript + + { "v" : 1, "key" : { "_id" : 1 }, "ns" : "test.contacts", "name" : "_id_" } + { "v" : 1, "key" : { "lname" : 1, "fname" : 1 }, "ns" : "test.contacts", "name" : "lname_1_fname_1" } + { "v" : 1, "key" : { "lname" : 1 }, "ns" : "test.contacts", "name" : "lname_1" } + + - Specify a lower, inclusive bounds for the index + ``lname_1_fname_1`` in the query execution. Using the ordering of + ``lname_1_fname_1``, the :method:`min() ` method + limits the query to the documents that are at or above the index + key bound of ``lname`` equal to ``cat`` and ``fname`` equal to + ``house``: + + .. code-block:: javascript + + db.contacts.find().min( { lname: 'cat', fname: 'house' } ) + + The query returns the following documents: + + .. code-block:: javascript + + { "_id" : 3, "fname" : "house", "lname" : "cat" } + { "_id" : 4, "fname" : "wild", "lname" : "cat" } + { "_id" : 7, "fname" : "big", "lname" : "dog" } + { "_id" : 5, "fname" : "ant", "lname" : "eater" } + { "_id" : 6, "fname" : "ant", "lname" : "elope" } + + The equivalent query with the :operator:`$gte` operator is: + + .. code-block:: javascript + + db.contacts.find( { $or: [ { lname: { $gt: 'cat' } }, + { lname: { $gte:'cat' }, + fname: { $gte: 'house' } } + ] } ).sort( { lname:1, fname: 1} ) + + Note that the equivalent query with the :operator:`$gte` operator + is **not**: + + .. code-block:: javascript + + db.contacts.find( { lname: { $gte: 'cat' } , fname: { $gte: 'house' } } ) + + The query with the :operator:`$gte` operator returns only the + documents with both ``lname`` value greater than or equal to + ``cat`` **and** ``fname`` value greater than or equal to ``house``: + + .. code-block:: javascript + + { "_id" : 3, "fname" : "house", "lname" : "cat" } + { "_id" : 4, "fname" : "wild", "lname" : "cat" } + + - Specify a range for the index ``lname_1`` in the query execution. + The :method:`min() ` method limits the query to the + documents that are at or above the index key bound of ``lname`` + equal to ``cat`` and the method:`max() ` method + limits the query to the documents that are below the index key + bound of ``lname`` equal to ``eater``: + + .. code-block:: javascript + + db.contacts.find().min( { lname: 'cat' } ).max( { lname: 'eater' } ) + + The query returns the following documents: + + .. code-block:: javascript + + { "_id" : 3, "fname" : "house", "lname" : "cat" } + { "_id" : 2, "fname" : "bob", "lname" : "cat" } + { "_id" : 4, "fname" : "wild", "lname" : "cat" } + { "_id" : 7, "fname" : "big", "lname" : "dog" } + + The equivalent query with the :operator:`$gte` and the + :operator:`$lt` operators is: + + .. code-block:: javascript + + db.contacts.find( { lname: { $gte:'cat', $lt: 'eater' } } ) From f96f89b9f6e4af06b347f98730a92b4dd3416938 Mon Sep 17 00:00:00 2001 From: kay Date: Sun, 11 Nov 2012 22:23:59 -0500 Subject: [PATCH 2/5] DOCS-671 min-max edits --- source/reference/method/cursor.max.txt | 147 ++++++++++----------- source/reference/method/cursor.min.txt | 173 ++++++++++++------------- 2 files changed, 150 insertions(+), 170 deletions(-) diff --git a/source/reference/method/cursor.max.txt b/source/reference/method/cursor.max.txt index c99eecf8d41..0b12c29f985 100644 --- a/source/reference/method/cursor.max.txt +++ b/source/reference/method/cursor.max.txt @@ -9,8 +9,8 @@ cursor.max() The :method:`max() ` method specifies the *exclusive* upper bound for a specific index in order to constrain the results of the :method:`find() ` method. The - :method:`max() ` method provides a straight-forward - way to specify an upper bound on multiple-key index. + :method:`max() ` method provides a way to specify an + upper bound on compound key indexes. The :method:`max() ` method takes the following parameter: @@ -23,116 +23,107 @@ cursor.max() { field1: , field2: ... fieldN:} - The fields correspond to *all* the keys of a particular - index *in order*. :program:`mongod` determines the index - using the fields in the ``indexbounds``; however, you can - explicitly specify the particular index with the - :method:`hint() ` method. - - .. note:: - - - The :method:`max() ` method exist primarily to - support the :program:`mongos` (sharding) process. - - - Because the :method:`max() ` method requires a - corresponding index, it may be preferable to use the - :operator:`$lt` operator in the query instead. - - - If you use :method:`max() ` method with the - :method:`min() ` method to specify a range, the - index bounds specified in :method:`min() ` method - and the :method:`max() ` method must both refer - to the keys of the same index. - - - The :method:`max() ` method is a shell wrapper - around the special operator :operator:`$max`. + 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 example of the :method:`max() ` method: - The examples assume a collection ``contacts`` with the following documents: + The examples assume a collection ``products`` with the following documents: .. code-block:: javascript - - { "_id" : 1, "fname" : "ant", "lname" : "arctica" } - { "_id" : 2, "fname" : "bob", "lname" : "cat" } - { "_id" : 3, "fname" : "house", "lname" : "cat" } - { "_id" : 4, "fname" : "wild", "lname" : "cat" } - { "_id" : 7, "fname" : "big", "lname" : "dog" } - { "_id" : 5, "fname" : "ant", "lname" : "eater" } - { "_id" : 6, "fname" : "ant", "lname" : "elope" } - The collection has the following three indexes: + { "_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 - { "v" : 1, "key" : { "_id" : 1 }, "ns" : "test.contacts", "name" : "_id_" } - { "v" : 1, "key" : { "lname" : 1, "fname" : 1 }, "ns" : "test.contacts", "name" : "lname_1_fname_1" } - { "v" : 1, "key" : { "lname" : 1 }, "ns" : "test.contacts", "name" : "lname_1" } + { "v" : 1, "key" : { "_id" : 1 }, "ns" : "test.products", "name" :"_id_" }, + { "v" : 1, "key" : { "item" : 1, "type" : 1 }, "ns" :"test.products", "name" : "item_1_type_1" }, + { "v" : 1, "key" : { "item" : 1, "type" : -1 }, "ns" : "test.products", "name" : "item_1_type_-1" } + { "v" : 1, "key" : { "price" : 1 }, "ns" : "test.products", "name" : "price_1" } - - Specify a lower, inclusive bounds for the index - ``lname_1_fname_1`` in the query execution. Using the ordering of - ``lname_1_fname_1``, the :method:`max() ` method - limits the query to the documents that are below the bound of - ``lname`` equal to ``dog`` and ``fname`` equal to ``big``: + - Using the ordering of ``item_1_type_1`` index, the :method:`max() + ` method 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.contacts.find().max( { lname: 'dog', fname: 'big' } ) + db.products.find().max( { item: 'apple', type: 'jonagold' } ).hint( { item: 1, type: 1 } ) The query returns the following documents: .. code-block:: javascript - { "_id" : 1, "fname" : "ant", "lname" : "arctica" } - { "_id" : 2, "fname" : "bob", "lname" : "cat" } - { "_id" : 3, "fname" : "house", "lname" : "cat" } - { "_id" : 4, "fname" : "wild", "lname" : "cat" } - - The equivalent query with the :operator:`$lt` operator is: + { "_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 } - .. code-block:: javascript + 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. - db.contacts.find( { lname: { $lt: 'dog' } } ) + - Using the ordering of the index ``price_1``, the :method:`max() + ` method limits the query to the documents that are + below the index key bound of ``price`` equal to ``1.99`` and the + :method:`min() ` method limits the query to the + documents that are at or above the index key bound of ``price`` + equal to ``1.39``: - Note that the equivalent query with the :operator:`$lt` operator - is **not**: - .. code-block:: javascript - db.contacts.find( { lname: { $lt: 'dog' } , fname: { $lt: 'big' } } ) + db.products.find().min( { price: 1.39 } ).max( { price: 1.99 } ).hint( { price: 1 } ) - The query with the :operator:`$lt` operator returns only the - documents with both ``lname`` value less than ``dog`` **and** - ``fname`` value less than ``big``: + The query returns the following documents: .. code-block:: javascript - { "_id" : 1, "fname" : "ant", "lname" : "arctica" } + { "_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 } - - Specify a range for the index ``lname_1`` in the query execution. - The :method:`min() ` method limits the query to the - documents that are at or above the index key bound of ``lname`` - equal to ``cat`` and the :method:`max() ` method - limits the query to the documents that are below the index key - bound of ``lname`` equal to ``eater``: + .. note:: - .. code-block:: javascript + - Because the :method:`max() ` method 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: - db.contacts.find().min( { lname: 'cat' } ).max( { lname: 'eater' } ) + .. code-block:: javascript - The query returns the following documents: + db.products.find( { _id: 7 } ).max( { price: 1.39 } ) - .. code-block:: javascript + The query will use the index on the ``price`` field, even if + the index on ``_id`` may be better. - { "_id" : 3, "fname" : "house", "lname" : "cat" } - { "_id" : 2, "fname" : "bob", "lname" : "cat" } - { "_id" : 4, "fname" : "wild", "lname" : "cat" } - { "_id" : 7, "fname" : "big", "lname" : "dog" } + - The :method:`max() ` method exist primarily to + support the :program:`mongos` (sharding) process. - The equivalent query with the :operator:`$gte` and the - :operator:`$lt` operators is: + - If you use :method:`max() ` method with the + :method:`min() ` method to specify a range, the + index bounds specified in :method:`min() ` method + and the :method:`max() ` method must both refer + to the keys of the same index. - .. code-block:: javascript + - The :method:`max() ` method is a shell wrapper + around the special operator :operator:`$max`. - db.contacts.find( { lname: { $gte:'cat', $lt: 'eater' } } ) diff --git a/source/reference/method/cursor.min.txt b/source/reference/method/cursor.min.txt index 88b403e1bc0..2094eb22dab 100644 --- a/source/reference/method/cursor.min.txt +++ b/source/reference/method/cursor.min.txt @@ -9,8 +9,8 @@ cursor.min() The :method:`min() ` method specifies the *inclusive* lower bound for a specific index in order to constrain the results of the :method:`find() ` method. The - :method:`min() ` method provides a straight-forward - way to specify a lower bounds on multiple-key index. + :method:`min() ` method provides a way to specify + lower bounds on compound key indexes. The :method:`min() ` method takes the following parameter: @@ -23,122 +23,111 @@ cursor.min() { field1: , field2: ... fieldN:} - The fields correspond to *all* the keys of a particular - index *in order*. Otherwise, :program:`mongod` determines - the index using the fields in the ``indexbounds``; however, - you can explicitly specify the particular index with the - :method:`hint() ` method. + 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. - .. note:: - - - The :method:`min() ` method exist primarily to - support the :program:`mongos` (sharding) process. - - - Because the :method:`min() ` method requires a - corresponding index, it may be preferable to use the - :operator:`$gte` operator in the query instead. - - - If you use :method:`min() ` method with the - :method:`max() ` method to specify a range, the - index bounds specified in :method:`min() ` method - and the :method:`max() ` method must both refer - to the keys of the same index. - - - The :method:`min() ` method is a shell wrapper - around the special operator :operator:`$min`. - - Consider the following example of the :method:`min() ` + Consider the following examples of the :method:`min() ` method: - The examples assume a collection ``contacts`` with the following documents: + The examples assume a collection ``products`` with the following documents: .. code-block:: javascript - - { "_id" : 1, "fname" : "ant", "lname" : "arctica" } - { "_id" : 2, "fname" : "bob", "lname" : "cat" } - { "_id" : 3, "fname" : "house", "lname" : "cat" } - { "_id" : 4, "fname" : "wild", "lname" : "cat" } - { "_id" : 7, "fname" : "big", "lname" : "dog" } - { "_id" : 5, "fname" : "ant", "lname" : "eater" } - { "_id" : 6, "fname" : "ant", "lname" : "elope" } - The collection has the following three indexes: + { "_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 - { "v" : 1, "key" : { "_id" : 1 }, "ns" : "test.contacts", "name" : "_id_" } - { "v" : 1, "key" : { "lname" : 1, "fname" : 1 }, "ns" : "test.contacts", "name" : "lname_1_fname_1" } - { "v" : 1, "key" : { "lname" : 1 }, "ns" : "test.contacts", "name" : "lname_1" } - - - Specify a lower, inclusive bounds for the index - ``lname_1_fname_1`` in the query execution. Using the ordering of - ``lname_1_fname_1``, the :method:`min() ` method - limits the query to the documents that are at or above the index - key bound of ``lname`` equal to ``cat`` and ``fname`` equal to - ``house``: + { "v" : 1, "key" : { "_id" : 1 }, "ns" : "test.products", "name" :"_id_" }, + { "v" : 1, "key" : { "item" : 1, "type" : 1 }, "ns" :"test.products", "name" : "item_1_type_1" }, + { "v" : 1, "key" : { "item" : 1, "type" : -1 }, "ns" : "test.products", "name" : "item_1_type_-1" } + { "v" : 1, "key" : { "price" : 1 }, "ns" : "test.products", "name" : "price_1" } + - Using the ordering of ``item_1_type_1`` index, the :method:`min() + ` method 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.contacts.find().min( { lname: 'cat', fname: 'house' } ) + db.products.find().min( { item: 'apple', type: 'jonagold' } ).hint( { item: 1, type: 1 } ) + The query returns the following documents: .. code-block:: javascript - { "_id" : 3, "fname" : "house", "lname" : "cat" } - { "_id" : 4, "fname" : "wild", "lname" : "cat" } - { "_id" : 7, "fname" : "big", "lname" : "dog" } - { "_id" : 5, "fname" : "ant", "lname" : "eater" } - { "_id" : 6, "fname" : "ant", "lname" : "elope" } - - The equivalent query with the :operator:`$gte` operator is: + { "_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``, the :method:`min() + ` method limits the query to the documents that are + at or above the index key bound of ``price`` equal to ``1.39`` and + the :method:`max() ` method limits the query to the + documents that are below the index key bound of ``price`` equal to + ``1.99``: .. code-block:: javascript - db.contacts.find( { $or: [ { lname: { $gt: 'cat' } }, - { lname: { $gte:'cat' }, - fname: { $gte: 'house' } } - ] } ).sort( { lname:1, fname: 1} ) - - Note that the equivalent query with the :operator:`$gte` operator - is **not**: - - .. code-block:: javascript + db.products.find().min( { price: 1.39 } ).max( { price: 1.99 } ).hint( { price: 1 } ) - db.contacts.find( { lname: { $gte: 'cat' } , fname: { $gte: 'house' } } ) - - The query with the :operator:`$gte` operator returns only the - documents with both ``lname`` value greater than or equal to - ``cat`` **and** ``fname`` value greater than or equal to ``house``: - - .. code-block:: javascript - - { "_id" : 3, "fname" : "house", "lname" : "cat" } - { "_id" : 4, "fname" : "wild", "lname" : "cat" } - - - Specify a range for the index ``lname_1`` in the query execution. - The :method:`min() ` method limits the query to the - documents that are at or above the index key bound of ``lname`` - equal to ``cat`` and the method:`max() ` method - limits the query to the documents that are below the index key - bound of ``lname`` equal to ``eater``: + The query returns the following documents: .. code-block:: javascript - db.contacts.find().min( { lname: 'cat' } ).max( { lname: 'eater' } ) + { "_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 } - The query returns the following documents: - - .. code-block:: javascript + .. note:: - { "_id" : 3, "fname" : "house", "lname" : "cat" } - { "_id" : 2, "fname" : "bob", "lname" : "cat" } - { "_id" : 4, "fname" : "wild", "lname" : "cat" } - { "_id" : 7, "fname" : "big", "lname" : "dog" } + - Because the :method:`min() ` method 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. - The equivalent query with the :operator:`$gte` and the - :operator:`$lt` operators is: + - The :method:`min() ` method exist primarily to + support the :program:`mongos` (sharding) process. - .. code-block:: javascript + - If you use :method:`min() ` method with the + :method:`max() ` method to specify a range, the + index bounds specified in :method:`min() ` method + and the :method:`max() ` method must both refer + to the keys of the same index. - db.contacts.find( { lname: { $gte:'cat', $lt: 'eater' } } ) + - The :method:`min() ` method is a shell wrapper + around the special operator :operator:`$min`. From 5c0e67e8438a1a283173d11dc700745cac5f3f4d Mon Sep 17 00:00:00 2001 From: kay Date: Tue, 13 Nov 2012 18:02:52 -0500 Subject: [PATCH 3/5] DOCS-671 min-max FAQ landing page --- source/faq/indexes.txt | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/source/faq/indexes.txt b/source/faq/indexes.txt index d8c9773347a..f6c3acd9020 100644 --- a/source/faq/indexes.txt +++ b/source/faq/indexes.txt @@ -116,3 +116,14 @@ 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? +------------------------------------------------ + +The :method:`min() ` and the :method:`max() +` methods provide a way to constrain the results of the +:method:`find() ` method using index keys. + + From 089f8df04f8849bb603e8b9bae29e5c5cebcd4f2 Mon Sep 17 00:00:00 2001 From: kay Date: Wed, 14 Nov 2012 00:13:30 -0500 Subject: [PATCH 4/5] DOCS-671 index as docs and spelling edits --- source/reference/method/cursor.max.txt | 14 +++++++------- source/reference/method/cursor.min.txt | 22 +++++++++++----------- 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/source/reference/method/cursor.max.txt b/source/reference/method/cursor.max.txt index 0b12c29f985..f189db50b32 100644 --- a/source/reference/method/cursor.max.txt +++ b/source/reference/method/cursor.max.txt @@ -53,12 +53,12 @@ cursor.max() .. code-block:: javascript - { "v" : 1, "key" : { "_id" : 1 }, "ns" : "test.products", "name" :"_id_" }, - { "v" : 1, "key" : { "item" : 1, "type" : 1 }, "ns" :"test.products", "name" : "item_1_type_1" }, - { "v" : 1, "key" : { "item" : 1, "type" : -1 }, "ns" : "test.products", "name" : "item_1_type_-1" } - { "v" : 1, "key" : { "price" : 1 }, "ns" : "test.products", "name" : "price_1" } + { "_id" : 1 } + { "item" : 1, "type" : 1 } + { "item" : 1, "type" : -1 } + { "price" : 1 } - - Using the ordering of ``item_1_type_1`` index, the :method:`max() + - Using the ordering of ``{ item: 1, type: 1 }`` index, the :method:`max() ` method limits the query to the documents that are below the bound of ``item`` equal to ``apple`` and ``type`` equal to ``jonagold``: @@ -80,7 +80,7 @@ cursor.max() 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``, the :method:`max() + - Using the ordering of the index ``{ price: 1 }``, the :method:`max() ` method limits the query to the documents that are below the index key bound of ``price`` equal to ``1.99`` and the :method:`min() ` method limits the query to the @@ -115,7 +115,7 @@ cursor.max() The query will use the index on the ``price`` field, even if the index on ``_id`` may be better. - - The :method:`max() ` method exist primarily to + - The :method:`max() ` method exists primarily to support the :program:`mongos` (sharding) process. - If you use :method:`max() ` method with the diff --git a/source/reference/method/cursor.min.txt b/source/reference/method/cursor.min.txt index 2094eb22dab..7b617bc890b 100644 --- a/source/reference/method/cursor.min.txt +++ b/source/reference/method/cursor.min.txt @@ -53,15 +53,15 @@ cursor.min() .. code-block:: javascript - { "v" : 1, "key" : { "_id" : 1 }, "ns" : "test.products", "name" :"_id_" }, - { "v" : 1, "key" : { "item" : 1, "type" : 1 }, "ns" :"test.products", "name" : "item_1_type_1" }, - { "v" : 1, "key" : { "item" : 1, "type" : -1 }, "ns" : "test.products", "name" : "item_1_type_-1" } - { "v" : 1, "key" : { "price" : 1 }, "ns" : "test.products", "name" : "price_1" } - - - Using the ordering of ``item_1_type_1`` index, the :method:`min() - ` method 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``: + { "_id" : 1 } + { "item" : 1, "type" : 1 } + { "item" : 1, "type" : -1 } + { "price" : 1 } + + - Using the ordering of ``{ item: 1, type: 1 }`` index, the + :method:`min() ` method 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 @@ -85,7 +85,7 @@ cursor.min() 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``, the :method:`min() + - Using the ordering of the index ``{ price: 1 }``, the :method:`min() ` method limits the query to the documents that are at or above the index key bound of ``price`` equal to ``1.39`` and the :method:`max() ` method limits the query to the @@ -120,7 +120,7 @@ cursor.min() The query will use the index on the ``price`` field, even if the index on ``_id`` may be better. - - The :method:`min() ` method exist primarily to + - The :method:`min() ` method exists primarily to support the :program:`mongos` (sharding) process. - If you use :method:`min() ` method with the From 9842c6d0b0ac2037190b2d1d823e14b4569d6dcd Mon Sep 17 00:00:00 2001 From: kay Date: Wed, 14 Nov 2012 11:39:19 -0500 Subject: [PATCH 5/5] DOCS-671 min-max edits --- source/faq/indexes.txt | 8 ++-- source/reference/method/cursor.max.txt | 56 +++++++++++++------------- source/reference/method/cursor.min.txt | 55 ++++++++++++------------- 3 files changed, 56 insertions(+), 63 deletions(-) diff --git a/source/faq/indexes.txt b/source/faq/indexes.txt index f6c3acd9020..1c44ab5e08d 100644 --- a/source/faq/indexes.txt +++ b/source/faq/indexes.txt @@ -122,8 +122,6 @@ criterion is part of the query. Can I use index keys to constrain query matches? ------------------------------------------------ -The :method:`min() ` and the :method:`max() -` methods provide a way to constrain the results of the -:method:`find() ` method using index keys. - - +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 index f189db50b32..649c6363f9d 100644 --- a/source/reference/method/cursor.max.txt +++ b/source/reference/method/cursor.max.txt @@ -8,11 +8,11 @@ cursor.max() The :method:`max() ` method specifies the *exclusive* upper bound for a specific index in order to constrain the results - of the :method:`find() ` method. The - :method:`max() ` method provides a way to specify an - upper bound on compound key indexes. + of :method:`find() `. :method:`max() + ` provides a way to specify an upper bound on compound + key indexes. - The :method:`max() ` method takes the following parameter: + :method:`max() ` takes the following parameter: :param document indexbounds: @@ -31,8 +31,7 @@ cursor.max() fields with different sort orders, the selection of the index may be ambiguous. - Consider the following example of the :method:`max() ` - method: + Consider the following examples of :method:`max() `: The examples assume a collection ``products`` with the following documents: @@ -58,10 +57,10 @@ cursor.max() { "item" : 1, "type" : -1 } { "price" : 1 } - - Using the ordering of ``{ item: 1, type: 1 }`` index, the :method:`max() - ` method limits the query to the documents that are - below the bound of ``item`` equal to ``apple`` and ``type`` equal - to ``jonagold``: + - 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 @@ -80,12 +79,12 @@ cursor.max() 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 }``, the :method:`max() - ` method limits the query to the documents that are - below the index key bound of ``price`` equal to ``1.99`` and the - :method:`min() ` method limits the query to the - documents that are at or above the index key bound of ``price`` - equal to ``1.39``: + - 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 @@ -103,10 +102,10 @@ cursor.max() .. note:: - - Because the :method:`max() ` method 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: + - 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 @@ -115,15 +114,14 @@ cursor.max() The query will use the index on the ``price`` field, even if the index on ``_id`` may be better. - - The :method:`max() ` method exists primarily to - support the :program:`mongos` (sharding) process. + - :method:`max() ` exists primarily to support the + :program:`mongos` (sharding) process. - - If you use :method:`max() ` method with the - :method:`min() ` method to specify a range, the - index bounds specified in :method:`min() ` method - and the :method:`max() ` method must both refer - to the keys of the same index. + - 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. - - The :method:`max() ` method is a shell wrapper - around the special operator :operator:`$max`. + - :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 index 7b617bc890b..089fbec9752 100644 --- a/source/reference/method/cursor.min.txt +++ b/source/reference/method/cursor.min.txt @@ -8,11 +8,11 @@ cursor.min() The :method:`min() ` method specifies the *inclusive* lower bound for a specific index in order to constrain the results - of the :method:`find() ` method. The - :method:`min() ` method provides a way to specify - lower bounds on compound key indexes. + of :method:`find() `. :method:`min() + ` provides a way to specify lower bounds on compound + key indexes. - The :method:`min() ` method takes the following parameter: + :method:`min() ` takes the following parameter: :param document indexbounds: @@ -31,8 +31,7 @@ cursor.min() fields with different sort orders, the selection of the index may be ambiguous. - Consider the following examples of the :method:`min() ` - method: + Consider the following examples of :method:`min() `: The examples assume a collection ``products`` with the following documents: @@ -58,10 +57,10 @@ cursor.min() { "item" : 1, "type" : -1 } { "price" : 1 } - - Using the ordering of ``{ item: 1, type: 1 }`` index, the - :method:`min() ` method 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``: + - 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 @@ -85,12 +84,11 @@ cursor.min() 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 }``, the :method:`min() - ` method limits the query to the documents that are - at or above the index key bound of ``price`` equal to ``1.39`` and - the :method:`max() ` method limits the query to the - documents that are below the index key bound of ``price`` equal to - ``1.99``: + - 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 @@ -108,10 +106,10 @@ cursor.min() .. note:: - - Because the :method:`min() ` method 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: + - 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 @@ -120,14 +118,13 @@ cursor.min() The query will use the index on the ``price`` field, even if the index on ``_id`` may be better. - - The :method:`min() ` method exists primarily to - support the :program:`mongos` (sharding) process. + - :method:`min() ` exists primarily to support the + :program:`mongos` (sharding) process. - - If you use :method:`min() ` method with the - :method:`max() ` method to specify a range, the - index bounds specified in :method:`min() ` method - and the :method:`max() ` method must both refer - to the keys of the same index. + - 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. - - The :method:`min() ` method is a shell wrapper - around the special operator :operator:`$min`. + - :method:`min() ` is a shell wrapper around the + special operator :operator:`$min`.