Paginar resultados mediante FetchXml

  • Artículo

Puede especificar un límite en la cantidad de filas recuperadas para cada solicitud estableciendo un tamaño de página. Al utilizar la paginación, puede recuperar páginas consecutivas de datos que representan todos los registros que coinciden con los criterios de una consulta de manera eficaz.

El tamaño de página predeterminado y máximo es 5000 filas. Si no establece un tamaño de página, Dataverse devolverá hasta 5000 filas de datos a la vez. Para obtener más filas, debe enviar solicitudes adicionales.

Nota

Modelos de paginación

Dataverse tiene dos modelos de paginación: simple y usando cookies de paginación:

Sencillo

  • Utiliza solo los atributos elemento de búsqueda count y page
  • Adecuado solo para conjuntos de datos pequeños
  • No se puede devolver un conjunto de datos de más de 50.000 registros
  • El rendimiento se reduce a medida que aumenta el número de filas

Cookies de paginación

Paginación sencilla

Puede solicitar la primera página configurando el atributo elemento de búsqueda page en 1 y el atributo count al tamaño de la página antes de enviar la solicitud:

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

Para obtener los siguientes tres registros, incremente el valor de page y envíe otra solicitud.

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

Con una paginación simple, a veces denominada paginación heredada, Dataverse recupera todos los resultados de la consulta hasta la página actual, selecciona el número de registros necesarios para la página y después ignora el resto. Esto permite retroceder y avanzar rápidamente entre los datos o saltar a una página específica. Sin embargo, el número total de registros está limitado a 50.000 y puede haber problemas de rendimiento para consultas complejas y resultados de consultas distintos ordenados arbitrariamente.

La paginación simple funciona bien para conjuntos de datos pequeños, pero a medida que aumenta el número de filas en conjunto de datos, el rendimiento se ve afectado. El número total de filas que se pueden recuperar mediante paginación simple es 50.000. Para obtener el mejor rendimiento en todos los casos, recomendamos utilizar cookies de paginación de forma constante.

Cookies de paginación

Cuando hay más filas para recuperar después de solicitar la primera página, Dataverse normalmente devuelve una cookie de paginación que se utilizará en las siguientes solicitudes para las páginas siguientes.

La cookie de paginación contiene datos sobre el primer y último registro de los resultados y ayuda a Dataverse a recuperar la siguiente fila de datos lo más rápido posible y debe usarse cuando se proporciona. No debe modificar los datos en la cookie de paginación, simplemente establezca el valor en el atributo elemento de búsqueda paging-cookie e incremente el valor del atributo page para solicitudes posteriores.

Consultas que no admiten cookies de paginación

Algunas consultas no admiten cookies de paginación. Cuando una consulta no admite cookies de paginación, no se devuelve ningún valor de cookie de paginación con el resultado. Por ejemplo, es posible que las consultas ordenadas mediante un atributo link-entity no admitan cookies de paginación.

Cuando Dataverse no devuelve una cookie de paginación, el modelo de paginación vuelve a la paginación simple, con todas las limitaciones que conlleva.

La forma de utilizar cookies de paginación depende de si utiliza el SDK para .NET o API web.

El siguiente método estático RetrieveAll devolverá todos los registros que coincidan con la consulta FetchXml y enviará múltiples solicitudes si la cantidad de registros excede el tamaño de la página.

Después de cada solicitud, el método comprueba la Propiedad EntityCollection.MoreRecords para determinar si más registros coinciden con los criterios. Si hay más registros, el método establece el valor de la Propiedad EntityCollection.PagingCookie devuelta en el atributo paging-cookie de elemento fetch y envía otra solicitud.

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

Puede adaptar el ejemploInicio rápido: ejecutar una solicitud de SDK para .NET (C#) para probar consultas FetchXml con los siguientes pasos:

  1. Agregue el método estático RetrieveAll a la clase Program.
  2. Modifique el método Main como se muestra a continuación:
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();
}

Importante

Esta consulta devolverá TODOS los registros que coincidan con los criterios. Asegúrese de incluir elementos de filtro para limitar los resultados.

Ordenación y paginación

La forma en que se ordena una página marca una gran diferencia al paginar datos. Si la información sobre cómo se ordenan los resultados es ambigua, Dataverse no puede devolver datos paginados de manera consistente o eficiente.

Especifique un pedido para su consulta. Con FetchXml, si no agrega ningún elemento de pedido a su consulta, Dataverse agrega un pedido basado en la clave principal de la tabla. Sin embargo, QueryExpression no lo hace, y cuando su consulta especifica resultados distinct, no se devuelven valores de clave principal, por lo que Dataverse no puede agregar este orden predeterminado. Debe especificar un orden de paginación. Sin ningún orden especificado, los resultados de la consulta de distinct pueden devolverse en orden aleatorio. OData no proporciona ninguna opción para devolver resultados distintos, pero aún así debes aplicar un orden al recuperar resultados paginados.

