Skip to content

Commit 7d614d2

Browse files
stephmarie17stephmarie17
committed
DOCSP-43425 Add sort data (#131)
Add sort data page and update vale test (cherry picked from commit 0063c48)
1 parent f03bb07 commit 7d614d2

File tree

8 files changed

+332
-18
lines changed

8 files changed

+332
-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
/fundamentals/crud/read-operations/cursor
1313
/fundamentals/crud/read-operations/change-streams
1414
/fundamentals/crud/read-operations/text-search
15+
/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
@@ -27,11 +27,12 @@ Read Operations
2727
- :ref:`rust-cursor-guide`
2828
- :ref:`rust-change-streams-guide`
2929
- :ref:`rust-search-text-guide`
30+
- :ref:`rust-sort-guide`
3031

3132
.. - :ref:`rust-query-guide`
3233
.. - :ref:`rust-count-guide`
3334
.. - :ref:`rust-distinct-guide`
34-
.. - :ref:`rust-sort-guide`
35+
3536
.. - :ref:`rust-skip-guide`
3637
.. - :ref:`rust-limit-guide`
3738
.. - :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
@@ -158,14 +158,14 @@ fields that you can set by calling their corresponding builder methods:
158158
- | The sort to use when returning results. By default, the driver
159159
returns documents in their natural order, or as they appear in
160160
the database. To learn more, see :manual:`natural order </reference/glossary/#std-term-natural-order>`
161-
in the Server manual glossary.
161+
in the Server manual glossary. To learn more about how to use the
162+
``sort()`` builder method, see :ref:`rust-sort-guide`.
162163
|
163164
| Type: ``Document``
164165
| Default: ``None``
165166

166167
.. TODO link to projection fundamentals page under projection setting
167168
.. TODO link to skip fundamentals page under skip setting
168-
.. TODO link to sort fundamentals page under sort setting
169169

170170
.. note:: Setting Options
171171

@@ -387,9 +387,10 @@ following documentation:
387387
- :ref:`rust-query-guide` guide
388388
- :ref:`rust-cursor-guide` guide
389389
- :ref:`rust-aggregation` guide
390+
- :ref:`rust-sort-guide` guide
390391

391392
.. - :ref:`rust-skip-guide`
392-
.. - :ref:`rust-sort-guide`
393+
393394
.. - :ref:`rust-limit-guide`
394395
.. - :ref:`rust-project-guide`
395396
.. - :ref:`rust-collations-guide`

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

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
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+
Chain the ``sort()`` method to the ``find()`` method to sort results retrieved
62+
by the query, as shown in the following example:
63+
64+
.. literalinclude:: /includes/fundamentals/code-snippets/crud/sort.rs
65+
:start-after: start-sort-query
66+
:end-before: end-sort-query
67+
:language: rust
68+
:dedent:
69+
70+
Options
71+
~~~~~~~
72+
73+
Alternatively, you can use the ``sort()`` method of the ``FindOptions``
74+
struct.
75+
76+
The following example performs a ``find()`` operation with the following behavior:
77+
78+
- Sorts the results in ascending order of the values of the ``author`` field
79+
- Skips the first document
80+
- Returns the remaining documents
81+
82+
.. literalinclude:: /includes/fundamentals/code-snippets/crud/sort.rs
83+
:start-after: start-sort-query-multiple-options
84+
:end-before: end-sort-query-multiple-options
85+
:language: rust
86+
:dedent:
87+
88+
Aggregation
89+
~~~~~~~~~~~
90+
91+
To sort your results within an aggregation pipeline, create a ``$sort`` stage
92+
and pass the list of stages to the ``aggregate()`` method.
93+
94+
The following example shows how to create a ``$sort`` stage that sorts documents
95+
in ascending order by the values of the ``author`` field:
96+
97+
.. literalinclude:: /includes/fundamentals/code-snippets/crud/sort.rs
98+
:start-after: start-sort-aggregation
99+
:end-before: end-sort-aggregation
100+
:language: rust
101+
:dedent:
102+
103+
Sorting Direction
104+
-----------------
105+
106+
The direction of your sort can either be **ascending** or **descending**. An
107+
ascending sort orders your results from smallest to largest. A descending sort
108+
orders your results from largest to smallest.
109+
110+
The following list contains examples of data sorted in ascending order:
111+
112+
* Numbers: 1, 2, 3, 43, 43, 55, 120
113+
* Dates: 1990-03-10, 1995-01-01, 2005-10-30, 2005-12-21
114+
* Words (ASCII): Banana, Dill, carrot, cucumber, hummus
115+
116+
The following list contains examples of data sorted in descending order:
117+
118+
* Numbers: 100, 30, 12, 12, 9, 3, 1
119+
* Dates: 2020-01-01, 1998-12-11, 1998-12-10, 1975-07-22
120+
* Words (reverse ASCII): pear, grapes, apple, Cheese
121+
122+
The following subsections show how to specify these sort criteria.
123+
124+
Ascending
125+
~~~~~~~~~
126+
127+
To specify an ascending sort, pass the field you want to sort by and ``1`` to
128+
the ``sort()`` method.
129+
130+
Example
131+
^^^^^^^
132+
133+
The following example specifies an ascending sort on the ``name`` field:
134+
135+
.. io-code-block::
136+
:copyable: true
137+
138+
.. input:: /includes/fundamentals/code-snippets/crud/sort.rs
139+
:start-after: start-ascending-sort
140+
:end-before: end-ascending-sort
141+
:language: rust
142+
:dedent:
143+
144+
.. output::
145+
:language: console
146+
:visible: false
147+
148+
Book { "_id": 4, "name": "A Dance with Dragons", "author": Martin, "length": 1104 }
149+
Book { "_id": 2, "name": "Atlas Shrugged", "author": Rand, "length": 1088 }
150+
Book { "_id": 3, "name": "Les Miserables", "author": Hugo, "length": 1462 }
151+
Book { "_id": 1, "name": "The Brothers Karamazov", "author": Dostoevsky, "length": 824 }
152+
153+
Descending
154+
~~~~~~~~~~
155+
156+
To specify a descending sort, pass the field you want to sort by and ``-1`` to
157+
the ``sort()`` method.
158+
159+
Example
160+
^^^^^^^
161+
162+
The following example specifies a descending sort on the ``name`` field:
163+
164+
.. io-code-block::
165+
:copyable: true
166+
167+
.. input:: /includes/fundamentals/code-snippets/crud/sort.rs
168+
:start-after: start-descending-sort
169+
:end-before: end-descending-sort
170+
:language: rust
171+
:dedent:
172+
173+
.. output::
174+
:language: console
175+
:visible: false
176+
177+
Book { "_id": 1, "name": "The Brothers Karamazov", "author": Dostoevsky, "length": 824 }
178+
Book { "_id": 3, "name": "Les Miserables", "author": Hugo, "length": 1462 }
179+
Book { "_id": 2, "name": "Atlas Shrugged", "author": Rand, "length": 1088 }
180+
Book { "_id": 4, "name": "A Dance with Dragons", "author": Martin, "length": 1104 }
181+
182+
Additional Information
183+
----------------------
184+
185+
To learn more about the operations metnioned in this guide, see the following:
186+
187+
- :ref:`rust-query-guide`
188+
- :ref:`rust-retrieve-guide`
189+
- :ref:`rust-compound-operations`
190+
- :ref:`rust-aggregation`
191+
192+
API Documentation
193+
~~~~~~~~~~~~~~~~~
194+
195+
To learn more about any of the methods or types discussed in this guide, see the
196+
following API Documentation:
197+
198+
- `find() <{+api+}/struct.Collection.html#method.find>`__
199+
- `FindOptions <{+api+}/options/struct.FindOptions.html>`__
200+
- `FindOneOptions <{+api+}/options/struct.FindOneOptions.html>`__
201+
- `Cursor <{+api+}/struct.Cursor.html>`__
202+
- `aggregate() <{+api+}/struct.Collection.html#method.aggregate>`__
203+
- `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)