LoadPartialEntity

Description

Loads just part of a record.

The LoadPartialEntity API (Application Programming Interface) method can be used to load just part of a record. Performance can be improved by skipping the extra Structured Query Language (SQL) statements to retrieve the field data for certain field types. The field types that can be excluded in this way are reference list, attachment list, and history.

Note: The newer HCL Compass releases automatically defer loading of some of these field types, and other field types can be configured to be deferred. This capability is known as deferred loading (or "lazy loading"). This API works seamlessly with that functionality, but goes further because it allows skipping some field types in older Compass database Feature Fevels (FL) that do not support deferred loading. An example is the history field, which is automatically deferred when the database is at feature level 9, or above. With the LoadPartialEntity API, the history field can be omitted when using a database at any feature level, using a Client version that supports this API method.

Syntax

Perl


 
$session.LoadPartialEntity(entDefName, displayName, list);


 
 $session.LoadPartialEntityByDbId(entDefName, dbId, list);

Identifier: Description
entDefName: The type name of the entity to be partially loaded.
displayName: The display name of the entity to be partially loaded.
list: Controls what fields are excluded.
dbID: The dbid of the entity to be partially loaded.

The entDefName , displayName, and dbID parameters are used to identify the record type and display name or DBID of the record to be loaded. These parameters are the same as for the GetEntity and GetEntityByDbId APIs. The list parameter contains a sequence of directives that are used to control what fields will, or will not, be loaded. Only some field types can be excluded when loading the record.

The list must contain field names or type directives. A type directive is used to exclude, or include, all fields of a specified type. The list is processed in order. Once a type directive is processed, the subsequent field names must name fields of that type.

Type Directives

A type directive is a string value that begins with either '+' or '-' followed by a field type designation. The designation can be either numeric or a string name. A special value of "all" is accepted to designate all field types. The numeric value is accepted because the HCL Compass API definition (in CQPerlExt.pm) only defines numeric values for field types. See examples below. The string name of the field type matches the name of the API constant, but without the "CQ_" prefix, and it is not case sensitive.

A leading '+' or '-' means that all fields of the given type will be included, or excluded. These type directives establish a mode for the field names to follow. The names are taken as the opposite of the mode established for the field type. Those names are considered as exceptions to the rule established for the field type. If more than one type directive is given for a particular field type, only the last one will have any effect. Since each type directive says to either include or exclude all fields of that type, it will override any directive for that type and the associated field names for that type that came before it.

Examples

For example, the following two list items cause the load to exclude all reference list fields except for the "SubTasks" field:


 "-$CQPerlExt::CQ_REFERENCE_LIST", # exclude all reference list fields 
 "SubTasks"                        # ... but do load field "SubTasks"

This is the equivalent of a specification using the string name for the field type:


 "-Reference_List", # exclude all reference list fields 
 "SubTasks"         # ... but do load field "SubTasks"

The following is an example of when a script needs to check if the next action to be performed on a record is past due. The check requires only two fields that represent that condition:


 "-all",  # exclude all fields 
"Status", # ... but do load field "Status" 
"DueDate" # ... and field "DueDate"

Note: Using "all" implicitly applies to just the fields that are allowed to be excluded from the load. In other words, using "-all" will not actually exclude many fields, since not all field types are supported for partial loading, and system-owned fields, such as "dbid", "ID", "State", etc., are always loaded. But this specification will implicitly take advantage of future changes that support excluding more field types, and will always load the smallest possible number of fields.

The following example is for a case where only attachment fields are needed. Using "-all" excludes all fields that can be excluded, and the next entry makes sure that all attachment fields are loaded.


 "-all",                          # exclude all fields 
"+$CQPerlExt::CQ_ATTACHMENT_LIST" # ... but include all attachment lists

More details about special directives, error handling, and how the loaded entity is shared, can be found in the technote How to Improve Performance for Perl Scripts that Load Records.