Version: 19

EntitySelection

Une entity selection est un objet contenant une ou plusieurs référence(s) à des entités appartenant à la même Dataclass. Une entity selection peut contenir 0, 1 ou X entités de la dataclass - où X peut représenter le nombre total d'entités contenues dans la dataclass.

Les entity selections peuvent être créées à partir de sélections existantes à l'aide de diverses fonctions de la classe DataClass telles que .all() ou .query(), ou de la classe EntityClass elle-même, telles que .and() ou orderBy(). Vous pouvez également créer des entity selections vides à l'aide de la fonction dataClass.newSelection() ou de la commande Create new selection.

Sommaire


[index] : 4D.Entity vous permet d'accéder aux entités de l'entity selection en utilisant la syntaxe standard de collection
.attributeName : Collection .attributeName : 4D.EntitySelection une "projection" des valeurs de l'attribut dans l'entity selection
.add( entity : 4D.Entity ) : 4D.EntitySelection ajoute l'entity spécifiée à l'entity selection et retourne l'entity selection modifiée
.and( entity : 4D.Entity ) : 4D.EntitySelection .and( entitySelection : 4D.EntitySelection ) : 4D.EntitySelection combine l'entity selection avec le paramètre entity ou entitySelection à l'aide de l'opérateur logique ET
.average( attributePath : Text ) : Real retourne la moyenne arithmétique de toutes les valeurs non nulles de attributePath dans l'entity selection
.contains( entity : 4D.Entity ) : Boolean retourne vrai si la référence d'entité appartient à l'entity selection
.copy( { option : Integer } ) : 4D.EntitySelection retourne une copie de l'entity selection d'origine
.count( attributePath : Text ) : Real retourne le nombre d'entités dans l'entity selection pour lesquelles la valeur de attributePath n'est pas null
.distinct( attributePath : Text { ; option : Integer } ) : Collection renvoie une collection contenant uniquement les valeurs distinctes (différentes) de attributePath dans l'entity selection
.drop( { mode : Integer } ) : 4D.EntitySelection supprime les entités appartenant à l'entity selection de la table liée à sa dataclass
.extract( attributePath : Text { ; option : Integer } ) : Collection .extract( attributePath { ; targetPath } { ; ...attributePathN : Text ; targetPathN : Text } ) : Collection retourne une collection contenant les valeurs attributePath extraites de l'entity selection
.first() : 4D.Entity retourne une référence vers l'entité en première position dans l'entity selection
.getDataClass() : 4D.DataClass retourne la dataclass de l'entity selection
.isAlterable() : Boolean retourne Vrai si l'entity selection est modifiable (altérable)
.isOrdered() : Boolean retourne Vrai si l'entity selection est triée
.last() : 4D.Entity retourne une référence vers l'entité en dernière position dans l'entity selection
.length : Integer retourne le nombre d'entités dans l'entity selection
.max( attributePath : Text ) : any retourne la plus haute valeur (ou valeur maximale) parmi toutes les valeurs de attributePath dans l'entity selection
.min( attributePath : Text ) : any retourne la plus faible valeur (ou valeur minimale) parmi toutes les valeurs de attributePath dans l'entity selection
.minus( entity : 4D.Entity ) : 4D.EntitySelection .minus( entitySelection : 4D.EntitySelection ) : 4D.EntitySelection exclut de l'entity selection à laquelle elle est appliquée l'entity ou les entités de l'entitySelection et retourne l'entity selection résultante
.or( entity : 4D.Entity ) : 4D.EntitySelection .or( entitySelection : 4D.EntitySelection ) : 4D.EntitySelection combine l'entity selection avec le paramètre entity ou entitySelection à l'aide de l'opérateur OU logique (non exclusif)
.orderBy( pathString : Text ) : 4D.EntitySelection .orderBy( pathObjects : Collection ) : 4D.EntitySelection renvoie une nouvelle entity selection triée contenant toutes les entités de l'entity selection dans l'ordre spécifié par le paramètre pathString ou pathObjects
.orderByFormula( formulaString : Text { ; sortOrder : Integer } { ; settings : Object} ) : 4D.EntitySelection .orderByFormula( formulaObj : Object { ; sortOrder : Integer } { ; settings : Object} ) : 4D.EntitySelection renvoie une nouvelle entity selection triée
.query( queryString : Text { ; ...value : any } { ; querySettings : Object } ) : 4D.EntitySelection .query( formula : Object { ; querySettings : Object } ) : 4D.EntitySelection recherche les entités répondant aux critères de recherche spécifiés dans queryString ou formula et (optionnellement) dans value(s) parmi toutes les entités de l'entity selection
.queryPath : Text contient une description détaillée de la requête telle qu'elle a été effectuée par 4D
.queryPlan : Text contient une description détaillée de la requête juste avant son exécution (c'est-à-dire, la requête planifiée)
.refresh() "invalide" immédiatement les données de l'entity selection dans le cache local d'ORDA
.slice( startFrom : Integer { ; end : Integer } ) : 4D.EntitySelection retourne une partie d'une entity selection dans une nouvelle entity selection
.sum( attributePath : Text ) : Real renvoie la somme de toutes les valeurs de attributePath dans l'entity selection
.toCollection( { options : Integer { ; begin : Integer { ; howMany : Integer } } ) : Collection .toCollection( filterString : Text {; options : Integer { ; begin : Integer { ; howMany : Integer }}} ) : Collection .toCollection( filterCol : Collection {; options : Integer { ; begin : Integer { ; howMany : Integer }}} ) : Collection crée et retourne une collection dans laquelle chaque élément est un objet contenant un ensemble de propriétés et de valeurs

Create entity selection

Create entity selection ( dsTable : Table { ; settings : Object } ) : 4D.EntitySelection

Paramètres	Type		Description
dsTable	Table	->	Table de la base 4D dont la sélection courante doit être utilisée pour construire l'entity selection
settings	Object	->	Option de création : contexte
Résultat	4D.EntitySelection	<-	Nouvelle entity selection liée à la dataclass de la table

Description

La commande Create entity selection construit et retourne une nouvelle entity selection altérable liée à la dataclass correspondant à la table dsTable, basée sur la sélection courante de cette table.

Si la sélection courante est triée, une entity selection triée est créée (l'ordre de la sélection courante est conservé). Si la sélection courante n'est pas triée, une entity selection non-triée est créée.

Si la table dsTable n'est pas exposée dans ds, une erreur est retournée. Cette commande ne peut pas être utilisée avec un datastore distant.

Dans le paramètre optionnel settings, vous pouvez passer un objet contenant la propriété suivante :

Propriété	Type	Description
context	Text	Nom du contexte d'optimisation appliqué à l'entity selection.

Exemple

var $employees : cs.EmployeeSelection
ALL RECORDS([Employee])
$employees:=Create entity selection([Employee]) 
// L'entity selection $employees contient maintenant un ensemble de 
// références vers toutes les entités de la dataclass Employee

Voir également

dataClass.newSelection()

[index]

Historique

Release	Modifications
17	Ajout

[index] : 4D.Entity

Description

La notation EntitySelection[index] vous permet d'accéder aux entités de l'entity selection en utilisant la syntaxe standard de collection: il vous suffit de passer la position de l'entité à laquelle vous souhaitez accéder dans le paramètre index.

A noter que l'entité correspondante est rechargée depuis le datastore.

index peut être tout nombre compris entre 0 et .length-1.

Si index est en-dehors de ces limites, une erreur est retournée.
Si index correspond à une entité supprimée, une valeur Null est retournée.

Attention : EntitySelection[index] est une expression non assignable, ce qui signifie qu'elle ne peut pas être utilisée comme référence modifiable d'entité avec des fonctions telles que .lock() ou .save(). Pour travailler avec l'entité correspondante, vous devez assigner l'expression retournée à une expression assignable, comme une variable. Exemples :

 $sel:=ds.Employee.all() //creation de l'entity selection
  //code invalide:
 $result:=$sel[0].lock() //ne fonctionnera PAS
 $sel[0].lastName:="Smith" //ne fonctionnera PAS
 $result:=$sel[0].save() //ne fonctionnera PAS
  //code valide :
 $entity:=$sel[0]  //OK
 $entity.lastName:="Smith" //OK
 $entity.save() //OK

Exemple

 var $employees : cs.EmployeeSelection
 var $employee : cs.EmployeeEntity
 $employees:=ds.Employee.query("lastName = :1";"H@")
 $employee:=$employees[2]  // La 3e entité de l'entity selection $employees est rechargée depuis le datastore

.attributeName

Historique

Release	Modifications
17	Ajout

.attributeName : Collection
.attributeName : 4D.EntitySelection

Description

Tout attribut de dataclass peut être utilisé en tant que propriété d'une entity selection afin de retourner une "projection" des valeurs de l'attribut dans l'entity selection. Les valeurs projetées peuvent être une collection ou une nouvelle entity selection, en fonction du kind (storage ou relation) de l'attribut.

Si le "kind" de attributeName est storage : .attributeName retourne une collection de valeurs du même type que attributeName.
Si le "kind" de attributeName est relatedEntity : .attributeName retourne une nouvelle entity selection de valeurs liées du même type que attributeName. Les doublons sont supprimés (une entity selection non ordonnée est retournée).
Si le "kind" de attributeName est relatedEntities : .attributeName retourne une nouvelle entity selection de valeurs liées du même type que attributeName. Les doublons sont supprimés (une entity selection non ordonnée est retournée).

Lorsqu'un attribut relationnel est utilisé comme propriété d'une entity selection, le résultat est toujours une autre entity selection, même si une seule entité est retournée. Dans ce cas, si aucune entité n'est renvoyée, le résultat est une sélection d'entités vide.

Si l'attribut n'existe pas dans l'entity selection, une erreur est retournée.

Exemple 1

Projection de valeurs de stockage :

 var $firstNames : Collection
 $entitySelection:=ds.Employee.all()
 $firstNames:=$entitySelection.firstName // firstName est un texte

Le résultat est une collection de chaînes, par exemple :

[
    "Joanna",
    "Alexandra",
    "Rick"
]

Exemple 2

Projection d'entité liée :

 var $es; $entitySelection : cs.EmployeeSelection
 $entitySelection:=ds.Employee.all()
 $es:=$entitySelection.employer // employer est lié à la dataclass Company

L'objet résultant est une entity selection de la dataclass Company sans doublons (s'il y en a).

Exemple 3

Projection d'entités liées :

 var $es : cs.EmployeeSelection
 $es:=ds.Employee.all().directReports // directReports est récursif et lié à la dataclass Employee

L'objet résultant est une entity selection de la dataclass Employee sans doublons (s'il y en a).

.add()

Historique

Release	Modifications
18 R5	Supporte uniquement les entity selections altérables
17	Ajout

.add( entity : 4D.Entity ) : 4D.EntitySelection

Paramètres	Type		Description
entity	4D.Entity	->	Entité à ajouter à l'entity selection
Résultat	4D.EntitySelection	<-	Entity selection incluant l'entity

Description

La fonction .add() ajoute l'entity spécifiée à l'entity selection et retourne l'entity selection modifiée.

Cette fonction modifie l'entity selection d'origine.

Attention : L'entity selection doit être altérable, c'est-à-dire qu'elle a été créée par exemple par .newSelection() ou Create entity selection, sinon .add() retournera une erreur. Les entity selections partageables n'acceptent pas l'ajout d'entités. Pour plus d'informations, reportez-vous au paragraphe Entity selections partageables ou altérables.

Si l'entity selection est ordonnée, le paramètre entity est ajouté à la fin de la sélection. Si une référence à la même entité appartient déjà à l'entity selection, elle est dupliquée et une nouvelle référence est ajoutée.
Si l'entity selection est non ordonnée, le paramètre entity est ajouté n'importe où dans la sélection, sans ordre spécifique.

Pour plus d'informations, reportez-vous au paragraphe Entity selections triées ou non triées.

L'entity selection modifiée est retournée par la fonction, afin que les appels vers la fonction puissent être chaînés.

Une erreur est générée si entity et l'entity selection ne sont pas liées à la même dataclass. Si entity est Null, aucune erreur n'est générée.

Exemple 1

 var $employees : cs.EmployeeSelection
 var $employee : cs.EmployeeEntity
 $employees:=ds.Employee.query("lastName = :1";"S@")
 $employee:=ds.Employee.new()
 $employee.lastName:="Smith"
 $employee.save()
 $employees.add($employee) //L'entité $employee est ajoutée à l'entity selection $employees

Exemple 2

Les appels vers la fonction peuvent être chaînés :

 var $sel : cs.ProductSelection
 var $p1;$p2;$p3 : cs.ProductEntity

 $p1:=ds.Product.get(10)
 $p2:=ds.Product.get(11)
 $p3:=ds.Product.get(12)
 $sel:=ds.Product.query("ID > 50")
 $sel:=$sel.add($p1).add($p2).add($p3)

.and()

Historique

Release	Modifications
17	Ajout

.and( entity : 4D.Entity ) : 4D.EntitySelection
.and( entitySelection : 4D.EntitySelection ) : 4D.EntitySelection

Paramètres	Type		Description
entity	4D.Entity	->	Entité à intersecter
entitySelection	4D.EntitySelection	->	Entity selection à intersecter
Résultat	4D.EntitySelection	<-	Entity selection résultante de l'intersection à l'aide de l'opérateur logique ET

Description

La fonction and() combine l'entity selection avec le paramètre entity ou entitySelection à l'aide de l'opérateur logique ET; elle retourne une nouvelle entity selection non ordonnée qui ne contient que les entités qui sont référencées à la fois dans l'entity selection et le paramètre.

Si vous passez entity comme paramètre, vous combinez cette entité avec l'entity selection. Si l'entité appartient à l'entity selection, une nouvelle entity selection contenant uniquement l'entité est retournée. Sinon, une entity selection vide est retournée.
Si vous passez entitySelection comme paramètre, vous combinez les deux entity selections. Une nouvelle entity selection contenant uniquement les entités référencées dans les deux sélections est retournée. S'il n'y a pas d'intersection d'entité, une entity selection vide est retournée.

Vous pouvez comparer des entity selections ordonnées et/ou non ordonnées. La sélection résultante est toujours non ordonnée.

Si l'entity selection initiale ou celle du paramètre entitySelection est vide, ou si entity est Null, une entity selection vide est retournée.

Si l'entity selection initiale et le paramètre ne sont pas liés à la même dataclass, une erreur est retournée.

Exemple 1

 var $employees; $result : cs.EmployeeSelection
 var $employee : cs.EmployeeEntity
 $employees:=ds.Employee.query("lastName = :1";"H@")   
  //l'entity selection $employees contient l'entité
  //ayant la clé primaire 710 et d'autres entités
  //par ex. "Colin Hetrick" / "Grady Harness" / "Sherlock Holmes" (clé primaire 710)
 $employee:=ds.Employee.get(710) // Retourne "Sherlock Holmes"

 $result:=$employees.and($employee) //$result est une entity selection contenant
  //uniquement l'entité avec la clé primaire 710 ("Sherlock Holmes")

Exemple 2

Nous voulons obtenir une sélection d'employés nommés "Jones" qui vivent à New York :

 var $sel1; $sel2; $sel3 : cs.EmployeeSelection
 $sel1:=ds.Employee.query("name =:1";"Jones")
 $sel2:=ds.Employee.query("city=:1";"New York")
 $sel3:=$sel1.and($sel2)

.average()

Historique

Release	Modifications
18 R6	Retourne undefined si l'entity selection est vide
17	Ajout

.average( attributePath : Text ) : Real

Paramètres	Type		Description
attributePath	Text	->	Chemin de l'attribut à utiliser pour le calcul
Résultat	Real	<-	Moyenne arithmétique des valeurs des entités pour l'attribut (Undefined pour une entity selection vide)

Description

La fonction .average() retourne la moyenne arithmétique de toutes les valeurs non nulles de attributePath dans l'entity selection.

Passez dans le paramètre attributePath le chemin de l'attribut à utiliser pour le calcul.

Seules les valeurs numériques sont utilisées pour le calcul. Notez cependant que, lorsque le attributePath de l'entity selection contient des valeurs de types variés, .average() tient compte de tous les éléments contenant des valeurs scalaires pour calculer la moyenne.

Les valeurs de type Date sont converties en valeurs numériques (secondes) et utilisées pour calculer la moyenne.

.average() retourne undefined si l'entity selection est vide ou si attributePath ne contient pas de valeurs numériques.

Une erreur est retournée si :

attributePath est un attribut relatif,
attributePath désigne un attribut qui n'existe pas dans la dataclass de l'entity selection.

Exemple

Nous voulons obtenir la liste des employés dont le salaire est supérieur au salaire moyen :

 var $averageSalary : Real
 var $moreThanAv : cs.EmployeeSelection
 $averageSalary:=ds.Employee.all().average("salary")
 $moreThanAv:=ds.Employee.query("salary > :1";$averageSalary)

.contains()

Historique

Release	Modifications
17	Ajout

.contains( entity : 4D.Entity ) : Boolean

Paramètres	Type		Description
entity	4D.Entity	->	Entité à évaluer
Résultat	Boolean	<-	Vrai si l'entité appartient à l'entity selection, sinon Faux

Description

La fonction .contains() retourne vrai si la référence d'entité appartient à l'entity selection, et faux sinon.

Dans entity, spécifiez l'entité à rechercher dans l'entity selection. Si l'entité est Null, la fonction retournera faux.

Si entity et l'entity selection n'appartiennent pas à la même dataclass, une erreur est générée.

Exemple

 var $employees : cs.EmployeeSelection
 var $employee : cs.EmployeeEntity

 $employees:=ds.Employee.query("lastName=:1";"H@")
 $employee:=ds.Employee.get(610)

 If($employees.contains($employee))
    ALERT("L'entité ayant la clé primaire 610 a un nom commençant par H")
 Else
    ALERT("L'entité ayant la clé primaire 610 n'a pas un nom commençant par H")
 End if

.count()

Historique

Release	Modifications
17	Ajout

.count( attributePath : Text ) : Real

Paramètres	Type		Description
attributePath	Text	->	Chemin de l'attribut à utiliser pour le calcul
Résultat	Real	<-	Nombre de valeurs de attributePath non null dans l'entity selection

Description

La fonction .count() retourne le nombre d'entités dans l'entity selection pour lesquelles la valeur de attributePath n'est pas null.

Seules les valeurs scalaires sont prises en compte. Les valeurs de type objet ou collection sont considérées comme des valeurs null.

Une erreur est retournée si :

attributePath est un attribut relatif,
attributePath n'est pas trouvé dans la dataclass de l'entity selection.

Exemple

Nous voulons trouver le nombre total d'employés d'une entreprise sans compter ceux dont l'intitulé du poste n'a pas été défini :

 var $sel : cs.EmployeeSelection
 var $count : Real

 $sel:=ds.Employee.query("employer = :1";"Acme, Inc")
 $count:=$sel.count("jobtitle")

.copy()

Historique

Release	Modifications
18 R5	Ajout

.copy( { option : Integer } ) : 4D.EntitySelection

Paramètres	Type		Description
option	Integer	->	`ck shared` : retourne une entity selection partageable
Résultat	4D.EntitySelection	<-	Copie de l'entity selection

Description

La fonction .copy() retourne une copie de l'entity selection d'origine.

Cette fonction ne modifie pas l'entity selection d'origine.

Par défaut, si le paramètre option est omis, la fonction retourne une nouvelle entity selection non partageable (même si la fonction est appliquée à une entity selection partageable). Passez la constante ck shared dans le paramètre option si vous souhaitez créer une entity selection partageable.

Pour plus d'informations, reportez-vous au paragraphe Entity selections partageables ou altérables.

Exemple

Vous créez une nouvelle entity selection de produits, vide lorsque le formulaire est chargé :

 Case of
    :(Form event code=On Load)
       Form.products:=ds.Products.newSelection()
 End case

Cette entity selection est ensuite mise à jour avec les produits et vous souhaitez partager les produits entre plusieurs process. Copiez l'entity selection Form.products comme sélection partageable:

 ...
  // L'entity selection Form.products est mise à jour
 Form.products.add(Form.selectedProduct)

 Use(Storage)
    If(Storage.products=Null)
       Storage.products:=New shared object()
    End if

    Use(Storage.products)
       Storage.products:=Form.products.copy(ck shared)
    End use
 End use

.distinct()

Historique

Release	Modifications
17	Ajout

.distinct( attributePath : Text { ; option : Integer } ) : Collection

Paramètres	Type		Description
attributePath	Text	->	Chemin de l'attribut dont vous souhaitez obtenir les valeurs distinctes
option	Integer	->	`dk diacritical` : évaluation diacritique ("A" # "a" par exemple)
Résultat	Collection	<-	Collection avec seulement les valeurs distinctes

Description

La fonction .distinct() renvoie une collection contenant uniquement les valeurs distinctes (différentes) de attributePath dans l'entity selection.

La collection retournée est automatiquement triée. Les valeurs Null ne sont pas renvoyées.

Dans le paramètre attributePath passez l'attribut d'entité dont vous voulez obtenir les valeurs distinctes. Seules les valeurs scalaires (texte, nombre, booléen ou date) peuvent être gérées. Si attributePath mène à une propriété d'objet qui contient des valeurs de différents types, celles-ci sont d'abord regroupées par type et triées ensuite. Les types sont renvoyés dans l'ordre suivant :

booléens
chaînes
nombres
dates

Vous pouvez utiliser la notation [] pour désigner une collection lorsque attributePath est un chemin dans un objet (cf. exemples).

Par défaut, une évaluation non diacritique est effectuée. Si vous souhaitez que l'évaluation soit sensible à la casse ou pour différencier des caractères accentués et non-accentués, passez la constante dk diacritical dans le paramètre option.

Une erreur est retournée si :

attributePath est un attribut relatif,
attributePath n'est pas trouvé dans la dataclass de l'entity selection.

Exemples

Vous souhaitez obtenir une collection contenant un seul élément par nom de pays :

 var $countries : Collection
 $countries:=ds.Employee.all().distinct("address.country")

nicknames est une collection et extra est un attribut d'objet :

$values:=ds.Employee.all().distinct("extra.nicknames[].first")

.drop()

Historique

Release	Modifications
17	Ajout

.drop( { mode : Integer } ) : 4D.EntitySelection

Paramètres	Type		Description
mode	Integer	->	`dk stop dropping on first error` : stoppe l'exécution de la fonction au niveau de la première entité non-supprimable
Résultat	4D.EntitySelection	<-	Entity selection vide si exécutée avec succès, sinon entity selection contenant la ou les entité(s) non supprimée(s)

| | | |

Description

La fonction .drop() supprime les entités appartenant à l'entity selection de la table liée à sa dataclass. L'entity selection reste en mémoire.

La suppression d'entités est permanente et ne peut pas être annulée. Il est recommandé d'appeler cette action dans une transaction afin d'avoir une possibilité de récupération.

Si une entité verrouillée est rencontrée lors de l'exécution de .drop(), elle n'est pas supprimée. Par défaut, la fonction traite toutes les entités de l'entity selection et renvoie des entités non supprimables dans l'entity selection. Si vous souhaitez que la fonction arrête l'exécution au niveau de la première entité non supprimable rencontrée, passez la constante dk stop dropping on first error dans le paramètre mode.

Exemple

Exemple sans l'option dk stop dropping on first error :

 var $employees; $notDropped : cs.EmployeeSelection
 $employees:=ds.Employee.query("firstName=:1";"S@")
 $notDropped:=$employees.drop() // $notDropped est une entity selection contenant toutes les entités non supprimées
 If($notDropped.length=0) ///La suppression est un succès, toutes les entités ont été supprimées
    ALERT("Vous avez supprimé "+String($employees.length)+" employés") //L'entity selection supprimée reste en mémoire
 Else
    ALERT("Problème durant la suppression, réessayez plus tard")
 End if

Exemple avec l'option dk stop dropping on first error :

 var $employees; $notDropped : cs.EmployeeSelection
 $employees:=ds.Employee.query("firstName=:1";"S@")
 $notDropped:=$employees.drop(dk stop dropping on first error) //$notDropped est une entity selection contenant la première entité non supprimée
 If($notDropped.length=0) //La suppression est un succès, toutes les entités ont été supprimées
    ALERT("Vous avez supprimé "+String($employees.length)+" employés") //L'entity selection supprimée reste en mémoire
 Else
    ALERT("Problème durant la suppression, réessayez plus tard")
 End if

.extract()

Historique

Release	Modifications
18 R3	Ajout

.extract( attributePath : Text { ; option : Integer } ) : Collection
.extract( attributePath { ; targetPath } { ; ...attributePathN : Text ; targetPathN : Text } ) : Collection

Paramètres	Type		Description
attributePath	Text	->	Chemin d'attribut dont les valeurs doivent être extraites dans la nouvelle collection
targetPath	Text	->	Chemin ou nom d'attribut cible
option	Integer	->	`ck keep null` : inclure les attributs null dans la collection retournée (ignorés par défaut).
Résultat	Collection	<-	Collection contenant les valeurs extraites

Description

La fonction .extract() retourne une collection contenant les valeurs attributePath extraites de l'entity selection.

attributePath peut désigner :

un attribut scalaire de dataclass,
une entité liée,
des entités liées.

Si attributePath est invalide, une collection vide est retournée.

Cette fonction accepte deux syntaxes.

.extract( attributePath : Text { ; option : Integer } ) : Collection

Avec cette syntaxe, .extract() remplit la collection retournée avec des valeurs de attributePath de l'entity selection.

Par défaut, les entités pour lesquelles attributePath est null ou indéfini sont ignorées dans la collection résultante. Vous pouvez passer la constante ck keep null dans le paramètre option pour intégrer ces valeurs comme des éléments null dans la collection retournée.

Les attributs dataclass avec .kind = "relatedEntity" sont extraits sous forme de collection d'entités (les duplications sont conservées).
Les attributs dataclass avec .kind = "relatedEntities" sont extraits sous forme de collection d'entity selections.

.extract ( attributePath ; targetPath { ; ...attributePathN ; ... targetPathN}) : Collection

Avec cette syntaxe, .extract() remplit la collection retournée avec les valeurs de attributePath. Chaque élément de la collection retournée est un objet avec les propriétés targetPath complétées par les propriétés attributePath correspondantes. Les valeurs null sont conservées (le paramètre option est ignoré avec cette syntaxe).

Si plusieurs attributePath sont renseignés, un targetPath doit être fourni pour chacun. Seules les paires [attributePath, targetPath] valides sont extraites.

Les attributs dataclass avec .kind = "relatedEntity" sont extraits sous forme d'entity.
Les attributs dataclass avec .kind = "relatedEntities" sont extraits sous forme d'entity selection.

Les entités d'une collection d'entités auxquelles on accède par [ ] ne sont pas rechargées depuis la base de données.

Exemple

Considérons les tables et relations suivantes :

 var $firstnames; $addresses; $mailing; $teachers : Collection
  //
  //
  //$firstnames est une collection de Chaînes


 $firstnames:=ds.Teachers.all().extract("firstname")
  //
  //$addresses est une collection d'entités liées à la dataclass Address
  //Les valeurs null d'Address sont extraites
 $addresses:=ds.Teachers.all().extract("address";ck keep null)
  //
  //
  //$mailing est une collection d'objets avec les propriétés "who" et "to"
  //Le contenu de la propriété "who" est de type Chaîne 
  //Le contenu de la propriété "to" est de type entity (dataclass Address)
 $mailing:=ds.Teachers.all().extract("lastname";"who";"address";"to")
  //
  //
  //$mailing est une collection d'objets avec les propriétés "who" et "city"
  //Le contenu de la propriété "who" est de type Chaîne 
  //Le contenu de la propriété "city" est de type Chaîne 
 $mailing:=ds.Teachers.all().extract("lastname";"who";"address.city";"city")
  //
  //$teachers est une collection d'objets avec les propriétés "where" et "who"
  //Le contenu de la propriété "where" est de type Chaîne
  //Le contenu de la propriété "who" est une entity selection (dataclass Teachers)
 $teachers:=ds.Address.all().extract("city";"where";"teachers";"who")
  //
  //$teachers est une collection d'entity selections
 $teachers:=ds.Address.all().extract("teachers")

.first()

Historique

Release	Modifications
17	Ajout

.first() : 4D.Entity

Paramètres	Type		Description
Résultat	4D.Entity	<-	Référence vers la première entité de l'entity selection (Null si la selection est vide)

Description

La fonction .first() retourne une référence vers l'entité en première position dans l'entity selection.

Le résultat de cette fonction est similaire à :

 $entity:=$entitySel[0]

Il existe cependant une différence entre les deux instructions lorsque la sélection est vide :

 var $entitySel : cs.EmpSelection
 var $entity : cs.EmpEntity
 $entitySel:=ds.Emp.query("lastName = :1";"Nonexistentname") //aucune entité correspondante
  //l'entity selection est alors vide
 $entity:=$entitySel.first() //renvoie Null
 $entity:=$entitySel[0]  //génère une erreur

Exemple

 var $entitySelection : cs.EmpSelection
 var $entity : cs.EmpEntity
 $entitySelection:=ds.Emp.query("salary > :1";100000)
 If($entitySelection.length#0)
    $entity:=$entitySelection.first()
 End if

.getDataClass()

Historique

Release	Modifications
17 R5	Ajout

.getDataClass() : 4D.DataClass

Paramètres	Type		Description
Résultat	4D.DataClass	<-	Dataclass à laquelle appartient l'entity selection

Description

La fonction .getDataClass() retourne la dataclass de l'entity selection.

Cette fonction est utile principalement dans le contexte de code générique.

Exemple

Le code générique suivant duplique toutes les entités de l'entity selection :

  //méthode duplicate_entities
  //duplicate_entities($entity_selection)

 #DECLARE ( $entitySelection : 4D.EntitySelection )  
 var $dataClass : 4D.DataClass
 var $entity; $duplicate : 4D.Entity
 var $status : Object
 $dataClass:=$entitySelection.getDataClass()
 For each($entity;$entitySelection)
    $duplicate:=$dataClass.new()
    $duplicate.fromObject($entity.toObject())
    $duplicate[$dataClass.getInfo().primaryKey]:=Null //réinitialise la clé primaire
    $status:=$duplicate.save()
 End for each

.isAlterable()

Historique

Release	Modifications
18 R5	Ajout

.isAlterable() : Boolean

Paramètres	Type		Description
Résultat	Boolean	<-	Vrai si l'entity selection est modifiable, sinon Faux

Description

La fonction .isAlterable() retourne Vrai si l'entity selection est modifiable (altérable), et Faux si elle n'est pas modifiable.

Pour plus d'informations, voir Entity selections partageables ou modifiables.

Exemple

Vous êtes sur le point d'afficher l'entity selection Form.products dans une list box pour permettre à l'utilisateur d'ajouter de nouveaux produits. Vous voulez vous assurer qu'elle est modifiable afin que l'utilisateur puisse ajouter de nouveaux produits sans erreur :

If (Not(Form.products.isAlterable()))
    Form.products:=Form.products.copy()
End if
...
Form.products.add(Form.product)

.isOrdered()

Historique

Release	Modifications
17	Ajout

.isOrdered() : Boolean

Paramètres	Type		Description
Résultat	Boolean	<-	Vrai si l'entity selection est triée, sinon Faux

Description

La fonction .isOrdered() retourne Vrai si l'entity selection est triée, et Faux si elle est non triée.

Cette fonction renvoie toujours Vrai lorsque l'entity selection provient d'un datastore distant.

Pour plus d'informations, voir Entity selections triées vs Entity selections non-triées.

Exemple

 var $employees : cs.EmployeeSelection
 var $employee : cs.EmployeeEntity
 var $isOrdered : Boolean
 $employees:=ds.Employee.newSelection(dk keep ordered)
 $employee:=ds.Employee.get(714) // // renvoie l'entité avec clé primaire 714

  //Dans une entity selection triée, vous pouvez ajouter la même entité plusieurs fois (les duplications sont conservées)
 $employees.add($employee)
 $employees.add($employee)
 $employees.add($employee)

 $isOrdered:=$employees.isOrdered()
 If($isOrdered)
    ALERT("L'entity selection est triée et contient "+String($employees.length)+" employés")
 End if

.last()

Historique

Release	Modifications
17	Ajout

.last() : 4D.Entity

Paramètres	Type		Description
Résultat	4D.Entity	<-	Référence vers la dernière entité de l'entity selection (Null si l'entity selection est vide)

Description

La fonction .last() retourne une référence vers l'entité en dernière position dans l'entity selection.

Le résultat de cette fonction est similaire à :

 $entity:=$entitySel[length-1]

Si l'entity selection est vide, la fonction renvoie Null.

Exemple

 var $entitySelection : cs.EmpSelection
 var $entity : cs.EmpEntity
 $entitySelection:=ds.Emp.query("salary < :1";50000)
 If($entitySelection.length#0)
    $entity:=$entitySelection.last()
 End if

.length

Historique

Release	Modifications
17	Ajout

.length : Integer

Description

La propriété .length retourne le nombre d'entités dans l'entity selection. Si l'entity selection est vide, elle contient 0.

Les entity selections ont toujours une propriété .length.

Exemple

 var $vSize : Integer
 $vSize:=ds.Employee.query("gender = :1";"male").length
 ALERT(String(vSize)+" employés masculins trouvés.")

.max()

Historique

Release	Modifications
17	Ajout
18 R6	Retourne undefined si l'entity selection est vide

.max( attributePath : Text ) : any

Paramètres	Type		Description
attributePath	Text	->	Chemin de l'attribut à utiliser pour le calcul
Résultat	any	<-	Valeur la plus haute de l'attribut

Description

La fonction .max() retourne la plus haute valeur (ou valeur maximale) parmi toutes les valeurs de attributePath dans l'entity selection. Autrement dit, elle retourne la valeur de la dernière entité de la sélection si elle était triée par ordre croissant avec la fonction .orderBy().

Si vous passez dans attributePath le chemin d'un attribut objet contenant des valeurs de différents types, la fonction .max() retournera la valeur maximale du premier type de valeur scalaire dans l'ordre par défaut de la liste des types 4D (voir .sort()).

.max() retourne undefined si l'entity selection est vide ou si attributePath n'est pas trouvé dans l'attribut objet.

Une erreur est retournée si :

attributePath est un attribut relatif,
attributePath désigne un attribut qui n'existe pas dans la dataclass de l'entity selection.

Exemple

Nous souhaitons connaître le salaire le plus élevé parmi les employées :

 var $sel : cs.EmpSelection
 var $maxSalary : Real
 $sel:=ds.Employee.query("gender = :1";"female")
 $maxSalary:=$sel.max("salary")

.min()

Historique

Release	Modifications
17	Ajout
18 R6	Retourne undefined si l'entity selection est vide

.min( attributePath : Text ) : any

Paramètres	Type		Description
attributePath	Text	->	Chemin de l'attribut à utiliser pour le calcul
Résultat	any	<-	Valeur la plus basse de l'attribut

Description

La fonction min() retourne la plus faible valeur (ou valeur minimale) parmi toutes les valeurs de attributePath dans l'entity selection. Autrement dit, elle retourne la valeur de la première entité de la sélection si elle était triée par ordre croissant avec la fonction .orderBy() (hors valeurs Null).

Si vous passez dans attributePath le chemin d'un attribut objet contenant des valeurs de différents types, la fonction .min() retournera la valeur minimale du premier type de valeur scalaire dans l'ordre par défaut de la liste des types 4D (voir .sort()).

.min() retourne undefined si l'entity selection est vide ou si attributePath n'est pas trouvé dans l'attribut objet.

Une erreur est retournée si :

attributePath est un attribut relatif,
attributePath désigne un attribut qui n'existe pas dans la dataclass de l'entity selection.

Exemple

Nous souhaitons connaître le salaire le plus bas parmi les employées :

 var $sel : cs.EmpSelection
 var $minSalary : Real
 $sel:=ds.Employee.query("gender = :1";"female")
 $minSalary:=$sel.min("salary")

.minus()

Historique

Release	Modifications
17	Ajout

.minus( entity : 4D.Entity ) : 4D.EntitySelection
.minus( entitySelection : 4D.EntitySelection ) : 4D.EntitySelection

Paramètres	Type		Description
entity	4D.Entity	->	Entité à soustraire
entitySelection	4D.EntitySelection	->	Entity selection à soustraire
Résultat	4D.EntitySelection	<-	Nouvelle entity selection ou une nouvelle référence sur l'entity selection existante

Description

La fonction minus() exclut de l'entity selection à laquelle elle est appliquée l'entity ou les entités de l'entitySelection et retourne l'entity selection résultante.

Si vous passez entity en paramètre, la fonction crée une nouvelle entity selection sans entity (si entity appartient à l'entity selection). Si entity n'était pas incluse dans l'entity selection d'origine, une nouvelle référence à l'entity selection est renvoyée.
Si vous passez entitySelection en paramètre, la fonction retourne une entity selection contenant les entités appartenant à l"entity selection d'origine, sans les entités appartenant à entitySelection.

Vous pouvez comparer des entity selections ordonnées et/ou non ordonnées. La sélection résultante est toujours non ordonnée.

Si l'entity selection initiale ou l'entity selection initiale et celle du paramètre entitySelection sont vides, une entity selection vide est retournée.

Si entitySelection est vide ou si entity est Null, une nouvelle référence à l'entity selection d'origine est renvoyée.

Si l'entity selection initiale et le paramètre ne sont pas liés à la même dataclass, une erreur est retournée.

Exemple 1

 var $employees; $result : cs.EmployeeSelection
 var $employee : cs.EmployeeEntity

 $employees:=ds.Employee.query("lastName = :1";"H@") 
  // l'entity selection $employees contient l'entité avec la clé primaire 710 ainsi que d'autres entités
  // par ex. "Colin Hetrick", "Grady Harness", "Sherlock Holmes" (clé primaire 710)

 $employee:=ds.Employee.get(710) // "Sherlock Holmes"

 $result:=$employees.minus($employee) //$result contient "Colin Hetrick", "Grady Harness"

Exemple 2

Vous voulez avoir une sélection d'employées nommées "Jones" qui vivent à New York :

 var $sel1; $sel2; $sel3 : cs.EmployeeSelection
 $sel1:=ds.Employee.query("name =:1";"Jones")
 $sel2:=ds.Employee.query("city=:1";"New York")
 $sel3:=$sel1.and($sel2).minus(ds.Employee.query("gender='male'"))

.or()

Historique

Release	Modifications
17	Ajout

.or( entity : 4D.Entity ) : 4D.EntitySelection
.or( entitySelection : 4D.EntitySelection ) : 4D.EntitySelection

Paramètres	Type		Description
entity	4D.Entity	->	Entité à intersecter
entitySelection	4D.EntitySelection	->	Entity selection à intersecter
Résultat	4D.EntitySelection	<-	Nouvelle entity selection ou nouvelle référence à l'entity selection d'origine

Description

La fonction .or() combine l'entity selection avec le paramètre entity ou entitySelection à l'aide de l'opérateur OU logique (non exclusif); elle retourne une nouvelle entity selection non triée contenant toutes les entités de l'entity selection et du paramètre.

Si vous passez entity comme paramètre, vous combinez cette entité avec l'entity selection. Si l'entité appartient à l'entity selection, une nouvelle référence à l'entity selection est retournée. Sinon, une nouvelle entity selection contenant l'entity selection d'origine et l'entité est retournée.
Si vous passez entitySelection comme paramètre, vous comparez les deux entity selections. Une nouvelle entity selection contenant les entités appartenant à la sélection d'entités d'origine ou à entitySelection est renvoyée (ou n'est pas exclusif, les entités référencées dans les deux sélections ne sont pas dupliquées dans la sélection résultante).

Vous pouvez comparer des entity selections ordonnées et/ou non ordonnées. La sélection résultante est toujours non ordonnée.

Si l'entity selection d'origine et celle du paramètre entitySelection sont vides, une entity selection vide est retournée. Si l'entity selection d'origine est vide, une référence à entitySelection ou une entity selection contenant uniquement entity est retournée.

Si entitySelection est vide ou si entity est Null, une nouvelle référence à l'entity selection d'origine est renvoyée.

Si l'entity selection initiale et le paramètre ne sont pas liés à la même dataclass, une erreur est retournée.

Exemple 1

 var $employees1; $employees2; $result : cs.EmployeeSelection
 $employees1:=ds.Employee.query("lastName = :1";"H@") //"Colin Hetrick","Grady Harness"
 $employees2:=ds.Employee.query("firstName = :1";"C@") //"Colin Hetrick", "Cath Kidston"
 $result:=$employees1.or($employees2) //$result contient "Colin Hetrick", "Grady Harness","Cath Kidston"

Exemple 2

 var $employees; $result : cs.EmployeeSelection
 var $employee : cs.EmployeeEntity
 $employees:=ds.Employee.query("lastName = :1";"H@") // "Colin Hetrick","Grady Harness", "Sherlock Holmes"
 $employee:=ds.Employee.get(686) //l'entité avec clé primaire 686 n'appartient pas à l'entity selection $employees 
  //elle correspond à l'employée "Mary Smith"

 $result:=$employees.or($employee) //$result contient "Colin Hetrick", "Grady Harness", "Sherlock Holmes", "Mary Smith"

.orderBy()

Historique

Release	Modifications
17	Ajout

.orderBy( pathString : Text ) : 4D.EntitySelection
.orderBy( pathObjects : Collection ) : 4D.EntitySelection

Paramètres	Type		Description
pathString	Text	->	Chemin(s) d'attribut(s) et mode(s) de tri pour l'entity selection
pathObjects	Collection	->	Collection d'objets critère
Résultat	4D.EntitySelection	<-	Nouvelle entity selection dans l'ordre spécifié

Description

La fonction .orderBy() renvoie une nouvelle entity selection triée contenant toutes les entités de l'entity selection dans l'ordre spécifié par le paramètre pathString ou pathObjects.

Cette fonction ne modifie pas l'entity selection d'origine.

Pour plus d'informations, reportez-vous au paragraphe Entity selections triées ou non triées.

Vous devez utiliser un paramètre de critère pour définir la manière dont les entités doivent être triées. Deux paramètres différents sont pris en charge :

pathString (Texte) : Ce paramètre contient une formule composée de chemins d'attribut de 1 à n et (optionnellement) de tri, séparés par des virgules. La syntaxe est :

"attributePath1 {desc or asc}, attributePath2 {desc or asc},..."

L'ordre dans lequel les attributs sont passés détermine la priorité de tri des entités. Par défaut, les attributs sont triés par ordre croissant. Vous pouvez définir l'ordre de tri de chaque propriété dans la formule de critère, séparée du chemin de propriété par un simple espace : passez "asc" pour trier par ordre croissant ou "desc" pour un ordre décroissant.

pathObjects (collection) : chaque élément de la collection contient un objet structuré de la façon suivante :

{
    "propertyPath": string,
    "descending": boolean
}

Par défaut, les attributs sont triés par ordre croissant ("descending" est false).

Vous pouvez ajouter autant d'objets que nécessaire dans la collection de critères.

Les valeurs nulles sont évaluées comme étant inférieures aux autres valeurs.

Si vous passez un chemin d'attribut non valide dans pathString ou pathObject, la fonction renvoie une entity selection vide.

Exemple

// tri avec formule
 $sortedEntitySelection:=$entitySelection.orderBy("firstName asc, salary desc")
 $sortedEntitySelection:=$entitySelection.orderBy("firstName")

  // tri avec collection avec ou sans ordres de tri
 $orderColl:=New collection
 $orderColl.push(New object("propertyPath";"firstName";"descending";False))
 $orderColl.push(New object("propertyPath";"salary";"descending";True))
 $sortedEntitySelection:=$entitySelection.orderBy($orderColl)

 $orderColl:=New collection
 $orderColl.push(New object("propertyPath";"manager.lastName"))
 $orderColl.push(New object("propertyPath";"salary"))
 $sortedEntitySelection:=$entitySelection.orderBy($orderColl)

.orderByFormula()

Historique

Release	Modifications
17 R6	Ajout

.orderByFormula( formulaString : Text { ; sortOrder : Integer } { ; settings : Object} ) : 4D.EntitySelection
.orderByFormula( formulaObj : Object { ; sortOrder : Integer } { ; settings : Object} ) : 4D.EntitySelection

Paramètres	Type		Description
formulaString	Text	->	Chaîne formule
formulaObj	Object	->	Objet formule
sortOrder	Integer	->	`dk ascending` (par défaut) ou`dk descending`
settings	Object	->	Paramètre(s) de la formule
Résultat	4D.EntitySelection	<-	Nouvelle entity selection triée

Description

La fonction .orderByFormula() renvoie une nouvelle entity selection triée contenant toutes les entités de l'entity selection dans l'ordre défini par les paramètres formulaString ou formulaObj et, éventuellement, sortOrder et settings.

Cette fonction ne modifie pas l'entity selection d'origine.

Vous pouvez utiliser soit le paramètre formulaString, soit le paramètre formulaObj :

formulaString : passez une expression 4D telle que "Year of(this.birthDate)".
formulaObj : passez un objet formule valide créé à l'aide de la commande Formula ou Formula from string.

La formule de formulaString ou formulaObj est exécutée pour chaque entité de l'entity selection et son résultat sert à définir la position de l'entité dans l'entity selection retournée. Le résultat doit être de type triable (booléen, date, numérique, texte, heure, null).

Un résultat null est toujours la plus petite valeur.

Par défaut, si vous omettez le paramètre sortOrder, l'entity selection résultante est triée par ordre croissant. Vous pouvez optionnellement passer l'une des valeurs suivantes dans le paramètre sortOrder :

Constante	Valeur	Commentaire
dk ascending	0	Ordre de tri croissant (défaut)
dk descending	1	Ordre de tri décroissant

Dans formulaString et formulaObj, l'entité qui est traitée ainsi que ses attributs sont disponibles via la commande This (par exemple, This.lastName).

Vous pouvez passer un ou plusieurs paramètre(s) à la formule à l'aide de la propriété args (objet) du paramètre settings : la formule reçoit l'objet settings.args dans $1.

Exemple 1

Pour effectuer un tri d'étudiants à l'aide d'une formule texte :

 var $es1; $es2 : cs.StudentsSelection
 $es1:=ds.Students.query("nationality=:1";"French")
 $es2:=$es1.orderByFormula("length(this.lastname)") //croissant par défaut
 $es2:=$es1.orderByFormula("length(this.lastname)";dk descending)

Pour effectuer le même tri dans le même ordre, mais à l'aide d'un objet formule :

 var $es1; $es2 : cs.StudentsSelection
 var $formula : Object
 $es1:=ds.Students.query("nationality=:1";"French")
 $formula:=Formula(Length(This.lastname))
 $es2:=$es1.orderByFormula($formula) // croissant par défaut
 $es2:=$es1.orderByFormula($formula;dk descending)

Exemple 2

Une formule est donnée sous forme d'objet formule avec des paramètres; l'objet settings.args est reçu dans $1 dans la méthode computeAverage.

Dans cet exemple, le champ objet "marks" de la dataclass Students contient les notes des étudiants dans chaque matière. Un seul objet formule est utilisé pour calculer la note moyenne des étudiants à l'aide de différents coefficients pour schoolA et schoolB.

 var $es1; $es2 : cs.StudentsSelection
 var $formula; $schoolA; $schoolB : Object
 $es1:=ds.Students.query("nationality=:1";"French")
 $formula:=Formula(computeAverage($1))

 $schoolA:=New object() //objet settings
 $schoolA.args:=New object("english";1;"math";1;"history";1) // Coefficients permettant de calculer la moyenne

  //Trier les étudiants en fonction du critère schoolA
 $es2:=$es1.entitySelection.orderByFormula($formula;$schoolA)

 $schoolB:=New object() //objet settings 
 $schoolB.args:=New object("english";1;"math";2;"history";3) // Coefficients permettant de calculer une moyenne

  //Trier les étudiants en fonction du critère schoolB
 $es2:=$es1.entitySelection.orderByFormula($formula;dk descending;$schoolB)

  //
  // méthode computeAverage 
  // -----------------------------
 #DECLARE ($coefList : Object) -> $result : Integer
 var $subject : Text
 var $average; $sum : Integer

 $average:=0
 $sum:=0

 For each($subject;$coefList)
    $sum:=$sum+$coefList[$subject]
 End for each

 For each($subject;This.marks)
    $average:=$average+(This.marks[$subject]*$coefList[$subject])
 End for each

 $result:=$average/$sum

.query()

Historique

Release	Modifications
17 R6	Prise en charge des paramètres Formula
17 R5	Prise en charge des placeholders pour les valeurs
17	Ajout

.query( queryString : Text { ; ...value : any } { ; querySettings : Object } ) : 4D.EntitySelection
.query( formula : Object { ; querySettings : Object } ) : 4D.EntitySelection

Paramètres	Type		Description
queryString	Text	->	Critères de recherche en texte
formula	Object	->	Critères de recherche en objet formule
value	any	->	Valeur(s) à utiliser comme placeholder(s)
querySettings	Object	->	Options de recherche : parameters, attributes, args, allowFormulas, context, queryPath, queryPlan
Résultat	4D.EntitySelection	<-	Nouvelle entity selection composée d'entités issues de l'entity selection répondant aux critères de recherche spécifiés dans queryString ou formula

Description

La fonction .query() recherche les entités répondant aux critères de recherche spécifiés dans queryString ou formula et (optionnellement) dans value(s) parmi toutes les entités de l'entity selection, et renvoie un nouvel objet de type EntitySelection contenant toutes les entités trouvées. Le mode lazy loading est appliqué.

Cette fonction ne modifie pas l'entity selection d'origine.

Si aucune entité correspondante n'est trouvée, une EntitySelection vide est retournée.

Pour plus d'informations sur la génération d'une recherche à l'aide des paramètres queryString, value, et querySettings, reportez-vous à la description de la fonction de dataclass .query().

Par défaut, si vous omettez la déclaration order by dans queryString, l'entity selection retournée n'est pas triée. A noter cependant qu'en client/server, elle se comporte comme une entity selection triée (les entités sont ajoutées à la fin de la sélection).

Exemple 1

 var $entitySelectionTemp : cs.EmployeeSelection
 $entitySelectionTemp:=ds.Employee.query("lastName = :1";"M@")
 Form.emps:=$entitySelectionTemp.query("manager.lastName = :1";"S@")

Exemple 2

Vous trouverez plus d'exemples de requêtes dans la page .query().

Voir également

.query() pour dataclass

.queryPath

Historique

Release	Modifications
17	Ajout

.queryPath : Text

Description

La propriété .queryPath contient une description détaillée de la requête telle qu'elle a été effectuée par 4D. Cette propriété est disponible pour les objets de type EntitySelection générés via des recherches si la propriété "queryPath":true a été passée dans le paramètre querySettings de la fonction .query().

Pour plus d'informations, veuillez vous reporter au paragraphe querySettings de la fonction de dataclass .query().

.queryPlan

Historique

Release	Modifications
17	Ajout

.queryPlan : Text

Description

La propriété .queryPlan contient une description détaillée de la requête juste avant son exécution (c'est-à-dire, la requête planifiée). Cette propriété est disponible pour les objets de type EntitySelection générés via des recherches si la propriété "queryPlan":true a été passée dans le paramètre querySettings de la fonction .query().

Pour plus d'informations, veuillez vous reporter au paragraphe querySettings de la fonction de dataclass .query().

.refresh()

Historique

Release	Modifications
18 R3	Ajout

.refresh()

| Paramètres | Type | | Description | | ---------- | ---- |::| ------------------------------------------------------ | | | | | Ne requiert aucun paramètre|

Description

Cette fonction est utilisable uniquement avec un datastore distant (client/serveur ou connexion Open datastore).

La fonction .refresh() "invalide" immédiatement les données de l'entity selection dans le cache local d'ORDA de sorte que, la prochaine fois que 4D accède à l'entity selection, elle soit rechargée à partir de la base.

Par défaut, le cache local d'ORDA est invalidé après 30 secondes. Dans le contexte des applications client/serveur à l'aide d'ORDA et du langage classique, cette fonction vous permet d'être certain que l'application distante fonctionne toujours avec les données les plus récentes.

Exemple 1

Dans cet exemple, les langages classiques et ORDA modifient simultanément les mêmes données :

 //Sur un 4D distant

 var $selection : cs.StudentsSelection
 var $student : cs.StudentsEntity

 $selection:=ds.Students.query("lastname=:1";"Collins")
  //La première entité est chargée dans le cache d'ORDA
 $student:=$selection.first()

  //Mise à jour avec un 4D classique, le cache ORDA cache n'en est pas informé
 QUERY([Students];[Students]lastname="Collins")
 [Students]lastname:="Colin"
 SAVE RECORD([Students])

  //pour obtenir la dernière version, le cache d'ORDA doit être invalidé
 $selection.refresh()
  // Même si le cache n'a pas expiré, la première entité est rechargée à partir du disque
 $student:=$selection.first()

  //$student.lastname contient "Colin"

Exemple 2

Une list box affiche l'entity selection Form.students, sur laquelle plusieurs clients travaillent.

// Methode formulaire:
 Case of
    :(Form event code=On Load)
       Form.students:=ds.Students.all()
 End case
  //
  //
  // Sur client #1, l'utilisateur charge, met à jour et sauvegarde la première entité
  // Sur client #2, l'utilisateur charge, met à jour et sauvegarde la même entité
  //
  //
  // Sur client #1:
 Form.students.refresh() // Invalide le cache ORDA pour l'entity selection Form.students
  // Le contenu de la list box est rafraîchi à partir de la base avec les mises à jour effectuées par le client #2

.slice()

Historique

Release	Modifications
17	Ajout

.slice( startFrom : Integer { ; end : Integer } ) : 4D.EntitySelection

Paramètres	Type		Description
startFrom	Integer	->	Indice auquel démarrer l'opération (inclus)
end	Integer	->	Indice de fin (non inclus)
Résultat	4D.EntitySelection	<-	Nouvelle entity selection contenant les entités copiées (shallow copy)

Description

La fonction slice() retourne une partie d'une entity selection dans une nouvelle entity selection, sélectionnée depuis l'indice (i.e. la position) startFrom jusqu'à l'indice end (end non inclus) ou jusqu'à la dernière entité de l'entity selection. Cette fonction effectue une shallow copy (copie superficielle) de l'entity selection (les mêmes références d'entités sont utilisées).

Cette fonction ne modifie pas l'entity selection d'origine.

L'entity selection retournée contient les entités comprises entre l'entité désignée par startFrom et, sans la contenir, celle désignée par end. Si seul le paramètre startFrom est spécifié, la sélection d'entités renvoyée contient toutes les entités à partir de startFrom jusqu'à la dernière entité de la sélection d'entités originale.

Si startFrom < 0, il est recalculé comme startFrom:=startFrom+length (il est considéré comme partant de la fin de l'entity selection). Si la valeur calculée est négative, startFrom prend la valeur 0.
Si startFrom >= length, la fonction retourne une entity selection vide.
Si end < 0, le paramètre est recalculé comme end:=end+length.
Si end < startFrom (valeurs passées ou recalculées), la fonction ne fait rien.

Si l'entity selection contient des entités qui ont été supprimées entre-temps, elles sont également retournées.

Exemple 1

Vous souhaitez obtenir une sous-sélection des 9 premières entités de l'entity selection :

var $sel; $sliced : cs.EmployeeSelection
$sel:=ds.Employee.query("salary > :1";50000)
$sliced:=$sel.slice(0;9)

Exemple 2

En supposant que ds.Employee.all().length = 10

var $slice : cs.EmployeeSelection
$slice:=ds.Employee.all().slice(-1;-2) //tente de retourner les entités de position 9 à 8, mais comme 9 > 8, retourne une entity selection vide

.sum( )

Historique

Release	Modifications
17	Ajout

.sum( attributePath : Text ) : Real

Paramètres	Type		Description
attributePath	Text	->	Chemin de l'attribut à utiliser pour le calcul
Résultat	Real	<-	Somme des valeurs de l'entity selection

Description

La fonction .sum() renvoie la somme de toutes les valeurs de attributePath dans l'entity selection.

.sum() retourne 0 si l'entity selection est vide.

La somme peut uniquement être effectuée sur des valeurs numériques. Si attributePath est de type objet, seules les valeurs numériques qu'il contient seront prises en compte (les autres types de valeurs sont ignorés). Dans ce cas, si attributePath désigne une propriété qui n'existe pas dans l'objet ou qui ne contient pas de valeurs numériques, .sum() retourne 0.

Une erreur est retournée si :

attributePath est un attribut qui n'est ni de type numérique ni de type objet,
attributePath est un attribut relatif,
attributePath n'est pas trouvé dans la dataclass de l'entity selection.

Exemple

var $sel : cs.EmployeeSelection
var $sum : Real

$sel:=ds.Employee.query("salary < :1";20000)
$sum:=$sel.sum("salary")

.toCollection( )

Historique

Release	Modifications
17	Ajout

.toCollection( { options : Integer { ; begin : Integer { ; howMany : Integer } } ) : Collection
.toCollection( filterString : Text {; options : Integer { ; begin : Integer { ; howMany : Integer }}} ) : Collection
.toCollection( filterCol : Collection {; options : Integer { ; begin : Integer { ; howMany : Integer }}} ) : Collection

Paramètres	Type		Description
filterString	Text	->	Chemin(s) d'attribut(s) à extraire
filterCol	Collection	->	Collection d'attribut(s) à extraire
options	Integer	->	`dk with primary key` : ajoute la clé primaire `dk with stamp` : ajoute le marqueur
begin	Integer	->	Désigne la position de début
howMany	Integer	->	Nombre d'entités à extraire
Résultat	Collection	<-	Collection d'objets contenant les attributs et valeurs de l'entity selection

Description

La fonction .toCollection() crée et retourne une collection dans laquelle chaque élément est un objet contenant un ensemble de propriétés et de valeurs correspondant aux noms et valeurs d'attributs de l'entity selection.

Si aucun paramètre de filtre n'est passé ou si le paramètre contient une chaîne vide ou "*", tous les attributs sont extraits. Les attributs dont la propriété kind est "relatedEntity" sont extraits avec la forme simple : un objet avec la propriété __KEY (clé primaire). Les attributs dont la propriété "kind" est "relatedEntities" ne sont pas extraits.

Vous pouvez également indiquer les attributs à extraire à l'aide d'un paramètre de filtre. Deux types de filtres sont utilisables :

filterString --une chaîne avec les chemins des propriétés séparés par des virgules : "propertyPath1, propertyPath2, ...".
filterCol --une collection de chaînes contenant des chemins de propriétés : ["propertyPath1","propertyPath2",...]

Si un filtre est spécifié pour un attribut de type relatedEntity :

propertyPath = "relatedEntity" -> l'extraction se fait dans une forme simple
propertyPath = "relatedEntity.*" -> toutes les propriétés sont extraites
propertyPath = "relatedEntity.propertyName1, relatedEntity.propertyName2, ..." -> seules ces propriétés sont extraites

Si un filtre est spécifié pour un attribut de type relatedEntity :

propertyPath = "relatedEntities.*" -> toutes les propriétés sont extraites
propertyPath = "relatedEntities.propertyName1, relatedEntities.propertyName2, ..." -> seules ces propriétés sont extraites

Dans le paramètre options , vous pouvez passer le(s) sélecteur(s) dk with primary key et/ou dk with stamp pour ajouter les clés primaires et/ou les marqueurs de l'entité dans les objets extraits.

Le paramètre begin vous permet d'indiquer la position de départ des entités à extraire. Vous pouvez passer toute valeur comprise entre 0 et la longueur de l'entity selection -1.

Le paramètre howMany vous permet de spécifier le nombre d'entités à extraire, à partir de celle désignée par begin. Les entités supprimées ne sont pas retournées mais sont prises en compte dans howMany. Par exemple, si howMany= 3 et s'il y a une entité supprimée, seulement 2 entités sont extraites.

Si howMany > length de l'entity selection, la fonction retourne (length - begin) objets.

Une collection vide est retournée si :

l'entity selection est vide, ou
begin est supérieur à la longueur de l'entity selection.

Exemple 1

La structure suivante sera utilisée pour les exemples de cette section :

Exemple sans paramètres de filtre ni d'options :

 var $employeesCollection : Collection
 var $employees : cs.EmployeeSelection

 $employeesCollection:=New collection
 $employees:=ds.Employee.all()
 $employeesCollection:=$employees.toCollection()

Retourne :

[
    {
        "ID": 416,
        "firstName": "Gregg",
        "lastName": "Wahl",
        "salary": 79100,
        "birthDate": "1963-02-01T00:00:00.000Z",
        "woman": false,
        "managerID": 412,
        "employerID": 20,
        "photo": "[object Picture]",
        "extra": null,
        "employer": {
            "__KEY": 20
        },
        "manager": {
            "__KEY": 412
        }
    },
    {
        "ID": 417,
        "firstName": "Irma",
        "lastName": "Durham",
        "salary": 47000,
        "birthDate": "1992-06-16T00:00:00.000Z",
        "woman": true,
        "managerID": 412,
        "employerID": 20,
        "photo": "[object Picture]",
        "extra": null,
        "employer": {
            "__KEY": 20
        },
        "manager": {
            "__KEY": 412
        }
    }
]

Exemple 2

Retourne :

var $employeesCollection : Collection
var $employees : cs.EmployeeSelection

$employeesCollection:=New collection
$employees:=ds.Employee.all()
$employeesCollection:=$employees.toCollection("";dk with primary key+dk with stamp)

Retourne :

[
    {
        "__KEY": 416,
        "__STAMP": 1,
        "ID": 416,
        "firstName": "Gregg",
        "lastName": "Wahl",
        "salary": 79100,
        "birthDate": "1963-02-01T00:00:00.000Z",
        "woman": false,
        "managerID": 412,
        "employerID": 20,
        "photo": "[object Picture]",
        "extra": null,
        "employer": {
            "__KEY": 20
        },
        "manager": {
            "__KEY": 412
        }
    },
    {
        "__KEY": 417,
        "__STAMP": 1,
        "ID": 417,
        "firstName": "Irma",
        "lastName": "Durham",
        "salary": 47000,
        "birthDate": "1992-06-16T00:00:00.000Z",
        "woman": true,
        "managerID": 412,
        "employerID": 20,
        "photo": "[object Picture]",
        "extra": null,
        "employer": {
            "__KEY": 20
        },
        "manager": {
            "__KEY": 412
        }
    }]

Exemple 3

Retourne :

var $employeesCollection; $filter : Collection
var $employees : cs.EmployeeSelection

$employeesCollection:=New collection
$filter:=New collection
$filter.push("firstName")
$filter.push("lastName")

$employees:=ds.Employee.all()
$employeesCollection:=$employees.toCollection($filter;0;0;2)

Retourne :

[
    {
        "firstName": "Gregg",
        "lastName": "Wahl"
    },
    {
        "firstName": "Irma",
        "lastName": "Durham"
    }
]

Exemple 4

Exemple avec le type relatedEntity avec une forme simple :

var $employeesCollection : Collection
$employeesCollection:=New collection
$employeesCollection:=$employees.toCollection("firstName,lastName,employer")

Retourne :

[
    {
        "firstName": "Gregg",
        "lastName": "Wahl",
        "employer": {
            "__KEY": 20
        }
    },
    {
        "firstName": "Irma",
        "lastName": "Durham",
        "employer": {
            "__KEY": 20
        }
    },
    {
        "firstName": "Lorena",
        "lastName": "Boothe",
        "employer": {
            "__KEY": 20
        }
    }
   ]

Exemple 5

Exemple avec le paramètre filterCol :

var $employeesCollection; $coll : Collection
$employeesCollection:=New collection
$coll:=New collection("firstName";"lastName")
$employeesCollection:=$employees.toCollection($coll)

Retourne :

[
    {
        "firstName": "Joanna",
        "lastName": "Cabrera"
    },
    {
        "firstName": "Alexandra",
        "lastName": "Coleman"
    }
]

Exemple 6

Dans cet exemple, les langages classiques et ORDA modifient simultanément les mêmes données :

var $employeesCollection; $coll : Collection
$employeesCollection:=New collection
$coll:=New collection
$coll.push("firstName")
$coll.push("lastName")
$coll.push("employer.*")
$employeesCollection:=$employees.toCollection($coll)

Retourne :

[
    {
        "firstName": "Gregg",
        "lastName": "Wahl",
        "employer": {
            "ID": 20,
            "name": "India Astral Secretary",
            "creationDate": "1984-08-25T00:00:00.000Z",
            "revenues": 12000000,
            "extra": null
        }
    },
    {
        "firstName": "Irma",
        "lastName": "Durham",
        "employer": {
            "ID": 20,
            "name": "India Astral Secretary",
            "creationDate": "1984-08-25T00:00:00.000Z",
            "revenues": 12000000,
            "extra": null
        }
    },
    {
        "firstName": "Lorena",
        "lastName": "Boothe",
        "employer": {
            "ID": 20,
            "name": "India Astral Secretary",
            "creationDate": "1984-08-25T00:00:00.000Z",
            "revenues": 12000000,
            "extra": null
        }
    }
  ]

Exemple 7

Exemple avec extraction de quelques propriétés de relatedEntity :

var $employeesCollection : Collection
$employeesCollection:=New collection
$employeesCollection:=$employees.toCollection("firstName, lastName, employer.name")

[
    {
        "firstName": "Gregg",
        "lastName": "Wahl",

        "employer": {
            "name": "India Astral Secretary"
        }
    },
    {
        "firstName": "Irma",
        "lastName": "Durham",
        "employer": {
            "name": "India Astral Secretary"
        }
    },
    {
        "firstName": "Lorena",
        "lastName": "Boothe",
        "employer": {
            "name": "India Astral Secretary"
        }
    }]

Exemple 8

Exemple avec extraction de certaines propriétés de relatedEntities:

 var $employeesCollection : Collection
 $employeesCollection:=New collection
 $employeesCollection:=$employees.toCollection("firstName, lastName, directReports.firstName")

Retourne :

[
    {
        "firstName": "Gregg",
        "lastName": "Wahl",
        "directReports": []
    },
    {
        "firstName": "Mike",
        "lastName": "Phan",
        "directReports": [
            {
                "firstName": "Gary"
            },
            {
                "firstName": "Sadie"
            },
            {
                "firstName": "Christie"
            }
        ]
    },
    {
        "firstName": "Gary",

        "lastName": "Reichert",
        "directReports": [
            {
                "firstName": "Rex"
            },
            {
                "firstName": "Jenny"
            },
            {
                "firstName": "Lowell"
            }
        ]
    }]

Exemple 9

Exemple avec extraction de toutes les propriétés de relatedEntities :

var $employeesCollection : Collection
$employeesCollection:=New collection
$employeesCollection:=$employees.toCollection("firstName, lastName, directReports.*")

[
    {
        "firstName": "Gregg",
        "lastName": "Wahl",
        "directReports": []
    },    
    {
        "firstName": "Mike",
        "lastName": "Phan",
        "directReports": [
            {
                "ID": 425,
                "firstName": "Gary",
                "lastName": "Reichert",
                "salary": 65800,
                "birthDate": "1957-12-23T00:00:00.000Z",
                "woman": false,
                "managerID": 424,
                "employerID": 21,
                "photo": "[object Picture]",
                "extra": null,
                "employer": {
                    "__KEY": 21
                },
                "manager": {
                    "__KEY": 424
                }
            },
            {
                "ID": 426,
                "firstName": "Sadie",
                "lastName": "Gallant",
                "salary": 35200,
                "birthDate": "2022-01-03T00:00:00.000Z",
                "woman": true,
                "managerID": 424,
                "employerID": 21,
                "photo": "[object Picture]",
                "extra": null,
                "employer": {
                    "__KEY": 21
                },
                "manager": {
                    "__KEY": 424
                }
            }
                   ]
    },
    {
        "firstName": "Gary",
        "lastName": "Reichert",
        "directReports": [
            {
                "ID": 428,
                "firstName": "Rex",
                "lastName": "Chance",
                "salary": 71600,
                "birthDate": "1968-08-09T00:00:00.000Z",
                "woman": false,

                "managerID": 425,
                "employerID": 21,
                "photo": "[object Picture]",
                "extra": null,
                "employer": {
                    "__KEY": 21
                },
                "manager": {
                    "__KEY": 425
                }
            },
            {
                "ID": 429,
                "firstName": "Jenny",
                "lastName": "Parks",
                "salary": 51300,
                "birthDate": "1984-05-25T00:00:00.000Z",
                "woman": true,
                "managerID": 425,
                "employerID": 21,
                "photo": "[object Picture]",
                "extra": null,
                "employer": {
                    "__KEY": 21
                },
                "manager": {
                    "__KEY": 425
                }
            }
           ]
 }
]

Sommaire​

Create entity selection​

Description​

Exemple​

Voir également​

[index]​

Description​

Exemple​

.attributeName​

Description​

Exemple 1​

Exemple 2​

Exemple 3​

.add()​

Description​

Exemple 1​

Exemple 2​

.and()​

Description​

Exemple 1​

Exemple 2​

.average()​

Description​

Exemple​

.contains()​

Description​

Exemple​

.count()​

Description​

Exemple​

.copy()​

Description​

Exemple​

.distinct()​

Description​

Exemples​

.drop()​

Description​

Exemple​

.extract()​

Description​

Exemple​

.first()​

Description​

Exemple​

.getDataClass()​

Description​

Exemple​

.isAlterable()​

Description​

Exemple​

.isOrdered()​

Description​

Exemple​

.last()​

Description​

Exemple​

.length​

Description​

Exemple​

.max()​

Description​

Exemple​

.min()​

Description​

Exemple​

.minus()​

Description​

Exemple 1​

Exemple 2​

.or()​

Description​

Exemple 1​

Exemple 2​

.orderBy()​

Description​

Exemple​

.orderByFormula()​

Description​

Exemple 1​

Sommaire

Create entity selection

Description

Exemple

Voir également

[index]

Description

Exemple

.attributeName

Description

Exemple 1

Exemple 2

Exemple 3

.add()

Description

Exemple 1

Exemple 2

.and()

Description

Exemple 1

Exemple 2

.average()

Description

Exemple

.contains()

Description

Exemple

.count()

Description

Exemple

.copy()

Description

Exemple

.distinct()

Description

Exemples

.drop()

Description

Exemple

.extract()

Description

Exemple

.first()

Description

Exemple

.getDataClass()

Description

Exemple

.isAlterable()

Description

Exemple

.isOrdered()

Description

Exemple

.last()

Description

Exemple

.length

Description

Exemple

.max()

Description

Exemple

.min()

Description

Exemple

.minus()

Description

Exemple 1

Exemple 2

.or()

Description

Exemple 1

Exemple 2

.orderBy()

Description

Exemple

.orderByFormula()

Description

Exemple 1