Query Builder de List Filter Online : conditions, groupes et requête CAML sous-jacente

Vue d'ensemble

Le Query Builder est la partie du composant WebPart Vitextra List Filter Online dans laquelle un éditeur de page définit le filtre prédéfini : l'ensemble des conditions que chaque élément doit satisfaire avant d'apparaître dans le composant WebPart. Les utilisateurs ne peuvent ni voir ni supprimer ce filtre ; ils ne font que restreindre davantage le résultat à l'aide du volet de filtre et des filtres d'en-tête de colonne.

Le filtre prédéfini est stocké sous la forme d'une arborescence de conditions et de groupes, puis traduit en une requête CAML que SharePoint exécute côté serveur. Rien n'est chargé dans le navigateur pour être filtré ensuite : la liste ne renvoie que les éléments correspondants, page par page, ce qui maintient la rapidité du composant WebPart sur les listes volumineuses.

Usages typiques du filtre prédéfini :

• Afficher uniquement les documents créés ou modifiés par l'utilisateur actuel.
• Afficher uniquement les enregistrements des 12 derniers mois sur une page de tableau de bord.
• Afficher uniquement les éléments approuvés, les éléments avec pièces jointes ou les éléments dont l'État n'est pas Fermé.
• Créer une page par service à partir d'une seule liste, sans créer un affichage par service.

Où trouver le Query Builder

1. Ouvrez la page en mode édition et sélectionnez Modifier le composant WebPart sur le composant WebPart List Filter Online.
2. Dans le volet de propriétés, faites défiler jusqu'au groupe Filtrer. L'étiquette Filtrer l'affichage : est suivie d'un aperçu du filtre actuel - Aucun filtre appliqué tant que rien n'est défini.
3. Sélectionnez Modifier le filtre. Le Query Builder s'ouvre dans un grand panneau latéral.
4. Construisez la requête, puis sélectionnez Enregistrer pour l'appliquer ou Annuler pour abandonner les modifications. Le composant WebPart s'actualise immédiatement avec le nouveau filtre.

Le Query Builder n'est disponible qu'une fois le site et la liste ou bibliothèque sélectionnés dans le groupe Source de données, car la liste des champs et leurs types proviennent de la liste sélectionnée.

Conditions et groupes

Une requête se compose de deux types de blocs.

