Über Schnellsuche-Abfragen

Artikel
07/08/2024

Modellgesteuerte Apps bieten Erfahrungen zum schnellen Auffinden von Datensätzen mithilfe der Schnellsuche oder der Rastersuche. Mit diesen Erfahrungen verfügen Benutzende über eine einzige Texteingabe, die auf mehrere Spalten in einer einzelnen Tabelle angewendet werden kann.

Modellgesteuerte Apps bieten außerdem ein Suchfeld, das die Dataverse-Such-APIs verwendet, wenn die Dataverse-Suche aktiviert ist. Bei der Dataverse-Suche können die Ergebnisse Ergebnisse aus mehreren Tabellen enthalten, um eine relevantere Suchfunktion zu ermöglichen. Wenn die Dataverse-Suche nicht aktiviert ist, bieten modellgesteuerte Apps eine Erfahrung für die Schnellsuche in mehreren Tabellen (Kategoriesuche), die Ergebnisse aus bis zu zehn Schnellsuchabfragen kombiniert. Erfahren Sie mehr über verfügbare Suchoptionen für modellgesteuerte Apps.

Hinweis

Schnellsuche-Abfragen bieten möglicherweise nicht für jede Situation nutzbare Erfahrungen. Siehe Einschränkungen

Erwägen Sie die Verwendung von Dataverse-Such-APIs anstelle von Schnellsuche-Abfragen für die folgenden Szenarien:

Was ist eine Schnellsuche-Abfrage?

Schnellsuche-Abfragen verwenden das folgende Muster:

Sie umfassen einen einzelnen Filter mit einem „OR“-Filteroperator.
- Mit FetchXml wird das Attribut type des Filterelements auf 'or' festgelegt.
- Mit QueryExpression wird die FilterExpression.FilterOperator auf LogicalOperator.Or eingestellt.
Sie können weitere Filter hinzufügen, diese werden jedoch erst ausgewertet, nachdem die Filterergebnisse der Schnellsuche verarbeitet wurden.
Der „OR“-Filter ist als Schnellsuche-Filter markiert:
- Mit FetchXml wird das Attribut isquickfindfields des Filterelements auf '1' festgelegt.
- Mit QueryExpression wird der FilterExpression.IsQuickFindFilter auf true gesetzt.
Der Filter hat mehr als eine Bedingung. Wenn nur eine Bedingung ausgewertet wird, zeigt die Abfrage eine bessere Leistung, wenn sie als normale Abfrage verarbeitet wird.
Alle Bedingungen innerhalb des Filters verwenden den „Gefällt mir“-Operator:
- Mit FetchXml wird das Attribut operator des Bedingungselements auf 'like' festgelegt.
- Mit QueryExpression verwendet ConditionExpression.Operator ConditionOperator.Like.
Der „Gefällt mir“-Operator erfordert eine Suchzeichenfolge, die mit % endet.

Hinweis

Der „Gefällt mir“-Operator ist der einzige unterstützte Operator für Schnellsuche-Abfragen. Es ist der einzige Operator, der für die Anwendungsszenarien erforderlich ist, die Schnellsuche-Abfragen unterstützen sollen. Andere Operatoren wurden nicht getestet.

Beispiele

Wie Sie eine Schnellsucheabfrage schreiben, hängt davon ab, ob Sie QueryExpression oder FetchXml verwenden.

Alle Beispiele in den folgenden Registerkarten tun dasselbe:

Akzeptieren Sie einen einzelnen Suchzeichenfolgenparameter. Dieser Wert kann ein Teil des Namens, eine Telefonnummer, eine E-Mail-Adresse oder eine Kontonummer sein.
Erstellen Sie eine Schnellsuche-Abfrage, die die Suchzeichenfolge anhand der folgenden Kontotabellenspalten testet:
- telephone2
- telephone1
- emailaddress1
- accountnumber
- name
Filtert Konten heraus, die nicht aktiv sind.
Ordnet die Ergebnisse nach Kontonamen.

QueryExpression
FetchXML

Sie können QueryExpression mit dem Dataverse SDK für .NET verwenden.

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

Sie können FetchXml mit dem Dataverse-SDK für .NET oder der Dataverse-Web-API verwenden.

Mit dem SDK für .NET zeigt diese statische QuickFindActiveAccountsFetchXml-Methode an, wie FetchExpression mit einer Schnellsuche-Abfrage verwendet wird.

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

Diese Get-QuickFindActiveAccounts-PowerShell-Funktion zeigt, wie FetchXml mit der Dataverse-Web-API verwendet wird. Die Variablen $baseURI und $baseHeaders sind außerhalb dieser Funktion gültig. Erfahren Sie mehr über das Erstellen wiederverwendbarer PowerShell-Funktionen, die die Web-API verwenden

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
}

Grenzwerte der Datensätze für die Schnellsuche

Im Power Platform Admin Center gibt es eine Dataverse-Einstellung namens Grenzwerte der Datensätze für die Schnellsuche, die standardmäßig aktiviert ist. Die QuickFindRecordLimitEnabled-Spalte der Organisationstabelle speichert diese Einstellung.

