Compartir vía

Visualización de resultados de página mediante FetchXML

Puede limitar el número de filas recuperadas para cada solicitud estableciendo un tamaño de página. Mediante la paginación, puede recuperar páginas consecutivas de datos para obtener de forma eficaz todos los registros que coincidan con los criterios de una consulta.

El tamaño de página predeterminado y máximo es 5000 para las tablas estándar y 500 para las tablas elásticas. Si no establece un tamaño de página, Dataverse devuelve 5000 o 500 filas de datos a la vez, según el tipo de tabla. Para obtener más filas, deberá enviar solicitudes adicionales.

Nota

Modelos de paginación de FetchXml

FetchXml tiene dos modelos de paginación: cookies sencillas y de paginación:

Sencillo

  • Utiliza solo los atributoselemento de búsquedacount y page
  • Adecuado solo para conjuntos de datos pequeños
  • No se puede devolver un conjunto de datos superior a 50 000 registros
  • El rendimiento se reduce a medida que aumenta el número de filas

Cookies de paginación

Paginación sencilla

Solicite la primera página estableciendo el atributo fetch elementpage en 1 y el count atributo en el tamaño de 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>

Mediante la 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, a continuación, omite el resto. Este método facilita la paginación hacia atrás y hacia delante a través de los datos o pasar a una página específica. Sin embargo, el número total de registros se limita a 50 000. Además, las consultas complejas y los resultados de consulta distintos ordenados arbitrariamente pueden causar problemas de rendimiento.

La paginación sencilla funciona bien para conjuntos de datos pequeños. Pero a medida que aumenta el número de filas del conjunto de datos, el rendimiento se ve afectado. El número total de filas que puede recuperar mediante la paginación simple es de 50 000. Para obtener el mejor rendimiento en todos los casos, use cookies de paginación de forma coherente.

Cookies de paginación

Cuando hay más filas que recuperar después de solicitar la primera página, Dataverse normalmente devuelve una cookie de paginación que se usará 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. Ayuda a Dataverse a recuperar la siguiente fila de datos lo antes posible. Use la cookie de paginación cuando esté disponible. No modifique los datos en la cookie de paginación. Establezca el valor en el atributo elemento fetchpaging-cookie e incremente el valor del page atributo para las 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, la consulta no devuelve un valor de cookie de paginación con el resultado. Por ejemplo, las consultas ordenadas mediante un link-entity atributo podrían no admitir 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 usar cookies de paginación depende de si usa el SDK para .NET o la API web.

El siguiente RetrieveAll método estático devuelve todos los registros que coinciden con la consulta FetchXML. Envía varias solicitudes si el número de registros supera el tamaño de página.

Después de cada solicitud, el método comprueba la propiedad EntityCollection.MoreRecords para ver 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 5,000</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);
}

Para probar las consultas FetchXML, adapte el ejemplo en Inicio rápido: Ejecute un SDK para la solicitud de .NET (C#) mediante los pasos siguientes:

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

Nota

Esta consulta devuelve todos los registros que coinciden con los criterios. Asegúrese de incluir elementos de filtro para limitar los resultados.

Lea la siguiente información importante sobre el uso de una cadena de conexión en el código de la aplicación.

Importante

Microsoft recomienda utilizar el flujo de autenticación más seguro disponible. El flujo de autenticación descrito en este artículo requiere un alto grado de confianza en la aplicación y conlleva riesgos que no están presentes en otros flujos. Solo debe usar este flujo cuando otros flujos más seguros, como las identidades administradas, no sean viables.

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 informa a Dataverse sobre la página anterior. 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 a medida que se avanza. 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 tu página es 50 y vuelves, obtendrás 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 órdenes y paginación consistentes, debe incluir algunos valores únicos o una combinación de valores de columna y especificar un orden para ser evaluados.

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:

Estado Estado Página
Abrir Activa 1 Inicio
Abrir Activo 1
Abrir Activo 1 Fin
Abrir Activo
Abrir Activo
Abrir Inactivas
Abrir 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 orden en columnas que contengan valores únicos o semiómnicos.

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, además de por Id. de caso. Los resultados tienen este aspecto:

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

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

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

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

Prácticas recomendadas para pedidos 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 recupere un conjunto limitado de datos para mostrarlos en una aplicación, o si necesita devolver más de 5000 filas de datos (500 para tablas elásticas), debe 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 numeración automática
  • 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 la ordenación al paginar datos

Las siguientes son opciones de orden que se deben evitar:

  • Órdenes que no incluyen identificadores únicos

  • Ordenación 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
    • Asigne nombre a los valores en 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

  • Last updated on