dataClass.query( )

4D v17.4

dataClass.query( )

Description

La méthode dataClass.query( ) recherche les entités répondant au(x) critère(s) de recherche spécifié(s) dans chaîneRecherche 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é.

Paramètre chaîneRecherche

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

cheminAttribut comparateur valeur {opérateurLogique cheminAttribut comparateur valeur}

où :

cheminAttribut : Nom de l'attribut de dataclass sur lequel vous souhaitez exécuter la recherche, par exemple "pays". Ce paramètre peut contenir tout 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.

Note : Vous ne pouvez pas rechercher des attributs dont les noms contiennent des caractères spéciaux tels que "." ou "[ ]" car ils ne seront pas correctement évalués dans la chaîne de recherche. Pour plus d'informations, veuillez consulter le paragraphe Identifiants de propriétés d'objets. De plus, les noms d'attributs ne peuvent pas contenir de symboles tels que "=", ">", "#", etc. qui peuvent être interprétés comme des comparateurs (voir ci-dessous).

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
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 paramètre :paramIndex (voir 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

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 :

"personne.nom = 'smith' AND personne.prenom = 'john'"

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 :

"(personne.age >= 30 OR personne.age <= 65) AND (personne.salaire <= 10000 OR personne.statut = 'Manager')"

Paramètre valeur (et placeholders)

Vous devez utiliser un ou plusieurs paramètre(s) valeur lorsque la recherche est construite à l'aide de placeholders. Les placeholders sont des marqueurs que vous insérez dans les chaînes de recherche et qui sont remplacés par une autre valeur au moment où la chaîne est évaluée. Vous pouvez utiliser jusqu'à 128 paramètres valeur.

Note : Les valeurs des placeholders peuvent également être passées sous forme de collection dans la propriété parameters du paramètre optionnel params (recherches avec entitySelection et dataClass uniquement). Pour plus d'informations, veuillez vous référer au paragraphe Paramètre params ci-dessous.

Dans chaîneRecherche, insérez :paramIndex pour chaque placeholder (ce qui signifie "utilise le paramètre paramIndex de la recherche comme valeur à comparer") puis passez la ou les valeur(s) requise(s) dans le ou les paramètre(s) valeur. Par exemple, pour rechercher les employés qui habitent Chicago et qui gagnent moins de $10 000, vous pouvez écrire :

"employee.city = :1 & employee.salary < :2"; "Chicago";10000

La valeur est évaluée une fois au début de la recherche ; elle n'est pas évaluée pour chaque élément.

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

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.
Cela résout les questions liées au formatage des valeurs ou des caractères. De plus, 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 :

$vSingles:=ds.Person.query("spouse = :1";Null) // n'aboutira pas

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 :

$vSingles:=ds.Person.query("spouse = null") //syntaxe valide

Paramètre params

Note : Ce paramètre est pris en charge uniquement par les méthodes entitySelection.query( ) et dataClass.query( ).

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

Propriété	Type	Description
parameters	Collection	Valeurs à comparer lorsque vous utilisez des placeholders dans la chaîneRecherche (autre moyen de passer des valeurs aux placeholders). Si des valeurs ont également été passées directement via les paramètres valeur, celles de parameters sont ajoutées à la séquence de placeholders.
queryPlan	Booléen	Dans la sélection d'entités résultante, retourne ou non la description détaillée de la recherche juste avant son exécution, i.e. le plan de la recherche. La valeur de propriété retournée est un objet qui inclut le plan de chaque requête et sous-requête (dans le cas d'une recherche complexe). Cette option est utile durant la phase de mise au point d'une application. Elle est généralement utilisée conjointement à queryPath. Valeur par défaut si omis : faux
queryPath	Booléen	Dans la sélection d'entités résultante, retourne ou non la description détaillée de la recherche telle qu'elle a réellement été exécutée. La valeur de propriété retournée est un objet qui inclut le chemin réel utilisé pour la recherche (généralement identique à celui du queryPlan, mais peut différer si le moteur a effectué une optimisation de la recherche), ainsi que la durée de traitement et le nombre d'entités trouvées. Cette option est utile durant la phase de mise au point d'une application. Valeur par défaut si omis : faux

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 :

 $sel:=ds.Employee.query("salary < :1 and employer.name = :2 or employer.revenues > :3";50000;"Lima West Kilo";10000000;Creer objet("queryPath";Vrai;"queryPlan";Vrai))