Wichtig

Wir empfehlen dringend, dass Sie die Einstellung Grenzwerte der Datensätze für die Schnellsuche aktiviert lassen. Diese Einstellung schützt Sie vor Systemlangsamkeit und möglichen Dienstunterbrechungen, wenn Schnellsuche-Abfragen die verfügbaren Ressourcen erschöpfen.

Da Schnellsuche-Abfragen bestimmte Benutzererfahrungen in Anwendungen unterstützen, müssen sie Ergebnisse zurückgeben, sonst schlagen sie schnell fehl. Der Benutzende muss nicht lange auf Ergebnisse warten und diese Abfragen können viele Systemressourcen beanspruchen, da sie Bedingungen für mehrere Spalten der Tabelle haben können.

Wenn die Einstellung Grenzwerte der Datensätze für die Schnellsuche aktiviert ist, geben Schnellsuchabfragen einen Fehler zurück, wenn die Anzahl der Ergebnisse 10.000 Zeilen überschreitet. Dies ist der zurückgegebene Fehler:

Name: QuickFindQueryRecordLimitExceeded
Code: 0x8004E024
Zahl: -2147164124
Meldung: The number of records for this search exceeds the Quick Search record limit. Please refine your query and try again.

Sie müssen diesen Fehler nicht in Ihrer Anwendung anzeigen, sollten aber damit rechnen, dass er auftreten kann. Sie können dies abmildern, indem Sie Folgendes tun:

Begrenzen Sie die Anzahl der von Ihrer Abfrage durchsuchten Felder.
Beziehen Sie in Ihrer Abfrage einschränkende Bedingungen ein.
Fordern Sie den Benutzenden auf, mehr Zeichen in das Suchfeld einzugeben, um insgesamt weniger Übereinstimmungen zu erhalten.

Ob die Abfrage erfolgreich ist, hängt möglicherweise mehr von der Anzahl der Datensätze in der Tabelle ab als davon, wie die Abfrage definiert ist. Um dies zu verstehen, müssen Sie verstehen, wie das Suchelementlimit berechnet wird.

So wird das Suchelementlimit berechnet

Das Suchelementlimit wird NUR mit den Elementen im Schnellsuche-Filter berechnet. Bei der Verarbeitung der Abfrage erkennt Dataverse, ob ein Schnellsuchfilter vorhanden ist, und verarbeitet diesen zuerst, sogar noch den Sicherheitsfiltern. Wenn die Ergebnisse des Schnellsuche-Filters 10.000 Zeilen überschreiten, gibt Dataverse die QuickFindQueryRecordLimitExceeded-Ausnahme aus und es werden keine anderen Filter verarbeitet. Das Hinzufügen weiterer Filter, um die Gesamtzahl der zurückgegebenen Datensätze zu senken, verringert das Potenzial der QuickFindQueryRecordLimitExceeded-Ausnahme nicht. Jemand, der eine Tabelle abfragt, ohne die Berechtigung zum Anzeigen aller übereinstimmenden Datensätze, kann diesen Fehler erhalten.

Grenzwerte der Schnellsuche-Datensätze umgehen

Wenn die Einstellung Grenzwerte der Datensätze für die Schnellsuche aktiviert ist und Sie eine Abfrage testen müssen, die den Grenzwert der Schnellsuche vorübergehend überschreitet, verwenden Sie FetchXml, um die Abfrage zu erstellen, und legen Sie das Attribut des Filterelements overridequickfindrecordlimitdisabled auf '1' fest.

Grenzwerte der Schnellsuche-Datensätze anwenden

Wenn die Einstellung Grenzwerte der Datensätze für die Schnellsuche deaktiviert ist und Sie eine Abfrage mit den angewendeten Grenzwerten vorübergehend testen müssen, verwenden Sie FetchXml, um die Abfrage zu erstellen, und legen Sie das Attribut des Filterelements overridequickfindrecordlimitenabled auf '1' fest.

Einschränkungen

Schnellsuche-Abfragen bieten möglicherweise nicht für jede Situation nutzbare Erfahrungen.

Da das Suchelementlimit vor der Anwendung von Sicherheitsfiltern berechnet wird, kann die Gesamtzahl der übereinstimmenden Datensätze im System den Grenzwert von 10.000 Datensätzen überschreiten, wenn die Tabelle eine große Anzahl von Datensätzen enthält, unabhängig davon, wie viele Datensätze mit Sicherheitsberechtigungen zum Anzeigen der aufrufende Benutzende hat. Das Verfeinern der Abfrage oder die Verwendung spezifischerer Suchkriterien reicht möglicherweise nicht aus, um Benutzenden ein brauchbares Erlebnis zu liefern.

Im schlimmsten Fall erhalten die Benutzenden eine QuickFindQueryRecordLimitExceeded-Ausnahme, sofern sie keine bestimmte Suchzeichenfolge eingeben, was nicht das erwartete Schnellsucherlebnis bietet.

Siehe auch

Daten mithilfe von FetchXml abfragen
Erstellen von Abfragen mit QueryExpression
Dataverse-Such-APIs

Freigeben über