Filtrer des lignes à l’aide de FetchXml

  • Article

Pour définir des conditions sur les lignes de données à renvoyer, utilisez l’élément filter au sein d’un élément entity, link-entity ou un autre élément filter.

Pour définir les conditions, ajoutez un ou plusieurs éléments condition au filtre. L’attribut filter type contenant détermine si toutes (and) ou une (or) des conditions doivent être remplies. La valeur par défaut est and. En imbriquant des éléments de filtre, vous pouvez créer des critères de filtre complexes qui combinent des critères évalués avec and ou or.

Chaque condition possède un attribut operator pour évaluer une valeur de colonne de ligne. Vous pouvez choisir entre de nombreuses valeurs d’opérateurs de condition.

Par exemple, la requête suivante renvoie les enregistrements de contact où address1_city est égal à « Redmond ». Elle utilise <filter type='and'> avec l’opérateur eq.

<fetch>
   <entity name='account'>
      <attribute name='name' />
      <filter type='and'>
         <condition attribute='address1_city'
            operator='eq'
            value='Redmond' />
      </filter>
   </entity>
</fetch>

Cette requête renvoie les enregistrements de contact où address1_city est égal à « Redmond », « Seattle » ou « Bellevue ». Elle utilise <filter type='or'> avec trois éléments de condition qui utilisent chacun l’opérateur eq.

<fetch>
   <entity name='account'>
      <attribute name='name' />
      <attribute name='address1_city' />
      <filter type='or'>
         <condition attribute='address1_city'
            operator='eq'
            value='Redmond' />
         <condition attribute='address1_city'
            operator='eq'
            value='Seattle' />
         <condition attribute='address1_city'
            operator='eq'
            value='Bellevue' />
      </filter>
   </entity>
</fetch>

La requête précédente peut également être représentée à l’aide de l’opérateur in avec un seul élément condition. Cette condition contient plusieurs éléments value pour spécifier les valeurs à comparer à address1_city.

<fetch>
   <entity name='account'>
      <attribute name='name' />
      <attribute name='address1_city' />
      <filter type='and'>
         <condition attribute='address1_city'
            operator='in'>
            <value>Redmond</value>
            <value>Seattle</value>
            <value>Bellevue</value>
         </condition>
      </filter>
   </entity>
</fetch>

Paramètres de l’opérateur

Les opérateurs peuvent ne nécessiter aucun paramètre, un seul paramètre ou plusieurs paramètres. L’opérateur détermine la manière dont vous définissez la valeur à évaluer.

Aucun paramètre

Certains opérateurs ne nécessitent aucun paramètre. Par exemple, vous pouvez utiliser l’opérateur eq-userid pour évaluer tout identificateur unique afin de déterminer s’il correspond à l’ID de l’utilisateur appelant.

<condition attribute='ownerid'
   operator='eq-userid' />

Paramètre unique

Lorsqu’un opérateur nécessite un seul paramètre, utilisez l’attribut value pour définir la valeur à évaluer. Par exemple, vous pouvez utiliser l’opérateur eq pour évaluer la valeur de la colonne de choix statecode d’un enregistrement en définissant l’attribut value.

<condition attribute='statecode'
   operator='eq'
   value='0' />

Paramètres multiples

Lorsqu’un opérateur nécessite plusieurs paramètres, utilisez l’élément value pour spécifier les valeurs à évaluer. Par exemple, vous pouvez utiliser l’opérateur between pour évaluer un nombre afin de déterminer s’il se situe entre un ensemble de valeurs.

<condition attribute="numberofemployees"
   operator="between">
   <value>6</value>
   <value>20</value>
</condition>

Lorsque vous appliquez un filtre au sein d’un élément link-entity, le filtre sera appliqué avec la jointure à moins que vous configuriez le filtre pour qu’il se produise après la jointure.

Lorsque la valeur de l’attribut link-type de link-entity est outer, vous souhaiterez peut-être que le filtre soit appliqué après la jointure en définissant la valeur de l’attribut entityname de condition. Si vous utilisez un link-entity alias, utilisez la valeur alias pour définir l’attribut entityname. Sinon, définissez la valeur de l’attribut entityname sur la valeur de l’attribut name de link-entity.

