Paginer des résultats à l’aide de FetchXml

  • Article

Vous pouvez spécifier une limite au nombre de lignes récupérées pour chaque requête en définissant une taille de page. À l’aide de la pagination, vous pouvez récupérer des pages consécutives de données qui représentent tous les enregistrements correspondant aux critères d’une requête de manière performante.

La taille de page par défaut et maximale est de 5 000 lignes. Si vous ne définissez pas de taille de page, Dataverse renverra jusqu’à 5 000 lignes de données à la fois. Pour obtenir plus de lignes, vous devez envoyer des requêtes supplémentaires.

Notes

  • N’utilisez pas l’attribut top de l’élément fetch avec la pagination. Ces différentes méthodes de limitation des résultats d’une requête ne sont pas compatibles.
  • Le tri joue un rôle important dans l’obtention de résultats de pagination cohérents. En savoir plus sur le tri et la pagination

Modèles de pagination

Dataverse a deux modèles de pagination : simple et avec des cookies de pagination :

Simple

  • Utilise uniquement les attributs count et page de l’élément fetch
  • Convient uniquement aux petits jeux de données
  • Impossible de renvoyer un jeu de données supérieur à 50 000 enregistrements
  • Performances réduites à mesure que le nombre de lignes augmente

Cookies de pagination

Pagination simple

Vous pouvez demander la première page en définissant l’attribut page de l’élément fetch sur 1 et l’attribut count sur la taille de la page avant d’envoyer la requête :

<fetch count='3' page='1'>
  <entity name='account'>
    <attribute name='name' />
    <order attribute='name' />
    <order attribute='accountid' />
  </entity>
</fetch>

Pour obtenir les trois enregistrements suivants, incrémentez la valeur page et envoyez une autre requête.

<fetch count='3' page='2'>
  <entity name='account'>
    <attribute name='name' />
    <order attribute='name' />
    <order attribute='accountid' />    
  </entity>
</fetch>

Avec la pagination simple, parfois appelée Pagination héritée, Dataverse récupère tous les résultats de la requête jusqu’à la page actuelle, sélectionne le nombre d’enregistrements nécessaires pour la page, puis ignore le reste. Cela permet de reculer et d’avancer rapidement entre les données ou de passer à une page spécifique. Cependant, le nombre total d’enregistrements est limité à 50 000 et des problèmes de performances peuvent se produire pour les requêtes complexes et les résultats de requêtes distincts triés de manière arbitraire.

La pagination simple fonctionne bien pour les petits jeux de données, mais à mesure que le nombre de lignes dans le jeu de données augmente, les performances sont affectées. Le nombre total de lignes qui peuvent être récupérées à l’aide d’une simple pagination est de 50 000. Pour de meilleures performances dans tous les cas, nous vous recommandons d’utiliser les cookies de pagination de manière cohérente.

Cookies de pagination

Lorsqu’il y a d’autres lignes à récupérer après avoir demandé la première page, Dataverse renvoie généralement un cookie de pagination à utiliser sur les requêtes suivantes pour les pages suivantes.

Le cookie de pagination contient des données sur le premier et le dernier enregistrement dans les résultats et aide Dataverse à récupérer la ligne de données suivante le plus rapidement possible et doit être utilisé lorsqu’il est fourni. Vous ne devez pas modifier les données du cookie de pagination, définissez simplement la valeur sur l’attribut paging-cookie de l’élément fetch et incrémentez la valeur de l’attribut page pour les requêtes ultérieures.

Requêtes qui ne prennent pas en charge les cookies de pagination

Certaines requêtes ne prennent pas en charge les cookies de pagination. Lorsque les cookies de pagination ne sont pas pris en charge par une requête, aucune valeur de cookie de pagination n’est renvoyée avec le résultat. Par exemple, les requêtes triées à l’aide d’un attribut link-entity peuvent ne pas prendre en charge les cookies de pagination.

Lorsque Dataverse ne renvoie pas de cookie de pagination, le modèle de pagination revient à la pagination simple, avec toutes les limitations qui l’accompagnent.

La manière d’utiliser les cookies de pagination dépend si vous utilisez le SDK pour .NET ou l’API Web.

La méthode statique RetrieveAll suivante renverra tous les enregistrements correspondant à la requête FetchXml, en envoyant plusieurs requêtes si le nombre d’enregistrements dépasse la taille de la page.

Après chaque requête, la méthode vérifie la propriété EntityCollection.MoreRecords pour déterminer si d’autres enregistrements correspondent aux critères. S’il y a d’autres enregistrements, la méthode définit la valeur de la propriété EntityCollection.PagingCookie renvoyée sur l’attribut paging-cookie de l’élément fetch et envoie une autre requête.

/// <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);
}

Vous pouvez adapter l’exemple Démarrage rapide : exécuter une requête du SDK pour .NET (C#) pour tester les requêtes FetchXml en procédant comme suit :

  1. Ajoutez la méthode statique RetrieveAll à la classe Program.
  2. Modifiez la méthode Main comme indiqué ci-dessous :
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();
}

Important

Cette requête renverra TOUS les enregistrements correspondant aux critères. Assurez-vous d’inclure des éléments de filtre pour limiter les résultats.

Étapes suivantes

Découvrez comment agréger des données.

Agréger des données

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).