Entity selections

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 "sorted" or "unsorted" (this point is discussed below). 

Entity selections are usually created using a query or returned from a relation attribute. For example:

This code returns in brokers all the people of type broker. To access an entity of the selection, use syntax similar to accessing an element in a collection. For example:

The entitySelection.orderBy( ) method returns a new entity selection according to the supplied sort criteria. For example:

This code returns in brokers the same entity selection of Person entities, but sorted by name.

Alternatively, you can use a relation attribute to return an entity selection. For example:

This code assigns to brokerCompanies all related companies of the people in the brokers entity selection, using the relation attribute myCompany. Using relation attributes on entity selections is a powerful and easy way to navigate up and down the chain of related entities.

To perform repeated actions to entities in an entity selection, like retrieving and modifying values of certain attributes, you can use the For each...End for each structure. For example:

You can create an object of type entity selection as follows:

• Querying the entities in a dataclass (see the dataClass.query( ) method);
• Using the dataClass.all( ) method to select all the entities in a dataclass;
• Using the Create entity selection command or the dataClass.newSelection( ) method to create a blank entity collection object;
• Using one of the various methods from the ORDA - EntitySelection theme that returns a new entity selection, such as entitySelection.or( );
• Using a relation attribute of type "related entities" (see below).

You can simultaneously create and use as many different entity selections as you want for a dataclass. Keep in mind that an entity selection only contains references to entities. Different entity selections can contain references to the same entities.

Note: An entity selection is only defined in the process where it was created. You cannot, for example, store a reference to an entity selection in an interprocess variable and use it in another process. 

All storage attributes (text, number, boolean, date) are available as properties of entity selections as well as entities. When used in conjunction with an entity selection, a scalar attribute returns a collection of scalar values. For example:

This code returns in localEmails a collection of email addresses as strings.

In addition to the variety of ways you can query, you can also use relation attributes as properties of entity selections to return new entity selections. For example, consider the following structure:

The last line will return in $myInvoices an entity selection of all invoices that have at least one invoice item related to a part in the entity selection myParts. 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. When a relation attribute is used as a property of an entity selection and no entities are returned, the result is an empty entity selection, not null.

Local entity selections can be ordered or unordered. Basically, both objects have similar functionality but there are some differences regarding their performance and available features. You can decide which type of entity selection to use according to your specific needs.

Note: Entity selections returned by 4D Server to a remote client are always ordered. 

• Unordered entity selections are built upon bit tables in memory. An unordered entity selection contains one bit for every entity in the dataclass, regardless of whether the entity is actually in the selection. Each bit is equal to 1 or 0, to indicate whether or not the entity is included in the selection. It is a very compact representation for each entity.
  As a consequence, operations using unordered entity selections are very fast. Also, unordered entity selections are very economical in terms of memory space. The size of an unordered entity selection, in bytes, is always equal to the total number of entities in the dataclass divided by 8. For example, if you create an unordered entity selection for a dataclass containing 10,000 entities, it takes up 1,250 bytes, which is about 1.2K in RAM.
  On the other hand, unordered entity selections cannot be ordered. You cannot rely on the position of entities within the selection. Also, you cannot have more than one reference to the same entity in the selection: each entity can only be added once.

• Ordered entity selections are built upon longint arrays (containing entity references) in memory. Each reference to an entity takes 4 bytes in memory. Processing and maintaining such selections takes more time and requires more memory space than unsorted selections.
  On the other hand, they can be ordered or reordered, and you can rely on entity positions. Also, you can add more than one reference to the same entity. 

The following table summarizes the main characteristics of each type of entity selection:

For optimization reasons, by default 4D ORDA usually creates unordered entity selections, except when you use the orderBy( ) method or use the appropriate options (see below). In this documentation, unless specified, "entity selection" usually refers to an "unordered entity selection".

As mentioned above, by default ORDA creates and handles unordered entity selections as a result of operations such as queries or comparisons like and( ). Ordered entity selections are created only when necessary or when specifically requested using options.

Ordered entity selections are created in the following cases:

• result of an orderBy( ) on a selection (of any type) or an orderBy( ) on a dataclass
• result of the newSelection( ) method with the dk keep ordered option

Unordered entity selections are created in the following cases:

• result of a standard query( ) on a selection (of any type) or a query( ) on a dataclass,
• result of the newSelection( ) method without option,
• result of any of the comparison methods, whatever the input selection types: or( ), and( ), minus( ).

Note that when an ordered entity selection becomes an unordered entity selection, any repeated entity references are removed.

If you want to transform an ordered entity selection to an unordered one, you can just apply an and( ) operation to it, for example:

The entity selection object itself cannot be copied as an object:

The entity selection properties are however enumerable: