Version: 20 R6

EntitySelection

An entity selection is an object containing one or more reference(s) to entities belonging to the same Dataclass. An entity selection can contain 0, 1 or X entities from the dataclass -- where X can represent the total number of entities contained in the dataclass.

Entity selections can be created from existing selections using various functions of the DataClass class such as .all() or .query(), or functions of the EntityClass class itself, such as .and() or orderBy(). You can also create blank entity selections using the dataClass.newSelection() function or the Create new selection command.

Summary


[index] : 4D.Entity allows you to access entities within the entity selection using the standard collection syntax
.attributeName : Collection .attributeName : 4D.EntitySelection a "projection" of values for the attribute in the entity selection
.add( entity : 4D.Entity ) : 4D.EntitySelection .add( entitySelection : 4D.EntitySelection ) : 4D.EntitySelection adds the specified entity or entitySelection to the original entity selection and returns the modified entity selection
.and( entity : 4D.Entity ) : 4D.EntitySelection .and( entitySelection : 4D.EntitySelection ) : 4D.EntitySelection combines the entity selection with an entity or entitySelection parameter using the logical AND operator
.at( index : Integer ) : 4D.Entity returns the entity at position index, allowing for positive and negative integer
.average( attributePath : Text ) : Real returns the arithmetic mean (average) of all the non-null values of attributePath in the entity selection
.clean() : 4D.EntitySelection returns a new entity selection based upon the original entity selection but without deleted entities, if any
.contains( entity : 4D.Entity ) : Boolean returns true if entity reference belongs to the entity selection
.copy( { option : Integer } ) : 4D.EntitySelection returns a copy of the original entity selection
.count( attributePath : Text ) : Real returns the number of entities in the entity selection with a non-null value in attributePath
.distinct( attributePath : Text { ; options : Integer } ) : Collection returns a collection containing only distinct (different) values from the attributePath in the entity selection
.distinctPaths( attribute : Text ) : Collection returns a collection of distinct paths found in the indexed object attribute for the entity selection
.drop( { mode : Integer } ) : 4D.EntitySelection removes the entities belonging to the entity selection from the table related to its dataclass within the datastore
.extract( attributePath : Text { ; option : Integer } ) : Collection .extract( attributePath { ; targetPath } { ; ...attributePathN : Text ; targetPathN : Text } ) : Collection returns a collection containing attributePath values extracted from the entity selection
.first() : 4D.Entity returns a reference to the entity in the first position of the entity selection
.getDataClass() : 4D.DataClass returns the dataclass of the entity selection
.getRemoteContextAttributes() : Text returns information about the optimization context used by the entity
.isAlterable() : Boolean returns True if the entity selection is alterable
.isOrdered() : Boolean returns True if the entity selection is ordered
.last() : 4D.Entity returns a reference to the entity in last position of the entity selection
.length : Integer returns the number of entities in the entity selection
.max( attributePath : Text ) : any returns the highest (or maximum) value among all the values of attributePath in the entity selection
.min( attributePath : Text ) : any returns the lowest (or minimum) value among all the values of attributePath in the entity selection
.minus( entity : 4D.Entity { ; keepOrder : Integer } ) : 4D.EntitySelection .minus( entitySelection : 4D.EntitySelection { ; keepOrder : Integer } ) : 4D.EntitySelection excludes from the entity selection to which it is applied the entity or the entities of entitySelection and returns the resulting entity selection
.or( entity : 4D.Entity ) : 4D.EntitySelection .or( entitySelection : 4D.EntitySelection ) : 4D.EntitySelection combines the entity selection with the entity or entitySelection parameter using the logical (not exclusive) OR operator
.orderBy( pathString : Text ) : 4D.EntitySelection .orderBy( pathObjects : Collection ) : 4D.EntitySelection returns a new ordered entity selection containing all entities of the entity selection in the order specified by pathString or pathObjects criteria
.orderByFormula( formulaString : Text { ; sortOrder : Integer } { ; settings : Object} ) : 4D.EntitySelection .orderByFormula( formulaObj : Object { ; sortOrder : Integer } { ; settings : Object} ) : 4D.EntitySelection returns a new, ordered entity selection
.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) among all the entities in the entity selection
.queryPath : Text contains a detailed description of the query as it was actually performed by 4D
.queryPlan : Text contains a detailed description of the query just before it is executed (i.e., the planned query)
.refresh() immediately "invalidates" the entity selection data in the local ORDA cache
.selected( selectedEntities : 4D.EntitySelection ) : Object returns an object describing the position(s) of selectedEntities in the original entity selection
.slice( startFrom : Integer { ; end : Integer } ) : 4D.EntitySelection returns a portion of an entity selection into a new entity selection
.sum( attributePath : Text ) : Real returns the sum for all attributePath values in the entity selection
.toCollection( { options : Integer { ; begin : Integer { ; howMany : Integer } } ) : Collection .toCollection( filterString : Text {; options : Integer { ; begin : Integer { ; howMany : Integer }}} ) : Collection .toCollection( filterCol : Collection {; options : Integer { ; begin : Integer { ; howMany : Integer }}} ) : Collection creates and returns a collection where each element is an object containing a set of properties and values

Create entity selection

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

Parameter	Type		Description
dsTable	Table	->	Table in the 4D database whose current selection will be used to build the entity selection
settings	Object	->	Build option: context
Result	4D.EntitySelection	<-	Entity selection matching the dataclass related to the given table

Description

The Create entity selection command builds and returns a new, alterable entity selection related to the dataclass matching the given dsTable, according to the current selection of this table.

If the current selection is sorted, an ordered entity selection is created (the order of the current selection is kept). If the current selection is unsorted, an unordered entity selection is created.

If the dsTable is not exposed in ds, an error is returned. This command cannot be used with a Remote datastore.

In the optional settings parameter, you can pass an object containing the following property:

Property	Type	Description
context	Text	Label for the optimization context applied to the entity selection.

Example

var $employees : cs.EmployeeSelection
ALL RECORDS([Employee])
$employees:=Create entity selection([Employee])
// The $employees entity selection now contains a set of reference
// on all entities related to the Employee dataclass

USE ENTITY SELECTION

USE ENTITY SELECTION (entitySelection)

Parameter	Type		Description
entitySelection	EntitySelection	->	An entity selection

Description

The USE ENTITY SELECTION command updates the current selection of the table matching the dataclass of the entitySelection parameter, according to the content of the entity selection.

This command cannot be used with a Remote datastore.

info

This command is designed to make 4D current selections benefit from the power of ORDA queries. For performance reasons, in 4D single-user and 4D Server, the command directly connects entitySelection to the current selection. Therefore, once entitySelection has been used, it must not be reused or altered afterwards.

note

After a call to USE ENTITY SELECTION, the first record of the updated current selection (if not empty) becomes the current record, but it is not loaded in memory. If you need to use the values of the fields in the current record, use the LOAD RECORD command after the USE ENTITY SELECTION command.

Example

var $entitySel : cs.EmployeeSelection

$entitySel:=ds.Employee.query("lastName = :1";"M@") //$entitySel is related to the Employee dataclass
REDUCE SELECTION([Employee];0)
USE ENTITY SELECTION($entitySel) //The current selection of the Employee table is updated

[index]

History

Release	Changes
17	Added

[index] : 4D.Entity

Description

The EntitySelection[index] notation allows you to access entities within the entity selection using the standard collection syntax: pass the position of the entity you want to get in the index parameter.

Note that the corresponding entity is reloaded from the datastore.

index can be any number between 0 and .length-1.

If index is out of range, an error is returned.
If index corresponds to a dropped entity, a Null value is returned.

caution

EntitySelection[index] is a non assignable expression, which means that it cannot be used as en editable entity reference with methods like .lock() or .save(). To work with the corresponding entity, you need to assign the returned expression to an assignable expression, such as a variable. Examples:

 $sel:=ds.Employee.all() //create the entity selection
  //invalid statements:
 $result:=$sel[0].lock() //will NOT work
 $sel[0].lastName:="Smith" //will NOT work
 $result:=$sel[0].save() //will NOT work
  //valid code:
 $entity:=$sel[0]  //OK
 $entity.lastName:="Smith" //OK
 $entity.save() //OK

Example

 var $employees : cs.EmployeeSelection
 var $employee : cs.EmployeeEntity
 $employees:=ds.Employee.query("lastName = :1";"H@")
 $employee:=$employees[2]  // The 3rd entity of the $employees entity selection is reloaded from the database

.attributeName

History

Release	Changes
17	Added

.attributeName : Collection
.attributeName : 4D.EntitySelection

Description

Any dataclass attribute can be used as a property of an entity selection to return a "projection" of values for the attribute in the entity selection. Projected values can be a collection or a new entity selection, depending on the kind (storage or relation) of the attribute.

If attributeName kind is storage: .attributeName returns a collection of values of the same type as attributeName.
If attributeName kind is relatedEntity: .attributeName returns a new entity selection of related values of the same type as attributeName. Duplications are removed (an unordered entity selection is returned).
If attributeName kind is relatedEntities: .attributeName returns a new entity selection of related values of the same type as attributeName. Duplications are removed (an unordered entity selection is returned).

When a relation attribute is used as a property of an entity selection, the result is always another entity selection, even if only one entity is returned. In this case, if no entities are returned, the result is an empty entity selection.

If the attribute does not exist in the entity selection, an error is returned.

Example 1

Projection of storage values:

 var $firstNames : Collection
 $entitySelection:=ds.Employee.all()
 $firstNames:=$entitySelection.firstName // firstName type is string

The resulting collection is a collection of strings, for example:

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

Example 2

Projection of related entity:

 var $es; $entitySelection : cs.EmployeeSelection
 $entitySelection:=ds.Employee.all()
 $es:=$entitySelection.employer // employer is related to a Company dataClass

The resulting object is an entity selection of Company with duplications removed (if any).

Example 3

Projection of related entities:

 var $es : cs.EmployeeSelection
 $es:=ds.Employee.all().directReports // directReports is related to Employee dataclass

The resulting object is an entity selection of Employee with duplications removed (if any).

.add()

History

Release	Changes
19 R7	Support of entitySelection parameter
18 R5	Only supports alterable entity selections
17	Added

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

Parameter	Type		Description
entity	4D.Entity	->	Entity to be added to the entity selection
entitySelection	4D.EntitySelection	->	Entity selection to be added to the original entity selection
Result	4D.EntitySelection	<-	Entity selection including the added entity or entitySelection

Description

The .add() function adds the specified entity or entitySelection to the original entity selection and returns the modified entity selection.

This function modifies the original entity selection.

warning

The entity selection must be alterable, i.e. it has been created for example by .newSelection() or Create entity selection, otherwise .add() will return an error. Shareable entity selections do not accept the addition of entities. For more information, please refer to the Shareable or alterable entity selections section.

Adding an entity

If the entity selection is ordered, entity is added at the end of the selection. If a reference to the same entity already belongs to the entity selection, it is duplicated and a new reference is added.
If the entity selection is unordered, entity is added anywhere in the selection, with no specific order.

Adding an entity selection

If the entity selection is ordered, its order is kept and entitySelection is added at the end of the selection. If references to the same entities of entitySelection already belong to the entity selection, they are duplicated and new references are added.
If the entity selection is unordered, it becomes ordered.

For more information, please refer to the Ordered or unordered entity selection section.

The modified entity selection is returned by the function, so that function calls can be chained.

An error occurs if entity and the entity selection are not related to the same Dataclass. If entity is Null, no error is raised.

Example 1

 var $employees : cs.EmployeeSelection
 var $employee : cs.EmployeeEntity
 $employees:=ds.Employee.newSelection()
 $employee:=ds.Employee.new()
 $employee.lastName:="Smith"
 $employee.save()
 $employees.add($employee) //The $employee entity is added to the $employees entity selection

Example 2

Calls to the function can be chained:

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

 $p1:=ds.Product.get(10)
 $p2:=ds.Product.get(11)
 $p3:=ds.Product.get(12)
 $sel:=ds.Product.newSelection()
 $sel:=$sel.add($p1).add($p2).add($p3)

Example 3

In a user interface, we have two lists. The user selects items from the list1 to add them to the list2.

$sellist2:=$sellist2.add($sellist1)

.and()

History

Release	Changes
17	Added

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

Parameter	Type		Description
entity	4D.Entity	->	Entity to intersect with
entitySelection	4D.EntitySelection	->	Entity selection to intersect with
Result	4D.EntitySelection	<-	New entity selection with the result of intersection with logical AND operator

Description

The .and() function combines the entity selection with an entity or entitySelection parameter using the logical AND operator; it returns a new, unordered entity selection that contains only the entities that are referenced in both the entity selection and the parameter.

If you pass entity as parameter, you combine this entity with the entity selection. If the entity belongs to the entity selection, a new entity selection containing only the entity is returned. Otherwise, an empty entity selection is returned.
If you pass entitySelection as parameter, you combine both entity selections. A new entity selection that contains only the entities that are referenced in both selections is returned. If there is no intersecting entity, an empty entity selection is returned.

You can compare ordered and/or unordered entity selections. The resulting selection is always unordered.

If the original entity selection or the entitySelection parameter is empty, or if the entity is Null, an empty entity selection is returned.

If the original entity selection and the parameter are not related to the same dataclass, an error is raised.

Example 1

 var $employees; $result : cs.EmployeeSelection
 var $employee : cs.EmployeeEntity
 $employees:=ds.Employee.query("lastName = :1";"H@")   
  //The $employees entity selection contains the entity
  //with primary key 710 and other entities
  //for ex. "Colin Hetrick" / "Grady Harness" / "Sherlock Holmes" (primary key 710)
 $employee:=ds.Employee.get(710) // Returns "Sherlock Holmes"

 $result:=$employees.and($employee) //$result is an entity selection containing   
  //only the entity with primary key 710 ("Sherlock Holmes")

Example 2

We want to have a selection of employees named "Jones" who live in New York:

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

.at()

History

Release	Changes
20	Added

.at( index : Integer ) : 4D.Entity

Parameter	Type		Description
index	Integer	->	Index of entity to return
Result	4D.Entity	<-	The entity at that index

Description

The .at() function returns the entity at position index, allowing for positive and negative integer.

If index is negative (from -1 to -n with n : length of the entity selection), the returned entity will be based on the reverse order of the entity selection.

The function returns Null if index is beyond entity selection limits.

Example

var $employees : cs.EmployeeSelection
var $emp1; $emp2 : cs.EmployeeEntity
$employees:=ds.Employee.query("lastName = :1";"H@")
$emp1:=$employees.at(2)  //3rd entity of the $employees entity selection
$emp2:=$employees.at(-3) //starting from the end, 3rd entity
	//of the $employees entity selection

.average()

History

Release	Changes
18 R6	Returns undefined if empty entity selection
17	Added

.average( attributePath : Text ) : Real

Parameter	Type		Description
attributePath	Text	->	Attribute path to be used for calculation
Result	Real	<-	Arithmetic mean (average) of entity attribute values (Undefined if empty entity selection)

Description

The .average() function returns the arithmetic mean (average) of all the non-null values of attributePath in the entity selection.

Pass in the attributePath parameter the attribute path to evaluate.

Only numerical values are taken into account for the calculation. Note however that, if the attributePath of the entity selection contains mixed value types, .average() takes all scalar elements into account to calculate the average value.

Date values are converted to numerical values (seconds) and used to calculate the average.

.average() returns undefined if the entity selection is empty or attributePath does not contain numerical values.

An error is returned if:

attributePath is a related attribute,
attributePath designates an attribute that does not exist in the entity selection dataclass.

Example

We want to obtain a list of employees whose salary is higher than the average salary:

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

.clean()

History

Release	Changes
20 R6	Added

.clean() : 4D.EntitySelection

Parameter	Type		Description
Result	4D.EntitySelection	<-	New entity selection without deleted entities

Description

The .clean() function returns a new entity selection based upon the original entity selection but without deleted entities, if any.

By default, when an entity is dropped, its reference(s) in existing entity selection(s) become undefined but are not removed from the entity selection object(s). Deleted entities are still included in the .length property and are displayed as blank lines if the entity selection is bound to an interface object such as a list. In this case, calling the .clean() function on the entity selection allows you to get a new, up-to-date entity selection, not containing undefined entity references.

The resulting entity selection keeps the same order criteria and the same alterable/shareable property as the original entity selection.

Example

var $sel; $sel2 : cs.SpecialitySelection
var $status : Object

$sel:=ds.Speciality.query("ID <= 4")
$status:=ds.Speciality.get(2).drop() //delete the entity from the dataclass
  //$sel.length = 4

$sel2:=$sel.clean()
  //$sel2.length = 3

.contains()

History

Release	Changes
17	Added

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

Parameter	Type		Description
entity	4D.Entity	->	Entity to evaluate
Result	Boolean	<-	True if the entity belongs to the entity selection, else False

Description

The .contains() function returns true if entity reference belongs to the entity selection, and false otherwise.

In entity, specify the entity to search for in the entity selection. If entity is Null, the function will return false.

If entity and the entity selection do not belong to the same dataclass, an error is raised.

Example

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

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

 If($employees.contains($employee))
    ALERT("The entity with primary key 610 has a last name beginning with H")
 Else
    ALERT("The entity with primary key 610 does not have a last name beginning with H")
 End if

.count()

History

Release	Changes
17	Added

.count( attributePath : Text ) : Real

Parameter	Type		Description
attributePath	Text	->	Path of the attribute to be used for calculation
Result	Real	<-	Number of non null attributePath values in the entity selection

Description

The .count() function returns the number of entities in the entity selection with a non-null value in attributePath.

Only scalar values are taken into account. Object or collection type values are considered as null values.

An error is returned if:

attributePath is a related attribute,
attributePath is not found in the entity selection dataclass.

Example

We want to find out the total number of employees for a company without counting any whose job title has not been specified:

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

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

.copy()

History

Release	Changes
18 R5	Added

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

Parameter	Type		Description
option	Integer	->	`ck shared`: return a shareable entity selection
Result	4D.EntitySelection	<-	Copy of the entity selection

Description

The .copy() function returns a copy of the original entity selection.

This function does not modify the original entity selection.

By default, if the option parameter is omitted, the function returns a new, alterable entity selection (even if the function is applied to a shareable entity selection). Pass the ck shared constant in the option parameter if you want to create a shareable entity selection.

For information on the shareable property of entity selections, please refer to the Shareable or alterable entity selections section.

Example

You create a new, empty entity selection of products when the form is loaded:

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

Then this entity selection is updated with products and you want to share the products between several processes. You copy the Form.products entity selection as a shareable one:

 ...
  // The Form.products entity selection is updated
 Form.products.add(Form.selectedProduct)

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

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

.distinct()

History

Release	Changes
20	Support of `dk count values`
17	Added

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

Parameter	Type		Description
attributePath	Text	->	Path of attribute whose distinct values you want to get
options	Integer	->	`dk diacritical`, `dk count values`
Result	Collection	<-	Collection with only distinct values

Description

The .distinct() function returns a collection containing only distinct (different) values from the attributePath in the entity selection.

The returned collection is automatically sorted. Null values are not returned.

In the attributePath parameter, pass the entity attribute whose distinct values you want to get. Only scalar values (text, number, boolean, or date) can be handled. If the attributePath leads to an object property that contains values of different types, they are first grouped by type and sorted afterwards. Types are returned in the following order:

booleans
strings
numbers
dates

You can use the [] notation to designate a collection when attributePath is a path within an object (see examples).

In the options parameter, you can pass one or a combination of the following constants:

Constant	Value	Comment
`dk diacritical`	8	Evaluation is case sensitive and differentiates accented characters. By default if omitted, a non-diacritical evaluation is performed
`dk count values`	32	Return the count of entities for every distinct value. When this option is passed, `.distinct()` returns a collection of objects containing a pair of `{"value":value; "count":count}` properties.

note

The dk count values option is only available with storage attributes of type boolean, string, number, and date.

An error is returned if:

attributePath is a related attribute,
attributePath is not found in the entity selection dataclass.

Examples

You want to get a collection containing a single element per country name:

var $countries : Collection
$countries:=ds.Employee.all().distinct("address.country")
//$countries[0]={"Argentina"}
//$countries[1]={"Australia"}
//$countries[2]={"Belgium"}
///...

nicknames is a collection and extra is an object attribute:

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

You want to get the number of different job names in the company:

var $jobs : Collection
$jobs:=ds.Employee.all().distinct("jobName";dk count values)  
//$jobs[0]={"value":"Developer";"count":17}
//$jobs[1]={"value":"Office manager";"count":5}
//$jobs[2]={"value":"Accountant";"count":2}
//...

.distinctPaths()

History

Release	Changes
20	Added

.distinctPaths( attribute : Text ) : Collection

Parameter	Type		Description
attribute	Text	->	Object attribute name whose paths you want to get
Result	Collection	<-	New collection with distinct paths

Description

The .distinctPaths() function returns a collection of distinct paths found in the indexed object attribute for the entity selection.

If attribute is not an indexed object attribute, an error is generated.

After the call, the size of the returned collection is equal to the number of distinct paths found in attribute for the entity selection. Paths are returned as strings including nested attributes and collections, for example "info.address.number" or "children[].birthdate". Entities with a null value in the attribute are not taken into account.

Example

You want to get all paths stored in a fullData object attribute:

var $paths : Collection
$paths:=ds.Employee.all().distinctPaths("fullData")
//$paths[0]="age"
//$paths[1]="Children"
//$paths[2]="Children[].age"
//$paths[3]="Children[].name"
//$paths[4]="Children.length"
///...

note

length is automatically added as path for nested collection properties.

.drop()

History

Release	Changes
17	Added

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

Parameter	Type		Description
mode	Integer	->	`dk stop dropping on first error`: stops method execution on first non-droppable entity
Result	4D.EntitySelection	<-	Empty entity selection if successful, else entity selection containing non-droppable entity(ies)

Description

The .drop() function removes the entities belonging to the entity selection from the table related to its dataclass within the datastore. The entity selection remains in memory.

Removing entities is permanent and cannot be undone. It is recommended to call this action in a transaction in order to have a rollback option.

If a locked entity is encountered during the execution of .drop(), it is not removed. By default, the method processes all entities of the entity selection and returns non-droppable entities in the entity selection. If you want the method to stop execution at the first encountered non-droppable entity, pass the dk stop dropping on first error constant in the mode parameter.

Example

Example without the dk stop dropping on first error option:

 var $employees; $notDropped : cs.EmployeeSelection
 $employees:=ds.Employee.query("firstName=:1";"S@")
 $notDropped:=$employees.drop() // $notDropped is an entity selection containing all the not dropped entities
 If($notDropped.length=0) //The delete action is successful, all the entities have been deleted
    ALERT("You have dropped "+String($employees.length)+" employees") //The dropped entity selection remains in memory
 Else
    ALERT("Problem during drop, try later")
 End if

Example with the dk stop dropping on first error option:

 var $employees; $notDropped : cs.EmployeeSelection
 $employees:=ds.Employee.query("firstName=:1";"S@")
 $notDropped:=$employees.drop(dk stop dropping on first error) //$notDropped is an entity selection containing the first not dropped entity
 If($notDropped.length=0) //The delete action is successful, all the entities have been deleted
    ALERT("You have dropped "+String($employees.length)+" employees") //The dropped entity selection remains in memory
 Else
    ALERT("Problem during drop, try later")
 End if

.extract()

History

Release	Changes
18 R3	Added

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

Parameter	Type		Description
attributePath	Text	->	Attribute path whose values must be extracted to the new collection
targetPath	Text	->	Target attribute path or attribute name
option	Integer	->	`ck keep null`: include null attributes in the returned collection (ignored by default)
Result	Collection	<-	Collection containing extracted values

Description

The .extract() function returns a collection containing attributePath values extracted from the entity selection.

attributePath can refer to:

a scalar dataclass attribute,
related entity,
related entities.

If attributePath is invalid, an empty collection is returned.

This function accepts two syntaxes.

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

With this syntax, .extract() populates the returned collection with the attributePath values of the entity selection.

By default, entities for which attributePath is null or undefined are ignored in the resulting collection. You can pass the ck keep null constant in the option parameter to include these values as null elements in the returned collection.

Dataclass attributes with .kind = "relatedEntity" are extracted as a collection of entities (duplications are kept).
Dataclass attributes with .kind = "relatedEntities" are extracted as a collection of entity selections.

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

With this syntax, .extract() populates the returned collection with the attributePath properties. Each element of the returned collection is an object with targetPath properties filled with the corresponding attributePath properties. Null values are kept (option parameter is ignored with this syntax).

If several attributePath are given, a targetPath must be given for each. Only valid pairs [attributePath, targetPath] are extracted.

Dataclass attributes with .kind = "relatedEntity" are extracted as an entity.
Dataclass attributes with .kind = "relatedEntities" are extracted as an entity selection.

Entities of a collection of entities accessed by [ ] are not reloaded from the database.

Example

Given the following table and relation:

 var $firstnames; $addresses; $mailing; $teachers : Collection
  //
  //
  //$firstnames is a collection of Strings


 $firstnames:=ds.Teachers.all().extract("firstname")
  //
  //$addresses is a collection of entities related to dataclass Address
  //Null values for address are extracted
 $addresses:=ds.Teachers.all().extract("address";ck keep null)
  //
  //
  //$mailing is a collection of objects with properties "who" and "to"
  //"who" property content is String type
  //"to" property content is entity type (Address dataclass)
 $mailing:=ds.Teachers.all().extract("lastname";"who";"address";"to")
  //
  //
  //$mailing is a collection of objects with properties "who" and "city"
  //"who" property content is String type
  //"city" property content is String type
 $mailing:=ds.Teachers.all().extract("lastname";"who";"address.city";"city")
  //
  //$teachers is a collection of objects with properties "where" and "who"
  //"where" property content is String
  //"who" property content is an entity selection (Teachers dataclass)
 $teachers:=ds.Address.all().extract("city";"where";"teachers";"who")
  //
  //$teachers is a collection of entity selections
 $teachers:=ds.Address.all().extract("teachers")

.first()

History

Release	Changes
17	Added

.first() : 4D.Entity

Parameter	Type		Description
Result	4D.Entity	<-	Reference to the first entity of the entity selection (Null if selection is empty)

Description

The .first() function returns a reference to the entity in the first position of the entity selection.

The result of this function is similar to:

 $entity:=$entitySel[0]

There is, however, a difference between both statements when the selection is empty:

 var $entitySel : cs.EmpSelection
 var $entity : cs.EmpEntity
 $entitySel:=ds.Emp.query("lastName = :1";"Nonexistentname") //no matching entity
  //entity selection is then empty
 $entity:=$entitySel.first() //returns Null
 $entity:=$entitySel[0]  //generates an error

Example

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

.getDataClass()

History

Release	Changes
17 R5	Added

.getDataClass() : 4D.DataClass

Parameter	Type		Description
Result	4D.DataClass	<-	Dataclass object to which the entity selection belongs

Description

The .getDataClass() function returns the dataclass of the entity selection.

This function is mainly useful in the context of generic code.

Example

The following generic code duplicates all entities of the entity selection:

  //duplicate_entities method
  //duplicate_entities($entity_selection)

 #DECLARE ( $entitySelection : 4D.EntitySelection )  
 var $dataClass : 4D.DataClass
 var $entity; $duplicate : 4D.Entity
 var $status : Object
 $dataClass:=$entitySelection.getDataClass()
 For each($entity;$entitySelection)
    $duplicate:=$dataClass.new()
    $duplicate.fromObject($entity.toObject())
    $duplicate[$dataClass.getInfo().primaryKey]:=Null //reset the primary key
    $status:=$duplicate.save()
 End for each

.getRemoteContextAttributes()

History

Release	Changes
19R5	Added

.getRemoteContextAttributes() : Text

Parameter	Type		Description
result	Text	<-	Context attributes linked to the entity selection, separated by a comma

Advanced mode: This function is intended for developers who need to customize ORDA default features for specific configurations. In most cases, you will not need to use it.

Description

The .getRemoteContextAttributes() function returns information about the optimization context used by the entity selection.

If there is no optimization context for the entity selection, the function returns an empty Text.

Example

var $ds : 4D.DataStoreImplementation
var $persons : cs.PersonsSelection
var $p : cs.PersonsEntity

var $info : Text
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

$info:=$persons.getRemoteContextAttributes()
//$info = "firstname,address,address.city"

.isAlterable()

History

Release	Changes
18 R5	Added

.isAlterable() : Boolean

Parameter	Type		Description
Result	Boolean	<-	True if the entity selection is alterable, False otherwise

Description

The .isAlterable() function returns True if the entity selection is alterable, and False if the entity selection is not alterable.

For more information, please refer to Shareable or alterable entity selections.

Example

You are about to display Form.products in a list box to allow the user to add new products. You want to make sure it is alterable so that the user can add new products without error:

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

.isOrdered()

History

Release	Changes
17	Added

.isOrdered() : Boolean

Parameter	Type		Description
Result	Boolean	<-	True if the entity selection is ordered, False otherwise

Description

The .isOrdered() function returns True if the entity selection is ordered, and False if it is unordered.

This function always returns True when the entity selection comes from a remote datastore.

For more information, please refer to Ordered or unordered entity selection.

Example

 var $employees : cs.EmployeeSelection
 var $employee : cs.EmployeeEntity
 var $isOrdered : Boolean
 $employees:=ds.Employee.newSelection(dk keep ordered)
 $employee:=ds.Employee.get(714) // Gets the entity with primary key 714

  //In an ordered entity selection, we can add the same entity several times (duplications are kept)
 $employees.add($employee)
 $employees.add($employee)
 $employees.add($employee)

 $isOrdered:=$employees.isOrdered()
 If($isOrdered)
    ALERT("The entity selection is ordered and contains "+String($employees.length)+" employees")
 End if

.last()

History

Release	Changes
17	Added

.last() : 4D.Entity

Parameter	Type		Description
Result	4D.Entity	<-	Reference to the last entity of the entity selection (Null if empty entity selection)

Description

The .last() function returns a reference to the entity in last position of the entity selection.

The result of this function is similar to:

 $entity:=$entitySel[length-1]

If the entity selection is empty, the function returns Null.

Example

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

.length

History

Release	Changes
17	Added

.length : Integer

Description

The .length property returns the number of entities in the entity selection. If the entity selection is empty, it returns 0.

Entity selections always have a .length property.

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.

Example

 var $vSize : Integer
 $vSize:=ds.Employee.query("gender = :1";"male").length
 ALERT(String(vSize)+" male employees found.")

.max()

History

Release	Changes
17	Added
18 R6	Returns undefined if empty entity selection

.max( attributePath : Text ) : any

Parameter	Type		Description
attributePath	Text	->	Path of the attribute to be used for calculation
Result	any	<-	Highest value of attribute

Description

The .max() function returns the highest (or maximum) value among all the values of attributePath in the entity selection. It actually returns the value of the last entity of the entity selection as it would be sorted in ascending order using the .orderBy() function.

If you pass in attributePath a path to an object property containing different types of values, the .max() function will return the maximum value within the first scalar type in the default 4D type list order (see .sort() description).

.max() returns undefined if the entity selection is empty or attributePath is not found in the object attribute.

An error is returned if:

attributePath is a related attribute,
attributePath designates an attribute that does not exist in the entity selection dataclass.

Example

We want to find the highest salary among all the female employees:

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

.min()

History

Release	Changes
17	Added
18 R6	Returns undefined if empty entity selection

.min( attributePath : Text ) : any

Parameter	Type		Description
attributePath	Text	->	Path of the attribute to be used for calculation
Result	any	<-	Lowest value of attribute

Description

The .min() function returns the lowest (or minimum) value among all the values of attributePath in the entity selection. It actually returns the first entity of the entity selection as it would be sorted in ascending order using the .orderBy() function (excluding null values).

If you pass in attributePath a path to an object property containing different types of values, the .min() function will return the minimum value within the first scalar value type in the type list order (see .sort() description).

.min() returns undefined if the entity selection is empty or attributePath is not found in the object attribute.

An error is returned if:

attributePath is a related attribute,
attributePath designates an attribute that does not exist in the entity selection dataclass.

Example

In this example, we want to find the lowest salary among all the female employees:

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

.minus()

History

Release	Changes
19 R7	Support of keepOrder parameter
17	Added

.minus( entity : 4D.Entity { ; keepOrder : Integer } ) : 4D.EntitySelection
.minus( entitySelection : 4D.EntitySelection { ; keepOrder : Integer } ) : 4D.EntitySelection

Parameter	Type		Description
entity	4D.Entity	->	Entity to substract
entitySelection	4D.EntitySelection	->	Entity selection to substract
keepOrder	Integer	->	`dk keep ordered` (integer) to keep the initial order in the resulting entity selection
Result	4D.EntitySelection	<-	New entity selection or a new reference on the existing entity selection

Description

The .minus() function excludes from the entity selection to which it is applied the entity or the entities of entitySelection and returns the resulting entity selection.

If you pass entity as parameter, the function creates a new entity selection without entity (if entity belongs to the entity selection). If entity was not included in the original entity selection, a new reference to the entity selection is returned.
If you pass entitySelection as parameter, the function returns an entity selection containing the entities belonging to the original entity selection without the entities belonging to entitySelection. You can compare ordered and/or unordered entity selections.

By default, if you omit the keepOrder parameter, the resulting entity selection is unordered. If you want to keep the order of the original entity selection (for example if you want to reuse the entity selection in a user interface), pass the dk keep ordered constant in keepOrder. In this case, the result is an ordered entity selection and the order of the initial entity selection is kept.

note

If you pass dk keep ordered in keepOrder and the removed entitySelection contains entities duplicated in the original entity selection, all occurences of the duplicates are removed.

If the original entity selection or both the original entity selection and the entitySelection parameter are empty, an empty entity selection is returned.

If entitySelection is empty or if entity is Null, a new reference to the original entity selection is returned.

If the original entity selection and the parameter are not related to the same dataclass, an error is raised.

Example 1

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

 $employees:=ds.Employee.query("lastName = :1";"H@")
  // The $employees entity selection contains the entity with primary key 710 and other entities
  // for ex. "Colin Hetrick", "Grady Harness", "Sherlock Holmes" (primary key 710)

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

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

Example 2

We want to have a selection of female employees named "Jones" who live in New York :

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

Example 3

In a user interface, we have a list that displays items in a specific order. If the user selects items in the list to remove them, the order must be kept when refreshing the list:

$listsel:=$listsel.minus($selectedItems; dk keep ordered)

.or()

History

Release	Changes
17	Added

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

Parameter	Type		Description
entity	4D.Entity	->	Entity to intersect with
entitySelection	4D.EntitySelection	->	Entity selection to intersect with
Result	4D.EntitySelection	<-	New entity selection or new reference to the original entity selection

Description

The .or() function combines the entity selection with the entity or entitySelection parameter using the logical (not exclusive) OR operator; it returns a new, unordered entity selection that contains all the entities from the entity selection and the parameter.

If you pass entity as parameter, you compare this entity with the entity selection. If the entity belongs to the entity selection, a new reference to the entity selection is returned. Otherwise, a new entity selection containing the original entity selection and the entity is returned.
If you pass entitySelection as parameter, you compare entity selections. A new entity selection containing the entities belonging to the original entity selection or entitySelection is returned (or is not exclusive, entities referenced in both selections are not duplicated in the resulting selection).

You can compare ordered and/or unordered entity selections. The resulting selection is always unordered.

If the original entity selection and the entitySelection parameter are empty, an empty entity selection is returned. If the original entity selection is empty, a reference to entitySelection or an entity selection containing only entity is returned.

If entitySelection is empty or if entity is Null, a new reference to the original entity selection is returned.

If the original entity selection and the parameter are not related to the same dataclass, an error is raised.

Example 1

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

Example 2

 var $employees; $result : cs.EmployeeSelection
 var $employee : cs.EmployeeEntity
 $employees:=ds.Employee.query("lastName = :1";"H@") // Returns "Colin Hetrick","Grady Harness", "Sherlock Holmes"
 $employee:=ds.Employee.get(686) //the entity with primary key 686 does not belong to the $employees entity selection
  //It matches the employee "Mary Smith"

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

.orderBy()

History

Release	Changes
17	Added

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

Parameter	Type		Description
pathString	Text	->	Attribute path(s) and sorting instruction(s) for the entity selection
pathObjects	Collection	->	Collection of criteria objects
Result	4D.EntitySelection	<-	New entity selection in the specified order

Description

The .orderBy() function returns a new ordered entity selection containing all entities of the entity selection in the order specified by pathString or pathObjects criteria.

This method does not modify the original entity selection.

For more information on ordered entity selections, please refer to the Ordered or unordered entity selection section.

You must use a criteria parameter to define how the entities must be sorted. Two different parameters are supported:

pathString (Text) : This parameter contains a formula made of 1 to x attribute paths and (optionally) sort orders, separated by commas. The syntax is:

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

The order in which the attributes are passed determines the sorting priority of the entities. By default, attributes are sorted in ascending order. You can set the sort order of a property in the criteria string, separated from the property path by a single space: pass "asc" to sort in ascending order or "desc" in descending order.

pathObjects (collection): each element of the collection contains an object structured in the following way:

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

By default, attributes are sorted in ascending order ("descending" is false).

You can add as many objects in the criteria collection as necessary.

Null values are evaluated as less than other values.

If you pass an invalid attribute path in pathString or pathObject, the function returns an empty entity selection.

Example

// order by formula
 $sortedEntitySelection:=$entitySelection.orderBy("firstName asc, salary desc")
 $sortedEntitySelection:=$entitySelection.orderBy("firstName")


  // order by collection with or without sort orders
 $orderColl:=New collection
 $orderColl.push(New object("propertyPath";"firstName";"descending";False))
 $orderColl.push(New object("propertyPath";"salary";"descending";True))
 $sortedEntitySelection:=$entitySelection.orderBy($orderColl)

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

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

.orderByFormula()

History

Release	Changes
17 R6	Added

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

Parameter	Type		Description
formulaString	Text	->	Formula string
formulaObj	Object	->	Formula object
sortOrder	Integer	->	`dk ascending` (default) or `dk descending`
settings	Object	->	Parameter(s) for the formula
Result	4D.EntitySelection	<-	New ordered entity selection

Description

The .orderByFormula() function returns a new, ordered entity selection containing all entities of the entity selection in the order defined through the formulaString or formulaObj and, optionally, sortOrder and settings parameters.

This function does not modify the original entity selection.

You can use either a formulaString or a formulaObj parameter:

formulaString: you pass a 4D expression such as "Year of(this.birthDate)".
formulaObj: pass a valid formula object created using the Formula or Formula from string command.

The formulaString or formulaObj is executed for each entity of the entity selection and its result is used to define the position of the entity in the returned entity selection. The result must be of a sortable type (boolean, date, number, text, time, null).

A null result is always the smallest value.

By default if you omit the sortOrder parameter, the resulting entity selection is sorted in ascending order. Optionnally, you can pass one of the following values in the sortOrder parameter:

Constant	Value	Comment
dk ascending	0	Ascending sort order (default)
dk descending	1	Descending sort order

Within the formulaString or formulaObj, the processed entity and thus its attributes are available through the This command (for example, This.lastName).

You can pass parameter(s) to the formula using the args property (object) of the settings parameter: the formula receives the settings.args object in $1.

Example 1

Sorting students using a formula provided as text:

 var $es1; $es2 : cs.StudentsSelection
 $es1:=ds.Students.query("nationality=:1";"French")
 $es2:=$es1.orderByFormula("length(this.lastname)") //ascending by default
 $es2:=$es1.orderByFormula("length(this.lastname)";dk descending)

Same sort order but using a formula object:

 var $es1; $es2 : cs.StudentsSelection
 var $formula : Object
 $es1:=ds.Students.query("nationality=:1";"French")
 $formula:=Formula(Length(This.lastname))
 $es2:=$es1.orderByFormula($formula) // ascending by default
 $es2:=$es1.orderByFormula($formula;dk descending)

Example 2

A formula is given as a formula object with parameters; settings.args object is received as $1 in the computeAverage method.

In this example, the "marks" object field in the Students dataClass contains students' grades for each subject. A single formula object is used to compute a student's average grade with different coefficients for schoolA and schoolB.

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

 $schoolA:=New object() //settings object
 $schoolA.args:=New object("english";1;"math";1;"history";1) // Coefficients to compute an average

  //Order students according to school A criteria
 $es2:=$es1.entitySelection.orderByFormula($formula;$schoolA)

 $schoolB:=New object() //settings object
 $schoolB.args:=New object("english";1;"math";2;"history";3) // Coefficients to compute an average

  //Order students according to school B criteria
 $es2:=$es1.entitySelection.orderByFormula($formula;dk descending;$schoolB)

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

 $average:=0
 $sum:=0

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

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

 $result:=$average/$sum

.query()

History

Release	Changes
17 R6	Support of Formula parameters
17 R5	Support of placeholders for values
17	Added

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

Parameter	Type		Description
queryString	Text	->	Search criteria as string
formula	Object	->	Search criteria as formula object
value	any	->	Value(s) to use for indexed placeholder(s)
querySettings	Object	->	Query options: parameters, attributes, args, allowFormulas, context, queryPath, queryPlan
Result	4D.EntitySelection	<-	New entity selection made up of entities from entity selection 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) among all the entities in the entity selection, and returns a new object of type EntitySelection containing all the entities that are found. Lazy loading is applied.

