Merge pull request #45 from ksadoff/DOCSP-9557

DOCSP-9557: Fundamentals > CRUD Operations > Read Operations > Sort Results

Author: ksadoff

source/fundamentals/crud/sort.txt

@@ -0,0 +1,138 @@
+============
+Sort Results
+============
+
+.. default-domain:: mongodb
+
+Use ``sort()`` to change the order in which read operations return
+documents. The ``sort()`` instance method tells MongoDB to order returned documents by the
+values of one or more fields in a certain direction. To sort returned
+documents by a field in ascending (lowest first) order, use the static method ``Sorts.ascending()``, 
+specifying the field on which to sort. To sort in descending (greatest first) order instead, 
+use the static method ``Sorts.descending()``, specifying the field on which to sort. For example,
+you can sort on ``id`` or ``name`` fields. If you do not specify a sort, MongoDB does not 
+guarantee the order of query results.
+
+Follow the instructions in the examples below to insert data into
+a collection and perform a sort on the results of a query.
+Consider a collection containing documents that describe books. To
+insert this data into a collection, run the following operation:
+
+.. code-block:: java
+
+    collection.insertMany(Arrays.asList(
+        new Document().append("_id", 1)
+            .append("title", "The Brothers Karamazov").append("length", 824)
+            .append("author", "Dostoyevsky"),
+        new Document().append("_id", 2)
+            .append("title", "Les Misérables").append("length", 1462).append("author", "Hugo"),
+        new Document().append("_id", 3)
+            .append("title", "Atlas Shrugged").append("length", 1088).append("author", "Rand"),
+        new Document().append("_id", 4)
+            .append("title", "Infinite Jest").append("length", 1104).append("author", "Wallace"),
+        new Document().append("_id", 5)
+            .append("title", "Cryptonomicon").append("length", 918).append("author", "Stephenson"),
+        new Document().append("_id", 6)
+            .append("title", "A Dance with Dragons").append("length", 1104)
+            .append("author", "Martin")
+    ));
+
+Call the ``sort()`` function and specify the order with ``ascending()`` to ensure that the
+operation returns books in alphabetical order by title:
+
+.. code-block:: java
+  :emphasize-lines: 5
+
+    import static com.mongodb.client.model.Sorts.ascending;
+
+    // define a cursor that can iterate through the results of the query
+    MongoCursor<Document> cursor = collection.find()
+        .sort(ascending("title")).iterator();
+    // print out items in alphabetical order
+    try {
+      while (cursor.hasNext()) {
+        System.out.println(cursor.next());
+      }
+    // close the cursor
+    } finally {
+      cursor.close();
+    }
+
+This sample code prints the documents in ascending order on the ``title`` field as follows:
+
+.. code-block:: java
+
+    Document{{_id=6, title=A Dance with Dragons, length=1104, author=Martin}}
+    Document{{_id=3, title=Atlas Shrugged, length=1088, author=Rand}}
+    Document{{_id=5, title=Cryptonomicon, length=918, author=Stephenson}}
+    Document{{_id=4, title=Infinite Jest, length=1104, author=Wallace}}
+    Document{{_id=2, title=Les Misérables, length=1462, author=Hugo}}
+    Document{{_id=1, title=The Brothers Karamazov, length=824, author=Dostoyevsky}}
+
+Sometimes, the order of two or more documents is ambiguous using a
+specified sort. Consider the case of sorting by length: in the above case, 
+both "A Dance with Dragons" and "Infinite Jest" have ``1104`` pages, so 
+the order in which ``sort()`` returns them is not guaranteed. To resolve ties in 
+your sorted results in a repeatable way, add additional fields to the 
+``Sorts.ascending()`` function call. 
+Call the ``sort()`` method, specifying ``length`` as 
+the first field by which to sort and the ``title`` field as the second field. In the event 
+that the ``length`` field comparison results in a tie, the operation compares the tied results 
+using the ``title`` field:
+
+
+.. code-block:: java
+  :emphasize-lines: 3
+    
+    // sort first by length, then title
+    MongoCursor<Document> cursor = collection.find()
+        .sort(ascending("length", "title")).iterator();
+
+This sample code prints your query results in ascending order by length. 
+When there are two documents with the same ``length`` value, it resolves the tie using the 
+``title`` field you specified as the second parameter.
+
+.. code-block:: java
+
+    Document{{_id=1, title=The Brothers Karamazov, length=824, author=Dostoyevsky}}
+    Document{{_id=5, title=Cryptonomicon, length=918, author=Stephenson}}
+    Document{{_id=3, title=Atlas Shrugged, length=1088, author=Rand}}
+    Document{{_id=6, title=A Dance with Dragons, length=1104, author=Martin}}
+    Document{{_id=4, title=Infinite Jest, length=1104, author=Wallace}}
+    Document{{_id=2, title=Les Misérables, length=1462, author=Hugo}}
+
+You can also sort by multiple fields in different orders, using ``Sorts.orderBy()``. 
+Consider this example where you first sort on ``length`` in an ascending order, and then on
+``title`` in a descending order:
+
+.. code-block:: java
+  :emphasize-lines: 7
+    
+    import static com.mongodb.client.model.Sorts.ascending;
+    import static com.mongodb.client.model.Sorts.descending;
+    import static com.mongodb.client.model.Sorts.orderBy;
+
+    // sort first by length ascending, then title descending
+    MongoCursor<Document> cursor = collection.find()
+        .sort(orderBy(ascending("length"), descending("title")))
+        .iterator();
+
+In the returned documents, notice how the two books with the same 
+length - "Infinite Jest" and "A Dance with Dragons" -
+appear in the reverse of the order shown in the previous example:
+
+.. code-block:: java
+
+    Document{{_id=1, title=The Brothers Karamazov, length=824, author=Dostoyevksy}}
+    Document{{_id=5, title=Cryptonomicon, length=918, author=Stephenson}}
+    Document{{_id=3, title=Atlas Shrugged, length=1088, author=Rand}}
+    Document{{_id=4, title=Infinite Jest, length=1104, author=Wallace}}
+    Document{{_id=6, title=A Dance with Dragons, length=1104, author=Martin}}
+    Document{{_id=2, title=Les Misérables, length=1462, author=Hugo}}
+
+For additional information on the classes and methods mentioned on this
+page, see the following API documentation:
+
+- :java-sync-api:`FindIterable <com/mongodb/client/FindIterable.html>`
+- :java-sync-api:`MongoCursor <com/mongodb/client/MongoCursor.html>`
+- :java-docs:`Sorts </apidocs/mongodb-driver-core/com/mongodb/client/model/Sorts.html>`