Par exemple, la requête suivante renvoie des contacts sans compte parent, ou un compte parent sans fax.

<fetch>
  <entity name='contact'>
    <attribute name='fullname' />
    <filter>
      <condition entityname='a'
        attribute='fax'
        operator='null' />
    </filter>
    <link-entity name='account'
      from='accountid'
      to='parentcustomerid'
      link-type='outer'
      alias='a' />
  </entity>
</fetch>

Filtrer les valeurs de colonne dans la même ligne

Vous pouvez créer des filtres qui comparent des colonnes de valeurs dans la même ligne à l’aide de l’attribut valueof. Par exemple, si vous souhaitez rechercher des enregistrements de contact où la valeur de la colonne firstname correspond à la valeur de la colonne lastname, vous pouvez utiliser cette requête :

<fetch>
   <entity name='contact' >
      <attribute name='firstname' />
      <filter>
         <condition attribute='firstname'
            operator='eq'
            valueof='lastname' />
      </filter>
   </entity>
</fetch>

Comparaisons croisées de tables

Avec FetchXML uniquement, vous pouvez comparer les valeurs de champ dans les tables associées. L’exemple suivant renvoie les lignes dans lesquelles la colonne fullname de contact correspond à la colonne compte name.

<fetch>
   <entity name='contact'>
      <attribute name='contactid' />
      <attribute name='fullname' />
      <filter type='and'>
         <condition attribute='fullname'
            operator='eq'
            valueof='acct.name' />
      </filter>
      <link-entity name='account'
         from='accountid'
         to='parentcustomerid'
         link-type='outer'
         alias='acct'>
         <attribute name='name' />
      </link-entity>
   </entity>
</fetch>

L’élément link-entity doit utiliser un attribut alias et la valeur du paramètre valueof doit faire référence à cet alias et au nom de la colonne dans la table associée.

Limitations des filtres de comparaison de colonnes

Des limitations s’appliquent à ces types de filtres :

  • Une condition ne peut utiliser que ces opérateurs :

    Opérateur Description
    eq Les valeurs sont comparées en termes d’égalité.
    ne Les deux valeurs ne sont pas égales.
    gt La valeur est supérieure à la valeur comparée.
    ge La valeur est supérieure ou égale à la valeur comparée.
    lt La valeur est inférieure à la valeur comparée.
    le La valeur est inférieure ou égale à la valeur comparée.

  • Seules deux colonnes peuvent être comparées à la fois

  • Les opérations de condition étendues ne sont pas prises en charge. Par exemple : valueof='amount'+ 100

  • Les colonnes doivent être du même type. Par exemple : vous ne pouvez pas comparer une valeur de chaîne avec une valeur numérique

Pour filtrer les valeurs dans les enregistrements associés sans renvoyer ces valeurs, utilisez un élément link-entity au sein de l’élément filter avec l’un des attributs link-type suivants :

Nom      Description
any Utilisez ce paramètre dans un élément de filtre. Restreint les résultats aux lignes parentes avec toutes les lignes correspondantes dans l’entité liée.
not any Utilisez ce paramètre dans un élément de filtre. Restreint les résultats aux lignes parentes sans lignes correspondantes dans l’entité liée.
all Utilisez ce paramètre dans un élément de filtre. Restreint les résultats aux lignes parentes où il existe des lignes avec une valeur de colonne from correspondante dans l’entité de lien, mais aucune de ces lignes correspondantes ne satisfait aux filtres supplémentaires définis pour cette entité de lien. Vous devez inverser les filtres supplémentaires pour trouver des lignes parentes où chaque ligne d’entité de lien correspondante satisfait à certains critères supplémentaires.
not all Utilisez ce paramètre dans un élément de filtre. Restreint les résultats aux lignes parentes avec toutes les lignes correspondantes dans l’entité liée. Ce type de lien est équivalent à any malgré le nom.

Lorsque vous utilisez ces types de liens dans un élement filter, ces filtres sont des conditions enfants qui suivent le comportement défini par l’attribut type du parent filter.

