Skip to content

Commit 146c2fa

Browse files
jordan-smith721jordan-smith721
authored
DOCSP-32165 Query Data (#13)
1 parent ec51e2a commit 146c2fa

File tree

4 files changed

+191
-10
lines changed

4 files changed

+191
-10
lines changed

‎source/fundamentals.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,5 +12,6 @@ Fundamentals
1212
:maxdepth: 1
1313

1414
/fundamentals/configure
15+
/fundamentals/query-data
1516

1617
- :ref:`entity-framework-configure`

‎source/fundamentals/query-data.txt

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
.. _entity-framework-query-data:
2+
3+
==========
4+
Query Data
5+
==========
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: EF, EF Core, code example, read
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
{+framework-core+} allows you to work with data in your application without
24+
explicitly running database commands. To query your data, use the
25+
Langage-Integrated Query (LINQ) syntax. LINQ allows you to write strongly typed
26+
queries using C#-specific keywords and operators. When you run the application,
27+
the {+provider-long+} automatically translates the LINQ queries and runs them on the
28+
database using the MongoDB Query API.
29+
30+
In this guide you can see examples of common query operations on
31+
an application configured to use the {+provider-long+}.
32+
33+
.. tip::
34+
35+
To learn how to configure an application to use the {+provider-short+}, see
36+
:ref:`entity-framework-configure`.
37+
38+
Find Entities
39+
-------------
40+
41+
Find a single entity by using the ``FirstOrDefault()`` method, or find
42+
multiple entities by using the ``Where()`` method.
43+
44+
Find a Single Entity
45+
~~~~~~~~~~~~~~~~~~~~
46+
47+
The ``FirstOrDefault()`` method returns the first entity it finds in your collection that
48+
matches the search criteria, and returns ``null`` if no matching entities
49+
are found.
50+
51+
The following code uses the ``FirstOrDefault()`` method to find a planet with
52+
the ``name`` field of "Mercury" from a ``DBSet`` called ``Planets`` and prints
53+
the planet name to the console:
54+
55+
.. literalinclude:: /includes/code-examples/quick-reference.cs
56+
:start-after: // start-find-one
57+
:end-before: // end-find-one
58+
:language: csharp
59+
:dedent:
60+
61+
To learn more about the ``FirstOrDefault()`` method, see the `.NET API documentation
62+
<https://learn.microsoft.com/en-us/dotnet/api/system.linq.queryable.firstordefault?view=net-8.0>`__.
63+
64+
Find Multiple Entities
65+
~~~~~~~~~~~~~~~~~~~~~~
66+
67+
You can use the ``Where()`` method to retrieve multiple entities from your
68+
collections. ``Where()`` returns all entities that match the search
69+
criteria.
70+
71+
The following code uses the ``Where()`` method to find all planets that have the
72+
``hasRings`` field set to ``true`` and prints the planet names to the console.
73+
74+
.. literalinclude:: /includes/code-examples/quick-reference.cs
75+
:start-after: // start-find-many
76+
:end-before: // end-find-many
77+
:language: csharp
78+
:dedent:
79+
80+
To learn more about the ``Where()`` method, see the `.NET API documentation
81+
<https://learn.microsoft.com/en-us/dotnet/api/microsoft.entityframeworkcore.query.queryablemethods.where>`__.
82+
83+
Sort Entities
84+
-------------
85+
86+
Use the ``OrderBy()`` method to specify an order in which to return entities
87+
from a query. ``OrderBy()`` sorts the elements in ascending order based on a
88+
specified sort criteria.
89+
90+
The following code uses the ``OrderBy()`` method to find all planets and sort
91+
them by the value of the ``orderFromSun`` field in ascending order. It then
92+
prints the results to the console.
93+
94+
.. io-code-block::
95+
:copyable: true
96+
97+
.. input::
98+
:language: csharp
99+
100+
var planetList = db.Planets.OrderBy(p => p.orderFromSun);
101+
102+
foreach (var p in planetList)
103+
{
104+
Console.WriteLine(p.name);
105+
}
106+
107+
.. output::
108+
:language: json
109+
:visible: false
110+
111+
Mercury
112+
Venus
113+
Earth
114+
Mars
115+
Jupiter
116+
Saturn
117+
Uranus
118+
Neptune
119+
120+
To learn more about the ``OrderBy()`` method, see the `.NET API documentation
121+
<https://learn.microsoft.com/en-us/dotnet/api/system.linq.queryable.orderby>`__.
122+
123+
.. tip:: Sort in Descending Order
124+
125+
You can sort the results of a query in descending order by using the
126+
``OrderByDescending()`` method.
127+
128+
To learn more about the ``OrderByDescending()`` method, see the `.NET API documentation
129+
<https://learn.microsoft.com/en-us/dotnet/api/system.linq.queryable.orderbydescending>`__.
130+
131+
You can perform a secondary sort on your query by using the ``ThenBy()`` method. The
132+
``ThenBy()`` method sorts the results of the ``OrderBy()`` method in ascending
133+
order based on a specified sort criteria. The ``ThenBy()`` method should be
134+
chained to the ``OrderBy()`` method.
135+
136+
.. tip:: Secondary Sort in Descending Order
137+
138+
You can perform a secondary sort in descending order by using the
139+
``ThenByDescending()`` method.
140+
141+
To learn more about the ``ThenByDescending()`` method, see the `.NET API documentation
142+
<https://learn.microsoft.com/en-us/dotnet/api/system.linq.queryable.thenbydescending>`__.
143+
144+
The following code uses the ``OrderBy()`` and ``ThenBy()`` methods to find all
145+
planets and sort them by the ``hasRings()`` field, with a secondary sort
146+
on the ``name`` field.
147+
148+
.. io-code-block::
149+
:copyable: true
150+
151+
.. input::
152+
:language: csharp
153+
154+
var planetList = db.Planets.OrderBy(o => o.hasRings).ThenBy(o => o.name);
155+
156+
foreach (var p in planetList)
157+
{
158+
Console.WriteLine("Has rings: " + p.hasRings + ", Name: " + p.name);
159+
}
160+
161+
.. output::
162+
:language: json
163+
:visible: false
164+
165+
Has rings: False, Name: Earth
166+
Has rings: False, Name: Mars
167+
Has rings: False, Name: Mercury
168+
Has rings: False, Name: Venus
169+
Has rings: True, Name: Jupiter
170+
Has rings: True, Name: Neptune
171+
Has rings: True, Name: Saturn
172+
Has rings: True, Name: Uranus
173+
174+
.. tip::
175+
176+
When sorting on fields with a boolean value, entities with a field value of
177+
``false`` show before those with a value of ``true``.
178+
179+
To learn more about the ``ThenBy()`` method, see the `.NET API documentation
180+
<https://learn.microsoft.com/en-us/dotnet/api/system.linq.queryable.thenby>`__.

‎source/includes/code-examples/quick-reference.cs

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ void FindOne()
2020
void FindMultiple()
2121
{
2222
// start-find-many
23-
var planets = db.Planets.Where(p => p.hasRings).ToList();
23+
var planets = db.Planets.Where(p => p.hasRings);
2424

2525
foreach (var p in planets)
2626
{
@@ -99,7 +99,7 @@ void DeleteMany()
9999
void OrderByExample()
100100
{
101101
// start-order-by
102-
var planetList = db.Planets.OrderBy(p => p.orderFromSun).ToList();
102+
var planetList = db.Planets.OrderBy(p => p.orderFromSun);
103103

104104
foreach (var p in planetList)
105105
{
@@ -111,7 +111,7 @@ void OrderByExample()
111111
void DoubleOrderBy()
112112
{
113113
// start-order-by-then-by
114-
var planetList = db.Planets.OrderBy(o => o.hasRings).ThenBy(o => o.name).ToList();
114+
var planetList = db.Planets.OrderBy(o => o.hasRings).ThenBy(o => o.name);
115115

116116
foreach (var p in planetList)
117117
{
@@ -123,7 +123,7 @@ void DoubleOrderBy()
123123
void TakeExample()
124124
{
125125
// start-take
126-
var planetList = db.Planets.Take(3).ToList();
126+
var planetList = db.Planets.Take(3);
127127

128128
foreach (var p in planetList)
129129
{
@@ -135,7 +135,7 @@ void TakeExample()
135135
void SkipExample()
136136
{
137137
// start-skip
138-
var planetList = db.Planets.OrderBy(p => p.orderFromSun).Skip(5).ToList();
138+
var planetList = db.Planets.OrderBy(p => p.orderFromSun).Skip(5);
139139

140140
foreach (var p in planetList)
141141
{

‎source/quick-reference.txt

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ their related API documentation.
6363
.. input::
6464
:language: csharp
6565

66-
var planets = db.Planets.Where(p => p.hasRings == true).ToList();
66+
var planets = db.Planets.Where(p => p.hasRings == true);
6767

6868
foreach (var p in planets)
6969
{
@@ -149,7 +149,7 @@ their related API documentation.
149149
.. input::
150150
:language: csharp
151151

152-
var planetList = db.Planets.OrderBy(p => p.orderFromSun).ToList();
152+
var planetList = db.Planets.OrderBy(p => p.orderFromSun);
153153

154154
foreach (var p in planetList)
155155
{
@@ -179,7 +179,7 @@ their related API documentation.
179179
.. input::
180180
:language: csharp
181181

182-
var planetList = db.Planets.OrderBy(o => o.hasRings).ThenBy(o => o.name).ToList();
182+
var planetList = db.Planets.OrderBy(o => o.hasRings).ThenBy(o => o.name);
183183

184184
foreach (var p in planetList)
185185
{
@@ -210,7 +210,7 @@ their related API documentation.
210210
.. input::
211211
:language: csharp
212212

213-
var planetList = db.Planets.Take(3).ToList();
213+
var planetList = db.Planets.Take(3);
214214

215215
foreach (var p in planetList)
216216
{
@@ -235,7 +235,7 @@ their related API documentation.
235235
.. input::
236236
:language: csharp
237237

238-
var planetList = db.Planets.OrderBy(p => p.orderFromSun).Skip(5).ToList();
238+
var planetList = db.Planets.OrderBy(p => p.orderFromSun).Skip(5);
239239

240240
foreach (var p in planetList)
241241
{

0 commit comments

Comments
 (0)