Skip to main content
Version: Next

Class: EntityManager<D>

core.EntityManager

The EntityManager is the central access point to ORM functionality. It is a facade to all different ORM subsystems such as UnitOfWork, Query Language and Repository API.

template driver type

Type parameters#

NameType
DD: IDatabaseDriver = IDatabaseDriver

Hierarchy#

Properties#

config#

Readonly config: Configuration<IDatabaseDriver<Connection>>


id#

Readonly id: number

Defined in#

packages/core/src/EntityManager.ts:23


name#

Readonly name: string

Defined in#

packages/core/src/EntityManager.ts:24

Methods#

addFilter#

addFilter<T1>(name, cond, entityName?, enabled?): void

Registers global filter to this entity manager. Global filters are enabled by default (unless disabled via last parameter).

Type parameters#

NameType
T1T1: AnyEntity<T1>

Parameters#

NameType
namestring
condFilterQuery<T1> | (args: Dictionary<any>) => FilterQuery<T1>
entityName?EntityName<T1> | [EntityName<T1>]
enabled?boolean

Returns#

void

Defined in#

packages/core/src/EntityManager.ts:150

addFilter<T1, T2>(name, cond, entityName?, enabled?): void

Registers global filter to this entity manager. Global filters are enabled by default (unless disabled via last parameter).

Type parameters#

NameType
T1T1: AnyEntity<T1>
T2T2: AnyEntity<T2>

Parameters#

NameType
namestring
condFilterQuery<T1 | T2> | (args: Dictionary<any>) => FilterQuery<T1 | T2>
entityName?[EntityName<T1>, EntityName<T2>]
enabled?boolean

Returns#

void

Defined in#

packages/core/src/EntityManager.ts:155

addFilter<T1, T2, T3>(name, cond, entityName?, enabled?): void

Registers global filter to this entity manager. Global filters are enabled by default (unless disabled via last parameter).

Type parameters#

NameType
T1T1: AnyEntity<T1>
T2T2: AnyEntity<T2>
T3T3: AnyEntity<T3>

Parameters#

NameType
namestring
condFilterQuery<T1 | T2 | T3> | (args: Dictionary<any>) => FilterQuery<T1 | T2 | T3>
entityName?[EntityName<T1>, EntityName<T2>, EntityName<T3>]
enabled?boolean

Returns#

void

Defined in#

packages/core/src/EntityManager.ts:160


assign#

assign<T>(entity, data, options?): T

Shortcut for wrap(entity).assign(data, { em })

Type parameters#

NameType
TT: AnyEntity<T>

Parameters#

NameType
entityT
dataEntityData<T> | Partial<EntityDTO<T>>
optionsAssignOptions

Returns#

T

Defined in#

packages/core/src/EntityManager.ts:564


begin#

begin(options?): Promise<void>

Starts new transaction bound to this EntityManager. Use ctx parameter to provide the parent when nesting transactions.

Parameters#

NameType
optionsObject
options.ctx?any
options.isolationLevel?IsolationLevel

Returns#

Promise<void>

Defined in#

packages/core/src/EntityManager.ts:411


canPopulate#

canPopulate<T>(entityName, property): boolean

Checks whether given property can be populated on the entity.

Type parameters#

NameType
TT: AnyEntity<T>

Parameters#

NameType
entityNameEntityName<T>
propertystring

Returns#

boolean

Defined in#

packages/core/src/EntityManager.ts:731


clear#

clear(): void

Clears the EntityManager. All entities that are currently managed by this EntityManager become detached.

Returns#

void

Defined in#

packages/core/src/EntityManager.ts:724


commit#

commit(): Promise<void>

Commits the transaction bound to this EntityManager. Flushes before doing the actual commit query.

Returns#

Promise<void>

Defined in#

packages/core/src/EntityManager.ts:418


count#

count<T>(entityName, where?, options?): Promise<number>

Returns total number of entities matching your where query.

