> For the complete documentation index, see [llms.txt](https://bxorm.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bxorm.ortusbooks.com/bxorm-2.x/reference/built-in-functions.md).

# Built-in Functions

Every bx-orm built-in function, grouped by what you want to do

bx-orm ships 47 built-in functions (BIFs) for working with entities, queries and the ORM session. They are grouped below by task; the navigation lists them alphabetically.

## Create and Save

Make new entities and write them to the database. See [Working with Entities](/bxorm-2.x/working-with-entities/working-with-entities.md).

| Function                                                              | Description                                                                         |
| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [EntityNew](/bxorm-2.x/reference/built-in-functions/entitynew.md)     | Instantiate a new entity, optionally with a struct of properties.                   |
| [EntitySave](/bxorm-2.x/reference/built-in-functions/entitysave.md)   | Save an entity, or an array of entities, to the persistence context.                |
| [EntityMerge](/bxorm-2.x/reference/built-in-functions/entitymerge.md) | Merge the state of the given entity into the current persistence context (session). |

## Load

Read entities by id, by filter or by example.

| Function                                                                                | Description                                                                              |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| [EntityLoad](/bxorm-2.x/reference/built-in-functions/entityload.md)                     | Load an entity or array of entities from the database.                                   |
| [EntityLoadByPK](/bxorm-2.x/reference/built-in-functions/entityloadbypk.md)             | Load an entity, or an array of entities, by primary key, optionally locked or read-only. |
| [EntityLoadByPKOrFail](/bxorm-2.x/reference/built-in-functions/entityloadbypkorfail.md) | Load an entity by its primary key, or throw `orm.notFound`.                              |
| [EntityLoadOrFail](/bxorm-2.x/reference/built-in-functions/entityloadorfail.md)         | Load one entity by id or filter, or throw `orm.notFound`.                                |
| [EntityLoadOrNew](/bxorm-2.x/reference/built-in-functions/entityloadornew.md)           | Load an entity by id or filter, or return a new, unsaved one.                            |
| [EntityLoadOrSave](/bxorm-2.x/reference/built-in-functions/entityloadorsave.md)         | Load an entity by id or filter, or create and save a new one.                            |
| [EntityLoadByExample](/bxorm-2.x/reference/built-in-functions/entityloadbyexample.md)   | Load entities matching an example entity.                                                |
| [EntityLoadReadOnly](/bxorm-2.x/reference/built-in-functions/entityloadreadonly.md)     | Load entities like `entityLoad()`, read-only.                                            |
| [EntityGetReference](/bxorm-2.x/reference/built-in-functions/entitygetreference.md)     | Get a lazy reference to an entity by id without loading it from the database.            |
| [EntityReload](/bxorm-2.x/reference/built-in-functions/entityreload.md)                 | Reload an entity from the database.                                                      |

## Delete

| Function                                                                | Description                                                   |
| ----------------------------------------------------------------------- | ------------------------------------------------------------- |
| [EntityDelete](/bxorm-2.x/reference/built-in-functions/entitydelete.md) | Delete an entity, or an array of entities, from the database. |

## Query

Query with the fluent builder or HQL. See [Criteria Queries](/bxorm-2.x/working-with-entities/criteria.md) and [Queries and HQL](/bxorm-2.x/working-with-entities/querying.md).

| Function                                                                            | Description                                                                                        |
| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| [EntityCriteria](/bxorm-2.x/reference/built-in-functions/entitycriteria.md)         | Start a fluent query on an entity: conditions, joins, projections, paging, bulk updates and locks. |
| [ORMExecuteQuery](/bxorm-2.x/reference/built-in-functions/ormexecutequery.md)       | Execute an HQL query with (optional) parameters and specific query options.                        |
| [ORMGetSQLFunctions](/bxorm-2.x/reference/built-in-functions/ormgetsqlfunctions.md) | Retrieve the named SQL functions registered with the `sqlFunctions` setting.                       |

## Convert

Turn entities into structs or queries. See [Entities as Structs](/bxorm-2.x/working-with-entities/structs.md).

| Function                                                                            | Description                                                             |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| [EntityToStruct](/bxorm-2.x/reference/built-in-functions/entitytostruct.md)         | Convert an entity or array of entities to a struct or array of structs. |
| [EntityLoadAsStruct](/bxorm-2.x/reference/built-in-functions/entityloadasstruct.md) | Load entities straight into structs, without loading the entities.      |
| [EntityToQuery](/bxorm-2.x/reference/built-in-functions/entitytoquery.md)           | Convert an entity or array of entities to a Query object.               |

## Inspect

Ask about an entity or the entity model.

| Function                                                                                        | Description                                                                                                 |
| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| [EntityGetName](/bxorm-2.x/reference/built-in-functions/entitygetname.md)                       | The entity name of an entity instance, lazy reference or name (a name comes back with its declared casing). |
| [EntityGetId](/bxorm-2.x/reference/built-in-functions/entitygetid.md)                           | The primary key of an entity (a struct for composite keys).                                                 |
| [EntityGetDatasource](/bxorm-2.x/reference/built-in-functions/entitygetdatasource.md)           | The name of the datasource an entity is stored in.                                                          |
| [EntityGetMetadata](/bxorm-2.x/reference/built-in-functions/entitygetmetadata.md)               | The mapping metadata of an entity, as a struct.                                                             |
| [EntityIsDirty](/bxorm-2.x/reference/built-in-functions/entityisdirty.md)                       | Whether an entity has changes that are not saved yet.                                                       |
| [EntityGetDirtyProperties](/bxorm-2.x/reference/built-in-functions/entitygetdirtyproperties.md) | The names of an entity's properties whose values differ from the stored ones.                               |
| [EntityIsAttached](/bxorm-2.x/reference/built-in-functions/entityisattached.md)                 | Check whether an entity is attached to the current ORM session.                                             |
| [EntityNameArray](/bxorm-2.x/reference/built-in-functions/entitynamearray.md)                   | Retrieve an array of entity names for this ORM application.                                                 |
| [EntityNameList](/bxorm-2.x/reference/built-in-functions/entitynamelist.md)                     | Retrieve a list of entity names for this ORM application.                                                   |

## Session and Transactions

Work with the ORM session and database locks. See [Session Management](/bxorm-2.x/advanced/session-management.md) and [Transactions](/bxorm-2.x/working-with-entities/transactions.md).

| Function                                                                                      | Description                                                                                            |
| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| [EntityEvict](/bxorm-2.x/reference/built-in-functions/entityevict.md)                         | Remove an entity, or an array of entities, from the ORM session without deleting it.                   |
| [EntityLock](/bxorm-2.x/reference/built-in-functions/entitylock.md)                           | Lock an entity's row in the database until the current transaction ends.                               |
| [ORMReadOnly](/bxorm-2.x/reference/built-in-functions/ormreadonly.md)                         | Run a closure with every entity it loads read-only.                                                    |
| [ORMFlush](/bxorm-2.x/reference/built-in-functions/ormflush.md)                               | Flush the Hibernate session, synchronizing the in-memory state with the database.                      |
| [ORMFlushAll](/bxorm-2.x/reference/built-in-functions/ormflushall.md)                         | Flush all open Hibernate sessions in the current request.                                              |
| [ORMClearSession](/bxorm-2.x/reference/built-in-functions/ormclearsession.md)                 | Clear the Hibernate session for the current context and provided (or default) datasource.              |
| [ORMCloseSession](/bxorm-2.x/reference/built-in-functions/ormclosesession.md)                 | Close the Hibernate session for the current context and provided (or default) datasource.              |
| [ORMCloseAllSessions](/bxorm-2.x/reference/built-in-functions/ormcloseallsessions.md)         | Close all Hibernate sessions for the current context on all datasources.                               |
| [ORMIsSessionDirty](/bxorm-2.x/reference/built-in-functions/ormissessiondirty.md)             | Whether the ORM session for a datasource has changes that are not flushed to the database yet.         |
| [ORMGetSessionStatistics](/bxorm-2.x/reference/built-in-functions/ormgetsessionstatistics.md) | Statistics of the ORM session for a datasource: how many entities and collections it holds, and which. |
| [ORMGetSession](/bxorm-2.x/reference/built-in-functions/ormgetsession.md)                     | Retrieve the Hibernate Session configured for this datasource or default datasource.                   |
| [ORMGetSessionFactory](/bxorm-2.x/reference/built-in-functions/ormgetsessionfactory.md)       | Retrieve the Hibernate SessionFactory configured for this datasource or default datasource.            |

## Second-Level Cache

Evict data from the secondary cache. See [Caching](/bxorm-2.x/advanced/caching.md).

| Function                                                                            | Description                                                                                      |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| [ORMEvictEntity](/bxorm-2.x/reference/built-in-functions/ormevictentity.md)         | Evict all entity data for this entity name from the second-level cache.                          |
| [ORMEvictCollection](/bxorm-2.x/reference/built-in-functions/ormevictcollection.md) | Evict all entity data for a given collection on a given entity type from the second-level cache. |
| [ORMEvictQueries](/bxorm-2.x/reference/built-in-functions/ormevictqueries.md)       | Evict all queries from the named or default cache on the named or default datasource.            |

## ORM Application

Reload and diagnose the ORM. See [Errors and Diagnostics](/bxorm-2.x/advanced/errors-and-diagnostics.md).

| Function                                                                                    | Description                                                                                                    |
| ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| [ORMReload](/bxorm-2.x/reference/built-in-functions/ormreload.md)                           | Reload the ORM application.                                                                                    |
| [ORMDiagnostics](/bxorm-2.x/reference/built-in-functions/ormdiagnostics.md)                 | A snapshot of the ORM for this application: the first thing to check when something is wrong. It never throws. |
| [ORMGetHibernateVersion](/bxorm-2.x/reference/built-in-functions/ormgethibernateversion.md) | Retrieve the installed Hibernate version.                                                                      |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://bxorm.ortusbooks.com/bxorm-2.x/reference/built-in-functions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.