EntityLoadByExample()

  • Category:
  • ORM
edit

Loads and returns an array of objects that match the sample entity.

Requires Extension: Hibernate ORM Engine Extension

EntityLoadByExample( sampleEntity=object, unique=boolean );

Returns: any

Argument Description
sampleEntity
object, required 		edit

Name of the sample entity that is used to match and filter similar entities to load.
unique
boolean, optional 		edit

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.

Usage Notes

edit

Creates a Hibernate query-by-example (QBE) using the provided entity instance. Any non-null property on the example entity is used as a filter criterion.

Set unique to true if you expect exactly one result — returns the entity directly instead of an array. Throws if multiple rows match.

Properties set to their default values (e.g. 0 for numeric, "" for string) may be included in the filter, which can produce unexpected results. Only set the properties you want to filter on.

Examples

edit 
// Create an example entity with filter criteria
example = entityNew( "User" );
example.setStatus( "active" );
example.setRole( "admin" );
// Load all matching entities
matches = entityLoadByExample( example );
// Load a single unique match
example = entityNew( "User" );
example.setEmail( "susi@example.com" );
user = entityLoadByExample( example, true );

See also