Type parameters#

NameType
TT: AnyEntity<T>

Parameters#

NameType
entityNameEntityName<T>
whereFilterQuery<T>
optionsCountOptions<T>

Returns#

Promise<number>

Defined in#

packages/core/src/EntityManager.ts:614


create#

create<T, P>(entityName, data, options?): Loaded<T, P>

Creates new instance of given entity and populates it with given data

Type parameters#

NameType
TT: AnyEntity<T>
PP: Populate<T> = any

Parameters#

NameType
entityNameEntityName<T>
dataEntityData<T>
optionsObject
options.managed?boolean

Returns#

Loaded<T, P>

Defined in#

packages/core/src/EntityManager.ts:557


find#

find<T, P>(entityName, where, options?): Promise<Loaded<T, P>[]>

Finds all entities matching your where query. You can pass additional options via the options parameter.

Type parameters#

NameType
TT: AnyEntity<T>
PP: Populate<T> = any

Parameters#

NameType
entityNameEntityName<T>
whereFilterQuery<T>
options?FindOptions<T, P>

Returns#

Promise<Loaded<T, P>[]>

Defined in#

packages/core/src/EntityManager.ts:92

find<T, P>(entityName, where, populate?, orderBy?, limit?, offset?): Promise<Loaded<T, P>[]>

Finds all entities matching your where query.

Type parameters#

NameType
TT: AnyEntity<T>
PP: Populate<T> = any

Parameters#

NameType
entityNameEntityName<T>
whereFilterQuery<T>
populate?P
orderBy?QueryOrderMap
limit?number
offset?number

Returns#

Promise<Loaded<T, P>[]>

Defined in#

packages/core/src/EntityManager.ts:97


findAndCount#

findAndCount<T, P>(entityName, where, options?): Promise<[Loaded<T, P>[], number]>

Calls em.find() and em.count() with the same arguments (where applicable) and returns the results as tuple where first element is the array of entities and the second is the count.

Type parameters#

NameType
TT: AnyEntity<T>
PP: Populate<T> = any

Parameters#

NameType
entityNameEntityName<T>
whereFilterQuery<T>
options?FindOptions<T, P>

Returns#

Promise<[Loaded<T, P>[], number]>

Defined in#

packages/core/src/EntityManager.ts:275

findAndCount<T, P>(entityName, where, populate?, orderBy?, limit?, offset?): Promise<[Loaded<T, P>[], number]>

Calls em.find() and em.count() with the same arguments (where applicable) and returns the results as tuple where first element is the array of entities and the second is the count.

Type parameters#

NameType
TT: AnyEntity<T>
PP: Populate<T> = any

Parameters#

NameType
entityNameEntityName<T>
whereFilterQuery<T>
populate?P
orderBy?QueryOrderMap
limit?number
offset?number

Returns#

Promise<[Loaded<T, P>[], number]>

Defined in#

packages/core/src/EntityManager.ts:281


findOne#

findOne<T, P>(entityName, where, options?): Promise<null | Loaded<T, P>>

Finds first entity matching your where query.

Type parameters#

NameType
TT: AnyEntity<T>
PP: Populate<T> = any

Parameters#

NameType
entityNameEntityName<T>
whereFilterQuery<T>
options?FindOneOptions<T, P>

Returns#

Promise<null | Loaded<T, P>>

Defined in#

packages/core/src/EntityManager.ts:300

findOne<T, P>(entityName, where, populate?, orderBy?): Promise<null | Loaded<T, P>>

Finds first entity matching your where query.

Type parameters#

NameType
TT: AnyEntity<T>
PP: Populate<T> = any

Parameters#

NameType
entityNameEntityName<T>
whereFilterQuery<T>
populate?P
orderBy?QueryOrderMap

Returns#

Promise<null | Loaded<T, P>>

Defined in#

packages/core/src/EntityManager.ts:305


findOneOrFail#

