DataClass

A DataClass provides an object interface to a database table. All dataclasses in a 4D application are available as a property of the ds datastore.

Sommaire

.attributeName : object objets disponibles directement en tant que propriétés
.all ( { settings : Object } ) : 4D.EntitySelection queries the datastore to find all the entities related to the dataclass and returns them as an entity selection
.clearRemoteCache() empties the ORDA cache of a dataclass
.fromCollection( objectCol : Collection { ; settings : Object } ) : 4D.EntitySelection updates or creates entities in the dataclass according to the objectCol collection of objects, and returns the corresponding entity selection
.get( primaryKey : Integer { ; settings : Object } ) : 4D.Entity .get( primaryKey : Text { ; settings : Object } ) : 4D.Entity queries the dataclass to retrieve the entity matching the primaryKey parameter
.getCount() : Integer returns the number of entities in a dataclass
.getDataStore() : cs.DataStore returns the datastore for the specified dataclass
.getInfo() : Object returns an object providing information about the dataclass
.getRemoteCache() : Object returns an object that holds the contents of the ORDA cache for a dataclass.
.new() : 4D.Entity creates in memory and returns a new blank entity related to the Dataclass
.newSelection( { keepOrder : Integer } ) : 4D.EntitySelection creates a new, blank, non-shareable entity selection, related to the dataclass, in memory
.query( queryString : Text { ; ...value : any } { ; querySettings : Object } ) : 4D.EntitySelection .query( formula : Object { ; querySettings : Object } ) : 4D.EntitySelection searches for entities that meet the search criteria specified in queryString or formula and (optionally) value(s)
.setRemoteCacheSettings(settings : Object) sets the timeout and maximum size of the ORDA cache for a dataclass.

.attributeName

Historique

Release	Modifications
19 R3	Ajout de l'attribut .exposed
17	Ajout

.attributeName : object

Description

Les attributs des dataclasses sont des objets disponibles directement en tant que propriétés de ces classes.

Les objets renvoyés ont des propriétés que vous pouvez lire pour obtenir des informations sur les attributs de votre dataclass.

Les objets attributs de dataclass peuvent être modifiés, mais la structure sous-jacente de la base de données ne sera pas altérée.

Objet retourné

Les objets attributs retournés contiennent les propriétés suivantes :

Propriété	Type	Description
autoFilled	Boolean	Vrai si la valeur de l'attribut est automatiquement remplie par 4D. Correspond aux propriétés de champs 4D suivantes : "Autoincrement" pour les champs de type numérique et "UUID Auto" pour les champs UUID (alpha). Not returned if .kind = "relatedEntity" or "relatedEntities".
exposed	Boolean	Vrai si l'attribut est exposé en REST
fieldNumber	entier	Numéro interne du champ 4D correspondant à l'attribut. Not returned if .kind = "relatedEntity" or "relatedEntities".
fieldType	Integer	Type de champ de la base de données 4D de l'attribut. Depends on the attribute kind. Possible values: if .kind = "storage": corresponding 4D field type, see Value type if .kind = "relatedEntity": 38 (is object) if .kind = "relatedEntities": 42 (is collection) if .kind = "calculated" or "alias" = same as above, depending on the resulting value (field type, relatedEntity or relatedEntities)
indexed	Boolean	Vrai s'il existe un index B-tree ou Cluster B-tree sur l'attribut. Not returned if .kind = "relatedEntity" or "relatedEntities".
inverseName	Text	Nom de l'attribut qui se trouve à l'autre côté de la relation. Returned only when .kind = "relatedEntity" or "relatedEntities".
keywordIndexed	Boolean	Vrai s'il existe un index de mots-clés sur l'attribut. Not returned if .kind = "relatedEntity" or "relatedEntities".
kind	Text	Catégorie de l'attribut. Possible values: "storage": storage (or scalar) attribute, i.e. attribute storing a value, not a reference to another attribute "calculated": computed attribute, i.e. defined through a get function "alias": attribute built upon another attribute "relatedEntity": N -> 1 relation attribute (reference to an entity) "relatedEntities": 1 -> N relation attribute (reference to an entity selection)
obligatoire	Boolean	Vrai si la saisie d'une valeur null est rejetée pour l'attribut. Not returned if .kind = "relatedEntity" or "relatedEntities". Attention : Cette propriété correspond à la propriété du champ "Reject NULL value input" au niveau de la base de données 4D. Elle n'est pas liée à la propriété "Mandatory" existante qui est une option de contrôle de la saisie de données pour une table.
name	Text	Nom de l'attribut sous forme de chaîne
path	Text	Path of an alias attribute based upon a relation
readOnly	Boolean	Vrai si l'attribut est en lecture seule. For example, computed attributes without set function are read-only.
relatedDataClass	Text	Nom de la dataclass liée à l'attribut. Returned only when .kind = "relatedEntity" or "relatedEntities".
type	Text	Type conceptuel de la valeur de l'attribut, utile pour la programmation générique. Depends on the attribute kind. Possible values: if .kind = "storage": "blob", "bool", "date", "image", "number", "object", or "string". "number" is returned for any numeric types including duration; "string" is returned for uuid, alpha and text attribute types; "blob" attributes are blob objects. if .kind = "relatedEntity": related dataClass name if .kind = "relatedEntities": related dataClass name + "Selection" suffix if .kind = "calculated" or "alias": same as above, depending on the result
unique	Boolean	Vrai si la valeur de l'attribut doit être unique. Not returned if .kind = "relatedEntity" or "relatedEntities".

tip

For generic programming, use Bool(attributeName.property), Num(attributeName.property) or String(attributeName.property) (depending on the property type) to get a valid value even if the property is not returned.

Exemple 1

$salary:=ds.Employee.salary //retourne l'attribut salary dans la dataclass Employee
$compCity:=ds.Company["city"] //retourne l'attribut city dans la dataclass Company

Exemple 2

Considérant la structure suivante d'une base :

var $firstnameAtt;$employerAtt;$employeesAtt : Object

 $firstnameAtt:=ds.Employee.firstname
  //{name:firstname,kind:storage,fieldType:0,type:string,fieldNumber:2,indexed:true,
  //keyWordIndexed:false,autoFilled:false,mandatory:false,unique:false}

 $employerAtt:=ds.Employee.employer
  //{name:employer,kind:relatedEntity,relatedDataClass:Company,
  //fieldType:38,type:Company,inverseName:employees}
  //38=Is object

 $employeesAtt:=ds.Company.employees
  //{name:employees,kind:relatedEntities,relatedDataClass:Employee,
  //fieldType:42,type:EmployeeSelection,inverseName:employer}
  //42=Is collection

