Filtrer des lignes à l’aide de FetchXml
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>
Filtres sur link-entity
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 colonnes de tableaux
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
Filtrer les valeurs dans les enregistrements associés
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.
Exemples de filtres de valeurs dans les enregistrements associés
Les exemples suivants illustrent le filtrage des valeurs des enregistrements associés. Ces exemples incluent les instructions SQL équivalentes pour aider à expliquer le comportement.
Filtre or avec link-type
any
Cette requête utilise un filter
de type or
avec un link-entity
enfant de type any
pour renvoyer les enregistrements dans contact qui :
- soit 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 »,
- ou ont la colonne de liste de sélection Contact.StateCode définie sur 1 : Inactif :
<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>
link-type
not any
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>
link-type
not all
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 colonnefrom
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>
link-type
all
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.
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é).