# ORMExecuteQuery

Execute an HQL query with (optional) parameters and specific query options.

## Parameters

The `parameters` argument can be used to bind parameters to the SQL query. You can use either an array of binding parameters or a struct of named binding parameters.

The SQL must have the parameters bound using the syntax `?` for positional parameters or `:name` for named parameters.

Example:

```
 ORMExecuteQuery( hql: "FROM autos WHERE make = ?", params: [ 'Ford' ] );
 ORMExecuteQuery( hql: "FROM autos WHERE make = :make", params: { make: 'Ford' } );
 
```

## Options

The options struct can contain any of the following keys:

* **`unique`** - Specifies whether to retrieve a single, unique item. Default is false.
* **`datasource`** - The datasource to use for the query. If not specified, the default datasource will be used.
* **`offset`** - Specifies the position from which to retrieve the objects. Default is 0.
* **`maxresults`** - Specifies the maximum number of objects to be retrieved. Default is no limit.
* **`readonly`** - If true, the query will be read-only. Default is false.

## Method Signature

```
ORMExecuteQuery(hql=[String], params=[Any], unique=[Any], options=[Struct])
```

### Arguments

| Argument  | Type     | Required | Description                                                                                                                                                                              | Default |
| --------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `hql`     | `String` | `true`   | The HQL query string to execute.                                                                                                                                                         |         |
| `params`  | `Any`    | `false`  | Optional parameters for the HQL query. Can be a struct of named parameters or an array of positional parameters.                                                                         |         |
| `unique`  | `Any`    | `false`  | <p>Optional boolean indicating whether to return a unique result (true) or a list of results (false). If true, the query will return<br>a single object or null if no results found.</p> |         |
| `options` | `Struct` | `false`  | Optional struct of additional query options.                                                                                                                                             |         |

## Examples

### Simple HQL Query Execution

The `ORMExecuteQuery` function allows you to execute HQL (Hibernate Query Language) queries against your ORM entities. This function is useful for retrieving data based on specific criteria defined in your HQL query.

```java
var allToyotas = ORMExecuteQuery(
    hql = "FROM Auto WHERE Make = :make",
    params = { make = "Toyota" },
    options = { unique = false }
);
```

## Passing parameters

You can pass parameters to your HQL query using either named parameters (as a struct) or positional parameters (as an array).

```java
var allToyotas = ORMExecuteQuery(
    hql = "FROM Auto WHERE Make = ?",
    params = [ "Toyota" ]
);
```

Using named parameters:

```java
var toyota = ORMExecuteQuery(
    hql = "FROM Auto WHERE Make = :make",
    params = { make = "Toyota" }
);
```

Named parameters are converted to JPA-style positional placeholders in the HQL string prior to execution. Thus, the above query is rewritten as:

```sql
FROM Auto WHERE Make = ?1
```

prior to query execution.

## Related

* [EntityDelete](/reference/built-in-functions/entitydelete.md)
* [EntityLoad](/reference/built-in-functions/entityload.md)
* [EntityLoadByExample](/reference/built-in-functions/entityloadbyexample.md)
* [EntityLoadByPK](/reference/built-in-functions/entityloadbypk.md)
* [EntityMerge](/reference/built-in-functions/entitymerge.md)
* [EntityNameArray](/reference/built-in-functions/entitynamearray.md)
* [EntityNameList](/reference/built-in-functions/entitynamelist.md)
* [EntityNew](/reference/built-in-functions/entitynew.md)
* [EntityReload](/reference/built-in-functions/entityreload.md)
* [EntitySave](/reference/built-in-functions/entitysave.md)
* [EntityToQuery](/reference/built-in-functions/entitytoquery.md)
* [ORMClearSession](/reference/built-in-functions/ormclearsession.md)
* [ORMCloseAllSessions](/reference/built-in-functions/ormcloseallsessions.md)
* [ORMCloseSession](/reference/built-in-functions/ormclosesession.md)
* [ORMEvictCollection](/reference/built-in-functions/ormevictcollection.md)
* [ORMEvictEntity](/reference/built-in-functions/ormevictentity.md)
* [ORMEvictQueries](/reference/built-in-functions/ormevictqueries.md)
* [ORMFlush](/reference/built-in-functions/ormflush.md)
* [ORMFlushAll](/reference/built-in-functions/ormflushall.md)
* [ORMGetHibernateVersion](/reference/built-in-functions/ormgethibernateversion.md)
* [ORMGetSession](/reference/built-in-functions/ormgetsession.md)
* [ORMGetSessionFactory](/reference/built-in-functions/ormgetsessionfactory.md)
* [ORMReload](/reference/built-in-functions/ormreload.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bxorm.ortusbooks.com/reference/built-in-functions/ormexecutequery.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.