This function does not modify the original entity selection.

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

For detailed information on how to build a query using queryString, value, and querySettings parameters, please refer to the DataClass .query() function description.

By default if you omit the order by statement in the queryString, the returned entity selection is not ordered. Note however that, in Client/Server mode, it behaves like an ordered entity selection (entities are added at the end of the selection).

Example 1

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

Example 2

More examples of queries can be found in the DataClass .query() page.

.queryPath

History

Release	Changes
17	Added

.queryPath : Text

Description

The .queryPath property contains a detailed description of the query as it was actually performed by 4D. This property is available for EntitySelection objects generated through queries if the "queryPath":true property was passed in the querySettings parameter of the .query() function.

For more information, refer to the querySettings parameter paragraph in the Dataclass.query() page.

.queryPlan

History

Release	Changes
17	Added

.queryPlan : Text

Description

The .queryPlan property contains a detailed description of the query just before it is executed (i.e., the planned query). This property is available for EntitySelection objects generated through queries if the "queryPlan":true property was passed in the querySettings parameter of the .query() function.

For more information, refer to the querySettings parameter paragraph in the Dataclass.query() page.

.refresh()

History

Release	Changes
18 R3	Added

.refresh()

Parameter	Type		Description
			Does not require any parameters

Description

This function only works with a remote datastore (client / server or Open datastore connection).

The .refresh() function immediately "invalidates" the entity selection data in the local ORDA cache so that the next time 4D requires the entity selection, it will be reloaded from the database.

By default, the local ORDA cache is invalidated after 30 seconds. In the context of client / server applications using both ORDA and the classic language, this method allows you to make sure a remote application will always work with the latest data.

Example 1

In this example, classic and ORDA code modify the same data simultaneously:

 //On a 4D remote

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

 $selection:=ds.Students.query("lastname=:1";"Collins")
  //The first entity is loaded in the ORDA cache
 $student:=$selection.first()

  //Update with classic 4D, ORDA cache is not aware of if
 QUERY([Students];[Students]lastname="Collins")
 [Students]lastname:="Colin"
 SAVE RECORD([Students])

  //to get the latest version, the ORDA cache must be invalidated
 $selection.refresh()
  // Even if cache is not expired, the first entity is reloaded from disk
 $student:=$selection.first()

  //$student.lastname contains "Colin"

Example 2

A list box displays the Form.students entity selection and several clients work on it.

// Form method:
 Case of
    :(Form event code=On Load)
       Form.students:=ds.Students.all()
 End case
  //
  //
  // On client #1, the user loads, updates, and saves the first entity
  // On client #2, the user loads, updates, and saves the same entity
  //
  //
  // On client #1:
 Form.students.refresh() // Invalidates the ORDA cache for the Form.students entity selection
  // The list box content is refreshed from the database with update made by client #2

