Whatever message this page gives is out now! Go check it out!

EntityLoad

Last update:
May 18, 2026

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.

Returns

Array (if unique=false) Single entity (if unique=true)

Category

ORM functions

Function syntax

EntityLoad(entityName,[id="",unique="",options=""])
EntityLoad(entityName,[id="",Order="",options=""])
EntityLoad(entityName,[Filter="",unique="",options=""])
EntityLoad(entityName,[Filter="",Order="",options=""])

See Also

EntityLoadByExample, EntityReload, EntityDelete

History

ColdFusion (2018 release): Introduced named parameters.
ColdFusion 9: Added this function.

Parameters

Parameter
Description
entityName
Name of the entity to be loaded.
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).
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.
filter
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 .
order
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 .
options
A struct with the following keys:
  • 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.

 

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 22.

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.
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:
{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")>

Share this page

Was this page helpful?
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Thank you for your feedback. Your response will help improve this page.

On this page