Freigeben über

Paging von Ergebnissen mit QueryExpression

  • Artikel

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

Auslagerungsmodelle

Dataverse verfügt über zwei Auslagerungsmodelle: einfach und unter Verwendung von Auslagerungs-Cookies:

Einfach

  • Verwendet nur die Eigenschaften QueryExpression.PageInfo Count und PageNumber
  • 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

Einfache Auslagerung

Sie können die erste Seite anfordern, indem Sie vor dem Senden der Anforderung die QueryExpression.PageInfo-Eigenschaft mit einer Instanz der PagingInfo-Klasse mit PagingInfo.PageNumber auf 1 und die PagingInfo.Count auf die Seitengröße festlegen:

var query = new QueryExpression(entityName: "account")
{
      ColumnSet = new ColumnSet("name"),
      PageInfo = new PagingInfo() { 
         Count = 3,
         PageNumber = 1
      }
};
query.AddOrder(attributeName:"name",orderType: OrderType.Ascending);
query.AddOrder(attributeName: "accountid", orderType: OrderType.Ascending);

Um die nächsten drei Datensätze zu erhalten, erhöhen Sie den Wert PageInfo.PageNumber und senden Sie eine weitere Anforderung.

query.PageInfo.PageNumber++;

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. 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 Paging-Cookie enthält Daten über den ersten und letzten Datensatz in den Ergebnissen und hilft Dataverse, die nächste Datenzeile so schnell wie möglich abzurufen. Bei der Rückgabe von der vorherigen Seite sollte ein Paging-Cookie verwendet werden. Sie sollten die Daten im Paging-Cookie nicht ändern, sondern nur den Wert auf die Eigenschaft QueryExpression.PageInfo.PagingCookie festlegen und den QueryExpression.PageInfo.PageNumber-Wert für nachfolgende Anforderungen schrittweise 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 mithilfe einer LinkEntity-Spalte sortiert wurden, möglicherweise keine Paging-Cookies.

Wenn Dataverse kein Auslagerungs-Cookie zurückgibt, greift das Auslagerungsmodell auf eine einfache Auslagerungs zurück, mit allen damit verbundenen Einschränkungen.

Die folgende statische RetrieveAll-Methode gibt alle Datensätze zurück, die der QueryExpression-Abfrage entsprechen, 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 weitere Datensätze vorhanden sind, setzt die Methode den Wert der zurückgegebenen EntityCollection.PagingCookie-Eigenschaft auf die PageInfo.PagingCookie-Eigenschaft von QueryExpression und sendet eine weitere Anforderung.

/// <summary>
/// Returns all records matching the criteria
/// </summary>
/// <param name="service">The authenticated IOrganizationService instance.</param>
/// <param name="query">The QueryExpression query</param>
/// <param name="page">The page size to use. Defaults to 5000</param>
/// <returns>All the records that match the criteria</returns>
static EntityCollection RetrieveAll(IOrganizationService service, 
QueryExpression query,
int page = 5000)
{
    // The records to return
    List<Entity> entities = new();

    // Set the page
    query.PageInfo.PageNumber = 1;
    // Set the count
    query.PageInfo.Count = page;

    while (true)
    {
        // Get the records
        EntityCollection results = service.RetrieveMultiple(query);

        entities.AddRange(results.Entities);

        if (!results.MoreRecords)
        {
            //Stop if there are no more records
            break;
        }
        // Set the PagingCookie with the PagingCookie from the previous query
        query.PageInfo.PagingCookie = results.PagingCookie;

        // Update the PageNumber
        query.PageInfo.PageNumber++;
    }

    return new EntityCollection(entities);
}

Sie können das Beispiel Schnellstart: Eine SDK für .NET-Anforderung ausführen (C#) zum Testen von QueryExpression-Abfragen mit den folgenden Schritten anpassen:

  1. Fügen Sie die statische RetrieveAll-Methode zur Program-Klasse hinzu.
  2. Ä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);

            QueryExpression query = new("contact")
            {
                ColumnSet = new ColumnSet("fullname", "jobtitle", "annualincome"),
                Orders = {
                    { 
                        new OrderExpression(
                            attributeName: "fullname", 
                            orderType: OrderType.Descending) 
                    }
                }
            };

            EntityCollection records = RetrieveAll(service: serviceClient,
                        query: query)

            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.

