Perform create, read, update, delete operations on ORM Objects

Create entities
Save entities
Update objects
Read/Load objects
Delete objects
Convert object to query
Merge entities

In any data-centric application, you can perform the following operations on the database:

Insert (Create)
Update
Retrieve
Delete

Once the object relational model is defined in a ColdFusion application, you can perform CRUD operations on the objects directly using the methods provided by ColdFusion ORM. ColdFusion ORM, in turn, takes care of persisting the object in the database.

Create entities

EntityNew

Creates an object for persistent CFC with the given entity name. This is similar to CreateObject but it uses entityname whereas CreateObject takes CFC name. If there is no CFC defined in the application with the given entityname, an error will be thrown.

If the persistent CFC has an init method, then the function EntityNew calls the init method while creating the object.

Syntax

<entity> EntityNew("<entityName>")

Save entities

EntitySave

Saves or Updates the data of the entity and all related entities to the database.

ColdFusion automatically tries to find if a new record should be inserted or an existing record be updated for the given entity. If forceinsert=true, then ColdFusion always tries to insert the entity as a new record.

Calling this method may not run the insert/update SQL immediately. It is possible that various SQL statements are queued and then run as a batch for performance reasons. The SQL statements are run when the ORM session is flushed.

Syntax

EntitySave(entity, [forceinsert])

Parameter	Description
`entity`	The Entity that needs to be saved in the database.
`forceinsert`	If true, then ColdFusion always tries to insert the entity as a new record.

Example:

<cfset artist = EntityNew("Artist")> 
<cfset artist.setFirstName("Marcia")> 
<cfset artist.setlastName("Em")> 
<cfset EntitySave(artist)>

Update objects

EntitySave

The method to update an object is the same as saving an object. Load the object that needs to be updated, make updates, and save the object.

Syntax

EntitySave(entity, [forceinsert])

Example

The following example changes the first name of an artist with an Artist ID 1:

<cfset artist1 = EntityLoad("Artist", 1, true)> 
<cfset artist1.setFirstName("Garcia")> 
<cfset EntitySave(artist1)>

Read/Load objects

Entities are loaded using the EntityLoad methods. All EntityLoad methods take the entity name as input.

If the persistent CFC has an init method, the methods call the init method while creating objects.

Syntax