.selected()

History

Release	Changes
19 R3	Added

.selected( selectedEntities : 4D.EntitySelection ) : Object

Parameter	Type		Description
selectedEntities	4D.EntitySelection	->	Entity selection with entities for which to know the rank in the entity selection
Result	Object	<-	Range(s) of selected entities in entity selection

Description

The .selected() function returns an object describing the position(s) of selectedEntities in the original entity selection.

This function does not modify the original entity selection.

Pass in the selectedEntities parameter an entity selection containing entities for which you want to know the position in the original entity selection. selectedEntities must be an entity selection belonging to the same dataclass as the original entity selection, otherwise an error 1587 - "The entity selection comes from an incompatible dataclass" is raised.

Result

The returned object contains the following properties:

Property	Type	Description
ranges	Collection	Collection of range objects
ranges[].start	Integer	First entity index in the range
ranges[].end	Integer	Last entity index in the range

If a ranges property contains a single entity, start = end. Index starts at 0.

The function returns an empty collection in the ranges property if the original entity selection or the selectedEntities entity selection is empty.

Example

var $invoices; $cashSel; $creditSel : cs.Invoices
var $result1; $result2 : Object

$invoices:=ds.Invoices.all()

$cashSelection:=ds.Invoices.query("payment = :1"; "Cash")
$creditSel:=ds.Invoices.query("payment IN :1"; New collection("Cash"; "Credit Card"))