findOneOrFail<T, P>(entityName, where, options?): Promise<Loaded<T, P>>

Finds first entity matching your where query. If nothing found, it will throw an error. You can override the factory for creating this method via options.failHandler locally or via Configuration.findOneOrFailHandler globally.

Type parameters#

NameType
TT: AnyEntity<T>
PP: Populate<T> = any

Parameters#

NameType
entityNameEntityName<T>
whereFilterQuery<T>
options?FindOneOrFailOptions<T, P>

Returns#

Promise<Loaded<T, P>>

Defined in#

packages/core/src/EntityManager.ts:362

findOneOrFail<T, P>(entityName, where, populate?, orderBy?): Promise<Loaded<T, P>>

Finds first entity matching your where query. If nothing found, it will throw an error. You can override the factory for creating this method via options.failHandler locally or via Configuration.findOneOrFailHandler globally.

Type parameters#

NameType
TT: AnyEntity<T>
PP: Populate<T> = any

Parameters#

NameType
entityNameEntityName<T>
whereFilterQuery<T>
populate?P
orderBy?QueryOrderMap

Returns#

Promise<Loaded<T, P>>

Defined in#

packages/core/src/EntityManager.ts:369


flush#

flush(): Promise<void>

Flushes all changes to objects that have been queued up to now to the database. This effectively synchronizes the in-memory state of managed objects with the database.

Returns#

Promise<void>

Defined in#

packages/core/src/EntityManager.ts:717


fork#

fork(clear?, useContext?): D[typeof EntityManagerType]

Returns new EntityManager instance with its own identity map

Parameters#

NameTypeDefault valueDescription
clearbooleantruedo we want clear identity map? defaults to true
useContextbooleanfalseuse request context? should be used only for top level request scope EM, defaults to false

Returns#

D[typeof EntityManagerType]

Defined in#

packages/core/src/EntityManager.ts:788


getComparator#

getComparator(): EntityComparator

Gets the EntityComparator.

Returns#

EntityComparator

Defined in#

packages/core/src/EntityManager.ts:872


getConnection#

getConnection(type?): ReturnType<D["getConnection"]>

Gets the Connection instance, by default returns write connection

Parameters#

NameType
type?"read" | "write"

Returns#

ReturnType<D["getConnection"]>

Defined in#

packages/core/src/EntityManager.ts:56


getContext#

getContext(): EntityManager<IDatabaseDriver<Connection>>

Gets the EntityManager based on current transaction/request context.

Returns#

EntityManager<IDatabaseDriver<Connection>>

Defined in#

packages/core/src/EntityManager.ts:819


getDriver#

getDriver(): D

Gets the Driver instance used by this EntityManager. Driver is singleton, for one MikroORM instance, only one driver is created.

Returns#

D

Defined in#

packages/core/src/EntityManager.ts:49


getEntityFactory#

getEntityFactory(): EntityFactory

Gets the EntityFactory used by the EntityManager.

Returns#

EntityFactory

Defined in#

packages/core/src/EntityManager.ts:812


getEventManager#

getEventManager(): EventManager

Returns#

EventManager

Defined in#

packages/core/src/EntityManager.ts:830


getFilterParams#

getFilterParams<T>(name): T

Returns filter parameters for given filter set in this context.

Type parameters#

NameType
TT: Dictionary<any> = Dictionary<any>

Parameters#

NameType
namestring

Returns#

T

Defined in#

packages/core/src/EntityManager.ts:186


getMetadata#

getMetadata(): MetadataStorage

Gets the MetadataStorage.

Returns#

MetadataStorage

Defined in#

packages/core/src/EntityManager.ts:865


getPlatform#

getPlatform(): ReturnType<D["getPlatform"]>

Gets the platform instance. Just like the driver, platform is singleton, one for a MikroORM instance.

Returns#

ReturnType<D["getPlatform"]>

Defined in#

packages/core/src/EntityManager.ts:63


getReference#

