Acerca de las consultas de búsqueda rápida

Artículo
03/14/2024

Las aplicaciones basadas en modelos brindan experiencias para encontrar registros rápidamente usando la búsqueda de búsqueda rápida o la Búsqueda de cuadrícula. Con estas experiencias, los usuarios tienen una única entrada de texto que se puede aplicar a varias columnas en una sola tabla.

Las aplicaciones basadas en modelos también proporcionan un cuadro de búsqueda que utiliza la API de búsqueda de Dataverse cuando la búsqueda de Dataverse está habilitada. Con la búsqueda de Dataverse, los resultados pueden incluir resultados de varias tablas para una capacidad de búsqueda más relevante. Cuando la búsqueda de Dataverse no está habilitada, las aplicaciones basadas en modelos proporcionan una experiencia de búsqueda rápida de tabla múltiple (búsqueda categorizada) que combina resultados de hasta 10 consultas de búsqueda rápida. Más información sobre las opciones de búsqueda disponibles para aplicaciones basadas en modelo.

Nota

Es posible que las consultas de búsqueda rápida no proporcionen experiencias utilizables para todas las situaciones. Consulte Limitaciones

Considere usar la API de búsqueda de Dataverse en lugar de consultas de búsqueda rápida para los siguientes escenarios:

¿Qué es una consulta de búsqueda rápida?

Las consultas de búsqueda rápida utilizan el siguiente patrón:

Incluyen un único filtro que utiliza un operador de filtro 'OR'.
- Con FetchXml, el atributo de elemento de filtro type se establece en 'or'.
- Con QueryExpression, FilterExpression.FilterOperator se establece en LogicalOperator.Or.
Puede agregar filtros adicionales, pero se evaluarán solo después de que se procesen los resultados del filtro de búsqueda rápida.
El filtro 'OR' está marcado como filtro de búsqueda rápida:
- Con FetchXml, el atributo de elemento de filtro isquickfindfields se establece en '1'.
- Con QueryExpression, FilterExpression.IsQuickFindFilter está configurado en true.
El filtro tiene más de una condición. Cuando solo se evalúa una condición, la consulta tendrá un mejor rendimiento cuando se procese como una consulta normal.
Todas las condiciones dentro del filtro utilizan el operador 'Como':
- Con FetchXml, el atributo elemento de condición operator se establece en 'like'.
- Con QueryExpression, ConditionExpression.Operator usa ConditionOperator.Like.
El operador 'como' requiere una cadena de búsqueda que termine con %.

Nota

El operador 'como' es el único operador admitido para consultas de búsqueda rápida. Es el único operador necesario para los escenarios de aplicación para los que están diseñadas las consultas de búsqueda rápida. Otros operadores no se han probado.

Ejemplos

La forma de escribir una consulta de búsqueda rápida depende de si está utilizando QueryExpression o FetchXml.

Cada uno de los ejemplos de las pestañas siguientes hace lo mismo:

Aceptar un único parámetro de cadena de búsqueda. Podría ser un nombre parcial, un número de teléfono, una dirección de correo electrónico o un número de cuenta.
Cree una consulta de búsqueda rápida que pruebe la cadena de búsqueda con las siguientes columnas de la tabla de cuentas:
- telephone2
- telephone1
- emailaddress1
- accountnumber
- name
Filtra cuentas que no están activas.
Ordena los resultados por nombre de cuenta.

QueryExpression
FetchXml

Puede utilizar QueryExpression con el SDK de Dataverse para .NET.

/// <summary>
/// Returns active accounts using quick find filter
/// </summary>
/// <param name="service">The authenticated IOrganizationService instance to use.</param>
/// <param name="searchString">The string to search for</param>
/// <returns>Collection of matching account records</returns>
static EntityCollection QuickFindActiveAccountsQueryExpression(
    IOrganizationService service, 
    string searchString)
{
    // Wildcard required for ConditionOperator.Like
    if (!searchString.EndsWith('%'))
    {
        searchString += '%';
    }

    QueryExpression query = new("account")
    {
        ColumnSet = new("accountid",
                        "name",
                        "accountnumber",
                        "primarycontactid",
                        "address1_city",
                        "telephone1",
                        "emailaddress1"),
        Criteria = new()
        {
            Filters =
            {
                new (LogicalOperator.Or)
                {    
                    // Specify Quick find filter
                    IsQuickFindFilter = true,
                    Conditions =
                    {
                        { new (attributeName: "telephone2", 
                            ConditionOperator.Like, 
                            value: searchString) },
                        { new (attributeName: "telephone1", 
                            ConditionOperator.Like, 
                            value: searchString) },
                        { new (attributeName: "emailaddress1", 
                            ConditionOperator.Like, 
                            value: searchString) },
                        { new (attributeName: "accountnumber", 
                            ConditionOperator.Like,
                            value: searchString) },
                        { new (attributeName: "name", 
                            ConditionOperator.Like,
                            value: searchString) }
                    }
                },
                // Condition to be evaluated after Quick find filter
                new (LogicalOperator.And)
                {
                     Conditions =
                    {
                        {new(attributeName:"statecode",
                            ConditionOperator.Equal, 
                            value: 0)}
                    }
                }
            }
        },
        Orders = {
            {
                new(attributeName: "name", 
                    orderType: OrderType.Ascending)
            }
        }
    };

    return service.RetrieveMultiple(query);
}