Anordnung und Auslagerung

Die Reihenfolge einer Seite macht beim Auslagern von Daten einen großen Unterschied. Wenn die Informationen zur Reihenfolge der Ergebnisse nicht eindeutig sind, kann Dataverse ausgelagerte Daten nicht konsistent oder effizient zurückgeben.

Geben Sie eine Reihenfolge für Ihre Abfrage an. Wenn Sie bei FetchXml Ihrer Abfrage keine Sortierelemente hinzufügen, fügt Dataverse eine Sortierung basierend auf dem Primärschlüssel der Tabelle hinzu. Dies ist bei QueryExpression jedoch nicht der Fall. Wenn Ihre Abfrage distinct-Ergebnisse angibt, werden außerdem keine Primärschlüsselwerte zurückgegeben, weshalb Dataverse diese Standardreihenfolge nicht hinzufügen kann. Sie müssen eine Auslagerungsreihenfolge angeben. Ohne Angabe einer Reihenfolge werden distinct-Abfrageergebnisse möglicherweise in zufälliger Reihenfolge zurückgegeben. OData bietet keine Option zum Zurückgeben unterschiedlicher Ergebnisse. Sie sollten beim Abrufen ausgelagerter Ergebnisse jedoch trotzdem eine Reihenfolge anwenden.

Die Auslagerung ist dynamisch. Jede Anforderung wird bei Eingang einzeln bewertet. Ein Auslagerungs-Cookie teilt Dataverse die vorherige Seite mit. Mit diesen Auslagerungs-Cookie-Daten kann Dataverse mit dem nächsten Datensatz nach dem letzten auf der vorherigen Seite beginnen.

Die Auslagerung funktioniert zukünftig am besten. Wenn Sie zurückgehen und eine Seite abrufen, die Sie zuvor abgerufen haben, können die Ergebnisse unterschiedlich sein, da seit dem letzten Abruf der Seite Datensätze hinzugefügt, gelöscht oder geändert werden konnten. Mit anderen Worten: Wenn Ihre Seitengröße 50 beträgt und Sie zurückgehen, erhalten Sie 50 Datensätze, es handelt sich jedoch möglicherweise nicht um dieselben 50 Datensätze. Wenn Sie die Seiten eines Dataset weiter durchgehen, können Sie davon ausgehen, dass alle Datensätze in einer konsistenten Reihenfolge zurückgegeben werden.

Die deterministische Sortierung ist wichtig

Deterministische Reihenfolge bedeutet, dass es eine Möglichkeit gibt, eine Reihenfolge konsistent zu berechnen. Bei einem bestimmten Datensatzsatz werden die Datensätze immer in derselben Reihenfolge zurückgegeben. Wenn Sie eine einheitliche Reihenfolge und ein Paging benötigen, müssen Sie einige eindeutige Werte oder Kombinationen aus Spaltenwerten einschließen und eine Reihenfolge angeben, in der sie ausgewertet werden sollen.

Nichtdeterministisches Beispiel

Schauen wir uns ein Beispiel an, das nichtdeterministisch ist. Dieses Dataset enthält nur Status und Status-Informationen und ist gefiltert, um nur Datensätze in einem offenen Status zurückzugeben. Die Ergebnisse sind nach Status geordnet. Die ersten drei Seiten werden angefordert. Die Ergebnisse sehen folgendermaßen aus:

Bundesstaat Status Seite
Eröffnung Aktiv 1 Start
Eröffnung Aktiv 1
Eröffnung Aktiv 1 Ende
Eröffnung Aktiv
Eröffnung Aktiv
Eröffnung Inaktiv
Eröffnung Inaktiv

Das Auslagerungs-Cookie speichert Informationen über den letzten Datensatz auf der Seite. Wenn die nächste Seite angefordert wird, ist der letzte Datensatz der ersten Seite nicht enthalten. Aufgrund der nichtdeterministischen Daten gibt es jedoch keine Garantie dafür, dass die beiden anderen Datensätze auf der ersten Seite nicht auf der zweiten Seite enthalten sind.

