dataClass.query( )

La méthode dataClass.query( ) recherche les entités répondant au(x) critère(s) de recherche spécifié(s) dans chaîneRecherche ou formule et (optionnellement) valeur, parmi toutes les entités de la dataclass, et retourne un nouvel objet du type EntitySelection contenant toutes les entités trouvées. Le lazy loading est appliqué.

Si aucune entité n'est trouvée, un objet EntitySelection vide est retourné.

Le paramètre chaîneRecherche doit respecter la syntaxe suivante :

où :

• cheminAttribut : Chemin de l'attribut sur lequel vous souhaitez exécuter la recherche. Ce paramètre peut contenir un nom simple (par exemple "pays") ou un chemin d'attribut valide (par exemple "pays.nom"). Dans le cas d'un chemin d'attribut de type Collection, la notation [ ] est utilisée pour gérer toutes les occurrences (par exemple "enfants[ ].age"). Vous pouvez également utiliser un texte d'exemple (ou placeholder) (voir ce-dessous).
  
  Note : Vous ne pouvez pas utiliser directement des attributs dont les noms contiennent des caractères spéciaux tels que ".", "[ ]", ou "=", ">", "#" etc., car ils ne seront pas correctement évalués dans la chaîne de recherche. Si vous souhaitez rechercher ces attributs, pensez à utiliser des textes d'exemple (placeholder) pour étendre une plage de caractères dans les chemins d'attribut (voir Paramètre valeur (et placeholders) ci-dessous).
  
  
• formule : Une formule valide (voir Formules) passée Texte dans ou Objet. La formule sera évaluée pour chaque entité traitée(*) et doit retourner une valeur booléenne. Dans la formule, l'entité est disponible via l'objet This.
  
  • Texte : la chaine de formule doit être précédée de la déclaration eval(), afin que l'analyseur de requêtes évalue l'expression correctement.
    Par exemple :
    
     "eval(length(This.lastname) >=30)"
    
    
  • Objet : l'objet formule est passé comme un placeholder (voir ci-dessous). La formule doit avoir été créée à l'aide des commandes Formula ou Formula from string. 

  (*) si la formule n'est pas le seul critère de recherche, le système d'optimisation des requêtes pourrait prioriser le traitement d'autres critères (ex : attributs indexés) et ainsi, la formule serait évaluée uniquement pour un sous-ensemble d'entités. 

  Les formules contenues dans les requêtes peuvent recevoir des paramètres via $1. Ce point est détaillé dans le paragraphe Paramètre formule ci-dessous.

  Notes : 
  - Vous pouvez également passer directement un paramètre formule au lieu d'un paramètre chaîneRecherche (recommandé lorsque les formules sont plus complexes). Voir le paragraphe Paramètre formule ci-dessous. 
  - Pour des raisons de sécurité, il est possible de désactiver les appels de formules dans les méthodes membres query(). Voir la description du paramètre chaîneRecherche. 

• comparateur : symbole d'opérateur utilisé pour comparer cheminAttribut et valeur. Les symboles suivants sont pris en charge :
  

  Comparaison	Symbole(s)	Commentaire
  Egal à	=, ==	Retourne les données correspondantes, prend en charge le joker de recherche (@), ne tient pas compte de la casse et est non diacritique.
  	===, IS	Retourne les données correspondantes, considère le @ comme un caractère standard, ne tient pas compte de la casse et est non diacritique.
  Différent de	#, !=	Prend en charge le joker de recherche (@)
  	!==, IS NOT	Considère le @ comme un caractère standard
  Inférieur à	<
  Supérieur à	>
  Inférieur ou égal à	<=
  Supérieur ou égal à	>=
  Inclus parmi	IN	Retourne les données égales à au moins une des valeurs d'une collection ou d'un ensemble de valeurs, prend en charge le joker de recherche (@)
  Condition Not appliquée à une assertion	NOT	Les parenthèse sont obligatoires lorsque NOT est utilisé devant une assertion contenant plusieurs opérateurs
  Contient mot-clé	%	Les mots-clés peuvent être définis dans les attributs de type texte ou image