$result1:=$invoices.selected($cashSelection)
$result2:=$invoices.selected($creditSel)

//$result1 = {ranges:[{start:0;end:0},{start:3;end:3},{start:6;end:6}]}
//$result2 = {ranges:[{start:0;end:1},{start:3;end:4},{start:6;end:7}]}

.slice()

History

Release	Changes
17	Added

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

Parameter	Type		Description
startFrom	Integer	->	Index to start the operation at (included)
end	Integer	->	End index (not included)
Result	4D.EntitySelection	<-	New entity selection containing sliced entities (shallow copy)

Description

The .slice() function returns a portion of an entity selection into a new entity selection, selected from the startFrom index to the end index (end is not included) or to the last entity of the entity selection. This method returns a shallow copy of the entity selection (it uses the same entity references).

This function does not modify the original entity selection.

The returned entity selection contains the entities specified by startFrom and all subsequent entities up to, but not including, the entity specified by end. If only the startFrom parameter is specified, the returned entity selection contains all entities from startFrom to the last entity of the original entity selection.

If startFrom < 0, it is recalculated as startFrom:=startFrom+length (it is considered as the offset from the end of the entity selection). If the calculated value < 0, startFrom is set to 0.
If startFrom >= length, the function returns an empty entity selection.
If end < 0, it is recalculated as end:=end+length.
If end < startFrom (passed or calculated values), the method does nothing.

