Über Schnellsuche-Abfragen

Artikel
03/14/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 Schnellsuche mit mehreren Tabellen (kategorisierte Suche), die Ergebnisse von bis zu 10 Schnellsuche-Abfragen 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 zusätzliche Filter hinzufügen, diese werden jedoch erst ausgewertet, nachdem die Schnellsuche-Filterergebnisse 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, weist die Abfrage eine bessere Leistung auf, 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 Schnellsuche-Abfrage schreiben, hängt davon ab, ob Sie QueryExpression oder FetchXml verwenden.

Jedes der Beispiele in den folgenden Registerkarten bewirkt dasselbe:

Akzeptieren Sie einen einzelnen Suchzeichenfolgenparameter. Dabei kann es sich um einen Teil des Namens, der Telefonnummer, der E-Mail-Adresse oder der Kontonummer handeln.
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 mit dem Namen 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 Schnellsuche-Abfragen 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 Schnellsuche-Filter vorhanden ist, und verarbeitet ihn zuerst, noch bevor Sicherheitsfilter angewendet werden. 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 zusätzlicher Filter, um eine geringere Gesamtzahl zurückgegebener Datensätze zu erhalten, verringert nicht das Potenzial der QuickFindQueryRecordLimitExceeded-Ausnahme. 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 einem Benutzenden ein nutzbares Erlebnis zu bieten.

Im schlimmsten Fall sehen Benutzende eine QuickFindQueryRecordLimitExceeded-Ausnahme, es sei denn, sie geben eine sehr spezifische Suchzeichenfolge ein, die nicht das erwartete „Schnellsuche“-Erlebnis bietet.

Siehe auch

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

Share via