• valeur : valeur à comparer à la valeur courante de la propriété (attribut) de chaque entité de la sélection ou élément de la collection. Peut être toute expression de même type que la propriété ou un texte d'exemple (placeholder) (voir Paramètre valeur (et placeholders) ci-dessous).
  Les valeurs constantes doivent être saisies entre apostrophes dans la chaîne de recherche. Les mots-clés suivants sont interdits sous forme de constante : true, false. Vous pouvez comparer la valeur Null dans une recherche en utilisant le mot-clé "null". La recherche trouvera les propriétés ayant la valeur null et indéfinie. 
  Pour rechercher une chaîne dans une chaîne (recherche de type "contient"), utilisez le symbole joker (@) dans valeur pour isoler la chaîne à chercher, comme dans cet exemple : "@Smith@".
  Pour les valeurs numériques, les décimales doivent être séparées par un '.' (point). Les dates doivent être passées dans le format "AAAA-MM-JJ".
  Dans le cas d'une recherche avec un comparateur IN, valeur doit être une collection, ou des valeurs du même type que les données du chemin d'attribut, fournies entre [ ] et séparées par des virgules (pour les chaînes, les caractères " doivent être échappés avec des "\").

• opérateurLogique : utilisé pour relier des conditions multiples dans la recherche (optionnel). Vous pouvez utiliser un des opérateurs logiques suivants (le nom ou le symbole peut être passé) :
  

  Conjonction	Symbole(s)
  AND	&, &&, and
  OR	|, ||, or

  
  
  
• trier par cheminAttribut : vous pouvez inclure une déclaration trier par cheminAttribut dans la requête afin que les données résultantes soient triées selon cette déclaration. Vous pouvez utiliser plusieurs tris par déclaration, en les séparant par des virgules (ex : trier par cheminAttribut1 decroiss, cheminAttribut2 croiss). Par défaut, l'ordre est croissant. Par défaut, le tri est par ordre croissant. Passez 'decroiss' pour définir un tri par ordre décroissant et 'croiss' pour définir un tri par ordre croissant. 
  Note : Si vous utilisez cette déclaration, la sélection d'entité retournée est ordonnée (pour plus d'informations, veuillez consulter Sélections d'entités triées vs Sélections d'entités non-triées).  

Utilisation des guillemets/apostrophes
Lorsque vous utilisez des guillemets dans les recherches, vous devez utiliser des apostrophes ' ' à l'intérieur des requêtes et des guillemets " " pour encadrer la recherche complète, sinon une erreur est générée. Par exemple :

Note : Les guillemets simples ne sont pas pris en charge dans les valeurs recherchées car ils casseraient la chaîne de recherche.
Par exemple, "comp.name = 'John's pizza' " génèrera une erreur. Si vous devez rechercher des valeurs contenant des guillemets simples, il est nécessaire d'utiliser des placeholders (voir ci-dessous).

Utilisation des parenthèses
Vous pouvez utiliser des parenthèses dans la recherche afin de prioriser les calculs. Par exemple, vous pouvez organiser une recherche de la manière suivante :

Au lieu d'insérer une formule dans le paramètre chaîneRecherche (voir ci-dessus), vous pouvez directement passer un objet formule en tant que critère de recherche booléen. L'utilisation d'un objet formule pour les requêtes est recommandée car vous bénéficiez d'une tokénisation et car il est plus facile de rechercher/lire du code.

La formule doit avoir été créée à l'aide de la commande Formula ou Formula from string. Dans ce cas :

• la formule est évaluée pour chaque entité et doit renvoyer vrai ou faux. Lors de l'exécution de la requête, si le résultat de la formule n'est pas un booléen, il est considéré comme faux.
• dans la formule, l'entité est disponible via l'objet This.  
• Si l'objet formule est null, l'erreur 1626 ("Attente d'un texte ou d'une formule") est générée, ce qui signifie que vous pouvez intercepter à l'aide d'une méthode installée avec ON ERR CALL.

Note : Pour des raisons de sécurité, les appels de formule dans les méthodes membres query() peuvent être interdits. Voir la description du paramètre params.

Passer des paramètres à des formules

Toute formule appelée par la méthode membre query() peut recevoir des paramètres :

• Les paramètres doivent être passés via la propriété args (objet) du paramètre params.
• La formule reçoit cet objet args en tant que paramètre $1.

Ce code montre comment les paramètres sont passés aux méthodes :

Des exemples supplémentaires sont fournis dans l'exemple 3.

4D Server : En mode client/serveur, les formules sont exécutées sur le serveur. Dans ce contexte, seul l'objet querySettings.args est envoyé aux formules.

4D vous permet d'utiliser des placeholders pour les arguments cheminAttribut et valeur du paramètre params. Un placeholder est un paramètre que vous insérez dans des chaines de recherche et qui est remplacé par une autre valeur au moment où la chaîne de recherche est évaluée. La valeur des placeholders est évaluée une seule fois, au début de la requête; elle n'est pas évaluée pour chaque élément.

Il existe deux types de placeholders : les placeholders indexés et les placeholders nommés.

