QUERY BY ATTRIBUTE

La commande QUERY BY ATTRIBUTE recherche les enregistrements répondant au(x) critère(s) de recherche spécifié(s) à l'aide des paramètres champObjet, cheminAttribut, opRech et valeur et retourne une sélection d'enregistrements de laTable.

Note : Pour plus d'informations sur les champs Objet (nouveauté 4D v15), reportez-vous à la section dans le manuel Mode Développement.

QUERY BY ATTRIBUTE modifie la sélection courante de laTable pour le process courant. Le premier enregistrement de la nouvelle sélection devient l'enregistrement courant. Si vous omettez le paramètre laTable, la commande s'applique à la table par défaut. Si aucune table par défaut n'a été définie, une erreur est générée.

Le paramètre optionnel opConj est utilisé pour combiner plusieurs appels à QUERY BY ATTRIBUTE en cas de recherche multiple. Les opérateurs de conjonction utilisables sont les mêmes que ceux de la commande QUERY :

Le paramètre opConj n'est pas nécessaire pour le premier appel à QUERY BY ATTRIBUTE lors d'une recherche complexe, ou si la recherche ne comporte qu'une ligne. Si vous l'omettez à l'intérieur d'une recherche complexe, le ET (&) est utilisé par défaut.

Dans champObjet, passez le champ objet parmi les attributs duquel vous souhaitez effectuer la recherche. Il peut provenir d'une autre table si celle-ci est la table 1 d'une table liée à laTable par un lien automatique ou manuel.
QUERY BY ATTRIBUTE prend en charge les attributs utilisateurs de 4D Write Pro lorsque les documents sont stockés dans des champs de type Objet. Pour plus d'informations sur ce point, reportez-vous à la section Stocker les documents 4D Write Pro dans des champs objet 4D. 

Dans cheminAttribut, passez le chemin de l'attribut dont vous souhaitez comparer les valeurs pour chaque enregistrement, par exemple "enfants.filles.age". Si vous passez un simple nom, par exemple "lieu", vous désignez l'attribut correspondant situé au premier niveau du champ objet. 
Si un attribut "x" est un tableau, QUERY BY ATTRIBUTE cherchera les enregistrements contenant un attribut "x" dans lequel au moins un élément correspond aux critères. Pour effectuer une recherche parmi les attributs de tableaux, il est nécessaire d'indiquer à la commande QUERY BY ATTRIBUTE que l'attribut "x" est un tableau en ajoutant "[]" à son nom dans le paramètre cheminAttribut (voir exemple 3).

Notes :

• N'oubliez pas que les noms d'attributs tiennent compte des majuscules/minuscules : il est possible d'avoir deux noms d'attributs différents "MonAtt" et "monAtt" dans le même champ d'un enregistrement.
• les noms d'attributs sont "nettoyés" afin d'éliminer les espaces superflus. Par exemple, " mon premier attribut .mon second attribut " est interprété "mon premier attribut .mon second attribut". 

Le paramètre opRech est l'opérateur qui va permettre de comparer champObjet et valeur. Vous pouvez utiliser l'un des symboles suivants :

Note : Il est possible de définir le comparateur sous la forme d'une expression texte au lieu d'un symbole. Reportez-vous à la description de la commande QUERY pour plus d'informations.

La valeur représente ce qui va être comparé au contenu de cheminAttribut. La valeur peut être toute expression du même type que cheminAttribut. Le type de la valeur n'est évalué qu'une seule fois, au démarrage de la recherche, et ne l'est donc pas pour chaque enregistrement. Si la recherche porte sur le contenu d'une chaîne de caractères, utilisez dans valeur le symbole "@" pour isoler le contenu à rechercher, par exemple "@Dupon@". Il est à noter, dans ce cas, que la recherche ne tire que partiellement parti de l'index (compacité du stockage des données).

Voici la structure type d'une recherche par attribut :

Note : La présence de l'attribut dans le champ objet est un critère implicite pour tous les opérateurs (hormis #). En revanche, pour l'opérateur #, il peut être indéfini (cf. ci-dessous).

Les recherches par attribut utilisant l'opérateur "#" pourront avoir des résultats différents selon que la propriété est cochée ou non pour le champ objet :