Exemple 3

Considérant les propriétés de table suivantes :

 var $sequenceNumberAtt : Object
 $sequenceNumberAtt=ds.Employee.sequenceNumber
  //{name:sequenceNumber,kind:storage,fieldType:0,type:string,fieldNumber:13,
  //indexed:true,keyWordIndexed:false,autoFilled:true,mandatory:false,unique:true}

.all()

Historique

Release	Modifications
17 R5	Support of the settings parameter
17	Ajout

.all ( { settings : Object } ) : 4D.EntitySelection

Paramètres	Type		Description
settings	Object	->	Option de création : contexte
Résultat	4D.EntitySelection	<-	Références vers toutes les entités de la dataclass

Description

The .all() function queries the datastore to find all the entities related to the dataclass and returns them as an entity selection.

Les entités sont renvoyées dans l'ordre par défaut, qui est initialement l'ordre dans lequel elles ont été créées. Notez cependant que, si des entités ont été supprimées et que de nouvelles entités ont été ajoutées, l'ordre par défaut ne reflète plus l'ordre de création.

Si aucune entité n'est trouvée, une entity selection vide est renvoyée.

Le mode lazy loading est appliqué.

settings

In the optional settings parameter, you can pass an object containing additional options. La propriété suivante est prise en charge :

Propriété	Type	Description
context	Text	Nom du contexte d'optimisation appliqué à l'entity selection. Ce contexte sera utilisé par le code qui manipule l'entity selection afin de bénéficier de l'optimisation. This feature is designed for ORDA client/server processing.

To know the total number of entities in a dataclass, it is recommended to use the getCount() function which is more optimized than the ds.myClass.all().length expression.

Exemple

 var $allEmp : cs.EmployeeSelection
 $allEmp:=ds.Employee.all()

.clearRemoteCache()

Historique

Release	Modifications
19 R5	Ajout

.clearRemoteCache()

Paramètres	Type		Description
			Ne requiert aucun paramètre

Description

The .clearRemoteCache() function empties the ORDA cache of a dataclass.

This function does not reset the timeout and maxEntries values.

Exemple

var $ds : 4D.DataStoreImplementation
var $persons : cs.PersonsSelection
var $p : cs.PersonsEntity
var $cache : Object
var $info : Collection
var $text : Text

$ds:=Open datastore(New object("hostname"; "www.myserver.com"); "myDS")

$persons:=$ds.Persons.all()
$text:=""
For each ($p; $persons)
    $text:=$p.firstname+" lives in "+$p.address.city+" / "
End for each

$cache:=$ds.Persons.getRemoteCache()

$ds.Persons.clearRemoteCache()
// Cache of the Persons dataclass = {timeout:30;maxEntries:30000;stamp:255;entries:[]}

.fromCollection()

Historique

Release	Modifications
17 R5	Support of the settings parameter
17	Ajout

.fromCollection( objectCol : Collection { ; settings : Object } ) : 4D.EntitySelection

Paramètres	Type		Description
objectCol	Collection	->	Collection d'objets à faire correspondre à des entités
settings	Object	->	Option de création : contexte
Résultat	4D.EntitySelection	<-	Entity selection issue de la collection

Description

The .fromCollection() function updates or creates entities in the dataclass according to the objectCol collection of objects, and returns the corresponding entity selection.

In the objectCol parameter, pass a collection of objects to create new or update existing entities of the dataclass. Les noms des propriétés doivent correspondre à ceux des attributs de la dataclass. Si un nom de propriété n'existe pas dans la dataclass, il est ignoré. Si une valeur d'attribut n'est pas définie dans la collection pour une entité créée, l'attribut prend la valeur Null.

The mapping between the objects of the collection and the entities is done on the attribute names and matching types. Si une propriété d'objet a le même nom qu'un attribut d'entité mais que leurs types ne sont pas compatibles, l'attribut de l'entité ne reçoit pas de valeur.

Create or update mode

For each object of objectCol:

• Si l'objet contient une propriété booléenne "__NEW" fixée à faux (ou ne contient pas de propriété booléenne "__NEW"), l'entité est modifiée ou créée avec les valeurs correspondantes des propriétés de l'objet. Aucune vérification spécifique n'est effectuée concernant la clé primaire :
  • Si la clé primaire est fournie et existe, l'entité est modifiée. Dans ce cas, la clé primaire peut être fournie telle quelle ou via la propriété "__KEY" (contenant la valeur de la propriété primaire).
  • Si la clé primaire est fournie (telle quelle) et n'existe pas, l'entité est créée
  • Si la clé primaire n'est pas fournie, l'entité est créée et la clé primaire est assignée selon les règles en vigueur de la base de données.
• If the object contains a boolean property "__NEW" set to true, the entity is created with the corresponding values of the attributes from the object. Une vérification est effectuée sur la clé primaire :
  • Si la clé primaire est fournie (telle quelle) et existe, une erreur est générée
  • Si la clé primaire est fournie (telle quelle) et n'existe pas, l'entité est créée
  • Si la clé primaire n'est pas fournie, l'entité est créée et la clé primaire est assignée selon les règles en vigueur de la base de données.

The "__KEY" property containing a value is taken into account only when the "__NEW" property is set to false (or is omitted) and a corresponding entity exists. Dans tous les autres cas, la valeur de la propriété "__KEY" est ignorée, la valeur de la clé primaire doit être passée "telle quelle".

Related entities

The objects of objectCol may contain one or more nested object(s) featuring one or more related entities, which can be useful to create or update links between entities.