If the entity selection contains entities that were dropped in the meantime, they are also returned.

Example 1

You want to get a selection of the first 9 entities of the entity selection:

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

Example 2

Assuming we have ds.Employee.all().length = 10

var $slice : cs.EmployeeSelection

$slice:=ds.Employee.all().slice(-1;-2) //tries to return entities from index 9 to 8, but since 9 > 8, returns an empty entity selection

.sum()

History

Release	Changes
17	Added

.sum( attributePath : Text ) : Real

Parameter	Type		Description
attributePath	Text	->	Path of the attribute to be used for calculation
Result	Real	<-	Sum of entity selection values

Description

The .sum() function returns the sum for all attributePath values in the entity selection.

.sum() returns 0 if the entity selection is empty.

The sum can only be done on values of number type. If the attributePath is an object property, only numerical values are taken into account for the calculation (other value types are ignored). In this case, if attributePath leads to a property that does not exist in the object or does not contain any numeric values, .sum() returns 0.

An error is returned if:

attributePath is not a numerical or an object attribute,
attributePath is a related attribute,
attributePath is not found in the entity selection dataclass.

Example

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

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

.toCollection()

History

Release	Changes
17	Added

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

Parameter	Type		Description
filterString	Text	->	String with entity attribute path(s) to extract
filterCol	Collection	->	Collection of entity attribute path(s) to extract
options	Integer	->	`dk with primary key`: adds the primary key `dk with stamp`: adds the stamp
begin	Integer	->	Designates the starting index
howMany	Integer	->	Number of entities to extract
Result	Collection	<-	Collection of objects containing attributes and values of entity selection