-	Placeholders indexés	Placeholders nommés
Définition	Les paramètres sont insérés comme : paramIndex (par exemple :1, :2...) dans chaîneRecherche et leurs valeurs sont fournies par la séquence du/des paramètre(s) valeur. Vous pouvez utiliser jusqu'à 128 paramètres valeur	Les paramètres sont insérés comme : paramName (par exemple :myparam) et leurs valeurs sont fournies dans les objets attributes et/ou parameters dans le paramètre params.
Exemple	$r:=class.query(":1=:2";"city";"Chicago")	$o.attributes:=New object("att";"city")   $o.parameters:=New object("name";"Chicago")   $r:=class.query(":att=:name";$o)

Vous pouvez combiner tous les types d'arguments dans chaîneRecherche. Une chaîneRecherche peut contenir, en termes de paramètres cheminAttribut et valeur : 

• des valeurs directes (pas de placeholders)
• des placeholders indexés et.ou nommés

Utiliser des placeholders dans les recherches est recommandé pour deux raisons :

1. Cela empêche l'injection de code malveillant : si vous utilisez dans la chaîne de recherche des variables dont le contenu provient directement de la saisie de l'utilisateur, celui-ci pourrait modifier les conditions de recherche en saisissant des arguments de recherche supplémentaires. Par exemple, imaginez une chaîne de recherche du type :
   
    $vquery:="statut = 'public'  &  nom = "+myname //l'utilisateur saisit son nom
 $result:=$col.query($vquery)
   
   Cette recherche semble sécurisée puisque les données non publiques sont filtrées. Cependant, si l'utilisateur saisit dans la zone myname : "smith OR status='private', la chaîne de recherche sera modifiée à l'étape de l'interprétation et pourra retourner des données privées.
   Lorsque vous utilisez des placeholders, le contournement des options de sécurité n'est pas possible :
   
    $result:=$col.query("statut='public'  &  nom=:1";myname)
   
   Dans ce cas, si l'utilisateur saisit smith OR status='private' dans la zone myname, cela ne sera pas interprété dans la chaîne de recherche, mais uniquement passé en tant que valeur. La recherche d'une personne nommée "smith OR status='private"' échouera simplement.
2. Cela résout les questions liées au formatage des valeurs ou des caractères, notamment lorsque vous gérez les paramètres cheminAttribut et valeur qui peuvent continir des caractères qui ne sont pas alphanumériqus tels que ".", "["...
3. Cela permet l'utilisation de variables ou d'expressions dans les arguments de recherche. Par exemple :
   
    $result:=$col.query("address.city = :1  &  name =:2";$city;$myVar+"@")
 $result2:=$col.query("company.name = :1";"John's Pizzas")

 

Recherche de valeurs null
Lorsque vous recherchez les valeurs null, vous ne pouvez pas utiliser la syntaxe placeholder car le moteur de recherche considère la valeur null comme une valeur de comparaison invalide. Par exemple, si vous exécutez la recherche suivante :