Les objets imbriqués décrivant les entités relatives doivent contenir une propriété "__KEY" (contenant la valeur de la clé primaire de l'entité relative) ou la clé primaire de l'entité relative elle-même. L'utilisation de la propriété __KEY permet de ne pas dépendre du nom de l'attribut clé primaire.

Ce mécanisme ne permet pas de créer ou de modifier les entités liées.

Stamp

Si une propriété __STAMP est fournie, une vérification est effectuée sur le stamp (marqueur interne) de l'entité dans le datastore et une erreur est retournée en cas d'invalidité ("Le stamp ne correspond pas à celui de l'enregistrement# XX de la table XXXX"). For more information, see Entity locking.

settings

In the optional settings parameter, you can pass an object containing additional options. La propriété suivante est prise en charge :

Propriété	Type	Description
context	Text	Nom du contexte d'optimisation appliqué à l'entity selection. Ce contexte sera utilisé par le code qui manipule l'entity selection afin de bénéficier de l'optimisation. This feature is designed for ORDA client/server processing.

Exemple 1

Nous souhaitons modifier une entité existante. La propriété __NEW n'est pas fixée, la clé primaire de l'employé est passée et existe :

 var $empsCollection : Collection
 var $emp : Object
 var $employees : cs.EmployeeSelection

 $empsCollection:=New collection
 $emp:=New object
 $emp.ID:=668 //Existing PK in Employee table
 $emp.firstName:="Arthur"
 $emp.lastName:="Martin"
 $emp.employer:=New object("ID";121) //Existing PK in the related dataClass Company
  // For this employee, we can change the Company by using another existing PK in the related dataClass Company
 $empsCollection.push($emp)
 $employees:=ds.Employee.fromCollection($empsCollection)

Exemple 2

Nous souhaitons modifier une entité existante. La propriété __NEW n'est pas fournie, la clé primaire de l'employé est avec l'attribut __KEY et existe :

 var $empsCollection : Collection
 var $emp : Object
 var $employees : cs.EmployeeSelection

 $empsCollection:=New collection
 $emp:=New object
 $emp.__KEY:=1720 //Existing PK in Employee table
 $emp.firstName:="John"
 $emp.lastName:="Boorman"
 $emp.employer:=New object("ID";121) //Existing PK in the related dataClass Company
  // For this employee, we can change the Company by using another existing PK in the related dataClass Company
 $empsCollection.push($emp)
 $employees:=ds.Employee.fromCollection($empsCollection)

Exemple 3

Création simple d'une entité à partir d'une collection :

 var $empsCollection : Collection
 var $emp : Object
 var $employees : cs.EmployeeSelection

 $empsCollection:=New collection
 $emp:=New object
 $emp.firstName:="Victor"
 $emp.lastName:="Hugo"
 $empsCollection.push($emp)
 $employees:=ds.Employee.fromCollection($empsCollection)

Exemple 4

Nous souhaitons créer une entité. La propriété __NEW est à Vrai, la clé primaire de l'employé n'est pas fournie :

 var $empsCollection : Collection
 var $emp : Object
 var $employees : cs.EmployeeSelection

 $empsCollection:=New collection
 $emp:=New object
 $emp.firstName:="Mary"
 $emp.lastName:="Smith"
 $emp.employer:=New object("__KEY";121) //Existing PK in the related dataClass Company
 $emp.__NEW:=True
 $empsCollection.push($emp)
 $employees:=ds.Employee.fromCollection($empsCollection)

Exemple 5

Nous souhaitons créer une entité. La propriété __NEW n'est pas passée, la clé primaire de l'employé est fournie et n'existe pas :

 var $empsCollection : Collection
 var $emp : Object
 var $employees : cs.EmployeeSelection

 $empsCollection:=New collection
 $emp:=New object
 $emp.ID:=10000 //Unexisting primary key
 $emp.firstName:="Françoise"
 $emp.lastName:="Sagan"
 $empsCollection.push($emp)
 $employees:=ds.Employee.fromCollection($empsCollection)

Exemple 6

Dans cet exemple, la première entité sera bien créée mais la seconde création échouera car les deux entités utilisent la même clé primaire :

 var $empsCollection : Collection
 var $emp; $emp2 : Object
 var $employees : cs.EmployeeSelection

 $empsCollection:=New collection
 $emp:=New object
 $emp.ID:=10001 // Unexisting primary key
 $emp.firstName:="Simone"
 $emp.lastName:="Martin"
 $emp.__NEW:=True
 $empsCollection.push($emp)

 $emp2:=New object
 $emp2.ID:=10001 // Same primary key, already existing
 $emp2.firstName:="Marc"
 $emp2.lastName:="Smith"
 $emp2.__NEW:=True
 $empsCollection.push($emp2)
 $employees:=ds.Employee.fromCollection($empsCollection)
  //first entity is created
  //duplicated key error for the second entity

Voir également

.toCollection()

.get()

Historique

Release	Modifications
17	Ajout

.get( primaryKey : Integer { ; settings : Object } ) : 4D.Entity
.get( primaryKey : Text { ; settings : Object } ) : 4D.Entity

Paramètres	Type		Description
primaryKey	Integer OR Text	->	Valeur de la clé primaire de l'entité à récupérer
settings	Object	->	Option de création : contexte
Résultat	4D.Entity	<-	Entité correspondant à la clé primaire indiquée

Description

The .get() function queries the dataclass to retrieve the entity matching the primaryKey parameter.

In primaryKey, pass the primary key value of the entity to retrieve. Le type de valeur doit correspondre au type de clé primaire définie dans le datastore (entier long ou texte). You can also make sure that the primary key value is always returned as Text by using the .getKey() function with the dk key as string parameter.

If no entity is found with primaryKey, a Null entity is returned.

Le chargement différé (lazy loading) est appliqué, ce qui signifie que les données associées sont chargées à partir du disque uniquement lorsque cela est nécessaire.

settings

In the optional settings parameter, you can pass an object containing additional options. La propriété suivante est prise en charge :

Propriété	Type	Description
context	Text	Nom du contexte d'optimisation appliqué à l'entité. Ce contexte sera utilisé par le code qui manipule l'entité afin de bénéficier de l'optimisation. This feature is designed for ORDA client/server processing.

Exemple 1

 var $entity : cs.EmployeeEntity  
 var $entity2 : cs.InvoiceEntity
 $entity:=ds.Employee.get(167) // return the entity whose primary key value is 167
 $entity2:=ds.Invoice.get("DGGX20030") // return the entity whose primary key value is "DGGX20030"

Exemple 2

This example illustrates the use of the context property:

 var $e1; $e2; $e3; $e4 : cs.EmployeeEntity
 var $settings; $settings2 : Object

 $settings:=New object("context";"detail")
 $settings2:=New object("context";"summary")

 $e1:=ds.Employee.get(1;$settings)
 completeAllData($e1) // In completeAllData method, an optimization is triggered and associated to context "detail"

 $e2:=ds.Employee.get(2;$settings)
 completeAllData($e2) // In completeAllData method, the optimization associated to context "detail" is applied

 $e3:=ds.Employee.get(3;$settings2)
 completeSummary($e3) //In completeSummary method, an optimization is triggered and associated to context "summary"

 $e4:=ds.Employee.get(4;$settings2)
 completeSummary($e4) //In completeSummary method, the optimization associated to context "summary" is applied

.getCount()

Historique

Release	Modifications
19 R5	Ajout

.getCount() : Integer

Paramètres	Type		Description
result	Integer	<-	Nombre d'entités dans la dataclass

Description

The .getCount() function returns the number of entities in a dataclass.

Si cette fonction est utilisée dans une transaction, les entités créées durant la transaction sont prises en compte.

Exemple

var $ds : 4D.DataStoreImplementation
var $number : Integer

$ds:=Open datastore(New object("hostname"; "www.myserver.com"); "myDS")

$number:=$ds.Persons.getCount()

.getDataStore()

Historique

Release	Modifications
17 R5	Ajout

.getDataStore() : cs.DataStore

Paramètres	Type		Description
Résultat	cs.DataStore	<-	Datastore de la dataclass

Description

The .getDataStore() function returns the datastore for the specified dataclass.

Le datastore peut être :

• the main datastore, as returned by the ds command.
• a remote datastore, opened using the Open datastore command.

Exemple

The SearchDuplicate project method searches for duplicated values in any dataclass.

 var $pet : cs.CatsEntity

 $pet:=ds.Cats.all().first() //get an entity
 SearchDuplicate($pet;"Dogs")

  // SearchDuplicate method
  // SearchDuplicate(entity_to_search;dataclass_name)

 #DECLARE ($pet : Object ; $dataClassName : Text)
 var $dataStore; $duplicates : Object  

 $dataStore:=$pet.getDataClass().getDataStore()
 $duplicates:=$dataStore[$dataClassName].query("name=:1";$pet.name)

.getInfo()

Historique

Release	Modifications
19 R3	Ajout propriété exposed
17 R5	Ajout

.getInfo() : Object

Paramètres	Type		Description
Résultat	Object	<-	Informations sur la dataclass

Description

The .getInfo() function returns an object providing information about the dataclass. Cette fonction est utile pour l'écriture de code générique.

Returned object

Propriété	Type	Description
exposed	Boolean	Vrai si la dataclass est exposée en REST
name	Text	Nom de la dataclass
primaryKey	Text	Nom de la clé primaire de la dataclass
tableNumber	Integer	Numéro interne de la table 4D

Exemple 1

 #DECLARE ($entity : Object)  
 var $status : Object

 computeEmployeeNumber($entity) //do some actions on entity

 $status:=$entity.save()
 if($status.success)
    ALERT("Record updated in table "+$entity.getDataClass().getInfo().name)
 End if

Exemple 2

 var $settings : Object
 var $es : cs.ClientsSelection

 $settings:=New object
 $settings.parameters:=New object("receivedIds";getIds())
 $settings.attributes:=New object("pk";ds.Clients.getInfo().primaryKey)
 $es:=ds.Clients.query(":pk in :receivedIds";$settings)

Exemple 3

 var $pk : Text
 var $dataClassAttribute : Object

 $pk:=ds.Employee.getInfo().primaryKey
 $dataClassAttribute:=ds.Employee[$pk] // If needed the attribute matching the primary key is accessible

.getRemoteCache()

Historique

Release	Modifications
19 R5	Ajout

.getRemoteCache() : Object

Paramètres	Type		Description
result	Object	<-	Objet décrivant le contenu du cache ORDA pour la dataclass.

Advanced mode: This function is intended for developers who need to customize ORDA default features for specific configurations. Dans la plupart des cas, vous n'aurez pas besoin de l'utiliser.

Description

The .getRemoteCache() function returns an object that holds the contents of the ORDA cache for a dataclass..

Calling this function from a 4D single-user application returns Null.

L'objet retourné contient les propriétés suivantes :

Propriété	Type	Description
maxEntries	Integer	Nombre maximum de collections "entries".
stamp	Integer	Marqueur du cache.
timeout	Integer	Durée avant qu'une nouvelle entrée dans le cache soit indiquée comme expirée.
entries	Collection	Contient un objet pour chaque entité dans le cache.

Each entry object in the entries collection has the following properties:

Propriété	Type	Description
data	Object	Objet contenant les données de l'entrée.
expired	Boolean	True si l'entrée a expiré.
key	Text	Clé primaire de l'entité.

The data object in each entry contains the following properties:

Propriété	Type	Description
__KEY	String	Clé primaire de l'entité
__STAMP	Longint	Stamp de l'entité dans la base de données
__TIMESTAMP	String	Timestamp de l'entité dans la base de données (le format est YYYY-MM-DDTHH:MM:SS:ms:Z)
dataClassAttributeName	Variant	S'il y a des données dans le cache pour un attribut de dataclass, il est retourné dans une propriété du même type que dans la base de données.

Les données concernant les entités liées sont stockées dans le cache de l'objet data.

Exemple

In the following example, $ds.Persons.all() loads the first entity with all its attributes. Then, the request optimization is triggered, so only firstname and address.city are loaded.

Note that address.city is loaded in the cache of the Persons dataclass.

Only the first entity of the Address dataclass is stored in the cache. Elle est chargée durant la première itération de la boucle.

var $ds : 4D.DataStoreImplementation
var $persons : cs.PersonsSelection
var $p : cs.PersonsEntity
var $cachePersons; $cacheAddress : Object
var $text : Text

$ds:=Open datastore(New object("hostname"; "www.myserver.com"); "myDS")

$persons:=$ds.Persons.all()

$text:=""
For each ($p; $persons)
    $text:=$p.firstname+" lives in "+$p.address.city+" / "
End for each

$cachePersons:=$ds.Persons.getRemoteCache()
$cacheAddress:=$ds.Adress.getRemoteCache()

Voir également

.setRemoteCacheSettings()
.clearRemoteCache()

.new()

Historique

Release	Modifications
17	Ajout

.new() : 4D.Entity

Paramètres	Type		Description
Résultat	4D.Entity	<-	Nouvelle entité correspondant à la dataclass

Description

The .new() function creates in memory and returns a new blank entity related to the Dataclass.

The entity object is created in memory and is not saved in the database until the .save( ) function is called. Si l'entité est supprimée avant d'être sauvegardée, elle ne peut pas être récupérée.

4D Server: In client-server, if the primary key of the corresponding table is auto-incremented, it will be calculated when the entity is saved on the server.

All attributes of the entity are initialized with the null value.

Attributes can be initialized with default values if the Map NULL values to blank values option is selected at the 4D database structure level.

Exemple

Cet exemple crée une nouvelle entité dans la dataclass "Log" et enregistre les informations dans l'attribut "info" :

 var $entity : cs.LogEntity
 $entity:=ds.Log.new() //create a reference
 $entity.info:="New entry" //store some information
 $entity.save() //save the entity

.newSelection()

Historique

Release	Modifications
17	Ajout

.newSelection( { keepOrder : Integer } ) : 4D.EntitySelection

Paramètres	Type		Description
keepOrder	Integer	->	dk keep ordered: creates an ordered entity selection, dk non ordered: creates an unordered entity selection (default if omitted)
Résultat	4D.EntitySelection	<-	Nouvelle entity selection vide liée à la dataclass

Description

The .newSelection() function creates a new, blank, non-shareable entity selection, related to the dataclass, in memory.

For information on non-shareable entity selections, please refer to this section.

If you want to create an ordered entity selection, pass the dk keep ordered selector in the keepOrder parameter. By default if you omit this parameter, or if you pass the dk non ordered selector, the method creates an unordered entity selection. Les entity selections non triées sont plus rapides, mais vous ne pouvez pas vous fier aux positions des entités. For more information, please see Ordered vs Unordered entity selections.

When created, the entity selection does not contain any entities (mySelection.length returns 0). This method lets you build entity selections gradually by making subsequent calls to the add() function.

Exemple

 var $USelection; $OSelection : cs.EmployeeSelection
 $USelection:=ds.Employee.newSelection() //create an unordered empty entity selection
 $OSelection:=ds.Employee.newSelection(dk keep ordered) //create an ordered empty entity selection

.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	<-	New entity selection made up of entities from dataclass meeting the search criteria specified in queryString or formula

Description

The .query() function searches for entities that meet the search criteria specified in queryString or formula and (optionally) value(s), for all the entities in the dataclass, and returns a new object of type EntitySelection containing all the entities that are found. Le mode lazy loading est appliqué.

If no matching entities are found, an empty EntitySelection is returned.

paramètre queryString

The queryString parameter uses the following syntax:

attributePath|formula comparator value   
 {logicalOperator attributePath|formula comparator value}   
 {order by attributePath {desc | asc}}

où :

• attributePath: path of attribute on which you want to execute the query. Ce paramètre peut contenir un nom simple (par exemple "pays") ou un chemin d'attribut valide (par exemple "pays.nom"). In case of an attribute path whose type is Collection, [] notation is used to handle all the occurences (for example children[].age).

You cannot use directly attributes whose name contains special characters such as ".", "[ ]", or "=", ">", "#"..., because they will be incorrectly evaluated in the query string. If you need to query on such attributes, you must consider using placeholders, which allow an extended range of characters in attribute paths (see Using placeholders below).

• formula: a valid formula passed as Text or Object. La formule sera évaluée pour chaque entité traitée et doit retourner une valeur booléenne. Within the formula, the entity is available through the This object.

  • Text: the formula string must be preceeded by the eval() statement, so that the query parser evaluates the expression correctly. For example: "eval(length(This.lastname) >=30)"
  • Object: the formula object is passed as a placeholder (see below). The formula must have been created using the Formula or Formula from string command.

• Keep in mind that 4D formulas only support & and | symbols as logical operators.
• Si la formule n'est pas le seul critère de recherche, le système d'optimisation des requêtes pourra prioriser le traitement d'autres critères (ex : attributs indexés) et ainsi, la formule sera évaluée uniquement pour un sous-ensemble d'entités.

Les formules contenues dans les requêtes peuvent recevoir des paramètres via $1. This point is detailed in the formula parameter paragraph below.

• You can also pass directy a formula parameter object instead of the queryString parameter (recommended when formulas are more complex). See formula parameter paragraph below.
• For security reasons, formula calls within query() functions can be disallowed. See querySettings parameter description.

• comparator: symbol that compares attributePath and value. 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 (@). Equivalent to "Not condition applied on a statement" (see below).
	!==, IS NOT	Considère le @ comme un caractère standard
Condition Not appliquée à une assertion	NOT	Les parenthèses sont obligatoires lorsque NOT est utilisé avant une déclaration contenant plusieurs opérateurs. Equivalent to "Not equal to" (see below).
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 (@)
Contient mot-clé	%	Les mots-clés peuvent être utilisés avec les attributs de type texte ou image

• value: the value to compare to the current value of the property of each entity in the entity selection. It can be a placeholder (see Using placeholders below) or any expression matching the data type property. Lorsque vous utilisez une valeur constante, les règles suivantes doivent être respectées :
  • text type constant can be passed with or without simple quotes (see Using quotes below). 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@". Les mots-clés suivants sont interdits pour des constantes de type texte : true, false.
  • boolean type constants: true or false (case sensitive).
  • numeric type constants: decimals are separated by a '.' (period).
  • date type constants: "YYYY-MM-DD" format
  • null constant: using the "null" keyword will find null and undefined properties.
  • in case of a query with an IN comparator, value must be a collection, or values matching the type of the attribute path between [ ] separated by commas (for strings, " characters must be escaped with \).
• logicalOperator: used to join multiple conditions in the query (optional). Vous pouvez utiliser un des opérateurs logiques suivants (le nom ou le symbole peut être passé) :

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

• order by attributePath: you can include an order by attributePath statement in the query so that the resulting data will be sorted according to that statement. You can use multiple order by statements, separated by commas (e.g., order by attributePath1 desc, attributePath2 asc). Par défaut, le tri est par ordre croissant. Passez 'desc' pour définir un tri par ordre décroissant et 'asc' pour définir un tri par ordre croissant.

If you use this statement, the returned entity selection is ordered (for more information, please refer to Ordered vs Unordered entity selections).

Utilisation de guillemets

Lorsque vous utilisez des guillemets dans des recherches, vous devez utiliser des guillemets simples ' ' à l'intérieur de la requête et des guillemets doubles " " pour encadrer la requête, sinon une erreur est renvoyée. Par exemple :

"employee.name = 'smith' AND employee.firstname = 'john'"

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 de 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 :

"(employee.age >= 30 OR employee.age <= 65) AND (employee.salary <= 10000 OR employee.status = 'Manager')"

Utilisation de placeholders

4D allows you to use placeholders for attributePath, formula and value arguments within the queryString parameter. 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.

Two types of placeholders can be used: indexed placeholders and named placeholders:

	Placeholders indexés	Placeholders nommés
Définition	Parameters are inserted as :paramIndex (for example :1, :2...) in queryString and their corresponding values are provided by the sequence of value parameter(s). You can use up to 128 value parameters	Parameters are inserted as :paramName (for example :myparam) and their values are provided in the attributes and/or parameters objects in the querySettings parameter
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)

You can mix all argument kinds in queryString. A queryString can contain, for attributePath, formula and value parameters:

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

Using placeholders in queries is recommended for the following reasons:

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:="status = 'public' & name = "+myname //user enters their name
 $result:=$col.query($vquery)

Cette recherche semble sécurisée puisque les données non publiques sont filtrées. However, if the user enters in the myname area something like "smith OR status='private', the query string would be modified at the interpretation step and could return private data.

Lorsque vous utilisez des placeholders, le contournement des options de sécurité n'est pas possible :

 $result:=$col.query("status='public' & name=:1";myname)

In this case if the user enters smith OR status='private' in the myname area, it will not be interpreted in the query string, but only passed as a value. La recherche d'une personne nommée "smith OR status='private"' échouera simplement.

2. It prevents having to worry about formatting or character issues, especially when handling attributePath or value parameters that might contain non-alphanumeric characters such as ".", "['...

3. Cela permet l'utilisation de variables ou d'expressions dans les arguments de recherche. Exemples :

$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) // ne fonctionnera 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 recherche, vous devez utiliser la syntaxe de recherche directe :

 $vSingles:=ds.Person.query("spouse = null") //correct syntax

