ORMExecuteQuery()

  • Category:
  • ORM
edit

Runs the HQL on the default data source specified for the application.

ORMExecuteQuery( hql=string, paramsOrUnique=any, uniqueOrQueryOptions=any, queryOptions=any );

Returns: any

Argument Description
hql
string, required 		edit

The hql query to execute
paramsOrUnique
any, optional 		edit

Object parameter for the entity

Alias: params
uniqueOrQueryOptions
any, optional 		edit

Specifies if the object parameter is unique

Alias: unique
queryOptions
any, optional 		edit

Options for the query

Usage Notes

edit

Executes an HQL (Hibernate Query Language) query. HQL operates on entity names and property names, not table and column names.

The function signature is flexible:

  • ORMExecuteQuery( hql ) — no params, returns array
  • ORMExecuteQuery( hql, params ) — params as struct (named) or array (positional)
  • ORMExecuteQuery( hql, unique ) — no params, returns single entity if true
  • ORMExecuteQuery( hql, params, unique ) — with params, returns single entity if true
  • ORMExecuteQuery( hql, params, unique, options ) — full form with query options

The options struct supports: maxresults, offset, cacheable, cachename, timeout, datasource.

ORMQueryExecute() is an alias for this function.

For bulk UPDATE/DELETE via HQL, entity lifecycle events do not fire. See ORM - Querying for full documentation.

Examples

edit 
// Named parameters
users = ORMExecuteQuery(
	"FROM User WHERE status = :status",
	{ status: "active" }
);

// Positional parameters
users = ORMExecuteQuery(
	"FROM User WHERE name = ?1",
	[ "Susi" ]
);

// Single result
user = ORMExecuteQuery(
	"FROM User WHERE email = :email",
	{ email: "susi@example.com" },
	true
);

// Pagination
page = ORMExecuteQuery(
	"FROM User ORDER BY name",
	{},
	false,
	{ maxresults: 10, offset: 20 }
);

// IN clause with array
users = ORMExecuteQuery(
	"FROM User WHERE role IN (:roles)",
	{ roles: [ "admin", "editor" ] }
);

// Aggregate
total = ORMExecuteQuery( "select count(u) from User u", {}, true );

// Bulk update (no entity events fired)
ORMExecuteQuery(
	"UPDATE User SET status = :status WHERE lastLogin < :cutoff",
	{ status: "inactive", cutoff: dateAdd( "m", -6, now() ) }
);

See also