EntityLoad (entityname) 
EntityLoad (entityname, id [, unique]) 
EntityLoad (entityname, filtercriteria [,unique] 
EntityLoad(entityname, filtercriteria, sortorder [, options]) 
EntityLoadByExample(sampleentity [, unique]) 
EntityReload(entity)

Examples

EntityLoad (entityname)

Loads and returns an array of entities of the specified entity name. For example, to retrieve all the objects of the “artist” CFC:
```
<cfset artist = EntityLoad('ARTIST')>
```
EntityLoad (entityname, id [, unique])

Loads and returns an entity whose Primary key's value is id. The entity is returned as an array by default. If unique is true, then the entity is returned.

If the entity has a composite key, then the id has to be specified as key-value pairs (ColdFusion struct).

Example 1:

This example loads the Artist object with PK 100 and returns a single-element array containing the artist object.
```
<cfset artistArr = EntityLoad('Artist', 100)>
```
Example 2:

This example loads the Artist object with PK 100 and returns the artist object.
```
<cfset artistobj = EntityLoad('Artist', 100, true)>
```
Example 3:

This example loads the OrderDetail object which has the composite key OrderID=100 and ProductID=1 and returns the orderdetail object.
```
<cfset orderDetail = EntityLoad('orderdetails', {OrderID=100, ProductID=1}, true)>
```
EntityLoad (entityname, filtercriteria [,unique]

Loads and returns an array of entities of the given entity name that matches the filtercriteria. filtercriteria is a key-value pair (ColdFusion struct) of property names and its values. If there are more than one key-value pair in filtercriteria, then they always use the AND operator. If you are sure that only one record exists that matches this filtercriteria, unique=true can be specified so that a single entity is returned instead of an array. If unique=true and multiple records are returned, then an exception occurs. For example, to retrieve details of all artists that have state ‘CA’:
```
<cfset artistsFromCA = EntityLoad('Artist', {state="CA"})>
```
To retrieve a unique object, specify unique= "true". If more than one object satisfies the condition, an exception occurs.

This example loads the artist object whose firstName is "Austin" and lastname is "Weber".
```
<cfset artist = EntityLoad('artist', {firstname="Austin", lastname="Weber"}, "true")>
```
EntityLoad(entityname,filtercriteria,sortorder[, options])

Loads and returns an array of entities that satisfy the filtercriteria that is sorted as specified by the sortorder parameter.

filtercriteria is a key-value pair (ColdFusion struct) of property names and its values. If there are more than one key-value pairs in filtercriteria, then they always use the AND operator.

sortorder is a string, and should be specified in the following syntax:

"propname1 asc, propname2 desc, ..."

Some examples of sortorder are as follows:

"firstname asc, lastname desc"

"firstname"

"country, age desc"

Example:

To retrieve artists whose state is CA, and sorted by City and FirstName:
```
<cfset artistsFromCA = EntityLoad('artist', {state="CA"}, "city asc, firstName")>
```
Certain configuration options can be input as name-value pairs as options argument. Several options can be specified to control the behavior of entity retrieval.
- maxResults: Specifies the maximum number of objects to be retrieved.
- offset: Specifies the start index of the resultset from where it has to start the retrieval.
- cacheable: Whether the result of this query is 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.
Maxresults and timeout are used for pagination.

Example

To load first 5 artists whose state is "CA" that are sorted on the firstName.
```
<cfset artists = EntityLoad("Artist",{state='CA"}, "FirstName", {maxResults=5})>
```
EntityLoadByExample(sampleentity [,unique])

Loads and returns an array of objects that match the sampleentity. The filter criteria is constructed by ANDing all the non-null properties of the sampleentity.For example, to retrieve an array of objects matching the specified values:
```
<cfset artist= CreateObject("component", "artist")> 
<cfset artist.setState("CA")> 
<cfset artist.setCity("Berkeley")> 
<cfset artist=EntityLoadByExample(artist)>
```
If you are sure that only one record exists that matches the specified filtercriteria, you can specify unique=true so that a single entity is returned instead of an array. If unique=true and multiple records are returned, then an exception occurs.
EntityReload(entity)

Reloads data for an entity that is already loaded in this session. This method refetches data from the database and repopulates the entity.

Delete objects

EntityDelete

This method deletes the record from the database for the specified entity. Depending on the cascade attribute specified in the mapping, it also deletes the associated objects.

Syntax

EntityDelete(entity)

Example

For example, to delete an Artist with ArtistID 5:

<cfset artist = EntityLoad('artist', 5, true)> 
<cfset EntityDelete(artist)>

Convert object to query

EntitytoQueryThis method converts the input entity object or the input array of entity objects to a query object. The name of the properties are used as the query column names. Use the optional parameter Entity_name to return the query of the given entity in the case of inheritance mapping. All the objects in the input array should be of the same type. Relationship properties are not be included in the result query.

Syntax

EntitytoQuery (orm_object, [entity_name]) 
EntitytoQuery (orm_object_array, [entity_name])

Example 1

<cfset artists = EntityLoad("Artist")> 
<cfset artistQuery = EntityToQuery(artists)>

Example 2

<cfset creditCardPayments = EntityLoad("CreditCardPayment")> 
<cfset paymentQuery = EntityToQuery(creditCardPayments, "payment")>

Merge entities

EntityMerge

To attach an entity to the current ORM session you can use the entitymerge function. It copies the state of the given object onto the persistent object with the same identifier and returns the persistent object.

If there is no persistent instance currently associated with the session, it is loaded. The given instance is not associated with the session. You need to use the returned object from this session. For details, see EntityMerge in CFML Reference.