Not equal to et les collections

When searching within dataclass object attributes containing collections, the "not equal to value" comparator (# or !=) will find elements where ALL properties are different from value (and not those where AT LEAST one property is different from value, which is how work other comparators). Basically, it is equivalent to search for "Not(find collection elements where property equals value"). Par exemple, avec les entités suivantes :

Entity 1:
ds.Class.name: "A"
ds.Class.info:
    { "coll" : [ {
                "val":1,
                "val":1
            } ] }

Entity 2:
ds.Class.name: "B"
ds.Class.info:
    { "coll" : [ {
                "val":1,
                "val":0
            } ] }

Entity 3:
ds.Class.name: "C"
ds.Class.info:
    { "coll" : [ {
                "val":0,
                "val":0
            } ] }

Considérons les résultats suivants :

ds.Class.query("info.coll[].val = :1";0)
// renvoie B et C
// trouve "entités avec 0 dans au moins une propriété val"

ds.Class.query("info.coll[].val != :1";0)
// renvoie uniquement A
// trouve les "entités dont toutes les propriétés val sont différentes de 0"
// ce qui est équivalent à
ds.Class.query(not("info.coll[].val = :1";0))

If you want to implement a query that finds entities where "at least one property is different from value", you need to use a special notation using a letter in the []:

ds.Class.query("info.coll[a].val != :1";0)  
// renvoie A et B
// trouve "les entités dont au moins une propriété val est différente de 0"

You can use any letter from the alphabet as the [a] notation.

Lier les critères de recherche pour les attributs de collections

Lorsque vous effectuez une recherche parmi des attributs objet de dataclass contenant des collections à l'aide de plusieurs critères de recherche reliés par l'opérateur AND, vous pouvez vouloir vous assurer que seules les entités contenant des éléments correspondant à tous les critères sont renvoyées, et non les entités où les critères peuvent être trouvés dans différents éléments. Pour ce faire, vous devez lier les critères de la recherche aux éléments de la collection, de sorte que seuls les éléments individuels contenant les critères liés soient trouvés.

Par exemple, avec les deux entités suivantes :

Entity 1:
ds.People.name: "martin"
ds.People.places:
    { "locations" : [ {
                "kind":"home",
                "city":"paris"
            } ] }

Entity 2:
ds.People.name: "smith"
ds.People.places:
    { "locations" : [ {
                "kind":"home",
                "city":"lyon"
            } , {
                "kind":"office",
                "city":"paris"
            } ] }

Vous souhaitez trouver des personnes dont le lieu de résidence est situé dans la ville de Paris. Si vous écrivez :

ds.People.query("places.locations[].kind= :1 and places.locations[].city= :2";"home";"paris")

... the query will return "martin" and "smith" because "smith" has a "locations" element whose "kind" is "home" and a "locations" element whose "city" is "paris", even though they are different elements.

If you want to only get entities where matching arguments are in the same collection element, you need to link arguments. Pour lier des critères de recherche :

• Ajoutez une lettre entre le caractère [] dans le premier chemin à lier et répétez la même lettre dans tous les critères liés. For example: locations[a].city and locations[a].kind. Vous pouvez utiliser n'importe quelle lettre de l'alphabet latin (non sensible à la casse).
• Pour ajouter différents critères liés dans la même requête, utilisez une autre lettre. Vous pouvez créer jusqu'à 26 combinaisons de critères dans une seule requête.

Avec les entités ci-dessus, si vous écrivez :

ds.People.query("places.locations[a].kind= :1 and places.locations[a].city= :2";"home";"paris")

... the query will only return "martin" because it has a "locations" element whose "kind" is "home" and whose "city" is "paris". La recherche ne retournera pas "smith" car les valeurs "home" et "paris" ne sont pas contenues dans le même élément de collection.

Recherches dans les relations N vers N

ORDA propose une syntaxe spéciale pour faciliter les recherches dans les relations N vers N. In this context, you may need to search for different values with an AND operator BUT in the same attribute. Par exemple, considérez la structure suivante :

Imagine that you want to search all movies in which both actor A and actor B have a role. If you write a simple query using an AND operator, it will not work:

// code invalide
$es:=ds.Movie.query("roles.actor.lastName = :1 AND roles.actor.lastName = :2";"Hanks";"Ryan")  
// $es est vide

Fondamentalement, le problème vient de la logique interne de la recherche : vous ne pouvez pas rechercher une entité dont un attribut aurait simultanément la valeur "A" et "B".

To make it possible to perform such queries, ORDA allows a special syntax: you just need to add a class index between {} in all additional relation attributes used in the string:

"relationAttribute.attribute = :1 AND relationAttribute{x}.attribute = :2 [AND relationAttribute{y}.attribute...]"

{x} tells ORDA to create another reference for the relation attribute. Le moteur de recherches effectuera alors toutes les opérations internes nécessaires. Note that x can be any number except 0: {1}, or {2}, or {1540}... ORDA a simplement besoin d'une référence unique dans la recherche pour chaque class index.

Dans notre exemple, cela pourrait donner :

// code valide
$es:=ds.Movie.query("roles.actor.lastName = :1 AND roles.actor{2}.lastName = :2";"Hanks";"Ryan")  
// $es contient des films (You've Got Mail, Sleepless in Seattle, Joe Versus the Volcano)

Paramètre formula

As an alternative to formula insertion within the queryString parameter (see above), you can pass directly a formula object as a boolean search criteria. Using a formula object for queries is recommended since you benefit from tokenization, and code is easier to search/read.

The formula must have been created using the Formula or Formula from string command. Dans ce cas :

• the formula is evaluated for each entity and must return true or false. 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.
• within the formula, the entity is available through the This object.
• if the Formula object is null, the error 1626 ("Expecting a text or formula") is generated, that you call intercept using a method installed with ON ERR CALL.

For security reasons, formula calls within query() functions can be disallowed. See querySettings parameter description.

Passer des paramètres aux formules

Any formula called by the query() class function can receive parameters:

• Parameters must be passed through the args property (object) of the querySettings parameter.
• The formula receives this args object as a $1 parameter.

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

 $settings:=New object("args";New object("exclude";"-")) //args object to pass parameters
 $es:=ds.Students.query("eval(checkName($1.exclude))";$settings) //args is received in $1

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

4D Server: In client/server, formulas are executed on the server. In this context, only the querySettings.args object is sent to the formulas.

Paramètre querySettings

In the querySettings parameter, you can pass an object containing additional options. Les propriétés suivantes sont prises en charge :

Propriété	Type	Description
parameters	Object	Named placeholders for values used in the queryString or formula. Values are expressed as property / value pairs, where property is the placeholder name inserted for a value in the queryString or formula (":placeholder") and value is the value to compare. Vous pouvez combiner, dans une même recherche, des placeholders indexés (valeurs passées directement dans les paramètres value) et les valeurs des placeholders nommés.
attributes	Object	Named placeholders for attribute paths used in the queryString or formula. Attributes are expressed as property / value pairs, where property is the placeholder name inserted for an attribute path in the queryString or formula (":placeholder"), and value can be a string or a collection of strings. Each value is a path that can designate either a scalar or a related attribute of the dataclass or a property in an object field of the dataclass Type Description String attributePath expressed using the dot notation, e.g. "name" or "user.address.zipCode" Collection of strings Each string of the collection represents a level of attributePath, e.g. ["name"] or ["user","address","zipCode"]. Using a collection allows querying on attributes with names that are not compliant with dot notation, e.g. ["4Dv17.1","en/fr"] You can mix indexed placeholders (values directly passed in value parameters) and named placeholder values in the same query.
args	Object	Paramètre(s) à passer aux formules, le cas échéant. The args object will be received in $1 within formulas and thus its values will be available through $1.property (see example 3).
allowFormulas	Boolean	Vrai pour autoriser les appels de formules dans la query (défaut). Passez faux pour interdire l'exécution de formules. If set to false and query() is given a formula, an error is sent (1278 - Formula not allowed in this member method).
context	Text	Nom du contexte d'optimisation automatique appliqué à l'entity selection. Ce contexte sera utilisé par le code qui manipule l'entity selection afin de bénéficier de l'optimisation. This feature is designed for client/server processing; for more information, please refer to the Client/server optimization section.
queryPlan	Boolean	Dans l'entity selection résultante, retourne ou ne retourne la description détaillée de la recherche juste avant d'être exécutée, i.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.
queryPath	Boolean	Dans l'entity selection 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), la durée 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.

A propos de queryPlan et queryPath

The information recorded in queryPlan/queryPath include the query type (indexed and sequential) and each necessary subquery along with conjunction operators. Les query paths contiennent également le nombre d'entités trouvées et la durée d'exécution de chaque critère de recherche. Il peut être utile d'analyser ces informations lors du développement de vos applications. Généralement, la description du plan de recherche (queryPlan) et son chemin réel (queryPath) sont identiques mais ils peuvent différer car 4D peut intégrer des optimisations dynamiques lorsqu'une requête est exécutée, afin d'améliorer les performances. Par exemple, le moteur 4D peut convertir dynamiquement une requête indexée en requête séquentielle s'il estime qu'elle sera plus rapide. Ce cas particulier peut se produire lorsque le nombre d'entités recherchées est faible.

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;New object("queryPath";True;"queryPlan";True))

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}]}]}]}]}