Les filtres qui utilisent ces types renvoient la ligne parent au plus une fois, même si plusieurs lignes correspondantes existent dans l’entité de lien. Ils ne permettent pas de renvoyer les valeurs de colonne à partir des lignes d’entité de lien.

Les exemples suivants illustrent le filtrage des valeurs des enregistrements associés. Ces exemples incluent les instructions SQL équivalentes pour aider à expliquer le comportement.

Cette requête utilise un filter de type or avec un link-entity enfant de type any pour renvoyer les enregistrements dans contact qui :

<fetch>
   <entity name='contact'>
      <attribute name='fullname' />
      <filter type='or'>
         <link-entity name='account'
            from='primarycontactid'
            to='contactid'
            link-type='any'>
            <filter type='and'>
               <condition attribute='name'
                  operator='eq'
                  value='Contoso' />
            </filter>
         </link-entity>
         <condition attribute='statecode'
            operator='eq'
            value='1' />
      </filter>
   </entity>
</fetch>

Cette requête utilise le type de lien not any pour renvoyer les enregistrements de la table contact qui ne sont pas référencés par la colonne de recherche PrimaryContactId d’un enregistrement de compte dont la colonne Nom est égale à « Contoso ». L’enregistrement contact peut toujours être référencé par les enregistrements de compte avec d’autres valeurs de la colonne Nom.

<fetch>
   <entity name='contact'>
      <attribute name='fullname' />
      <filter type='and'>
         <link-entity name='account'
            from='primarycontactid'
            to='contactid'
            link-type='not any'>
            <filter type='and'>
               <condition attribute='name'
                  operator='eq'
                  value='Contoso' />
            </filter>
         </link-entity>
      </filter>
   </entity>
</fetch>

Notes

La signification des types de lien all et not all est l’opposé de ce que les noms peuvent impliquer, et ils sont généralement utilisés avec des filtres inversés :

  • Une entité lien de type not all est équivalente à any et renvoie les enregistrements parents qui ont des enregistrements d’entité de lien correspondant aux filtres.
  • Une entité de lien de type all renvoie les enregistrements parents lorsqu’il existe certains enregistrements d’entité de lien avec une valeur de colonne from correspondante mais aucune de ces lignes d’entité de lien ne satisfait aux filtres supplémentaires définis au sein de l’élément link-entity.

Cette requête utilise un link-entity de type not all pour renvoyer les enregistrements de la table contact qui sont référencés par la colonne de recherche PrimaryContactId d’au moins un enregistrement de compte dont la colonne Nom est égale à « Contoso ».

<fetch>
   <entity name='contact'>
      <attribute name='fullname' />
      <filter type='and'>
         <link-entity name='account'
            from='primarycontactid'
            to='contactid'
            link-type='not all'>
            <filter type='and'>
               <condition attribute='name'
                  operator='eq'
                  value='Contoso' />
            </filter>
         </link-entity>
      </filter>
   </entity>
</fetch>

Cette requête utilise un link-entity de type all pour renvoyer les enregistrements de la table contact qui sont référencés par la colonne de recherche PrimaryContactId de certains enregistrements de compte, mais aucun de ces enregistrements de compte n’ont leur colonne Nom égale à « Contoso ».

<fetch>
   <entity name='contact'>
      <attribute name='fullname' />
      <filter type='and'>
         <link-entity name='account'
            from='primarycontactid'
            to='contactid'
            link-type='all'>
            <filter type='and'>
               <condition attribute='name'
                  operator='eq'
                  value='Contoso' />
            </filter>
         </link-entity>
      </filter>
   </entity>
</fetch>

Limites de condition

Vous ne pouvez pas inclure plus de 500 éléments condition et link-entity au total dans une requête FetchXml. Sinon, vous voyez cette erreur :

Nom: TooManyConditionsInQuery
Code : 0x8004430C
Nombre : -2147204340
Message : Number of conditions in query exceeded maximum limit.

Vous devez réduire le nombre de conditions pour exécuter la requête. Vous pourrez peut-être réduire le nombre de conditions en utilisant l’opérateur in qui peut être utilisé avec des nombres, des identificateurs uniques et des chaînes pouvant aller jusqu’à 850 caractères.

Étapes suivantes

Découvrez comment paginer des résultats.

Résultats sur la page

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).