• Propriété Traduire les NULL en valeurs vides cochée (option par défaut, recommandée dans la plupart des cas).
  Dans ce cas, l'opérateur "#" doit être perçu comme sélectionnant les enregistrements dont "aucun attribut" du champ ne contient la valeur recherchée. Dans ce contexte, 4D considère de façon similaire :
  
  • les champs pour lesquels la valeur de l'attribut est différente de la valeur recherchée,
  • les champs pour lesquels l'attribut n'est pas présent (ou contient la valeur Null).

  Par exemple, la recherche suivante retournera les enregistrements des personnes ayant un chien dont le nom n'est pas Médor, ainsi que les enregistrements des personnes n'ayant pas de chien, ou ayant un chien sans nom :
  

   QUERY BY ATTRIBUTE([Personnes];[Personnes]Animaux;"chien.nom";#;"Médor")
  
  Autre exemple : cette recherche retournera tous les enregistrements pour lesquels [Table]ChampObjet contient un objet qui contient un attribut attribut1 qui est lui-même un objet qui contient un attribut attribut2 dont la valeur n'est pas valeur, ainsi que les enregistrements dont le champ objet ne contient pas attribut1 ou attribut2 :
  
   QUERY BY ATTRIBUTE([Table] ;[Table]ChampObjet ;"attribut1.attribut2";#;valeur)

  Ce principe s'applique également aux attributs tableaux. Par exemple :
  

   QUERY BY ATTRIBUTE([Personnes];[Personnes]OB_Field;"locations[].city";#;"paris")

  Cette recherche retournera les enregistrements des personnes n'ayant aucune adresse à Paris.

  Pour obtenir spécifiquement les enregistrements dans lesquels l'attribut est indéfini, vous pouvez utiliser un objet vide (cf. exemple 2). A noter toutefois que la recherche de valeurs NULL dans les éléments de tableaux n'est prise en charge.

• Propriété Traduire les NULL en valeurs vides non cochée (mode "SQL").
  Dans ce cas, les attributs non définis (attributs non présents dans le champ ou ayant la valeur Null) ne sont pas considérés comme équivalents aux valeurs vides par défaut. Par conséquent, les recherches du type "attribut A est différent de valeur B" ne retourneront pas les enregistrements dans lesquels l'attribut A est indéfini.
  Pour reprendre l'exemple précédent, lorsque l'option Traduire les NULL en valeurs vides n'est pas cochée pour le champ [Personnes]Animaux, la recherche suivante retournera uniquement les enregistrements des personnes ayant un chien dont l'attribut "nom" ne contient pas "Médor". Les enregistrements des personnes n'ayant pas de chien, ou ayant un chien sans nom ne seront pas retournés dans ce cas.
  
   QUERY BY ATTRIBUTE([Personnes];[Personnes]Animaux;"chien.nom";#;"Médor")
  
  Ce fonctionnement, plus proche de la logique SQL, est à réserver pour des besoins spécifiques.

Voici les règles à observer pour la construction de recherche par attribut à lignes multiples :

• La première ligne ne doit pas contenir d'opérateur de conjonction,
• Les suivantes peuvent débuter par un opérateur de conjonction. Si vous l'omettez, l'opérateur ET (&) est utilisé par défaut.
• Toutes les lignes, à l'exception de la dernière, doivent s'achever par le symbole *.
• QUERY BY ATTRIBUTE peut être combiné à des commandes QUERY classiques (voir exemple).
• Pour lancer la recherche, ne passez pas le paramètre * dans la dernière ligne. Autre solution : vous pouvez exécuter la commande QUERY sans autre paramètre que la table.

Note : Chaque table maintient sa propre construction de recherche courante. Cela signifie que vous pouvez créer de multiples recherches simultanément, une pour chaque table.

Quelle que soit la manière dont la recherche a été définie :

• Si l'exécution d'une recherche nécessite un certain temps, 4D affiche automatiquement un message contenant un thermomètre de progression. Ce type de message peut être désactivé à l'aide des commandes MESSAGES ON et MESSAGES OFF. Si le thermomètre de progression est affiché, l'utilisateur peut cliquer sur le bouton Stop pour interrompre l'opération. Si la recherche s'est correctement déroulée, la variable système OK prend la valeur 1. Sinon, si la recherche est interrompue, OK prend la valeur 0 (zéro).
• Si des champs objet indexés sont spécifiés, la recherche est optimisée à chaque fois que c'est possible (la recherche commence par les champs indexés), réduisant au maximum la durée de l'opération.

Les dates sont stockées dans les objets en fonction des paramètres de la base ; par défaut, la timezone est prise en compte (voir le sélecteur JSON use local time dans la commande SET DATABASE PARAMETER).

!1973-05-22! -> "1973-05-21T23:00:00.000Z"

Ce paramétrage est également respecté durant les recherches, donc vous n'avez pas à vous en préoccuper si vous utilisez toujours votre base dans la même zone et si les paramètres sont identiques sur chaque machine qui accède aux données. Dans ce contexte, la recherche suivante retournera bien les enregistrements dont l'attribut Anniversaire est égal à !1973-05-22! (stocké "1973-05-21T23:00:00.00Z") :

Si vous ne souhaitez pas utiliser le paramétrage GMT, vous pouvez exécuter l'instruction suivante :

Attention, la portée de ce paramètre est limitée au process. Si vous exécutez cette instruction, le 1er Octobre 1965 sera stocké "1965-10-01T00:00:00.000Z" mais vous devrez fixer le même paramètre avant de lancer vos recherches :

Vous pouvez utiliser la propriété virtuelle "length" avec cette commande. Cette propriété est automatiquement disponible pour tous les attributs de type tableau, et retourne la taille du tableau, c'est-à-dire le nombre d'éléments qu'il contient. Elle peut être utilisée dans le contexte de l'exécution de la commande QUERY BY ATTRIBUTE (cf. exemple 4).

Dans cet exemple, l'attribut "age" est soit une chaîne soit un entier et nous souhaitons trouver les personnes dont l'âge est situé entre 20 et 29. Les deux premières lignes interrogent l'attribut en tant qu'entier (>=20 et < 30) et les suivantes interrogent l'attribut en tant que chaîne (débute par "2" mais est différent de "2").

La commande QUERY BY ATTRIBUTE peut être utilisée pour rechercher des enregistrements dans lesquels certains attributs sont définis (ou non définis). Pour cela, vous devez utiliser un objet vide : 

Note : Cette syntaxe spécifique n'est pas prise en charge avec les attributs de type tableau. La recherche de valeurs NULL dans les attributs de tableau donne des résultats invalides.

Vous voulez chercher un champ contenant des attributs tableaux. Avec les deux enregistrements suivants :

Enregistrement 1 :
[Personnes]nom : "martin"
[Personnes]OBFied :
    "locations" : [ {
                "kind":"office",
                "city":"paris"
            } ]

Enregistrement 2 :
[Personnes]nom : "smith"
[Personnes]OBFied :
    "locations" : [ {
                "kind":"home",
                "city":"lyon"
            } , {
                "kind":"office",
                "city":"paris"
            } ]

... QUERY BY ATTRIBUTE trouvera les personnes ayant une localisation à "paris" par cette recherche :

Note : Si vous avez défini plusieurs critères sur le même attribut tableau, les critères correspondants ne s'appliqueront pas nécessairement au même élément de tableau. Dans l'exemple ci-dessous, la recherche retournera "smith" car l'attribut a un élément "locations" dont le "kind" est "home" et un élément "locations" dont le "city" est "paris", même s'il ne s'agit pas du même élément :

Cet exemple illustre l'utilisation de la propriété virtuelle "length". Votre base de données comporte un champ objet [Customer]full_Data avec les données suivantes :

Vous souhaitez obtenir les enregistrements des clients qui ont deux enfants ou plus. Vous pouvez écrire :

Si la recherche est correctement effectuée, la variable système OK prend la valeur 1.
La variable OK prend la valeur 0 si :

• l'utilisateur clique sur le bouton Annuler / Stop,
• en mode 'recherche et verrouillage' (cf. commande SET QUERY AND LOCK), la recherche a trouvé au moins un enregistrement verrouillé. Dans ce cas également, l'ensemble système LockedSet est mis à jour.