DataClass
Une dataclass fournit une interface objet à une table de la base de données. Toutes les dataclasses d'une application 4D sont disponibles en tant que propriété du datastore ds
.
Sommaire
.attributeName : DataClassAttribute objets disponibles directement en tant que propriétés |
.all ( { settings : Object } ) : 4D.EntitySelection interroge le datastore pour trouver toutes les entités de la dataclass et les renvoie en tant qu'entity selection |
.clearRemoteCache() vide le cache ORDA d'une dataclass |
.fromCollection( objectCol : Collection { ; settings : Object } ) : 4D.EntitySelection modifie ou crée des entités dans la dataclass en utilisant la collection d'objets objectCol et retourne l'entity selection correspondante |
.get( primaryKey : Integer { ; settings : Object } ) : 4D.Entity .get( primaryKey : Text { ; settings : Object } ) : 4D.Entity interroge la dataclass pour récupérer l'entité correspondant au paramètre primaryKey |
.getCount() : Integer retourne le nombre d'entités dans une dataclass |
.getDataStore() : cs.DataStore retourne le datastore de la dataclass |
.getInfo() : Object retourne un objet qui fournit des informations sur la dataclass |
.getRemoteCache() : Object retourne un objet qui contient le cache ORDA pour la dataclass. |
.new() : 4D.Entity crée en mémoire et renvoie une nouvelle entité vide pour la dataclass |
.newSelection( { keepOrder : Integer } ) : 4D.EntitySelection crée en mémoire une entity selection vide, non partageable, liée à la dataclass |
.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) |
.setRemoteCacheSettings(settings : Object) sets the timeout and maximum size of the ORDA cache for a dataclass. |
.attributeName
Historique
Version | Modifications |
---|---|
v17 | Ajout |
.attributeName : DataClassAttribute
Description
Les attributs des dataclasses sont des objets disponibles directement en tant que propriétés de ces classes.
Les objets renvoyés sont du type DataClassAttribute
. Ces objets ont des propriétés que vous pouvez utiliser et lire pour obtenir des informations sur vos attributs de dataclass.
Les objets de l'attribut Dataclass peuvent être modifiés, mais la structure sous-jacente de la base de données ne sera pas altérée.
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
Version | Modifications |
---|---|
v17 R5 | Prise en charge du paramètre settings |
v17 | 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
La fonction .all()
interroge le datastore pour trouver toutes les entités de la dataclass et les renvoie en tant qu'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
Dans le paramètre optionnel settings, vous pouvez passer un objet contenant des options supplémentaires. 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. Cette fonctionnalité est conçue pour le traitement client/serveur ORDA. |
Pour obtenir le nombre total d'entités dans une dataclass, il est recommandé d'utiliser la fonction
getCount()
qui est plus optimisée que l'expressionds.myClass.all().length
.
Exemple
var $allEmp : cs.EmployeeSelection
$allEmp:=ds.Employee.all()
.clearRemoteCache()
Historique
Version | Modifications |
---|---|
v19 R5 | Ajout |
.clearRemoteCache()
Paramètres | Type | Description | |
---|---|---|---|
Ne requiert aucun paramètre |
|
Description
La fonction .clearRemoteCache()
vide le cache ORDA d'une dataclass.
Cette fonction ne réinitialise pas les valeurs de
timeout
etmaxEntries
.
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
Version | Modifications |
---|---|
v17 R5 | Prise en charge du paramètre settings |
v17 | 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
La fonction .fromCollection()
modifie ou crée des entités dans la dataclass en utilisant la collection d'objets objectCol et retourne l'entity selection correspondante.
Dans le paramètre objectCol passez une collection d'objets destinée à créer ou à modifier des entités de la 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.
La correspondance entre les objets de la collection et les entités est effectuée au niveau des noms d'attributs et de leur type de données. 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.
Mode création ou modification
Pour chaque objet de 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.
- si l'objet contient une propriété booléenne "__NEW" fixée à vrai, l'entité est créée avec les valeurs correspondantes des propriétés de l'objet. 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 nested objects featuring related entities must contain a "__KEY" property (filled with the primary key value of the related entity) or the primary key attribute of the related entity itself. The use of a __KEY property allows independence from the primary key attribute name.
Related entities
Les objets de objectCol peuvent contenir un ou plusieurs objet(s) imbriqué(s) décrivant une ou plusieurs entité(s) relative(s), ce qui peut être utile pour créer ou modifier des relations entre les entités.
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"). Pour plus d'informations, voir Verrouillage d'une entité.
settings
Dans le paramètre optionnel settings, vous pouvez passer un objet contenant des options supplémentaires. 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. Cette fonctionnalité est conçue pour le traitement client/serveur ORDA. |
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 //Clé primaire existante dans la dataclass Employee
$emp.firstName:="Arthur"
$emp.lastName:="Martin"
$emp.employer:=New object("ID";121) //Clé primaire existante dans la dataclass liée Company
// Nous modifions la Company de cet employé en lui assignant une autre clé primaire existante dans la dataclass liée 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 //Clé primaire existante dans la dataclass Employee
$emp.firstName:="John"
$emp.lastName:="Boorman"
$emp.employer:=New object("ID";121) //Clé primaire existante dans la dataclass liée Company
// Nous modifions la Company de cet employé en lui assignant une autre clé primaire existante dans la dataclass relative 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) //Clé primaire existante dans la dataclass liée 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 //clé primaire qui n'existe pas
$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 // Clé primaire inexistante
$emp.firstName:="Simone"
$emp.lastName:="Martin"
$emp.__NEW:=True
$empsCollection.push($emp)
$emp2:=New object
$emp2.ID:=10001 // ERREUR clé primaire identique
$emp2.firstName:="Marc"
$emp2.lastName:="Smith"
$emp2.__NEW:=True
$empsCollection.push($emp2)
$employees:=ds.Employee.fromCollection($empsCollection)
//la première entité est créée
//erreur clé dupliquée pour la seconde
Voir également
.get()
Historique
Version | Modifications |
---|---|
v17 | 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
La fonction .get()
interroge la dataclass pour récupérer l'entité correspondant au paramètre primaryKey.
Dans primaryKey, passez la valeur de clé primaire de l'entité à récupérer. Le type de valeur doit correspondre au type de clé primaire définie dans le datastore (entier long ou texte). Vous pouvez également vous assurer que la valeur de la clé primaire est toujours renvoyée en tant que texte en utilisant la fonction .getKey()
avec le paramètre dk key as string
.
Si aucune entité avec primaryKey n'est trouvée, une entité Null est retournée.
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
Dans le paramètre optionnel settings, vous pouvez passer un objet contenant des options supplémentaires. 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. Cette fonctionnalité est conçue pour le traitement client/serveur ORDA. |
Exemple 1
var $entity : cs.EmployeeEntity
var $entity2 : cs.InvoiceEntity
$entity:=ds.Employee.get(167) // retourne l'entité dont la valeur de clé primaire est 167
$entity2:=ds.Invoice.get("DGGX20030") // retourne l'entité dont la valeur de clé primaire est "DGGX20030"
Exemple 2
Cet exemple illustre l'utilisation de la propriété context :
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) // Dans la méthode completeAllData, une optimisation est lancée et associée au contexte "detail"
$e2:=ds.Employee.get(2;$settings)
completeAllData($e2) // Dans la méthode completeAllData, l'optimisation associée au contexte "detail" est appliquée
$e3:=ds.Employee.get(3;$settings2)
completeSummary($e3) //Dans la méthode completeSummary, une optimisation est lancée et associée au contexte "summary"
$e4:=ds.Employee.get(4;$settings2)
completeSummary($e4) //Dans la méthode completeSummary, l'optimisation associée au contexte "summary" est appliquée
.getCount()
Historique
Version | Modifications |
---|---|
v19 R5 | Ajout |
.getCount() : Integer
Paramètres | Type | Description | |
---|---|---|---|
result | Integer | <- | Nombre d'entités dans la dataclass |
|
Description
La fonction .getCount()
retourne le nombre d'entités dans une 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
Version | Modifications |
---|---|
v17 R5 | Ajout |
.getDataStore() : cs.DataStore
Paramètres | Type | Description | |
---|---|---|---|
Résultat | cs.DataStore | <- | Datastore de la dataclass |
|
Description
La fonction .getDataStore()
retourne le datastore de la dataclass.
Le datastore peut être :
- le datastore principal, retourné par la commande
ds
. - un datastore distant, ouvert à l'aide de la commande
Open datastore
.
Exemple
La méthode projet SearchDuplicate recherche des valeurs dupliquées dans une dataclass.
var $pet : cs.CatsEntity
$pet:=ds.Cats.all().first() //lire une entité
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
Version | Modifications |
---|---|
v19 R3 | Ajout propriété exposed |
v17 R5 | Ajout |
.getInfo() : Object
Paramètres | Type | Description | |
---|---|---|---|
Résultat | Object | <- | Informations sur la dataclass |
|
Description
La fonction .getInfo()
retourne un objet qui fournit des informations sur la dataclass. Cette fonction est utile pour l'écriture de code générique.
Objet retourné
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) //Exécuter des actions sur une entité
$status:=$entity.save()
if($status.success)
ALERT("Enregistrement mis à jour dans la 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] // Le cas échéant, l'attribut correspondant à la clé primaire est accessible
Voir également
.getRemoteCache()
Historique
Version | Modifications |
---|---|
v19 R5 | Ajout |
.getRemoteCache() : Object
Paramètres | Type | Description | |
---|---|---|---|
result | Object | <- | Objet décrivant le contenu du cache ORDA pour la dataclass. |
|
Mode avancé : Cette fonction est destinée aux développeurs qui souhaitent personnaliser les fonctionnalités par défaut de ORDA dans le cadre de configurations spécifiques. Dans la plupart des cas, vous n'aurez pas besoin de l'utiliser.
Description
La fonction getRemoteCache()
retourne un objet qui contient le cache ORDA pour la dataclass..
Si elle est appelée depuis une application 4D monoposte, la fonction retourne 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. |
Chaque objet "entrée" de la collection entries
contient les propriétés suivantes :
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é. |
L'objet data
de chaque entrée contient les propriétés suivantes :
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
Dans l'exemple suivant, $ds.Persons.all()
charge la première entité avec tous ses attributs. Ensuite, l'optimiseur de requêtes entre en jeu, et seuls firstname
et address.city
sont chargés.
Notez que address.city
est chargé dans le cache de la dataclass Persons
.
Seule la première entité de la dataclass Address
est stockée dans le 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
Version | Modifications |
---|---|
v17 | Ajout |
.new() : 4D.Entity
Paramètres | Type | Description | |
---|---|---|---|
Résultat | 4D.Entity | <- | Nouvelle entité correspondant à la dataclass |
|
Description
La fonction .new()
crée en mémoire et renvoie une nouvelle entité vide pour la dataclass.
L'objet entité est créé en mémoire et n'est pas sauvegardé dans la base de données tant que la fonction .save( )
n'est pas appelée. Si l'entité est supprimée avant d'être sauvegardée, elle ne peut pas être récupérée.
4D Server: En client-serveur, si la clé primaire de la table correspondante est auto-incrémentée, elle sera calculée au moment de la sauvegarde de l'entité sur le serveur.
Tous les attributs de l'entité sont initialisés avec la valeur null.
Les attributs peuvent être initialisés à des valeurs par défaut si l'option Traduire les NULL en valeurs vides est sélectionnée au niveau de la structure de la base 4D.
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() //crée une référence
$entity.info:="New entry" //valorise l'attribut info
$entity.save() //sauvegarde l'entité
.newSelection()
Historique
Version | Modifications |
---|---|
v17 | Ajout |
.newSelection( { keepOrder : Integer } ) : 4D.EntitySelection
Paramètres | Type | Description | |
---|---|---|---|
keepOrder | Integer | -> | dk keep ordered : crée une entity selection triée,dk non ordered : crée une entity selection non triée (défaut si omis) |
Résultat | 4D.EntitySelection | <- | Nouvelle entity selection vide liée à la dataclass |
|
Description
La fonction .newSelection()
crée en mémoire une entity selection vide, non partageable, liée à la dataclass.
Pour plus d'informations sur les sélections d'entités non partageables, veuillez vous reporter à cette section.
Si vous voulez créer une entity selection triée, passez le sélecteur dk keep ordered
dans le paramètre keepOrder. Par défaut, si vous omettez ce paramètre ou si vous passez le sélecteur dk non ordered
la fonction crée une entity selection non triée. Les entity selections non triées sont plus rapides, mais vous ne pouvez pas vous fier aux positions des entités. Pour plus d'informations, voir Entity selections triées vs Entity selections non-triées.
Une fois créée, l'entity selection ne contient aucune entité (mySelection.length
retourne 0). Cette fonction vous permet de construire progressivement des entity selections en effectuant des appels à la fonction add()
.
Exemple
var $USelection; $OSelection : cs.EmployeeSelection
$USelection:=ds.Employee.newSelection() //crée une entity selection non triée vide
$OSelection:=ds.Employee.newSelection(dk keep ordered) //crée une entity selection triée vide
.query()
Historique
Version | Modifications |
---|---|
v17 R6 | Prise en charge des paramètres Formula |
v17 R5 | Prise en charge des placeholders pour les valeurs |
v17 | 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 constituée des entités de la dataclass correspondant au(x) critère(s) de recherche fournis 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), pour toutes les entités de la dataclass, et retourne un nouvel objet de type EntitySelection
contenant toutes les entités trouvées. Le mode lazy loading est appliqué.
Si aucune entité correspondante n'est trouvée, une EntitySelection
vide est retournée.
queryString parameter
Le paramètre queryString doit respecter la syntaxe suivante :
attributePath|formula comparator value
{logicalOperator attributePath|formula comparator value}
{order by attributePath {desc | asc}}
where:
attributePath : Chemin de l'attribut sur lequel vous souhaitez exécuter la recherche. Ce paramètre peut contenir un nom simple (par exemple "pays") ou un chemin d'attribut valide (par exemple "pays.nom"). In case of an attribute path whose type is
Collection
,[]
notation is used to handle all the occurences (for examplechildren[].age
).Vous ne pouvez pas utiliser directement des attributs dont les noms contiennent des caractères spéciaux tels que ".", "[ ]", ou "=", ">", "#"..., car ils ne seront pas correctement évalués dans la chaîne de recherche. Si vous souhaitez rechercher ces attributs, vous devez utiliser des placeholders, qui permettent d'utiliser un ensemble de caractères plus étendu dans les chemins d'attribut (voir Utiliser des placeholders ci-dessous).
formula : Une formule valide passée en
Text
ou enObject
. La formule sera évaluée pour chaque entité traitée et doit retourner une valeur booléenne. Dans la formule, l'entité est disponible via l'objetThis
.Text : la chaine de formule doit être précédée de la déclaration
eval()
, afin que l'analyseur de requêtes évalue l'expression correctement. Par exemple : "eval(length(This.lastname) >=30)"Object: l'objet formule est passé en tant que placeholder (voir ci-dessous). La formule doit avoir été créée à l'aide des commandes
Formula
ouFormula from string
.- Keep in mind that 4D formulas only support
&
and|
symbols as logical operators.
- Keep in mind that 4D formulas only support
- 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. Ce point est détaillé dans le paragraphe Paramètre formula ci-dessous.
- Vous pouvez également passer directement un paramètre
formula
au lieu d'un paramètrequeryString
(recommandé lorsque les formules sont plus complexes). Voir le paragraphe Paramètre formula ci-dessous. - Pour des raisons de sécurité, les appels de formule dans les fonctions
query()
peuvent être interdits. Voir la description du paramètrequerySettings
.
comparator : symbole d'opérateur utilisé pour comparer attributePath et 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 #, != Supports the wildcard (@). 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 Parenthesis are mandatory when NOT is used before a statement containing several operators. 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 : valeur à comparer à la valeur courante de l'attribut de chaque entité de la sélection ou élément de la collection. Peut être un placeholder (voir Utiliser des placeholders ci-dessous) ou toute expression correspondant à la propriété du type de donnée. Lorsque vous utilisez une valeur constante, les règles suivantes doivent être respectées :
- Les valeurs constantes de type texte peuvent être passées avec ou sans guillemets (voir Utilisation des guillemets ci-dessous). 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.
- Valeurs constantes de typebooléen: true or false (sensible à la casse).
- Valeurs constantes de type numérique : les décimales doivent être séparées par un '.'
- Constantes de type date : "YYYY-MM-DD" format
- Constantes null : en utilisant le mot-clé "null", la recherche trouvera les propriétés ayant la valeur null et undefined.
- Dans le cas d'une recherche avec un comparateur IN, valuedoit être une collection, ou des valeurs du même type que les données du chemin d'attribut, fournies entre [ ] et séparées par des virgules (pour les chaînes, les caractères
"
doivent être échappés avec des\
).
logicalOperator : utilisé pour relier des conditions multiples dans la recherche (optionnel). Vous pouvez utiliser un des opérateurs logiques suivants (le nom ou le symbole peut être passé) :
Conjonction Symbole(s) AND &, &&, and OU |,||, or order by attributePath : vous pouvez inclure une déclaration order by attributePath dans la requête afin que les données résultantes soient triées selon cette déclaration. Vous pouvez utiliser plusieurs tris par déclaration, en les séparant par des virgules (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. >Si vous utilisez cette déclaration, l'entity selection retournée est triée (pour plus d'informations, veuillez consulter Entity selections triées vs Entity selection non triées).
Using quotes
When you use quotes within queries, you must use single quotes ' ' inside the query and double quotes " " to enclose the whole query, otherwise an error is returned. 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).
Using parenthesis
You can use parentheses in the query to give priority to the calculation. For example, you can organize a query as follows:
"(employee.age >= 30 OR employee.age <= 65) AND (employee.salary <= 10000 OR employee.status = 'Manager')"
Using placeholders
4D allows you to use placeholders for attributePath, formula and value arguments within the queryString parameter. A placeholder is a parameter that you insert in query strings and that is replaced by another value when the query string is evaluated. The value of placeholders is evaluated once at the beginning of the query; it is not evaluated for each element.
Two types of placeholders can be used: indexed placeholders and named placeholders:
Placeholders indexés | Placeholders nommés | |
---|---|---|
Définition | You can mix all argument kinds in queryString. A queryString can contain, for attributePath, formula and value parameters: | Les paramètres sont insérés sous la forme :paramName (par exemple :myparam) et leurs valeurs sont fournies dans les objets attributes et/ou parameters dans le paramètre querySettings |
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:
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 //l'utilisateur saisit son nom
$result:=$col.query($vquery)This query seems secured since non-public data are filtered. 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.
When using placeholders, overriding security conditions is not 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. Looking for a person named "smith OR status='private'" will just fail.
Cela résout les questions liées au formatage des valeurs ou des caractères, notamment lorsque vous gérez des paramètres attributePath et value qui peuvent contenir des caractères non-alphanumériques tels que ".", "["...
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")
Looking for null values
When you look for null values, you cannot use the placeholder syntax because the query engine considers null as an unexpected comparison value. For example, if you execute the following query:
$vSingles:=ds.Person.query("spouse = :1";Null) // ne fonctionnera PAS
You will not get the expected result because the null value will be evaluated by 4D as an error resulting from the parameter evaluation (for example, an attribute coming from another query). For these kinds of queries, you must use the direct query syntax:
$vSingles:=ds.Person.query("spouse = null") //syntaxe valide
Not equal to in 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"). For example, with the following entities:
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
} ] }
Consider the following results:
ds.Class.query("info.coll[].val = :1";0)
// returns B and C
// finds "entities with 0 in at least one val property"
ds.Class.query("info.coll[].val != :1";0)
// returns A only
// finds "entities where all val properties are different from 0"
// which is the equivalent to
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)
// returns A and B
// finds "entities where at least one val property is different from 0"
You can use any letter from the alphabet as the [a]
notation.
Linking collection attribute query arguments
This feature is only available in queries on dataclasses and entity selections. It cannot be used in queries on collections.
When searching within dataclass object attributes containing collections using multiple query arguments joined by the AND operator, you may want to make sure that only entities containing elements that match all arguments are returned, and not entities where arguments can be found in different elements. To do this, you need to link query arguments to collection elements, so that only single elements containing linked arguments are found.
For example, with the following two entities:
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"
} ] }
You want to find people with a "home" location kind in the city "paris". If you write:
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. To link query arguments:
- Ajoutez une lettre entre le caractère [] dans le premier chemin à lier et répétez la même lettre dans tous les arguments liés. Par exemple :
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.
With the above entities, if you write:
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". The query will not return "smith" because the values "home" and "paris" are not in the same collection element.
Queries in many-to-many relations
ORDA offers a special syntax to facilitate queries in many-to-many relations. In this context, you may need to search for different values with an AND
operator BUT in the same attribute. For example, take a look at the following structure:
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
Basically, the issue is related to the internal logic of the query: you cannot search for an attribute whose value would be both "A" and "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. It will then perform all the necessary bitmap operations internally. Note that x can be any number except 0: {1}, or {2}, or {1540}... ORDA only needs a unique reference in the query for each class index.
In our example, it would be:
// 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)
formula parameter
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.
La formule doit avoir été créée à l'aide des commandes Formula
ou Formula from string
. In this case:
- formula est évaluée pour chaque entité et doit renvoyer vrai ou faux. Lors de l'exécution de la requête, si le résultat de la formule n'est pas un booléen, il est considéré comme faux.
- dans formula, l'entité est disponible via l'objet
This
. - si l'objet
Formula
est null, l'erreur 1626 ("Attente d'un texte ou d'une formule") est générée, que vous pouvez intercepter à l'aide d'une méthode installée avecON ERR CALL
.Pour des raisons de sécurité, les appels de formule dans les fonctions
query()
peuvent être interdits. Voir la description du paramètre querySettings.
Passing parameters to formulas
Any formula called by the query()
class function can receive parameters:
- Les paramètres doivent être passés via la propriété args du paramètre querySettings.
- La formule reçoit cet objet args en tant que paramètre $1.
This small code shows the principles of how parameter are passed to methods:
$settings:=New object("args";New object("exclude";"-")) //objet args pour passer des paramètres
$es:=ds.Students.query("eval(checkName($1.exclude))";$settings) //args est reçu dans $1
Additional examples are provided in example 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.
querySettings parameter
In the querySettings parameter, you can pass an object containing additional options. The following properties are supported:
Propriété | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
parameters | Object | Placeholders nommés pour les valeurs utilisées dans queryString ou formula. Les valeurs sont exprimées sous forme de paires propriété / valeur, où propriété est le nom du placeholder inséré pour une valeur dans queryString ou formula (":placeholder") et où valeur correspond à la valeur à comparer. 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 | Placeholders nommés pour les chemins d'attributs utilisés dans queryString ou formula. Les attributs sont exprimés sous forme de paires propriété / valeur, où propriété est le nom du placeholder inséré pour un chemin d'attribut dans queryString or formula (":placeholder"), et où valeur peut être une chaine ou une collection de chaines. Chaque valeur est un chemin qui peut désigner soit un attribut scalaire ou relatif de la dataclass soit une propriété d'un champ objet de la dataclass
| ||||||
args | Object | Paramètre(s) à passer aux formules, le cas échéant. L'objet args sera reçu dans $1 à l'intérieur des formules et donc ses valeurs seront disponibles via la propriété $1.property (cf. exemple 3). | ||||||
allowFormulas | Boolean | Vrai pour autoriser les appels de formules dans la query (défaut). Passez faux pour interdire l'exécution de formules. Si la query() contient une formule alors que cette propriété est à Faux, une erreur est retournée (1278 - Formule non autorisée). | ||||||
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. Cette fonctionnalité est conçue pour le traitement client/serveur ; pour plus d'informations, veuillez vous reporter à la section Optimisation client/serveur. | ||||||
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. Note : Cette propriété est prise en charge uniquement par les fonctions entitySelection.query() et dataClass.query() . | ||||||
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. Note : Cette propriété est prise en charge uniquement par les fonctions entitySelection.query() et dataClass.query() . |
About queryPlan and queryPath
The information recorded in queryPlan
/queryPath
include the query type (indexed and sequential) and each necessary subquery along with conjunction operators. Query paths also contain the number of entities found and the time required to execute each search criterion. You may find it useful to analyze this information while developing your application(s). Generally, the description of the query plan and its path are identical but they can differ because 4D can implement dynamic optimizations when a query is executed in order to improve performance. For example, the 4D engine can dynamically convert an indexed query into a sequential one if it estimates that it is faster. This particular case can occur when the number of entities being searched for is low.
For example, if you execute the following query:
$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
This section provides various examples of queries.
Query on a string:
$entitySelection:=ds.Customer.query("firstName = 'S@'")
Query with a NOT statement:
$entitySelection:=ds.Employee.query("not(firstName=Kim)")
Queries with dates:
$entitySelection:=ds.Employee.query("birthDate > :1";"1970-01-01")
$entitySelection:=ds.Employee.query("birthDate <= :1";Current date-10950)
Query with indexed placeholders for values:
$entitySelection:=ds.Customer.query("(firstName = :1 or firstName = :2) and (lastName = :3 or lastName = :4)";"D@";"R@";"S@";"K@")
Query with indexed placeholders for values on a related dataclass:
$entitySelection:=ds.Employee.query("lastName = :1 and manager.lastName = :2";"M@";"S@")
Query with indexed placeholder including a descending order by statement:
$entitySelection:=ds.Student.query("nationality = :1 order by campus.name desc, lastname";"French")
Query with named placeholders for values:
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)
Query that uses both named and indexed placeholders for values:
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)
Query with queryPlan and queryPath objects:
$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
Query with an attribute path of Collection type:
$entitySelection:=ds.Employee.query("extraInfo.hobbies[].name = :1";"horsebackriding")
Query with an attribute path of Collection type and linked attributes:
$entitySelection:=ds.Employee.query("extraInfo.hobbies[a].name = :1 and extraInfo.hobbies[a].level=:2";"horsebackriding";2)
Query with an attribute path of Collection type and multiple linked attributes:
$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)
Query with an attribute path of Object type:
$entitySelection:=ds.Employee.query("extra.eyeColor = :1";"blue")
Query with an IN statement:
$entitySelection:=ds.Employee.query("firstName in :1";New collection("Kim";"Dixie"))
Query with a NOT (IN) statement:
$entitySelection:=ds.Employee.query("not (firstName in :1)";New collection("John";"Jane"))
Query with indexed placeholders for attributes:
var $es : cs.EmployeeSelection
$es:=ds.Employee.query(":1 = 1234 and :2 = 'Smith'";"salesperson.userId";"name")
//salesperson est une entité reliée
Query with indexed placeholders for attributes and named placeholders for values:
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
Query with indexed placeholders for attributes and values:
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
This section illustrates queries with named placeholders for attributes.
Given an Employee dataclass with 2 entities:
Entity 1:
name: "Marie"
number: 46
softwares:{
"Word 10.2": "Installed",
"Excel 11.3": "To be upgraded",
"Powerpoint 12.4": "Not installed"
}
Entity 2:
name: "Sophie"
number: 47
softwares:{
"Word 10.2": "Not installed",
"Excel 11.3": "To be upgraded",
"Powerpoint 12.4": "Not installed"
}
Query with named placeholders for attributes:
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)
Query with named placeholders for attributes and values:
var $querySettings : Object
var $es : cs.EmployeeSelection
var $name : Text
$querySettings:=New object
//Placeholders pour les valeurs
//Il est demandé à l'utilisateur de saisir un nom
$name:=Request("Veuillez saisir un nom à rechercher :")
If(OK=1)
$querySettings.parameters:=New object("givenName";$name)
//Placeholders pour les chemins d'attributs
$querySettings.attributes:=New object("attName";"name")
$es:=ds.Employee.query(":attName= :givenName";$querySettings)
End if
Exemple 3
These examples illustrate the various ways to use formulas with or without parameters in your queries.
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)
Several formulas can be applied:
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)
//méthode checkName
#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:="*" // modifie les paramètres sans mettre à jour l'objet $formula
$es:=ds.Students.query(":1 and nationality=:2";$formula;"French";$settings)
We want to disallow formulas, for example when the user enters their query:
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) //Une erreur est gnérée si $queryString contient une formule
End if
Voir également
.query()
for entity selections
.setRemoteCacheSettings()
Historique
Version | Modifications |
---|---|
v19 R5 | Ajout |
.setRemoteCacheSettings(settings : Object)
Paramètres | Type | Description | |
---|---|---|---|
settings | Object | -> | Object that sets the timeout and maximum size of the ORDA cache for the dataclass. |
|
Mode avancé : Cette fonction est destinée aux développeurs qui souhaitent personnaliser les fonctionnalités par défaut de ORDA dans le cadre de configurations spécifiques. 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). Once the timeout has passed, the entities of the dataclass in the cache are considered as expired. This means that:
- 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. It is useful when working with data that does not change very frequently, and thus when new requests to the server are not necessary.
maxEntries
sets the max number of entities in the ORDA cache. Default is 30 000.
The minimum number of entries is 300, so the value of maxEntries
must be equal to or higher than 300. Otherwise it is ignored and the maximum number of entries is set to 300.
If no valid properties are passed as timeout
and maxEntries
, the cache remains unchanged, with its default or previously set values.
When an entity is saved, it is updated in the cache and expires once the timeout is reached.
Exemple
var $ds : 4D.DataStoreImplementation
$ds:=Open datastore(New object("hostname"; "www.myserver.com"); "myDS")
$ds.Buildings.setRemoteCacheSettings(New object("timeout"; 60; "maxEntries"; 350))