Um eine deterministische Reihenfolge zu erreichen, fügen Sie Reihenfolgen für Spalten hinzu, die eindeutige oder halbeindeutige Werte enthalten.

Deterministisches Beispiel

Diese Abfrage ähnelt der nichtdeterministischen Abfrage, enthält jedoch die Spalte Fall-ID, die eindeutige Werte enthält. Es wird auch nach Status, aber auch nach Fall-ID sortiert. Die Ergebnisse sehen folgendermaßen aus:

Bundesstaat Status Fall-ID Seite
Eröffnung Aktiv Case-0010 1 Start
Eröffnung Aktiv Case-0021 1
Eröffnung Aktiv Case-0032 1 Ende
Eröffnung Aktiv Case-0034
Eröffnung Aktiv Case-0070
Eröffnung Inaktiv Case-0015
Eröffnung Inaktiv Case-0047

Auf der nächsten Seite hat das Cookie Case-0032 als letzten Datensatz auf der ersten Seite gespeichert, sodass Seite zwei mit dem nächsten Datensatz nach diesem Datensatz startet. Die Ergebnisse sehen folgendermaßen aus:

Bundesstaat Status Fall-ID Seite
Eröffnung Aktiv Case-0010 1 Start
Eröffnung Aktiv Case-0021 1
Eröffnung Aktiv Case-0032 1 Ende
Eröffnung Aktiv Case-0034 2 Start
Eröffnung Aktiv Case-0070 2
Eröffnung Inaktiv Case-0015 2 Ende
Eröffnung Inaktiv Case-0047

Da diese Abfrage eindeutige Spaltenwerte anordnet, ist die Reihenfolge konsistent.

Best Practices für Reihenfolgen beim Auslagern von Daten

Hinweis

Wenn möglich, sollten Abfragen nach dem Primärschlüssel für die Tabelle sortiert werden, da Dataverse standardmäßig für die Sortierung nach dem Primärschlüssel optimiert ist. Die Sortierung nach nicht eindeutigen oder komplexen Feldern führt zu übermäßigem Overhead und langsameren Abfragen.

Wenn Sie einen begrenzten Satz von Daten zur Anzeige in einer Anwendung abrufen oder mehr als 5.000 Datenzeilen zurückgeben müssen, müssen Sie die Ergebnisse auslagern. Die Auswahl, die Sie bei der Bestimmung der Reihenfolge der Ergebnisse treffen, kann bestimmen, ob sich die Zeilen auf jeder von Ihnen abgerufenen Datenseite mit anderen Seiten überschneiden. Ohne die richtige Reihenfolge kann derselbe Datensatz auf mehr als einer Seite erscheinen.

Um zu verhindern, dass derselbe Datensatz auf mehr als einer Seite erscheint, wenden Sie die folgenden Best Practices an:

Am besten fügen Sie eine Spalte mit einem eindeutigen Bezeichner ein. Zum Beispiel:

  • Spalten für Primärschlüssel der Tabellen
  • AutoWert-Spalten
  • Benutzer-/Kontakt-IDs

Wenn Sie keine Spalte mit einem eindeutigen Bezeichner einschließen können, schließen Sie mehrere Felder ein, die höchstwahrscheinlich zu eindeutigen Kombinationen führen. Zum Beispiel:

  • Vorname + Nachname + E-Mail-Adresse
  • Vollständiger Name + E-Mail-Adresse
  • E-Mail-Adresse + Firmenname

Anti-Muster für Reihenfolgen beim Auslagern von Daten

Die folgenden Auswahlmöglichkeiten für die Sortierung sollten Sie vermeiden:

  • Sortierungen ohne eindeutige Bezeichner

  • Sortierungen in berechneten Feldern

  • Sortierungen mit einzelnen oder mehreren Feldern, die wahrscheinlich keine Eindeutigkeit bieten, wie:

    • Status und Zustand
    • Auswahlmöglichkeiten oder Ja/Nein
    • Namenswerte allein. Zum Beispiel name, firstname, lastname
    • Textfelder wie Titel, Beschreibungen und mehrzeiliger Text
    • Nicht eindeutige Nummernfelder

Nächste Schritte,

Erfahren Sie, wie Sie Daten aggregieren können.

Aggregatdaten

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).