getReference<T, PK>(entityName, id, wrapped, convertCustomTypes?): IdentifiedReference<T, PK>

Gets a reference to the entity identified by the given type and identifier without actually loading it, if the entity is not yet loaded

Type parameters#

NameType
TT: AnyEntity<T>
PKPK: string | number | symbol

Parameters#

NameType
entityNameEntityName<T>
idPrimary<T>
wrappedtrue
convertCustomTypes?boolean

Returns#

IdentifiedReference<T, PK>

Defined in#

packages/core/src/EntityManager.ts:571

getReference<T>(entityName, id): T

Gets a reference to the entity identified by the given type and identifier without actually loading it, if the entity is not yet loaded

Type parameters#

NameType
TT: AnyEntity<T>

Parameters#

NameType
entityNameEntityName<T>
idPrimary<T> | Primary<T>[]

Returns#

T

Defined in#

packages/core/src/EntityManager.ts:576

getReference<T>(entityName, id, wrapped, convertCustomTypes?): T

Gets a reference to the entity identified by the given type and identifier without actually loading it, if the entity is not yet loaded

Type parameters#

NameType
TT: AnyEntity<T>

Parameters#

NameType
entityNameEntityName<T>
idPrimary<T>
wrappedfalse
convertCustomTypes?boolean

Returns#

T

Defined in#

packages/core/src/EntityManager.ts:581

getReference<T>(entityName, id, wrapped?, convertCustomTypes?): T | Reference<T>

Gets a reference to the entity identified by the given type and identifier without actually loading it, if the entity is not yet loaded

Type parameters#

NameType
TT: AnyEntity<T>

Parameters#

NameType
entityNameEntityName<T>
idPrimary<T>
wrapped?boolean
convertCustomTypes?boolean

Returns#

T | Reference<T>

Defined in#

packages/core/src/EntityManager.ts:586


getRepository#

getRepository<T, U>(entityName): GetRepository<T, U>

Gets repository for given entity. You can pass either string name or entity class reference.

Type parameters#

NameType
TT: AnyEntity<T>
UU: EntityRepository<T, U> = EntityRepository<T>

Parameters#

NameType
entityNameEntityName<T>

Returns#

GetRepository<T, U>

Defined in#

packages/core/src/EntityManager.ts:70


getTransactionContext#

getTransactionContext<T>(): undefined | T

Gets the transaction context (driver dependent object used to make sure queries are executed on same connection).

Type parameters#

NameType
TT: unknown = any

Returns#

undefined | T

Defined in#

packages/core/src/EntityManager.ts:844


getUnitOfWork#

getUnitOfWork(): UnitOfWork

Gets the UnitOfWork used by the EntityManager to coordinate operations.

Returns#

UnitOfWork

Defined in#

packages/core/src/EntityManager.ts:805


getValidator#

getValidator(): EntityValidator

Gets EntityValidator instance

Returns#

EntityValidator

Defined in#

packages/core/src/EntityManager.ts:85


isInTransaction#

isInTransaction(): boolean

Checks whether this EntityManager is currently operating inside a database transaction.

Returns#

boolean

Defined in#

packages/core/src/EntityManager.ts:837


lock#

lock(entity, lockMode, options?): Promise<void>

Runs your callback wrapped inside a database transaction.

Parameters#

NameType
entityAnyEntity<any>
lockModeLockMode
optionsnumber | Date | { lockTableAliases?: string[] ; lockVersion?: number | Date }

Returns#

Promise<void>

Defined in#

packages/core/src/EntityManager.ts:435


map#

map<T>(entityName, result): T

Maps raw database result to an entity and merges it to this EntityManager.

Type parameters#

NameType
TT: AnyEntity<T>

Parameters#

NameType
entityNameEntityName<T>
resultEntityDictionary<T>

Returns#

T

Defined in#

packages/core/src/EntityManager.ts:499


merge#

merge<T>(entity, refresh?): T