Description

The .toCollection() function creates and returns a collection where each element is an object containing a set of properties and values corresponding to the attribute names and values for the entity selection.

If no filter parameter is passed or the first parameter contains an empty string or "*", all the attributes are extracted. Attributes with kind property as "relatedEntity" are extracted with the simple form: an object with property __KEY (primary key). Attributes with kind property as "relatedEntities" are not extracted.

Or, you can designate the entity attributes to extract using a filter parameter. You can use one of these two filters:

filterString --a string with property paths separated with commas: "propertyPath1, propertyPath2, ...".
filterCol --a collection of strings containing property paths: ["propertyPath1","propertyPath2",...]

If a filter is specified for an attribute of the relatedEntity kind:

propertyPath = "relatedEntity" -> it is extracted with simple form
propertyPath = "relatedEntity.*" -> all the properties are extracted
propertyPath = "relatedEntity.propertyName1, relatedEntity.propertyName2, ..." -> only those properties are extracted

If a filter is specified for an attribute of the relatedEntities kind:

propertyPath = "relatedEntities.*" -> all the properties are extracted
propertyPath = "relatedEntities.propertyName1, relatedEntities.propertyName2, ..." -> only those properties are extracted

In the options parameter, you can pass the dk with primary key and/or dk with stamp selector(s) to add the entity's primary keys and/or stamps in extracted objects.