Vous n'obtiendrez pas le résultat souhaité car la valeur null sera évaluée par 4D comme une erreur résultant de l'évaluation du paramètre (pouvant être, par exemple, un attribut provenant d'une autre recherche). Pour ce type de recherches, vous devez utiliser la syntaxe de recherche directe :

Dans le paramètre params, vous pouvez passer un objet contenant des options supplémentaires. Vous pouvez utiliser les propriétés suivantes :

Property	Type	Description
parameters	Objet	Placeholders nommés pour les valeurs utilisées dans in the chaîneRecherche. Les valeurs sont exprimées sous forme de paires propriété / valeur, où propriété est le nom du placeholder inséré pour une valeur, dans la chaîneRecherche (":placeholder") et où valeur correspond à la valeur à comparer. Vous pouvez combiner, dans la même recherche, les valeurs des placeholders indexés (valeurs passées directement dans les paramètres valeur) et les valeurs des placeholders nommés.
attributes	Objet	Placeholders nommés pour les chemins d'attribut utilisés dans used in the chaîneRecherche. Les attributs sont exprimés sous forme de paires propriété / valeur, où propriété est le nom du placeholder inséré pour un chemin d'attribut dans la chaîneRecherche (":placeholder") et où valeur peut être une chaine ou une collection de chaines. Chaque valeur correspond à un chemin qui peut être désigné soit par un attribut scalaire ou relatif de la dataclass soit par une propriété d'un champ objet de la dataclass Type Description String cheminAttribut exprimé à l'aide de la notation par point, ex : "name" ou "user.address.zipCode" Collection de chaînes Chaque chaine de la collection représente un niveau de cheminAttribut, ex : ["name"] ou ["user","address","zipCode"]. L'utilisation d'une collection permet de rechercher des attributs dont les noms ne sont pas conformes à la notation, ex : ["4Dv17.1","en/fr"] Vous pouvez combiner les valeurs des placeholders indexés (valeurs passées directement dans les paramètres valeur) et les valeurs des placeholders nommés dans la même recherche.
context	Texte	Nom du contexte d'optimisation automatique appliqué à la sélection d'entités. Ce contexte sera utilisé par le code qui gère la sélection d'entités afin de bénéficier de l'optimisation. Cette fonctionnalité est conçue pour le traitement client/serveur ; pour plus d'informations, veuillez vous reporter à la section Optimisation client/serveur .
queryPlan	Booléen	Dans la sélection d'entités résultante, retourne ou ne retourne la description détaillée de la recherche juste avant d'être exécutée, i.e. la recherche programmée. La propriété retournée est un objet qui inclut chaque recherche et sous-recherche programmée (dans le cas d'une recherche complexe). Cette option est utile durant la phase de développement d'une application. Elle est utilisée conjointement à queryPath. Par défaut, si elle est omise : faux. Note : Cette propriété est prise en charge uniquement par les méthodes entitySelection.query( ) et dataClass.query( ).
queryPath	Booléen	Dans la sélection d'entités résultante, retourne ou ne retourne pas la description détaillée de la recherche telle qu'elle est effectuée. La propriété retournée est un objet qui contient le chemin utilisé pour la recherche (généralement identique à celui de queryPlan, mais il peut être différent si le moteur parvient à optimiser la recherche), l'heure du traitement et le nombre d'enregistrements trouvés. Cette option est utile durant la phase de développement d'une application. Par défaut, si elle est omise : faux. Note : Cette propriété est prise en charge uniquement par les méthodes entitySelection.query( ) et dataClass.query( ).

A propos du queryPlan et du queryPath 

Les informations enregistrées dans le queryPlan et le queryPath incluent le type de recherche (indexée ou séquentielle), chaque sous-recherche nécessaire, ainsi que les opérateurs de conjonction. Le queryPath contient également le nombre d'entités trouvées et le temps nécessaire à l'exécution de chaque critère de recherche. Il vous sera utile d'analyser ces informations lors du développement de vos applications. Généralement, les descriptions du plan et du chemin de recherche sont identiques mais elles peuvent différer car 4D peut mettre en oeuvre des optimisations dynamiques lors de l'exécution de la recherche, afin d'améliorer les performances. Par exemple, le moteur de recherche de 4D peut convertir dynamiquement une recherche indexée en recherche séquentielle s'il estime qu'elle s'exécutera plus rapidement. Ce cas particulier peut se produire lorsque le nombre d'entités parmi lesquelles la recherche est effectuée est limité.

Par exemple, si vous exécutez la recherche suivante :

queryPlan:

queryPath:

Cette section fournit divers exemples de recherches.

Recherche dans une chaîne :

Recherche avec une instruction NOT :

Recherche avec des dates :

Recherche avec des placeholders indexés pour les valeurs :

Recherche avec des placeholders indexés pour les valeurs sur une dataClass liée :

Recherche avec des placeholders nommés pour les valeurs :

Recherche utilisant les placeholders nommés et indexés pour les valeurs :

Recherche avec objets queryPlan et queryPath :

Recherche avec un chemin d'attribut de type Collection :

Recherche avec un chemin d'attribut de type Objet :

Recherche avec instruction IN :

Recherche avec instruction NOT (IN) :

Recherche avec des placeholders indexés pour les attributs : 

Recherche avec des placeholders indexés pour les attributs et avec des placeholders nommés pour les valeurs :

Recherche avec des placeholders indexés pour les attributs et les valeurs :

Cette section illustre les recherches avec des placeholders nommés pour les attributs. 

Considérons une dataclass Employee avec 2 entités :

• Entity 1:
  name: "Marie"
  number: 46
  softwares:{
  "Word 10.2": "Installé",
  "Excel 11.3": "A mettre à jour",
  "Powerpoint 12.4": "Pas installé"
  }
• Entity 2
  name: "Sophie"
  number: 47
  softwares:{
  "Word 10.2": "Pas installé",
  "Excel 11.3": "A mettre à jour",
  "Powerpoint 12.4": "Pas installé" 
  }

Recherche avec des placeholders nommés pour les attributs :

Recherche avec des placeholders nommés pour les attributs et les valeurs :