entityLoad
Description
Loads and returns an array of entities for the specified entity name. You can also specify a filter criteria and sort order. All EntityLoad methods take the entity name as input.
Categories
Related
History
ColdFusion
9: Added this function.
Syntax
EntityLoad (entityname) EntityLoad (entityname, id [, unique]) EntityLoad (entityname, filtercriteria [,unique] EntityLoad(entityname, filtercriteria, sortorder [, options])
Attributes
| Attribute | Description | Required | Default |
|---|---|---|---|
| entity name | Name of the entity to be loaded. | ||
| filtercriteria | Key-value pair (ColdFusion Struct) of property names and values. If there are more than one key-value pair, then the AND operator is used.If specified, loads and returns an array of entities of the specified entity name that matches the filtercriteria. | ||
| ID | The primary key value of the entity that must be loaded. If the entity has a composite key, then the ID has to be specified as key-value pairs (ColdFusion struct). | ||
| options | The following options to customize the output: ignorecase: Ignores the case of sort order when set to true. Use only if you specify the sortorder parameter. offset: Specifies the position from which to retrieve the objects. maxResults: Specifies the maximum number of objects to be retrieved. cacheable: Whether the result has to be cached in the secondary cache. Default is false. cachename: Name of the cache in secondary cache. timeout: Specifies the timeout value (in seconds) for the query. | ||
| sortorder | String used to specify the sortorder of the entities that are returned.If specified, loads and returns an array of entities that satisfy the filtercriteria sorted as specified by the sortorder. | ||
| unique | If unique is set to true, then the entity is returned. If you are sure that only one record exists that matches this filtercriteria, then you can specify unique=true, so that a single entity is returned instead of an array. If you set unique=true and multiple records are returned, then an exception occurs. |
Returns
Array (if unique=false)
Single
entity (if unique=true)
Usage
For pagination, you can use the options offset and maxResults as shown in the example:
EntityLoad('employee', {department='qa'} , {offset=21, maxResults=10})
This example retrieves the (next) 10 objects of employees whose department is qa from offset 21.
EntityLoad('employee', {department='qa'} , {offset=21, maxResults=10})
This example retrieves the (next) 10 objects of employees whose department is qa from offset 21.
Example
Example with only entity name
specified:
<cfset employees = EntityLoad('employee')>
Example
with EntityName, ID, and unique set
to true. Instead of true, if you
set unique as false, then array is returned with
one entity.
<cfset employee = EntityLoad('employee', 100, true)>
Entity name, composite key.
<cfset orderDetail = EntityLoad('orderdetails', {OrderID=100, ProductID=1}, true)>
Example
which describes how to retrieve objects whose country is UK,
and sorted by Department ascending and Age descending:
<cfset employeesInUKSorted = EntityLoad('employee',
{country="UK"}, "Department Asc, Age Desc")>
Example
that describes how to retrieve details of all the employees who
live in 'UK':
<cfset employeesFromUK = EntityLoad('employee', {country="UK"}>
Example
that describes how to retrieve a unique object. If you specify unique= "true" and
more than one object satisfies the condition, then an exception occurs.
<cfset employee = EntityLoad('employee', {firstname="Marcia", lastname="Em"}, "true")>