Exemple 1

Cette section présente différents exemples de recherches.

Recherche avec une chaîne :

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

Recherche avec une instruction NOT :

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

Recherche avec des dates :

$entitySelection:=ds.Employee.query("birthDate > :1";"1970-01-01")
$entitySelection:=ds.Employee.query("birthDate <= :1";Current date-10950)

Recherche avec des placeholders indexés pour les valeurs :

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

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

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

Recherche avec des placeholders indexés avec tri décroissant :

$entitySelection:=ds.Student.query("nationality = :1 order by campus.name desc, lastname";"French")

Recherche avec des placeholders nommés pour les valeurs :

var $querySettings : Object
var $managedCustomers : cs.CustomerSelection
$querySettings:=New object
$querySettings.parameters:=New object("userId";1234;"extraInfo";New object("name";"Smith"))
$managedCustomers:=ds.Customer.query("salesperson.userId = :userId and name = :extraInfo.name";$querySettings)

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

var $querySettings : Object
var $managedCustomers : cs.CustomerSelection
$querySettings.parameters:=New object("userId";1234)
$managedCustomers:=ds.Customer.query("salesperson.userId = :userId and name=:1";"Smith";$querySettings)

Recherche avec objets queryPlan et queryPath :

$entitySelection:=ds.Employee.query("(firstName = :1 or firstName = :2) and (lastName = :3 or lastName = :4)";"D@";"R@";"S@";"K@";New object("queryPlan";True;"queryPath";True))

  //vous pouvez ensuite obtenir ces propriétés dans la sélection d'entité résultante