queryPlan:

{Or:[{And:[{item:[index : Employee.salary ] < 50000},{item:Join on Table : Company  :  Employee.employerID = Company.ID,subquery:[{item:[index : Company.name ] = Lima West Kilo}]}]},{item:Join on Table : Company  :  Employee.employerID = Company.ID,subquery:[{item:[index : Company.revenues ] > 10000000}]}]}

queryPath:

{steps:[{description:OR,time:63,recordsfounds:1388132,steps:[{description:AND,time:32,recordsfounds:131,steps:[{description:[index : Employee.salary ] < 50000,time:16,recordsfounds:728260},{description:Join on Table : Company  :  Employee.employerID = Company.ID,time:0,recordsfounds:131,steps:[{steps:[{description:[index : Company.name ] = Lima West Kilo,time:0,recordsfounds:1}]}]}]},{description:Join on Table : Company  :  Employee.employerID = Company.ID,time:31,recordsfounds:1388132,steps:[{steps:[{description:[index : Company.revenues ] > 10000000,time:0,recordsfounds:933}]}]}]}]}

Exemples

Voici divers exemples de recherches valides.

Recherche standard avec placeholders :

 $entitySelection:=dataClass.query("(firstName = :1 or firstName = :2) and (lastName = :3 or lastName = :4)";"D@";"R@";"S@";"K@")

Recherche standard sans placeholders :

$entitySelection :=dataClass.query("firstName = 'S@'")

Recherche avec une dataClass liée :

$entitySelection:=dataClass.query("lastName = :1 and manager.lastName = :2";"M@";"S@")

Recherche avec objets queryPlan et queryPath :

 $entitySelection:=dataClass.query("(firstName = :1 or firstName = :2) and (lastName = :3 or lastName = :4)";"D@";"R@";"S@";"K@";Creer objet("queryPlan";Vrai;"queryPath";Vrai))

 

  //vous pouvez ensuite récupérer ces propriétés dans la sélection d'entités résultante :

 C_OBJET($queryPlan;$queryPath)

 $queryPlan:=$entitySelection.queryPlan

 $queryPath:=$entitySelection.queryPath

Recherche avec placeholders et des valeurs passées dans une collection :

 $params:=Creer objet

 $params.parameters:=Creer collection("D@";"R@";"S@";"K@")

 $entitySelection:=dataClass.query("(firstName = :1 or firstName = :2) and (lastName = :3 or lastName = :4)";$params)

Recherche avec instruction NOT :

$entitySelection:=dataClass.query("not(firstName=Kim)")

Recherche avec un chemin d'attribut de type Collection :

$entitySelection:=dataClass.query("additionalInfo.hobbies[].name = horsebackriding")

Recherche avec un chemin d'attribut de type Objet :

$entitySelection:=ds.Employee.query("extra.eyeColor = :1";"blue")

Recherche avec instruction IN :

$entitySelection:=dataClass.query("firstName in :1";Creer collection("Kim";"Dixie"))

Recherche avec instruction NOT (IN) :

$entitySelection:=ds.Employee.query("not (firstName in :1)";Creer collection("John";"Jane"))

Recherches avec une date :

 $entitySelection:=dataClass.query("birthDate > :1";"1970-01-01")

 $entitySelection:=dataClass.query("birthDate <= :1";Date du jour-10950)

Voir aussi

collection.query( )
dataClass.all( )
dataClass.newSelection( )
entitySelection.query( )
entitySelection.queryPath
entitySelection.queryPlan