Merges given entity to this EntityManager so it becomes managed. You can force refreshing of existing entities via second parameter. By default it will return already loaded entities without modifying them.

Type parameters#

NameType
TT: AnyEntity<T>

Parameters#

NameType
entityT
refresh?boolean

Returns#

T

Defined in#

packages/core/src/EntityManager.ts:519

merge<T>(entityName, data, refresh?, convertCustomTypes?): T

Merges given entity to this EntityManager so it becomes managed. You can force refreshing of existing entities via second parameter. By default it will return already loaded entities without modifying them.

Type parameters#

NameType
TT: AnyEntity<T>

Parameters#

NameType
entityNameEntityName<T>
dataEntityData<T> | EntityDTO<T>
refresh?boolean
convertCustomTypes?boolean

Returns#

T

Defined in#

packages/core/src/EntityManager.ts:525


nativeDelete#

nativeDelete<T>(entityName, where, options?): Promise<number>

Fires native delete query. Calling this has no side effects on the context (identity map).

Type parameters#

NameType
TT: AnyEntity<T>

Parameters#

NameType
entityNameEntityName<T>
whereFilterQuery<T>
optionsDeleteOptions<T>

Returns#

Promise<number>

Defined in#

packages/core/src/EntityManager.ts:487


nativeInsert#

nativeInsert<T>(entity): Promise<Primary<T>>

Fires native insert query. Calling this has no side effects on the context (identity map).

Type parameters#

NameType
TT: AnyEntity<T>

Parameters#

NameType
entityT

Returns#

Promise<Primary<T>>

Defined in#

packages/core/src/EntityManager.ts:443

nativeInsert<T>(entityName, data): Promise<Primary<T>>

Fires native insert query. Calling this has no side effects on the context (identity map).

Type parameters#

NameType
TT: AnyEntity<T>

Parameters#

NameType
entityNameEntityName<T>
dataEntityData<T>

Returns#

Promise<Primary<T>>

Defined in#

packages/core/src/EntityManager.ts:448


nativeUpdate#

nativeUpdate<T>(entityName, where, data, options?): Promise<number>

Fires native update query. Calling this has no side effects on the context (identity map).

Type parameters#

NameType
TT: AnyEntity<T>

Parameters#

NameType
entityNameEntityName<T>
whereFilterQuery<T>
dataEntityData<T>
optionsUpdateOptions<T>

Returns#

Promise<number>

Defined in#

packages/core/src/EntityManager.ts:473


persist#

persist(entity): EntityManager<D>

Tells the EntityManager to make an instance managed and persistent. The entity will be entered into the database at or before transaction commit or as a result of the flush operation.

Parameters#

NameType
entityAnyEntity<any> | Reference<AnyEntity<any>> | (AnyEntity<any> | Reference<AnyEntity<any>>)[]

Returns#

EntityManager<D>

Defined in#

packages/core/src/EntityManager.ts:636


persistAndFlush#

persistAndFlush(entity): Promise<void>

Persists your entity immediately, flushing all not yet persisted changes to the database too. Equivalent to em.persist(e).flush().

Parameters#

NameType
entityAnyEntity<any> | Reference<AnyEntity<any>> | (AnyEntity<any> | Reference<AnyEntity<any>>)[]

Returns#

Promise<void>

Defined in#

packages/core/src/EntityManager.ts:661


persistLater#

persistLater(entity): void

Tells the EntityManager to make an instance managed and persistent. The entity will be entered into the database at or before transaction commit or as a result of the flush operation.

deprecated use persist()

Parameters#

NameType
entityAnyEntity<any> | AnyEntity<any>[]

Returns#

void

Defined in#

packages/core/src/EntityManager.ts:671


populate#

populate<T, P>(entities, populate, options?): Promise<Loaded<T, P>>

Loads specified relations in batch. This will execute one query for each relation, that will populate it on all of the specified entities.

Type parameters#

