Ergebnisse mithilfe von FetchXml auslagern
Sie können eine Grenze für die Anzahl der für jede Anfrage abgerufenen Zeilen festlegen, indem Sie eine Seitengröße festlegen. Mithilfe der Auslagerung können Sie aufeinanderfolgende Datenseiten abrufen, die alle Datensätze darstellen, die den Kriterien einer Abfrage entsprechen, und zwar auf leistungsstarke Weise.
Die standardmäßige und maximale Seitengröße beträgt 5.000 Zeilen. Wenn Sie keine Seitengröße festlegen, gibt Dataverse bis zu 5.000 Datenzeilen gleichzeitig zurück. Um mehr Zeilen zu erhalten, müssen Sie zusätzliche Anfragen senden.
Hinweis
- Verwenden Sie das Attribut Fetch-Element
top
nicht mit der Auslagerung. Diese verschiedenen Methoden zur Einschränkung der Ergebnisse einer Abfrage sind nicht kompatibel. - Die Reihenfolge spielt eine wichtige Rolle für konsistente Auslagerungsergebnisse. Weitere Informationen zur Reihenfolge und Auslagerung
Auslagerungsmodelle
Dataverse verfügt über zwei Auslagerungsmodelle: einfach und unter Verwendung von Auslagerungs-Cookies:
Einfach
- Verwendet nur die Attribute Fetch-Element
count
undpage
- Nur für kleine Datasets geeignet
- Es kann kein Dataset zurückgegeben werden, das größer als 50.000 Datensätze ist
- Die Leistung nimmt mit zunehmender Zeilenanzahl ab
Auslagerungs-Cookies
- Verwendet die Attribute Fetch-Element,
count
,page
undpaging-cookie
- Legen Sie den Attributwert
paging-cookie
auf den Wert fest, der auf der vorherigen Seite zurückgegeben wurde - Empfohlen für alle Dataset-Größen
- Einige Abfragen erlauben keine Auslagerungs-Cookies
- Weitere Informationen zur Verwendung von Auslagerungs-Cookies
Einfache Auslagerung
Sie können die erste Seite anfordern, indem Sie das Attribut Fetch-Element page
auf 1 und das Attribut count
auf die Seitengröße setzen, bevor Sie die Anforderung senden:
<fetch count='3' page='1'>
<entity name='account'>
<attribute name='name' />
<order attribute='name' />
<order attribute='accountid' />
</entity>
</fetch>
Um die nächsten drei Datensätze zu erhalten, erhöhen Sie den Wert page
und senden Sie eine weitere Anforderung.
<fetch count='3' page='2'>
<entity name='account'>
<attribute name='name' />
<order attribute='name' />
<order attribute='accountid' />
</entity>
</fetch>
Mit einer einfachen Auslagerung, manchmal auch als Legacy-Auslagerung bezeichnet, ruft Dataverse alle Ergebnisse der Abfrage bis zur aktuellen Seite ab, wählt die Anzahl der Datensätze aus, die für die Seite benötigt werden, und ignoriert dann den Rest. Dies ermöglicht ein schnelles Vor- und Zurückblättern der Daten oder das Springen zu einer bestimmten Seite. Allerdings ist die Gesamtzahl der Datensätze auf 50.000 begrenzt und es kann zu Leistungsproblemen bei komplexen Abfragen und willkürlich sortierten unterschiedlichen Abfrageergebnissen kommen.
Die einfache Auslagerung eignet sich gut für kleine Dataset, aber wenn die Anzahl der Zeilen im Dataset zunimmt, leidet die Leistung. Die Gesamtzahl der Zeilen, die mit der einfachen Auslagerung abgerufen werden können, beträgt 50.000. Für eine optimale Leistung empfehlen wir in jedem Fall die konsequente Verwendung von Auslagerungs-Cookies.
Auslagerungs-Cookies
Wenn nach der Anforderung der ersten Seite weitere Zeilen abzurufen sind, gibt Dataverse normalerweise ein Auslagerungs-Cookie zurück, das bei den folgenden Anforderungen für die nächsten Seiten verwendet wird.
Das Auslagerungs-Cookie enthält Daten zum ersten und letzten Datensatz in den Ergebnissen und hilft Dataverse dabei, die nächste Datenzeile so schnell wie möglich abzurufen und sollte verwendet werden, wenn es bereitgestellt wird. Sie sollten die Daten im Auslagerungs-Cookie nicht ändern, sondern einfach den Wert auf das Attribut Fetch-Element paging-cookie
festlegen und den Attributwert page
für nachfolgende Anforderungen erhöhen.
Abfragen, die keine Auslagerungs-Cookies unterstützen
Einige Abfragen unterstützen keine Auslagerungs-Cookies. Wenn Auslagerungs-Cookies von einer Abfrage nicht unterstützt werden, wird mit dem Ergebnis kein Auslagerungs-Cookie-Wert zurückgegeben. Beispielsweise unterstützen Abfragen, die nach einem link-entity
-Attribut sortiert wurden, möglicherweise keine Auslagerungs-Cookies.
Wenn Dataverse kein Auslagerungs-Cookie zurückgibt, greift das Auslagerungsmodell auf eine einfache Auslagerungs zurück, mit allen damit verbundenen Einschränkungen.
Beispiele für Auslagerungs-Cookies
Wie Sie Auslagerungs-Cookies verwenden, hängt davon ab, ob Sie das SDK für .NET oder die Web-API verwenden.
Die folgende statische RetrieveAll
-Methode gibt alle Datensätze zurück, die mit der FetchXml-Abfrage übereinstimmen, und sendet mehrere Anforderungen, wenn die Anzahl der Datensätze die Seitengröße überschreitet.
Nach jeder Anforderung überprüft die Methode die EntityCollection.MoreRecords-Eigenschaft, um festzustellen, ob weitere Datensätze den Kriterien entsprechen. Wenn mehr Datensätze vorhanden sind, legt die Methode den Wert der zurückgegebenen EntityCollection.PagingCookie-Eigenschaft auf das paging-cookie
-Attribut des Fetch-Elements fest und sendet eine weitere Anforderung.
/// <summary>
/// Returns all records matching the criteria
/// </summary>
/// <param name="service">The authenticated IOrganizationService instance.</param>
/// <param name="fetchXml">The fetchXml Query string</param>
/// <param name="pageSize">The page size to use. Default is 5000</param>
/// <returns>All the records that match the criteria</returns>
static EntityCollection RetrieveAll(IOrganizationService service, string fetchXml, int pageSize = 5000)
{
// The records to return
List<Entity> entities = new();
XElement fetchNode = XElement.Parse(fetchXml);
int page = 1; //Start with page 1
//Set the page
fetchNode.SetAttributeValue("page", page);
// Set the page size
fetchNode.SetAttributeValue("count", pageSize);
while (true)
{
// Get the page
EntityCollection results = service.RetrieveMultiple(new FetchExpression(fetchNode.ToString()));
entities.AddRange(results.Entities);
if (!results.MoreRecords)
{
break;
}
// Set the fetch paging-cookie attribute with the paging cookie from the previous query
fetchNode.SetAttributeValue("paging-cookie", results.PagingCookie);
fetchNode.SetAttributeValue("page", page++);
}
return new EntityCollection(entities);
}
Sie können das Beispiel Schnellstart: Eine SDK für .NET-Anforderung ausführen (C#) zum Testen von FetchXml-Abfragen mit den folgenden Schritten anpassen:
- Fügen Sie die statische
RetrieveAll
-Methode zurProgram
-Klasse hinzu. - Ändern Sie die
Main
-Methode wie unten gezeigt:
static void Main(string[] args)
{
using (ServiceClient serviceClient = new(connectionString))
{
if (serviceClient.IsReady)
{
//WhoAmIResponse response =
// (WhoAmIResponse)serviceClient.Execute(new WhoAmIRequest());
//Console.WriteLine("User ID is {0}.", response.UserId);
string fetchQuery = @"<fetch count='3' page='1'>
<entity name='contact'>
<attribute name='fullname'/>
<attribute name='jobtitle'/>
<attribute name='annualincome'/>
<order descending='true' attribute='fullname'/>
</entity>
</fetch>";
EntityCollection records = RetrieveAll(service: serviceClient,
fetchXml: fetchQuery,
pageSize: 25);
Console.WriteLine($"Success: {records.Entities.Count}");
}
else
{
Console.WriteLine(
"A web service connection was not established.");
}
}
// Pause the console so it does not close.
Console.WriteLine("Press the <Enter> key to exit.");
Console.ReadLine();
}
Wichtig
Diese Abfrage gibt ALLE Datensätze zurück, die den Kriterien entsprechen. Stellen Sie sicher, dass Sie Filterelemente einschließen, um die Ergebnisse einzuschränken.
Ordering and paging
How a page is ordered makes a big difference when paging data. If the information about how the results are ordered is ambiguous, Dataverse can't consistently or efficiently return paged data.
Specify an order for your query. With FetchXml, if you don't add any order elements to your query, Dataverse adds an order based on the primary key of the table. However QueryExpression does not, and when your query specifies distinct
results, no primary key values are returned, so Dataverse can't add this default order. You must specify a paging order. Without any order specified, distinct
query results might be returned in random order. OData doesn't provide any option to return distinct results, but you should still apply an order when retrieving paged results.
Paging is dynamic. Each request is evaluated independently as they're received. A paging cookie tells Dataverse the previous page. With this paging cookie data, Dataverse can start with the next record after the last one on the preceding page.
Paging works best going forward. If you go back and retrieve a page you previously retrieved, the results can be different because records could be added, deleted, or modified during since you last retrieved the page. In other words, if your page size is 50 and you go back, you get 50 records, but they might not be the same 50 records. If you keep progressing forward through the pages of a data set, you can expect all the records are returned in a consistent sequence.
Deterministic ordering is important
Deterministic ordering means that there's a way to calculate an order consistently. With a given set of records, the records are always returned in the same order. If you need consistent orders and paging, you must include some unique values or combination of column values that are and specify an order for them to be evaluated.
Nondeterministic example
Let's look at an example that is nondeterministic. This data set contains only State and Status information and is filtered to only return records in an open State. The results are ordered by Status. The first three pages are requested. The results look like this:
State | Status | Page |
---|---|---|
Open | Active | 1 Start |
Open | Active | 1 |
Open | Active | 1 End |
Open | Active | |
Open | Active | |
Open | Inactive | |
Open | Inactive |
The paging cookie saves information about the last record on the page. When the next page is requested, the last record from the first page isn't included. However, given the nondeterministic data, there's no guarantee that the other two records on the first page aren't included in the second page.
To achieve deterministic ordering, add orders on columns that contain unique values, or values that are semi-unique.
Deterministic example
This query is like the nondeterministic one, but it includes the Case ID column that includes unique values. It's also ordered by Status, but also ordered using Case ID. The results look like this:
State | Status | Case ID | Page |
---|---|---|---|
Open | Active | Case-0010 | 1 Start |
Open | Active | Case-0021 | 1 |
Open | Active | Case-0032 | 1 End |
Open | Active | Case-0034 | |
Open | Active | Case-0070 | |
Open | Inactive | Case-0015 | |
Open | Inactive | Case-0047 |
In the next page, the cookie will have Case-0032
stored as the last record in the first page, so page two will start with the next record after that record. The results look like this:
State | Status | Case ID | Page |
---|---|---|---|
Open | Active | Case-0010 | 1 Start |
Open | Active | Case-0021 | 1 |
Open | Active | Case-0032 | 1 End |
Open | Active | Case-0034 | 2 Start |
Open | Active | Case-0070 | 2 |
Open | Inactive | Case-0015 | 2 End |
Open | Inactive | Case-0047 |
Because this query orders unique column values, the order is consistent.
Best practices for orders when paging data
Hinweis
When possible, queries should order on the primary key for the table because Dataverse is optimized for ordering on the primary key by default. Ordering by non-unique or complex fields cause excess overhead and slower queries.
When you retrieve a limited set of data to display in an application, or if you need to return more than 5,000 rows of data, you need to page the results. The choices you make in determining the order of the results can determine whether the rows in each page of data you retrieve overlaps with other pages. Without proper ordering, the same record can appear in more than one page.
To prevent the same record from appearing in more than one page, apply the following best practices:
It's best to include a column that has a unique identifier. For example:
- Table primary key columns
- Autonumber columns
- User/contact IDs
If you can't include a column with a unique identifier, include multiple fields that will most likely result in unique combinations. For example:
- First name + last name + email address
- Full name + email address
- Email address + company name
Anti-patterns for orders when paging data
The following are ordering choices to avoid:
Orders that don't include unique identifiers
Orders on calculated fields
Orders that have single or multiple fields that aren't likely to provide uniqueness such as:
- Status and state
- Choices or Yes/No
- Name values by themselves. For example
name
,firstname
,lastname
- Text fields like titles, descriptions, and multi-line text
- Non unique number fields
Nächste Schritte,
Erfahren Sie, wie Sie Daten aggregieren können.
Hinweis
Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)
Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Tickets als Feedbackmechanismus für Inhalte auslaufen lassen und es durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter:Einreichen und Feedback anzeigen für