La paginación es dinámica. Cada solicitud se evalúa de forma independiente a medida que se recibe. Una cookie de paginación indica la página anterior de Dataverse. Con estos datos de cookie de paginación, Dataverse puede comenzar con el siguiente registro después del último en la página anterior.

La paginación funciona mejor en el futuro. Si regresa y recupera una página que recuperó anteriormente, los resultados pueden ser diferentes porque se podrían agregar, eliminar o modificar registros desde la última vez que recuperó la página. En otras palabras, si el tamaño de su página es 50 y regresa, obtendrá 50 registros, pero es posible que no sean los mismos 50 registros. Si continúa avanzando por las páginas de un conjunto de datos, puede esperar que todos los registros se devuelvan en una secuencia coherente.

La ordenación determinista es importante

Orden determinista significa que hay una manera de calcular un orden de manera consistente. Con un conjunto de registros determinado, los registros siempre se devuelven en el mismo orden. Si necesita pedidos y paginación consistentes, debe incluir algunos valores únicos o una combinación de valores de columna y especificar un orden para que se evalúen.

Ejemplo no determinista

Veamos un ejemplo que es nodeterminista. Este conjunto de datos contiene solo información de estado y estado y se filtra para devolver solo registros en un estado abierto. Los resultados se ordenan por estado. Se solicitan las tres primeras páginas. Los resultados tienen este aspecto:

Valor Estado Página
Apertura Activas 1 Inicio
Apertura Activas 1
Apertura Activas 1 Fin
Apertura Activas
Apertura Activas
Apertura Inactivas
Apertura Inactivas

La cookie de paginación guarda información sobre el último registro de la página. Cuando se solicita la página siguiente, no se incluye el último registro de la primera página. Sin embargo, dados los datos no deterministas, no hay garantía de que los otros dos registros de la primera página no estén incluidos en la segunda página.

Para lograr un orden determinista, agregue pedidos en columnas que contengan valores únicos o valores semiúnicos.

Ejemplo determinista

Esta consulta es como la no determinista, pero incluye la columna Id. de caso que incluye valores únicos. También se ordena por Estado y por Id. de caso. Los resultados tienen este aspecto:

Valor Estado Id. de caso Página
Apertura Activas Caso-0010 1 Inicio
Apertura Activas Caso-0021 1
Apertura Activas Caso-0032 1 Fin
Apertura Activas Caso-0034
Apertura Activas Caso-0070
Apertura Inactivas Caso-0015
Apertura Inactivas Caso-0047

En la siguiente página, la cookie tendrá el Case-0032 almacenado como el último registro en la primera página, por lo que la página dos comenzará con el siguiente registro en el conjunto después de ese registro. Los resultados tienen este aspecto:

Valor Estado Id. de caso Página
Apertura Activas Caso-0010 1 Inicio
Apertura Activas Caso-0021 1
Apertura Activas Caso-0032 1 Fin
Apertura Activas Caso-0034 2 Inicio
Apertura Activas Caso-0070 2
Apertura Inactivas Caso-0015 2 Fin
Apertura Inactivas Caso-0047

Dado que esta consulta ordena valores de columna únicos, el orden es coherente.

Procedimientos recomendados para órdenes al paginar datos

Nota

Cuando sea posible, las consultas deben ordenarse según la clave principal de la tabla porque Dataverse está optimizada para ordenar según la clave principal de forma predeterminada. Ordenar por campos no únicos o complejos genera una sobrecarga excesiva y consultas más lentas.

Cuando recupera un conjunto limitado de datos para mostrar en una aplicación, o si necesita devolver más de 5000 filas de datos, necesita paginar los resultados. Las elecciones que haga para determinar el orden de los resultados pueden determinar si las filas de cada página de datos que recupere se superponen con otras páginas. Sin un orden adecuado, el mismo registro puede aparecer en más de una página.

Para evitar que el mismo registro aparezca en más de una página, aplique los siguientes procedimientos recomendados:

Lo mejor es incluir una columna que tenga un identificador único. Por ejemplo:

  • Columnas de clave principal de tabla
  • Columnas de autonumeración
  • Id. de usuario/contacto

Si no puede incluir una columna con un identificador único, incluya varios campos que probablemente darán como resultado combinaciones únicas. Por ejemplo:

  • Nombre + apellido + dirección de correo electrónico
  • Nombre completo + dirección de correo electrónico
  • Dirección de correo electrónico + nombre de la empresa

Antipatrones para órdenes al paginar datos

Las siguientes son opciones de orden que se deben evitar:

  • Órdenes que no incluyen identificadores únicos

  • Órdenes en campos calculados

  • Órdenes que tienen campos únicos o múltiples que es poco probable que proporcionen unicidad, como:

    • Estatus y estado
    • Elecciones o Sí/No
    • Nombre los valores por sí mismos. Por ejemplo name, firstname, lastname
    • Campos de texto como títulos, descripciones y texto de varias líneas
    • Campos numéricos no únicos

Pasos siguientes

Aprenda a agregar datos.

Agregar datos

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).