Puede usar FetchXml con el SDK de Dataverse para .NET o la API web de Dataverse.

Con el SDK para .NET, este método QuickFindActiveAccountsFetchXml estático muestra cómo usar FetchExpression con una consulta de búsqueda rápida.

/// <summary>
/// Returns active accounts using quick find filter with FetchXml
/// </summary>
/// <param name="service">The authenticated IOrganizationService instance to use.</param>
/// <param name="searchString">The string to search for</param>
/// <returns>Collection of matching account records</returns>
static EntityCollection QuickFindActiveAccountsFetchXml(IOrganizationService service, string searchString) {
    
    // Wildcard required for ConditionOperator.Like
    if (!searchString.EndsWith('%'))
    {
        searchString += '%';
    }

    string query = string.Format(@"<fetch>
           <entity name='account'>
              <attribute name='accountid' />
              <attribute name='name' />
              <attribute name='accountnumber' />
              <attribute name='primarycontactid' />
              <attribute name='address1_city' />
              <attribute name='telephone1' />
              <attribute name='emailaddress1' />
              <filter type='or'
                 isquickfindfields='1'>
                 <condition attribute='telephone2'
                    operator='like'
                    value='{0}' />
                 <condition attribute='telephone1'
                    operator='like'
                    value='{0}' />
                 <condition attribute='emailaddress1'
                    operator='like'
                    value='{0}' />
                 <condition attribute='accountnumber'
                    operator='like'
                    value='{0}' />
                 <condition attribute='name'
                    operator='like'
                    value='{0}' />
              </filter>
              <filter type='and'>
                 <condition attribute='statecode'
                    operator='eq'
                    value='0' />
              </filter>
              <order attribute='name'
              descending='false' />
           </entity>
        </fetch>", searchString);

    return service.RetrieveMultiple(new FetchExpression(query));
}

Esta función de PowerShell Get-QuickFindActiveAccounts demuestra cómo usar FetchXml con la API web de Dataverse. Las variables $baseURI y $baseHeaders tienen un ámbito fuera de esta función. Más información sobre la creación de funciones de PowerShell reutilizables que utilizaron la API web

function Get-QuickFindActiveAccounts {
   param (
      [Parameter(Mandatory)] 
      [String] 
      $searchString
   )
   #  Wildcard required for ConditionOperator.Like
   if (!$searchString.EndsWith('%')) {
      $searchString += '%'
   }

   $query = "<fetch>
      <entity name='account'>
         <attribute name='accountid' />
         <attribute name='name' />
         <attribute name='accountnumber' />
         <attribute name='primarycontactid' />
         <attribute name='address1_city' />
         <attribute name='telephone1' />
         <attribute name='emailaddress1' />
         <filter type='or'
            isquickfindfields='1'>
            <condition attribute='telephone2'
               operator='like'
               value='{0}' />
            <condition attribute='telephone1'
               operator='like'
               value='{0}' />
            <condition attribute='emailaddress1'
               operator='like'
               value='{0}' />
            <condition attribute='accountnumber'
               operator='like'
               value='{0}' />
            <condition attribute='name'
               operator='like'
               value='{0}' />
         </filter>
         <filter type='and'>
            <condition attribute='statecode'
               operator='eq'
               value='0' />
         </filter>
         <order attribute='name'
         descending='false' />
      </entity>
   </fetch>" -f $searchString

   $uri = $baseURI + 'accounts?fetchXml=' + [uri]::EscapeUriString($query)
   # Header for GET operations that have annotations
   $getHeaders = $baseHeaders.Clone()
   $getHeaders.Add('If-None-Match', $null)
   $getHeaders.Add('Prefer', 'odata.include-annotations="*"')
   $RetrieveMultipleRequest = @{
      Uri     = $uri
      Method  = 'Get'
      Headers = $getHeaders
   }
   Invoke-RestMethod @RetrieveMultipleRequest
}

Límites de registro de búsqueda rápida

Dentro del Centro de administración de Power Platform, hay una configuración de Dataverse llamada Límites de registros de búsqueda rápida que está activada de forma predeterminada. La columna QuickFindRecordLimitEnabled de la tabla de la organización almacena esta configuración.

Importante

Le recomendamos encarecidamente que deje habilitada la configuración Límites de registros de búsqueda rápida. Esta configuración le protege de la lentitud del sistema y posibles interrupciones del servicio cuando las consultas de búsqueda rápida agotan los recursos disponibles.

Debido a que las consultas de búsqueda rápida admiten experiencias de usuario específicas en las aplicaciones, deben devolver resultados o fallar rápidamente. El usuario no esperará mucho tiempo para obtener resultados y estas consultas pueden utilizar muchos recursos del sistema porque pueden tener condiciones en varias columnas de la tabla.

Cuando la configuración de Límites de registro de búsqueda rápida está habilitada, las consultas de búsqueda rápida devuelven un error si el número de resultados supera las 10.000 filas. El error devuelto es:

Nombre: QuickFindQueryRecordLimitExceeded
Código: 0x8004E024
Número: -2147164124
Mensaje: The number of records for this search exceeds the Quick Search record limit. Please refine your query and try again.

No es necesario que muestre este error en su aplicación, pero debe esperar que pueda ocurrir. Puede mitigar esto mediante:

La limitación del número de campos buscados por su consulta.
Incluya condiciones limitantes en su consulta.
Solicite al usuario que introduzca más caracteres en el cuadro de búsqueda para proporcionar menos coincidencias totales.

El éxito de la consulta puede depender más del número de registros de la tabla que de cómo se define la consulta. Para comprender esto, debe comprender cómo se calcula el límite de elementos de búsqueda.

Cómo se calcula el límite de elementos de búsqueda

El límite de elementos de búsqueda se calcula utilizando SOLO los elementos en el filtro de búsqueda rápida. Al procesar la consulta, Dataverse detecta si existe un filtro de búsqueda rápida y lo procesa primero, incluso antes de aplicar los filtros de seguridad. Si los resultados del filtro de búsqueda rápida superan las 10.000 filas, Dataverse arroja la QuickFindQueryRecordLimitExceeded excepción y no se procesan otros filtros. Agregar filtros adicionales para obtener un número total menor de registros devueltos no disminuirá el potencial de la excepción QuickFindQueryRecordLimitExceeded. Alguien que consulte una tabla sin privilegios para ver todos los registros coincidentes puede recibir este error.

Eludir el límite de registros de búsqueda rápida

Cuando la configuración de Límites de registros de búsqueda rápida está habilitada y necesita probar una consulta que exceda límite de búsqueda rápida de forma temporal, utilice FetchXml para redactar la consulta y establecer el atributo elemento de filtro overridequickfindrecordlimitdisabled en '1'.

Aplicar el límite de registros de búsqueda rápida

Cuando la configuración de Límites de registros de búsqueda rápida está deshabilitada y necesita probar una consulta con los límites aplicados de forma temporal, utilice FetchXml para redactar la consulta y establecer el atributo elemento de filtro overridequickfindrecordlimitenabled en '1'.

Limitaciones

Es posible que las consultas de búsqueda rápida no proporcionen experiencias utilizables para todas las situaciones.

Dado que el límite de elementos de búsqueda se calcula antes de aplicar los filtros de seguridad, el número total de registros coincidentes en el sistema puede superar el límite de 10.000 registros cuando la tabla contiene un gran número de registros, independientemente de cuántos registros tenga privilegios de seguridad para ver el usuario que realiza la llamada. Refinar la consulta o utilizar criterios de búsqueda más específicos puede no ser suficiente para brindar una experiencia útil a un usuario.

En el peor de los casos, los usuarios verán una excepción de QuickFindQueryRecordLimitExceeded a menos que introduzcan una cadena de búsqueda muy específica, que no proporciona la experiencia esperada de 'búsqueda rápida'.

Consulte también

Consultar datos mediante FetchXML
Crear consultas con QueryExpression
API de búsqueda de Dataverse

Compartir vía