NameType
TT: AnyEntity<T>
PP: string | number | boolean | symbol | readonly string[] | readonly keyof T[] | PopulateChildren<T>

Parameters#

NameType
entitiesT
populateP
options?EntityLoaderOptions<T>

Returns#

Promise<Loaded<T, P>>

Defined in#

packages/core/src/EntityManager.ts:751

populate<T, P>(entities, populate, options?): Promise<Loaded<T, P>[]>

Loads specified relations in batch. This will execute one query for each relation, that will populate it on all of the specified entities.

Type parameters#

NameType
TT: AnyEntity<T>
PP: string | number | boolean | symbol | readonly string[] | readonly keyof T[] | PopulateChildren<T>

Parameters#

NameType
entitiesT[]
populateP
options?EntityLoaderOptions<T>

Returns#

Promise<Loaded<T, P>[]>

Defined in#

packages/core/src/EntityManager.ts:756

populate<T, P>(entities, populate, options?): Promise<Loaded<T, P> | Loaded<T, P>[]>

Loads specified relations in batch. This will execute one query for each relation, that will populate it on all of the specified entities.

Type parameters#

NameType
TT: AnyEntity<T>
PP: string | number | boolean | symbol | readonly string[] | readonly keyof T[] | PopulateChildren<T>

Parameters#

NameType
entitiesT | T[]
populateP
options?EntityLoaderOptions<T>

Returns#

Promise<Loaded<T, P> | Loaded<T, P>[]>

Defined in#

packages/core/src/EntityManager.ts:761


remove#

remove<T>(entity): EntityManager<D>

Marks entity for removal. A removed entity will be removed from the database at or before transaction commit or as a result of the flush operation.

To remove entities by condition, use em.nativeDelete().

Type parameters#

NameType
TT: AnyEntity<T>

Parameters#

NameType
entityT | Reference<T> | (T | Reference<T>)[]

Returns#

EntityManager<D>

Defined in#

packages/core/src/EntityManager.ts:681


removeAndFlush#

removeAndFlush(entity): Promise<void>

Removes an entity instance immediately, flushing all not yet persisted changes to the database too. Equivalent to em.remove(e).flush()

Parameters#

NameType
entityAnyEntity<any> | Reference<AnyEntity<any>>

Returns#

Promise<void>

Defined in#

packages/core/src/EntityManager.ts:699


removeLater#

removeLater(entity): void

Marks entity for removal. A removed entity will be removed from the database at or before transaction commit or as a result of the flush operation.

deprecated use remove()

Parameters#

NameType
entityAnyEntity<any>

Returns#

void

Defined in#

packages/core/src/EntityManager.ts:709


resetTransactionContext#

resetTransactionContext(): void

Resets the transaction context.

Returns#

void

Defined in#

packages/core/src/EntityManager.ts:858


rollback#

rollback(): Promise<void>

Rollbacks the transaction bound to this EntityManager.

Returns#

Promise<void>

Defined in#

packages/core/src/EntityManager.ts:427


setFilterParams#

setFilterParams(name, args): void

Sets filter parameter values globally inside context defined by this entity manager. If you want to set shared value for all contexts, be sure to use the root entity manager.

Parameters#

NameType
namestring
argsDictionary<any>

Returns#

void

Defined in#

packages/core/src/EntityManager.ts:179


setTransactionContext#

setTransactionContext(ctx): void

Sets the transaction context.

Parameters#

NameType
ctxany

Returns#

void

Defined in#

packages/core/src/EntityManager.ts:851


transactional#

transactional<T>(cb, options?): Promise<T>

Runs your callback wrapped inside a database transaction.

Type parameters#

Name
T

Parameters#

NameType
cb(em: D[typeof EntityManagerType]) => Promise<T>
optionsObject
options.ctx?any
options.isolationLevel?IsolationLevel

Returns#

Promise<T>

Defined in#

packages/core/src/EntityManager.ts:392