Skip to content

Commit 12c638e

Browse files
mcmorisimcmorisi
committed
DOCSP-45005: Specify Docs to Return (#290)
(cherry picked from commit e9347d6)
1 parent 646946f commit 12c638e

File tree

3 files changed

+303
-0
lines changed

3 files changed

+303
-0
lines changed

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

+2
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,11 @@ Read Operations
1515
Count Documents </fundamentals/crud/read-operations/count>
1616
/fundamentals/crud/read-operations/distinct
1717
Monitor Data Changes </fundamentals/crud/read-operations/change-streams>
18+
/fundamentals/crud/read-operations/specify-documents-to-return
1819

1920
- :ref:`csharp-retrieve`
2021
- :ref:`csharp-project`
2122
- :ref:`csharp-count-documents`
2223
- :ref:`csharp-distinct`
2324
- :ref:`csharp-change-streams`
25+
- :ref:`csharp-specify-documents-to-return`

‎source/fundamentals/crud/read-operations/specify-documents-to-return.txt

+220
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
.. _csharp-specify-documents-to-return:
2+
3+
===========================
4+
Specify Documents to Return
5+
===========================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: read, paginate, pagination, order, code example
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to specify which documents to return
24+
from a read operation by chaining the following methods to the ``Find()``
25+
method:
26+
27+
- :ref:`Limit() <csharp-return-documents-limit>`: Specifies the maximum number of documents
28+
to return from a query
29+
- :ref:`Sort() <csharp-return-documents-sort>`: Specifies the sort order for the returned documents
30+
- :ref:`Skip() <csharp-return-documents-skip>`: Specifies the number of documents to skip before
31+
returning query results
32+
33+
Sample Data
34+
~~~~~~~~~~~
35+
36+
The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants``
37+
database from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the
38+
:atlas:`Get Started with Atlas </getting-started>` guide.
39+
40+
The examples on this page use the following ``Restaurant`` class as a model for the
41+
documents in the collection:
42+
43+
.. literalinclude:: /includes/fundamentals/code-examples/LimitSortSkip.cs
44+
:start-after: start-restaurant-class
45+
:end-before: end-restaurant-class
46+
:language: csharp
47+
48+
.. _csharp-return-documents-limit:
49+
50+
Limit
51+
-----
52+
53+
To specify the maximum number of documents returned from a read operation, use
54+
the ``Limit()`` method provided by the ``IFindFluent`` interface. After calling
55+
the ``Find()`` method, chain the ``Limit()`` method to modify the behavior of the
56+
operation.
57+
58+
The following example finds all restaurants that have a ``cuisine`` field value
59+
of ``"Italian"`` and limits the results to ``5`` documents:
60+
61+
.. io-code-block::
62+
:copyable:
63+
64+
.. input:: /includes/fundamentals/code-examples/LimitSortSkip.cs
65+
:start-after: start-limit
66+
:end-before: end-limit
67+
:language: csharp
68+
:dedent:
69+
70+
.. output::
71+
:visible: false
72+
73+
V & T Restaurant
74+
Mimis Restaurant & Bar
75+
Venice Restaurant
76+
Areo Restaurant
77+
Tre Giovani Pizza & Pasta
78+
79+
.. tip::
80+
81+
The preceding example returns the first five documents matched by the query
82+
according to their :manual:`natural order </reference/glossary/#std-term-natural-order>`
83+
in the database. The following section describes how to return the documents
84+
in a specified order.
85+
86+
.. _csharp-return-documents-sort:
87+
88+
Sort
89+
----
90+
91+
To return documents in a specified order, use the ``Sort()`` method provided by
92+
the ``IFindFluent`` interface. After calling the ``Find()`` method, chain the ``Sort()``
93+
method to modify the behavior of the operation.
94+
95+
When calling ``Sort()``, you must pass in the sort definition as a parameter. You can construct a sort
96+
definition by using the ``Builders<T>.Sort.Ascending()`` method to sort values from
97+
lowest to highest, or the ``Builders<T>.Sort.Ascending()`` method to sort them from highest
98+
to lowest. Both of these methods take the field name to sort by as a parameter. These methods
99+
can be chained to sort returned documents by multiple fields.
100+
101+
The following example returns all documents that have a ``cuisine`` field value
102+
of ``"Italian"``, sorted in ascending order of ``name`` field values:
103+
104+
.. io-code-block::
105+
:copyable:
106+
107+
.. input:: /includes/fundamentals/code-examples/LimitSortSkip.cs
108+
:start-after: start-sort
109+
:end-before: end-sort
110+
:language: csharp
111+
:dedent:
112+
113+
.. output::
114+
:visible: false
115+
116+
(Lewis Drug Store) Locanda Vini E Olii
117+
101 Restaurant And Bar
118+
44 Sw Ristorante & Bar
119+
900 Park
120+
A Voce
121+
...
122+
123+
.. _csharp-return-documents-skip:
124+
125+
Skip
126+
----
127+
128+
To skip a specified number of documents before returning your query results, use
129+
the ``Skip()`` method provided by the ``IFindFluent`` interface. After calling
130+
the ``Find()`` method, chain the ``Skip()`` method to modify the behavior of the
131+
operation.
132+
133+
The following example returns all documents that have a ``cuisine`` field value
134+
of ``"Italian"`` and skips the first ``10`` documents:
135+
136+
.. io-code-block::
137+
:copyable:
138+
139+
.. input:: /includes/fundamentals/code-examples/LimitSortSkip.cs
140+
:start-after: start-skip
141+
:end-before: end-skip
142+
:language: csharp
143+
:dedent:
144+
145+
.. output::
146+
:visible: false
147+
148+
Trattoria Alba
149+
Da Umberto Restaurant
150+
La Strada Restaurant
151+
Pasta Lovers Trattoria
152+
Nanni Restaurant
153+
Villa Mosconi Restaurant
154+
Villa Berulia
155+
Marco Polo Ristorante
156+
Cafe Luna
157+
Baraonda
158+
159+
.. _csharp-return-documents-combine:
160+
161+
Combine Limit, Sort, and Skip
162+
-----------------------------
163+
164+
You can chain the ``Limit()``, ``Sort()``, and ``Skip()`` methods to a single
165+
``Find()`` method call. This allows you to set a maximum number of sorted documents
166+
to return from the read operation, skipping a specified number of documents before
167+
returning.
168+
169+
The following example returns ``5`` documents that have a ``cuisine`` value of
170+
``"Italian"``. The results are sorted in ascending order by the ``name`` field value,
171+
skipping the first ``10`` documents:
172+
173+
.. io-code-block::
174+
:copyable:
175+
176+
.. input:: /includes/fundamentals/code-examples/LimitSortSkip.cs
177+
:start-after: start-limit-sort-skip
178+
:end-before: end-limit-sort-skip
179+
:language: csharp
180+
:dedent:
181+
182+
.. output::
183+
:visible: false
184+
185+
Acqua
186+
Acqua Restaurant
187+
Acqua Santa
188+
Acquista Trattoria
189+
Acquolina Catering
190+
Adriatic Restaurant Pizzeria Bar
191+
Adrienne'S Pizza Bar
192+
Ai Fiori
193+
Aita Restaurant
194+
Al Di La
195+
196+
.. note::
197+
198+
The order in which you call these methods doesn't change the documents
199+
that are returned. The {+driver-short+} automatically reorders the calls to
200+
perform the sort operation first, the skip operation next, and then the limit
201+
operation.
202+
203+
Additional Information
204+
----------------------
205+
206+
For more information about retrieving documents, see the :ref:`csharp-retrieve` guide.
207+
208+
For more information about specifying a query, see the :ref:`csharp-specify-query` guide.
209+
210+
API Documentation
211+
~~~~~~~~~~~~~~~~~
212+
213+
To learn more about any of the methods or types discussed in this
214+
guide, see the following API documentation:
215+
216+
- `Find() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollectionExtensions.Find.html>`_
217+
- `IFindFluent <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IFindFluent-2.html>`_
218+
- `Limit() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IFindFluent-2.Limit.html>`_
219+
- `Sort() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IFindFluent-2.Sort.html>`_
220+
- `Skip() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IFindFluent-2.Skip.html>`_

‎source/includes/fundamentals/code-examples/LimitSortSkip.cs

+81
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
using MongoDB.Bson;
2+
using MongoDB.Bson.Serialization.Attributes;
3+
using MongoDB.Bson.Serialization.Conventions;
4+
using MongoDB.Driver;
5+
6+
public class LimitSortSkip
7+
{
8+
// Replace with your connection string
9+
private const string MongoConnectionString = "<connection string URI>";
10+
11+
public static void Main(string[] args)
12+
{
13+
var mongoClient = new MongoClient(MongoConnectionString);
14+
var database = mongoClient.GetDatabase("sample_restaurants");
15+
var collection = database.GetCollection<Restaurant>("restaurants");
16+
17+
{
18+
// start-limit
19+
var filter = Builders<Restaurant>.Filter.Eq("cuisine", "Italian");
20+
var results = collection.Find(filter).Limit(5).ToList();
21+
22+
foreach (var result in results)
23+
{
24+
Console.WriteLine(result.Name);
25+
}
26+
// end-limit
27+
}
28+
29+
{
30+
// start-sort
31+
var filter = Builders<Restaurant>.Filter.Eq("cuisine", "Italian");
32+
var sort = Builders<Restaurant>.Sort.Ascending("name");
33+
var results = collection.Find(filter).Sort(sort).ToList();
34+
35+
foreach (var result in results)
36+
{
37+
Console.WriteLine(result.Name);
38+
}
39+
// end-sort
40+
}
41+
42+
{
43+
// start-skip
44+
var filter = Builders<Restaurant>.Filter.Eq("cuisine", "Italian");
45+
var results = collection.Find(filter).Skip(10).ToList();
46+
47+
foreach (var result in results)
48+
{
49+
Console.WriteLine(result.Name);
50+
}
51+
// end-skip
52+
}
53+
54+
{
55+
// start-limit-sort-skip
56+
var filter = Builders<Restaurant>.Filter.Eq("cuisine", "Italian");
57+
var sort = Builders<Restaurant>.Sort.Ascending("name");
58+
59+
var results = collection.Find(filter).Limit(10).Sort(sort).Skip(10).ToList();
60+
61+
foreach (var result in results)
62+
{
63+
Console.WriteLine(result.Name);
64+
}
65+
// end-limit-sort-skip
66+
}
67+
}
68+
}
69+
70+
// start-restaurant-class
71+
[BsonIgnoreExtraElements]
72+
public class Restaurant {
73+
public ObjectId Id { get; set; }
74+
75+
[BsonElement("name")]
76+
public string Name { get; set; }
77+
78+
[BsonElement("cuisine")]
79+
public string Cuisine { get; set; }
80+
}
81+
// end-restaurant-class

0 commit comments

Comments
 (0)