• Une condition est une comparaison : champ - opérateur - valeur, par exemple Amount - Est supérieur à - 5000. Certains opérateurs ne nécessitent aucune valeur (Contient des données, Est l’utilisateur actuel, Aujourd'hui).
• Un groupe contient des conditions et d'autres groupes et les relie par un seul opérateur logique - ET (chaque membre doit être vrai) ou OU (au moins un membre doit être vrai). Le bouton bascule sur le bord gauche du groupe permet de passer de l'un à l'autre.

Le panneau comporte toujours un groupe racine, qui ne peut pas être supprimé. Dans n'importe quel groupe, le bouton Ajouter propose deux commandes :

• Condition - ajoute une ligne vide au groupe actuel ;
• Groupe - ajoute un groupe imbriqué (ET par défaut) que vous remplissez de la même manière.

Les groupes peuvent être imbriqués dans d'autres groupes. Chaque ligne et chaque groupe imbriqué possède une icône de suppression à droite ; supprimer un groupe supprime tout son contenu.

La requête de la figure se lit ainsi : le Titre n'est pas vide et commence par « C » et (créé par moi ou modifié par moi) et (créé au cours de la dernière année ou modifié au cours de la dernière année) et (possède des pièces jointes, ou le Client est renseigné et le Montant est supérieur à 5 000).

Opérateurs par type de colonne

La liste des opérateurs d'une ligne dépend du type du champ sélectionné. Le tableau présente les opérateurs que le Query Builder propose pour chaque type de colonne pris en charge.

Contient des données et Ne contient pas de données vérifient si la colonne possède une valeur, exactement comme IsNotNull et IsNull en CAML.

L'éditeur de valeur suit lui aussi le type de colonne : un sélecteur de date pour les dates (deux sélecteurs de date pour Entre), un champ numérique pour les nombres et les devises, un sélecteur de personnes pour Personne ou groupe, un sélecteur de termes pour Métadonnées gérées, une liste Oui / Non pour Oui/Non et Pièces jointes, une liste d'états pour État d'approbation, et une zone de texte pour les colonnes de texte, de choix et de recherche.

Conditions statiques et dynamiques

Une condition statique compare la colonne à une valeur fixe que vous saisissez : une date, un nombre, un texte, une personne. La valeur est écrite telle quelle dans la requête. Entre inclut les deux dates, au jour calendaire près ; si une seule des deux dates est renseignée, la condition devient un Le ou après le ou un Le ou avant le ouvert.

Une condition dynamique est résolue par SharePoint au moment de l'exécution de la requête, de sorte que la même page affiche des éléments différents selon l'utilisateur et le jour :

Le nombre de X Derniers et X Prochains se saisit dans le champ de valeur de la ligne. X derniers mois et X dernières années sont convertis en date de début au moment de la génération de la requête : une page configurée avec Modifié - X dernières années - 1 couvre donc toujours les douze derniers mois sans que personne ne modifie le filtre.

Combinaison du filtre prédéfini et des filtres des utilisateurs

Lorsqu'un utilisateur applique un filtre dans le volet de filtre ou dans un en-tête de colonne, le composant WebPart ne remplace pas le filtre prédéfini. Il construit une nouvelle requête dans laquelle le filtre prédéfini et les filtres de l'utilisateur sont reliés par ET :

<Where>
  <And>
    
    
  </And>
</Where>

Conséquences à connaître :

• Les utilisateurs peuvent restreindre le résultat, mais jamais l'élargir au-delà du filtre prédéfini. Une page filtrée sur Créé par - Est l’utilisateur actuel n'affiche jamais les éléments d'une autre personne, quelle que soit la sélection de l'utilisateur dans le volet.
• Le tri, le regroupement, les totaux et l'export Excel s'appliquent tous au résultat combiné.
• Les filtres enregistrés et les liens vers un filtre (voir KB10253. Enregistrer des filtres et partager un lien vers une vue filtrée dans List Filter Online) ne stockent que la partie utilisateur de la requête. Le filtre prédéfini fait partie de la configuration de la page et voyage avec elle.

De l'arborescence au CAML

CAML, le langage de requête des listes SharePoint, n'admet que deux opérandes à l'intérieur de <And> et <Or>. Un groupe de trois membres ou plus ne peut donc pas s'écrire en un seul élément ; il doit être replié en une chaîne de paires imbriquées. Le Query Builder effectue ce repli pour vous, ainsi que les détails propres à chaque type : l'attribut Type de chaque valeur, LookupId pour les colonnes de recherche et IncludeTimeValue pour les comparaisons de dates.

La requête de la figure ci-dessus produit une clause <Where> d'environ 70 lignes. Son squelette - avec les comparaisons abrégées - se présente ainsi :

<Where>
  <And>
    <Or>  
      <Eq><FieldRef Name="Author" /><Value Type="Integer"><UserID /></Value></Eq>
      <Eq><FieldRef Name="Editor" /><Value Type="Integer"><UserID /></Value></Eq>
    </Or>
    <And>
      <Or>  
        <And> <Geq Created 2025-10-21 /> <Leq Created <Today /> /> </And>
        <And> <Geq Modified 2025-10-21 /> <Leq Modified <Today /> /> </And>
      </Or>
      <And>
        <Or>  
          <And> <IsNotNull Customer /> <Gt Amount 5000 /> </And>
          <Eq Attachments 1 />
        </Or>
        <And> <IsNotNull Title /> <BeginsWith Title "C" /> </And>
      </And>
    </And>
  </And>
</Where>

Chaque ligne X dernières années est devenue un <And> de deux comparaisons de dates, chaque groupe OU est devenu un élément <Or>, et les quatre membres du groupe racine ET sont devenus trois éléments <And> imbriqués.

Afficher la requête générée

Pour voir le CAML exact que le composant WebPart envoie - y compris le filtre prédéfini, les filtres utilisateur en cours, les champs de l'affichage, la limite de lignes et le regroupement :

1. Dans le volet de propriétés, développez Outils de développement et activez Activer le mode Développeur.
2. Enregistrez la page. Un menu d'outils de développement apparaît à l'extrémité droite de la barre de commandes du composant WebPart.
3. Sélectionnez Requête CAML. La requête s'ouvre dans une boîte de dialogue et peut être copiée.

Filtres prédéfinis sur les listes volumineuses

Sur les listes de plus de 5 000 éléments, SharePoint n'exécute une requête que si la première condition qui restreint le résultat porte sur une colonne indexée et est suffisamment sélective. Le filtre prédéfini est le premier à s'exécuter : c'est donc lui qui décide si la page s'ouvre ou non.

• Commencez le groupe racine par une condition sur une colonne indexée (vérifiez les index de Créé, Modifié, Créé par, Modifié par et ID dans les paramètres de la liste et créez au besoin des index pour les colonnes compatibles).
• Privilégiez ET à la racine : un OU entre deux colonnes non indexées ne peut utiliser aucun index.
• Les conditions de date dynamiques (X derniers mois, Aujourd'hui) sont de bonnes premières conditions lorsque la colonne de date est indexée.

Les détails, l'avertissement d'index dans le configurateur de filtres et la création d'index en un clic sont décrits dans KB10257. Filtrer les grandes listes : colonnes indexées et seuil de 5 000 éléments.

Limitations

• Le Query Builder travaille avec les colonnes d'une seule liste ou bibliothèque - celle sélectionnée dans la source de données. Des conditions sur les colonnes d'autres listes ne sont pas possibles.
• Les valeurs de recherche et de choix sont comparées au texte que vous saisissez ; le Query Builder ne propose pas de sélecteur pour celles-ci.
• Un groupe imbriqué ne contenant aucune condition est ignoré lors de la génération de la requête.
• En pratique, deux ou trois niveaux couvrent presque tous les scénarios ; une arborescence plus profonde est difficile à lire dans l'aperçu.
• Le filtre prédéfini n'est pas affiché aux utilisateurs. Si les utilisateurs doivent savoir pourquoi certains éléments manquent, indiquez-le dans le titre du composant WebPart ou sur la page.