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 Objet 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. 

Dans cheminAttribut, passez le nom ou le chemin de l'attribut dont vous souhaitez comparer les valeurs. Vous pouvez passer un attribut unique, par exemple "age" : dans ce cas, tous les attributs de ce nom seront comparés dans chaque enregistrement. Vous pouvez également passer un chemin, par exemple "enfants.filles.age", auquel cas seuls les attributs correspondant strictement seront comparés dans chaque enregistrement.
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).

Avec les champs objets, 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 :

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 :

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

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).

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 :

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 :