Warning

If you use another attribute than the primary key as the One attribute in a relation, the value of this attribute will be written in the "__KEY" property. Keep in mind that it is recommended to use the primary key as One attribute in your relations, especially when you use .toCollection() and .fromCollection() functions.

The begin parameter allows you to indicate the starting index of the entities to extract. You can pass any value between 0 and entity selection length-1.

The howMany parameter lets you specify the number of entities to extract, starting with the one specified in begin. Dropped entities are not returned but are taken into account according to howMany. For example, if howMany= 3 and there is 1 dropped entity, only 2 entities are extracted.

If howMany > length of the entity selection, the method returns (length - begin) objects.

An empty collection is returned if:

the entity selection is empty, or
begin is greater than the length of the entity selection.

Example 1

The following structure will be used throughout all examples of this section:

Example without filter or options parameter:

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

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

Returns:

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

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

Example 2

Example with options:

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

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

Returns:

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

Example 3

Example with slicing and filtering on properties:

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


$employeesCollection:=New collection
$filter:=New collection


$filter.push("firstName")
$filter.push("lastName")

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

Returns:

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

Example 4

Example with relatedEntity type with simple form:

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

returns:

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

Example 5

Example with filterCol parameter:

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

Returns:

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

Example 6

Example with extraction of all properties of a relatedEntity:

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

Returns:

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

Example 7

Example with extraction of some properties of a relatedEntity:

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

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

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

Example 8

Example with extraction of some properties of relatedEntities:

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

Returns:

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

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

Example 9

Example with extraction of all properties of relatedEntities:

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

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

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

Summary​

Create entity selection​

Description​

Example​

See also​

USE ENTITY SELECTION​

Description​

Example​

[index]​

Description​

Example​

.attributeName​

Description​

Example 1​

Example 2​

Example 3​

.add()​

Description​

Example 1​

Example 2​

Example 3​

.and()​

Description​

Example 1​

Example 2​

.at()​

Description​

Example​

.average()​

Description​

Example​

.clean()​

Description​

Example​

See also​

.contains()​

Description​

Example​

.count()​

Description​

Example​

.copy()​

Description​

Example​

.distinct()​

Description​

Examples​

.distinctPaths()​

Description​

Example​

.drop()​

Description​

Example​

.extract()​

Description​

Example​

.first()​

Description​

Example​

.getDataClass()​

Description​

Example​

.getRemoteContextAttributes()​

Description​

Example​

See also​

.isAlterable()​

Description​

Example​

.isOrdered()​

Description​

Example​

.last()​

Description​

Example​

.length​

Description​

Example​

.max()​

Description​

Summary

Create entity selection

Description

Example

See also

USE ENTITY SELECTION

Description

Example

[index]

Description

Example

.attributeName

Description

Example 1

Example 2

Example 3

.add()

Description

Example 1

Example 2

Example 3

.and()

Description

Example 1

Example 2

.at()

Description

Example

.average()

Description

Example

.clean()

Description

Example

See also

.contains()

Description

Example

.count()

Description

Example

.copy()

Description

Example

.distinct()

Description

Examples

.distinctPaths()

Description

Example

.drop()

Description

Example

.extract()

Description

Example

.first()

Description

Example

.getDataClass()

Description

Example

.getRemoteContextAttributes()

Description

Example

See also

.isAlterable()

Description

Example

.isOrdered()

Description

Example

.last()

Description

Example

.length

Description

Example

.max()

Description