Skip to content

Commit 8983261

Browse files
stephmarie17stephmarie17
committed
DOCSP-44658 Add sort data page (#155)
(cherry picked from commit 8f5104f)
1 parent ae96e17 commit 8983261

File tree

8 files changed

+313
-18
lines changed

8 files changed

+313
-18
lines changed

‎.github/workflows/check-autobuilder.yml‎

Lines changed: 0 additions & 13 deletions
This file was deleted.

‎.github/workflows/vale-tdbx.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,9 @@ jobs:
1111
steps:
1212
- name: checkout
1313
uses: actions/checkout@master
14+
15+
- name: Install docutils
16+
run: sudo apt-get install -y docutils
1417

1518
- id: files
1619
uses: masesgroup/retrieve-changed-files@v2

‎source/fundamentals/aggregation.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -257,6 +257,9 @@ To learn more about the behavior of the ``aggregate()`` method, see the
257257
:ref:`Aggregation Operations <rust-retrieve-aggregation>` section of the
258258
Retrieve Data guide.
259259

260+
To learn more about sorting results within an aggregation pipeline, see the
261+
:ref:`rust-sort-guide` guide.
262+
260263
API Documentation
261264
~~~~~~~~~~~~~~~~~
262265

‎source/fundamentals/crud/read-operations.txt‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,11 @@ Read Operations
1212
Data Cursors </fundamentals/crud/read-operations/cursor>
1313
Open Change Streams </fundamentals/crud/read-operations/change-streams>
1414
Search Text </fundamentals/crud/read-operations/text-search>
15+
Sort Data </fundamentals/crud/read-operations/sort>
1516

1617
..
1718
/fundamentals/crud/read-operations/count
1819
/fundamentals/crud/read-operations/distinct
19-
/fundamentals/crud/read-operations/sort
2020
/fundamentals/crud/read-operations/skip
2121
/fundamentals/crud/read-operations/limit
2222
/fundamentals/crud/read-operations/project
@@ -26,11 +26,12 @@ Read Operations
2626
- :ref:`rust-cursor-guide`
2727
- :ref:`rust-change-streams-guide`
2828
- :ref:`rust-search-text-guide`
29+
- :ref:`rust-sort-guide`
2930

3031
.. - :ref:`rust-query-guide`
3132
.. - :ref:`rust-count-guide`
3233
.. - :ref:`rust-distinct-guide`
33-
.. - :ref:`rust-sort-guide`
34+
3435
.. - :ref:`rust-skip-guide`
3536
.. - :ref:`rust-limit-guide`
3637
.. - :ref:`rust-project-guide`

‎source/fundamentals/crud/read-operations/retrieve.txt‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -161,14 +161,14 @@ The following table describes commonly used settings that you can specify in
161161
- | The sort to use when returning results. By default, the driver
162162
returns documents in their natural order, or as they appear in
163163
the database. To learn more, see :manual:`natural order </reference/glossary/#std-term-natural-order>`
164-
in the Server manual glossary.
164+
in the Server manual glossary. To learn more about how to use the
165+
``sort()`` builder method, see :ref:`rust-sort-guide`.
165166
|
166167
| Type: ``Document``
167168
| Default: ``None``
168169

169170
.. TODO link to projection fundamentals page under projection setting
170171
.. TODO link to skip fundamentals page under skip setting
171-
.. TODO link to sort fundamentals page under sort setting
172172

173173
.. note:: Instantiating Options
174174

@@ -393,9 +393,10 @@ following documentation:
393393
- :ref:`rust-query-guide` guide
394394
- :ref:`rust-cursor-guide` guide
395395
- :ref:`rust-aggregation` guide
396+
- :ref:`rust-sort-guide` guide
396397

397398
.. - :ref:`rust-skip-guide`
398-
.. - :ref:`rust-sort-guide`
399+
399400
.. - :ref:`rust-limit-guide`
400401
.. - :ref:`rust-project-guide`
401402
.. - :ref:`rust-collations-guide`

‎source/fundamentals/crud/read-operations/sort.txt‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
.. _rust-sort-guide:
2+
3+
============
4+
Sort Results
5+
============
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: code example, read operation, sort, sort results
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the {+driver-long+} to perform **sort**
24+
operations to specify the order of your read operation results.
25+
26+
Use the ``sort()`` method when building options to change the order in which
27+
read operations return documents. The ``sort()`` method tells MongoDB to order
28+
returned documents by the values of one or more fields in a certain direction.
29+
To sort returned documents by a field in ascending (lowest first) order, use a
30+
value of ``1``. To sort in descending (greatest first) order instead, use
31+
``-1``. If you do not specify a sort, MongoDB does not guarantee the order of
32+
query results.
33+
34+
Sample Data for Examples
35+
------------------------
36+
37+
The examples in this guide use the following ``Book`` struct as a model for
38+
documents in the ``books`` collection:
39+
40+
.. literalinclude:: /includes/fundamentals/code-snippets/crud/sort.rs
41+
:start-after: start-book-struct
42+
:end-before: end-book-struct
43+
:language: rust
44+
:dedent:
45+
46+
The following code shows how to insert sample data into the ``books``
47+
collection:
48+
49+
.. literalinclude:: /includes/fundamentals/code-snippets/crud/sort.rs
50+
:start-after: start-sample-data
51+
:end-before: end-sample-data
52+
:language: rust
53+
:dedent:
54+
55+
Methods for Sorting
56+
-------------------
57+
58+
You can sort results retrieved by a query, or you can sort results within an
59+
aggregation pipeline.
60+
61+
This example shows how to call the ``find()`` method with the following
62+
parameters:
63+
64+
- Query filter that matches all documents
65+
- ``FindOptions`` instance that sorts matched documents by ``author`` in
66+
ascending order
67+
68+
.. literalinclude:: /includes/fundamentals/code-snippets/crud/sort.rs
69+
:start-after: start-sort-query
70+
:end-before: end-sort-query
71+
:language: rust
72+
:dedent:
73+
74+
Aggregation
75+
~~~~~~~~~~~
76+
77+
To sort your results within an aggregation pipeline, create a ``$sort`` stage
78+
and pass the list of stages to the ``aggregate()`` method.
79+
80+
The following example shows how to create a ``$sort`` stage that sorts documents
81+
in ascending order by the values of the ``author`` field:
82+
83+
.. literalinclude:: /includes/fundamentals/code-snippets/crud/sort.rs
84+
:start-after: start-sort-aggregation
85+
:end-before: end-sort-aggregation
86+
:language: rust
87+
:dedent:
88+
89+
Sorting Direction
90+
-----------------
91+
92+
The direction of your sort can either be **ascending** or **descending**. An
93+
ascending sort orders your results from smallest to largest. A descending sort
94+
orders your results from largest to smallest.
95+
96+
The following list contains examples of data sorted in ascending order:
97+
98+
* Numbers: 1, 2, 3, 43, 43, 55, 120
99+
* Dates: 1990-03-10, 1995-01-01, 2005-10-30, 2005-12-21
100+
* Words (ASCII): Banana, Dill, carrot, cucumber, hummus
101+
102+
The following list contains examples of data sorted in descending order:
103+
104+
* Numbers: 100, 30, 12, 12, 9, 3, 1
105+
* Dates: 2020-01-01, 1998-12-11, 1998-12-10, 1975-07-22
106+
* Words (reverse ASCII): pear, grapes, apple, Cheese
107+
108+
The following subsections show how to specify these sort criteria.
109+
110+
Ascending
111+
~~~~~~~~~
112+
113+
To specify an ascending sort, pass the field you want to sort by and ``1`` to
114+
the ``sort()`` method.
115+
116+
Example
117+
^^^^^^^
118+
119+
The following example specifies an ascending sort on the ``name`` field:
120+
121+
.. io-code-block::
122+
:copyable: true
123+
124+
.. input:: /includes/fundamentals/code-snippets/crud/sort.rs
125+
:start-after: start-ascending-sort
126+
:end-before: end-ascending-sort
127+
:language: rust
128+
:dedent:
129+
130+
.. output::
131+
:language: console
132+
:visible: false
133+
134+
Book { "_id": 4, "name": "A Dance with Dragons", "author": Martin, "length": 1104 }
135+
Book { "_id": 2, "name": "Atlas Shrugged", "author": Rand, "length": 1088 }
136+
Book { "_id": 3, "name": "Les Miserables", "author": Hugo, "length": 1462 }
137+
Book { "_id": 1, "name": "The Brothers Karamazov", "author": Dostoevsky, "length": 824 }
138+
139+
Descending
140+
~~~~~~~~~~
141+
142+
To specify a descending sort, pass the field you want to sort by and ``-1`` to
143+
the ``sort()`` method.
144+
145+
Example
146+
^^^^^^^
147+
148+
The following example specifies a descending sort on the ``name`` field:
149+
150+
.. io-code-block::
151+
:copyable: true
152+
153+
.. input:: /includes/fundamentals/code-snippets/crud/sort.rs
154+
:start-after: start-descending-sort
155+
:end-before: end-descending-sort
156+
:language: rust
157+
:dedent:
158+
159+
.. output::
160+
:language: console
161+
:visible: false
162+
163+
Book { "_id": 1, "name": "The Brothers Karamazov", "author": Dostoevsky, "length": 824 }
164+
Book { "_id": 3, "name": "Les Miserables", "author": Hugo, "length": 1462 }
165+
Book { "_id": 2, "name": "Atlas Shrugged", "author": Rand, "length": 1088 }
166+
Book { "_id": 4, "name": "A Dance with Dragons", "author": Martin, "length": 1104 }
167+
168+
Additional Information
169+
----------------------
170+
171+
To learn more about the operations mentioned in this guide, see the following:
172+
173+
- :ref:`rust-query-guide`
174+
- :ref:`rust-retrieve-guide`
175+
- :ref:`rust-compound-operations`
176+
- :ref:`rust-aggregation`
177+
178+
API Documentation
179+
~~~~~~~~~~~~~~~~~
180+
181+
To learn more about any of the methods or types discussed in this guide, see the
182+
following API documentation:
183+
184+
- `find() <{+api+}/struct.Collection.html#method.find>`__
185+
- `FindOptions <{+api+}/options/struct.FindOptions.html>`__
186+
- `FindOneOptions <{+api+}/options/struct.FindOneOptions.html>`__
187+
- `Cursor <{+api+}/struct.Cursor.html>`__
188+
- `aggregate() <{+api+}/struct.Collection.html#method.aggregate>`__
189+
- `AggregateOptions <{+api+}/options/struct.AggregateOptions.html>`__

‎source/fundamentals/crud/read-operations/text-search.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -349,6 +349,7 @@ following documentation:
349349

350350
- :ref:`rust-query-guide`
351351
- :ref:`rust-retrieve-guide`
352+
- :ref:`rust-sort-guide`
352353
- :ref:`rust-aggregation`
353354
- :ref:`rust-indexes`
354355
- :manual:`Text Indexes </core/index-text/>` in the Server manual

0 commit comments

Comments
 (0)