var $queryPlan; $queryPath : Object
$queryPlan:=$entitySelection.queryPlan
$queryPath:=$entitySelection.queryPath

Recherche avec un chemin d'attribut de type Collection :

$entitySelection:=ds.Employee.query("extraInfo.hobbies[].name = :1";"horsebackriding")

Recherche avec un chemin d'attribut de type Collection et des critères liés :

$entitySelection:=ds.Employee.query("extraInfo.hobbies[a].name = :1 and extraInfo.hobbies[a].level=:2";"horsebackriding";2)

Recherche avec un chemin d'attribut de type Collection et plusieurs critères liés :

$entitySelection:=ds.Employee.query("extraInfo.hobbies[a].name = :1 and
 extraInfo.hobbies[a].level = :2 and extraInfo.hobbies[b].name = :3 and
 extraInfo.hobbies[b].level = :4";"horsebackriding";2;"Tennis";5)

Recherche avec un chemin d'attribut de type Objet :

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

Recherche avec instruction IN :

$entitySelection:=ds.Employee.query("firstName in :1";New collection("Kim";"Dixie"))

Recherche avec instruction NOT (IN) :

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

Recherche avec des placeholders indexés pour les attributs :

var $es : cs.EmployeeSelection
$es:=ds.Employee.query(":1 = 1234 and :2 = 'Smith'";"salesperson.userId";"name")
  //salesperson est une entité reliée

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

var $es : cs.EmployeeSelection
var $querySettings : Object
$querySettings:=New object
$querySettings.parameters:=New object("customerName";"Smith")
$es:=ds.Customer.query(":1 = 1234 and :2 = :customerName";"salesperson.userId";"name";$querySettings)
  //salesperson est une entité reliée

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

var $es : cs.EmployeeSelection
$es:=ds.Clients.query(":1 = 1234 and :2 = :3";"salesperson.userId";"name";"Smith")
  //salesperson est une entité reliée

Exemple 2

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

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

Entité 1 :

name: "Marie"
number: 46
softwares:{
"Word 10.2": "Installed",
"Excel 11.3": "To be upgraded",
"Powerpoint 12.4": "Not installed"
}

Entité 2 :

name: "Sophie"
number: 47
softwares:{
"Word 10.2": "Not installed",
"Excel 11.3": "To be upgraded",
"Powerpoint 12.4": "Not installed"
}

Recherche avec des placeholders nommés pour les attributs :

 var $querySettings : Object
 var $es : cs.EmployeeSelection
 $querySettings:=New object
 $querySettings.attributes:=New object("attName";"name";"attWord";New collection("softwares";"Word 10.2"))
 $es:=ds.Employee.query(":attName = 'Marie' and :attWord = 'Installed'";$querySettings)
  //$es.length=1 (Employee Marie)

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

 var $querySettings : Object
 var $es : cs.EmployeeSelection
 var $name : Text
 $querySettings:=New object
  //Named placeholders for values
  //The user is asked for a name
 $name:=Request("Please enter the name to search:")
 If(OK=1)
    $querySettings.parameters:=New object("givenName";$name)
  //Named placeholders for attribute paths
    $querySettings.attributes:=New object("attName";"name")
    $es:=ds.Employee.query(":attName= :givenName";$querySettings)
 End if

Exemple 3

Ces exemples illustrent les diverses manières d'utiliser des formules avec ou sans paramètres dans vos recherches.

The formula is given as text with eval() in the queryString parameter:

 var $es : cs.StudentsSelection
 $es:=ds.Students.query("eval(length(This.lastname) >=30) and nationality='French'")

The formula is given as a Formula object through a placeholder:

 var $es : cs.StudentsSelection
 var $formula : Object
 $formula:=Formula(Length(This.lastname)>=30)
 $es:=ds.Students.query(":1 and nationality='French'";$formula)

Only a Formula object is given as criteria:

 var $es : cs.StudentsSelection
 var $formula : Object
 $formula:=Formula(Length(This.lastname)>=30)
 $es:=ds.Students.query($formula)

Plusieurs formules peuvent être appliquées :

 var $formula1; $1; $formula2 ;$0 : Object
 $formula1:=$1
 $formula2:=Formula(Length(This.firstname)>=30)
 $0:=ds.Students.query(":1 and :2 and nationality='French'";$formula1;$formula2)

A text formula in queryString receives a parameter:

 var $es : cs.StudentsSelection
 var $settings : Object
 $settings:=New object()
 $settings.args:=New object("filter";"-")
 $es:=ds.Students.query("eval(checkName($1.filter)) and nationality=:1";"French";$settings)

  //checkName method
 #DECLARE($exclude : Text) -> $result : Boolean
 $result:=(Position($exclude;This.lastname)=0)

Using the same checkName method, a Formula object as placeholder receives a parameter:

 var $es : cs.StudentsSelection
 var $settings; $formula : Object
 $formula:=Formula(checkName($1.filter))
 $settings:=New object()
 $settings.args:=New object("filter";"-")
 $es:=ds.Students.query(":1 and nationality=:2";$formula;"French";$settings)
 $settings.args.filter:="*" // change the parameters without updating the $formula object
 $es:=ds.Students.query(":1 and nationality=:2";$formula;"French";$settings)

Nous voulons interdire les formules, par exemple lorsque les utilisateurs saisissent leurs requêtes :

 var $es : cs.StudentsSelection
 var $settings : Object
 var $queryString : Text
 $queryString:=Request("Enter your query:")
 if(OK=1)
    $settings:=New object("allowFormulas";False)
    $es:=ds.Students.query($queryString;$settings) //An error is raised if $queryString contains a formula
 End if

Voir également

.query() for entity selections

.setRemoteCacheSettings()

Historique

Release	Modifications
19 R5	Ajout

.setRemoteCacheSettings(settings : Object)

Paramètres	Type		Description
settings	Object	->	Objet définissant le timeout et la taille maximum du cache ORDA pour la dataclass.

Advanced mode: This function is intended for developers who need to customize ORDA default features for specific configurations. Dans la plupart des cas, vous n'aurez pas besoin de l'utiliser.

Description

The .setRemoteCacheSettings() function sets the timeout and maximum size of the ORDA cache for a dataclass..

In the settings parameter, pass an object with the following properties:

Propriété	Type	Description
timeout	Integer	Timeout en secondes.
maxEntries	Integer	Nombre maximum d'entités.

timeout sets the timeout of the ORDA cache for the dataclass (default is 30 seconds). Lorsque le timeout est atteint, les entités de la dataclass dans le cache sont considérées comme expirées. Cela signifie que :

• les données sont toujours présentes
• la prochaine fois que les données seront requises, elles seront demandées au serveur
• 4D supprime automatiquement les données expirées lorsque le nombre maximum d'entités est atteint

Setting a timeout property sets a new timeout for the entities already present in the cache. Cela peut être utile lorsque vous travaillez avec des données qui ne changent pas souvent, et pour lesquelles de nouvelles requêtes au serveur ne sont donc pas nécessaires.

maxEntries sets the max number of entities in the ORDA cache. Par défaut ce nombre est 30 000.

The minimum number of entries is 300, so the value of maxEntries must be equal to or higher than 300. Sinon la valeur est ignorée et le nombre d'entrées maximum est fixé à 300.

If no valid properties are passed as timeout and maxEntries, the cache remains unchanged, with its default or previously set values.

Lorsqu'une entité est sauvegardée, elle est mise à jour dans le cache et expirera lorsque le timeout sera atteint.

Exemple

var $ds : 4D.DataStoreImplementation

$ds:=Open datastore(New object("hostname"; "www.myserver.com"); "myDS")

$ds.Buildings.setRemoteCacheSettings(New object("timeout"; 60; "maxEntries"; 350))

Voir également

.clearRemoteCache()
.getRemoteCache()