EntityManager <D>
Hierarchy
- EntityManager<D>
- EntityManager
Index
Properties
Accessors
Methods
- addFilter
- assign
- begin
- canPopulate
- clear
- clearCache
- commit
- count
- create
- createQueryBuilder
- execute
- find
- findAndCount
- findOne
- findOneOrFail
- flush
- fork
- getComparator
- getConnection
- getDriver
- getEntityFactory
- getEventManager
- getFilterParams
- getHydrator
- getKnex
- getMetadata
- getPlatform
- getReference
- getRepository
- getTransactionContext
- getUnitOfWork
- getValidator
- insert
- insertMany
- isInTransaction
- lock
- map
- merge
- nativeDelete
- nativeInsert
- nativeUpdate
- persist
- persistAndFlush
- persistLater
- populate
- qb
- raw
- refresh
- remove
- removeAndFlush
- removeLater
- repo
- resetTransactionContext
- rollback
- setFilterParams
- setFlushMode
- setTransactionContext
- transactional
- upsert
- upsertMany
Properties
readonly_id
readonlyconfig
readonlyglobal
readonlyname
Accessors
id
Returns the ID of this EntityManager. Respects the context, so global EM will give you the contextual ID if executed inside request context handler.
Returns number
schema
Returns the default schema of this EntityManager. Respects the context, so global EM will give you the contextual schema if executed inside request context handler.
Returns undefined | string
Sets the default schema of this EntityManager. Respects the context, so global EM will set the contextual schema if executed inside request context handler.
Parameters
schema: undefined | null | string
Returns void
Methods
addFilter
Registers global filter to this entity manager. Global filters are enabled by default (unless disabled via last parameter).
Type parameters
- T1
Parameters
name: string
cond: FilterQuery<T1> | (args: Dictionary) => MaybePromise<FilterQuery<T1>>
optionalentityName: EntityName<T1> | [EntityName<T1>]
optionalenabled: boolean
Returns void
assign
Shortcut for
wrap(entity).assign(data, { em })Type parameters
- Entity: object
Parameters
entity: Entity
data: EntityData<Entity> | Partial<EntityDTO<Entity>>
options: AssignOptions = {}
Returns Entity
begin
Starts new transaction bound to this EntityManager. Use
ctxparameter to provide the parent when nesting transactions.Parameters
options: Omit<TransactionOptions, ignoreNestedTransactions> = {}
Returns Promise<void>
canPopulate
Checks whether given property can be populated on the entity.
Type parameters
- Entity: object
Parameters
entityName: EntityName<Entity>
property: string
Returns boolean
clear
Clears the EntityManager. All entities that are currently managed by this EntityManager become detached.
Returns void
clearCache
Clears result cache for given cache key. If we want to be able to call this method, we need to set the cache key explicitly when storing the cache.
// set the cache key to 'book-cache-key', with expiration of 60s
const res = await em.find(Book, { ... }, { cache: ['book-cache-key', 60_000] });
// clear the cache key by name
await em.clearCache('book-cache-key');Parameters
cacheKey: string
Returns Promise<void>
commit
Commits the transaction bound to this EntityManager. Flushes before doing the actual commit query.
Returns Promise<void>
count
Returns total number of entities matching your
wherequery.Type parameters
- Entity: object
- Hint: string = never
Parameters
entityName: EntityName<Entity>
where: FilterQuery<Entity> = ...
options: CountOptions<Entity, Hint> = {}
Returns Promise<number>
create
Creates new instance of given entity and populates it with given data. The entity constructor will be used unless you provide
{ managed: true }in the options parameter. The constructor will be given parameters based on the defined constructor of the entity. If the constructor parameter matches a property name, its value will be extracted fromdata. If no matching property exists, the wholedataparameter will be passed. This means we can also defineconstructor(data: Partial<T>)andem.create()will pass the data into it (unless we have a property nameddatatoo).Type parameters
- Entity: object
Parameters
entityName: EntityName<Entity>
data: RequiredEntityData<Entity>
options: CreateOptions = {}
Returns Entity
createQueryBuilder
Creates a QueryBuilder instance
Type parameters
- T: object
Parameters
entityName: EntityName<T> | QueryBuilder<T>
optionalalias: string
optionaltype: ConnectionType
Returns QueryBuilder<T>
execute
Type parameters
- T: QueryResult<{ id: number }> | EntityData<Partial<any>> | EntityData<Partial<any>>[] = EntityData<Partial<any>>[]
Parameters
queryOrKnex: string | Raw<any> | QueryBuilder<any, any>
params: any[] = []
method: get | all | run = 'all'
Returns Promise<T>
find
Finds all entities matching your
wherequery. You can pass additional options via theoptionsparameter.Type parameters
- Entity: object
- Hint: string = never
Parameters
entityName: EntityName<Entity>
where: FilterQuery<Entity>
options: FindOptions<Entity, Hint> = {}
Returns Promise<Loaded<Entity, Hint>[]>
findAndCount
Calls
em.find()andem.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
- Entity: object
- Hint: string = never
Parameters
entityName: EntityName<Entity>
where: FilterQuery<Entity>
options: FindOptions<Entity, Hint> = {}
Returns Promise<[Loaded<Entity, Hint>[], number]>
findOne
Finds first entity matching your
wherequery.Type parameters
- Entity: object
- Hint: string = never
Parameters
entityName: EntityName<Entity>
where: FilterQuery<Entity>
options: FindOneOptions<Entity, Hint> = {}
Returns Promise<null | Loaded<Entity, Hint>>
findOneOrFail
Finds first entity matching your
wherequery. If nothing found, it will throw an error. If thestrictoption is specified and nothing is found or more than one matching entity is found, it will throw an error. You can override the factory for creating this method viaoptions.failHandlerlocally or viaConfiguration.findOneOrFailHandler(findExactlyOneOrFailHandlerwhen specifyingstrict) globally.Type parameters
- Entity: object
- Hint: string = never
Parameters
entityName: EntityName<Entity>
where: FilterQuery<Entity>
options: FindOneOrFailOptions<Entity, Hint> = {}
Returns Promise<Loaded<Entity, Hint>>
flush
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>
fork
Returns new EntityManager instance with its own identity map
Parameters
options: ForkOptions = {}
Returns D[typeof EntityManagerType]
getComparator
Gets the EntityComparator.
Returns EntityComparator
getConnection
Gets the Connection instance, by default returns write connection
Parameters
optionaltype: ConnectionType
Returns ReturnType<D[getConnection]>
getDriver
Gets the Driver instance used by this EntityManager. Driver is singleton, for one MikroORM instance, only one driver is created.
Returns D
getEntityFactory
Gets the EntityFactory used by the EntityManager.
Returns EntityFactory
getEventManager
Returns EventManager
getFilterParams
Returns filter parameters for given filter set in this context.
Type parameters
- T: Dictionary = Dictionary
Parameters
name: string
Returns T
getHydrator
Gets the Hydrator used by the EntityManager.
Returns IHydrator
getKnex
Returns configured knex instance.
Parameters
optionaltype: ConnectionType
Returns Knex<any, any[]>
getMetadata
Gets the
MetadataStorage.Returns MetadataStorage
getPlatform
Gets the platform instance. Just like the driver, platform is singleton, one for a MikroORM instance.
Returns ReturnType<D[getPlatform]>
getReference
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
- Entity: object
- PK: string | number | symbol
Parameters
entityName: EntityName<Entity>
id: Primary<Entity>
options: Omit<GetReferenceOptions, wrapped> & { wrapped: true }
Returns Ref<Entity, PK>
getRepository
Gets repository for given entity. You can pass either string name or entity class reference.
Type parameters
- T: object
- U: EntityRepository<T, U> = SqlEntityRepository<T>
Parameters
entityName: EntityName<T>
Returns GetRepository<T, U>
getTransactionContext
Gets the transaction context (driver dependent object used to make sure queries are executed on same connection).
Type parameters
- T: unknown = any
Returns undefined | T
getUnitOfWork
Gets the UnitOfWork used by the EntityManager to coordinate operations.
Parameters
useContext: boolean = true
Returns UnitOfWork
getValidator
Gets EntityValidator instance
Returns EntityValidator
insert
Fires native insert query. Calling this has no side effects on the context (identity map).
Type parameters
- Entity: object
Parameters
entityNameOrEntity: Entity | EntityName<Entity>
optionaldata: Entity | EntityData<Entity>
options: NativeInsertUpdateOptions<Entity> = {}
Returns Promise<Primary<Entity>>
insertMany
Fires native multi-insert query. Calling this has no side effects on the context (identity map).
Type parameters
- Entity: object
Parameters
entityNameOrEntities: EntityName<Entity> | Entity[]
optionaldata: Entity[] | EntityData<Entity>[]
options: NativeInsertUpdateOptions<Entity> = {}
Returns Promise<Primary<Entity>[]>
isInTransaction
Checks whether this EntityManager is currently operating inside a database transaction.
Returns boolean
lock
Runs your callback wrapped inside a database transaction.
Type parameters
- T: object
Parameters
entity: T
lockMode: LockMode
options: number | Date | LockOptions = {}
Returns Promise<void>
map
Maps raw database result to an entity and merges it to this EntityManager.
Type parameters
- Entity: object
Parameters
entityName: EntityName<Entity>
result: EntityDictionary<Entity>
options: { schema?: string } = {}
optionalschema: string
Returns Entity
merge
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
- Entity: object
Parameters
entity: Entity
optionaloptions: MergeOptions
Returns Entity
nativeDelete
Fires native delete query. Calling this has no side effects on the context (identity map).
Type parameters
- Entity: object
Parameters
entityName: EntityName<Entity>
where: FilterQuery<Entity>
options: DeleteOptions<Entity> = {}
Returns Promise<number>
nativeInsert
alias for
em.insert()Type parameters
- Entity: object
Parameters
entityNameOrEntity: Entity | EntityName<Entity>
optionaldata: Entity | EntityData<Entity>
options: NativeInsertUpdateOptions<Entity> = {}
Returns Promise<Primary<Entity>>
nativeUpdate
Fires native update query. Calling this has no side effects on the context (identity map).
Type parameters
- Entity: object
Parameters
entityName: EntityName<Entity>
where: FilterQuery<Entity>
data: EntityData<Entity>
options: UpdateOptions<Entity> = {}
Returns Promise<number>
persist
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.
Type parameters
- Entity: object
Parameters
entity: Entity | Reference<Entity> | (Entity | Reference<Entity>)[]
Returns SqlEntityManager<D>
persistAndFlush
Persists your entity immediately, flushing all not yet persisted changes to the database too. Equivalent to
em.persist(e).flush().Parameters
entity: Partial<any> | Reference<Partial<any>> | (Partial<any> | Reference<Partial<any>>)[]
Returns Promise<void>
persistLater
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
entity: Partial<any> | Partial<any>[]
Returns void
populate
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
- Entity: object
- Hint: string = never
Parameters
entities: Entity | Entity[]
populate: boolean | (Hint extends any ? ((Hint & `${string}.`) extends never ? Hint : Hint & `${string}.`) extends Q ? Q extends `${A}.${B}` ? A extends StringKeys<Entity, never> ? `${A}.${B extends any ? ((B & `${string}.`) extends never ? B : B & `${string}.`) extends Q ? Q extends `${A}.${B}` ? A extends StringKeys<Exclude<GetStringKey<Entity, A, never>, undefined | null>, never> ? `${A}.${B extends any ? ((B & `${string}.`) extends never ? B : B & `${string}.`) extends Q ? Q extends `${A}.${B}` ? A extends StringKeys<Exclude<GetStringKey<Exclude<GetStringKey<Entity, A, never>, undefined | null>, A, never>, undefined | null>, never> ? `${A}.${B extends any ? ((B & `${string}.`) extends never ? B : B & `${string}.`) extends Q ? Q extends `${A}.${B}` ? A extends StringKeys<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Entity, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, never> ? `${A}.${B extends any ? ((B & `${string}.`) extends never ? B : B & `${string}.`) extends Q ? Q extends `${A}.${B}` ? A extends StringKeys<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Entity, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, never> ? `${A}.${B extends any ? ((B & `${string}.`) extends never ? B : B & `${string}.`) extends Q ? Q extends `${A}.${B}` ? A extends StringKeys<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Entity, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, never> ? `${A}.${string}` : never : Q extends StringKeys<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Entity, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, never> ? (Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Entity, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, Q, never>, undefined | null> extends unknown ? Exclude<B, `${string}.`> : never) | (StringKeys<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Entity, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, Q, never>, undefined | null>, never> extends never ? never : `${Q}.`) : StringKeys<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Entity, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, never> : never : never}` : never : Q extends StringKeys<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Entity, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, never> ? (Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Entity, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, Q, never>, undefined | null> extends unknown ? Exclude<B, `${string}.`> : never) | (StringKeys<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Entity, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, Q, never>, undefined | null>, never> extends never ? never : `${Q}.`) : StringKeys<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Entity, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, never> : never : never}` : never : Q extends StringKeys<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Entity, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, never> ? (Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Entity, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, Q, never>, undefined | null> extends unknown ? Exclude<B, `${string}.`> : never) | (StringKeys<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Entity, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, Q, never>, undefined | null>, never> extends never ? never : `${Q}.`) : StringKeys<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Entity, A, never>, undefined | null>, A, never>, undefined | null>, A, never>, undefined | null>, never> : never : never}` : never : Q extends StringKeys<Exclude<GetStringKey<Exclude<GetStringKey<Entity, A, never>, undefined | null>, A, never>, undefined | null>, never> ? (Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Entity, A, never>, undefined | null>, A, never>, undefined | null>, Q, never>, undefined | null> extends unknown ? Exclude<B, `${string}.`> : never) | (StringKeys<Exclude<GetStringKey<Exclude<GetStringKey<Exclude<GetStringKey<Entity, A, never>, undefined | null>, A, never>, undefined | null>, Q, never>, undefined | null>, never> extends never ? never : `${Q}.`) : StringKeys<Exclude<GetStringKey<Exclude<GetStringKey<Entity, A, never>, undefined | null>, A, never>, undefined | null>, never> : never : never}` : never : Q extends StringKeys<Exclude<GetStringKey<Entity, A, never>, undefined | null>, never> ? (Exclude<GetStringKey<Exclude<GetStringKey<Entity, A, never>, undefined | null>, Q, never>, undefined | null> extends unknown ? Exclude<B, `${string}.`> : never) | (StringKeys<Exclude<GetStringKey<Exclude<GetStringKey<Entity, A, never>, undefined | null>, Q, never>, undefined | null>, never> extends never ? never : `${Q}.`) : StringKeys<Exclude<GetStringKey<Entity, A, never>, undefined | null>, never> : never : never}` : never : Q extends StringKeys<Entity, never> ? (Exclude<GetStringKey<Entity, Q, never>, undefined | null> extends unknown ? Exclude<Hint, `${string}.`> : never) | (StringKeys<Exclude<GetStringKey<Entity, Q, never>, undefined | null>, never> extends never ? never : `${Q}.`) : StringKeys<Entity, never> : never : never)[]
options: EntityLoaderOptions<Entity, Hint> = {}
Returns Promise<Loaded<Entity, Hint>[]>
qb
Shortcut for
createQueryBuilder()Type parameters
- T: object
Parameters
entityName: EntityName<T>
optionalalias: string
optionaltype: ConnectionType
Returns QueryBuilder<T>
raw
Creates raw SQL query that won't be escaped when used as a parameter.
Type parameters
- R = Raw<any>
Parameters
sql: string
bindings: ValueDict | RawBinding[] = []
Returns R
refresh
Refreshes the persistent state of an entity from the database, overriding any local changes that have not yet been persisted.
Type parameters
- Entity: object
- Hint: string = never
Parameters
entity: Entity
options: FindOneOptions<Entity, Hint> = {}
Returns Promise<null | Loaded<Entity, Hint>>
remove
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
- Entity: object
Parameters
entity: Entity | Reference<Entity> | (Entity | Reference<Entity>)[]
Returns SqlEntityManager<D>
removeAndFlush
Removes an entity instance immediately, flushing all not yet persisted changes to the database too. Equivalent to
em.remove(e).flush()Parameters
entity: Partial<any> | Reference<Partial<any>>
Returns Promise<void>
removeLater
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.
Type parameters
- Entity: object
Parameters
entity: Entity
Returns void
repo
Shortcut for
em.getRepository().Type parameters
- Entity: object
- Repository: EntityRepository<Entity, Repository> = EntityRepository<Entity>
Parameters
entityName: EntityName<Entity>
Returns GetRepository<Entity, Repository>
resetTransactionContext
Resets the transaction context.
Returns void
rollback
Rollbacks the transaction bound to this EntityManager.
Returns Promise<void>
setFilterParams
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
name: string
args: Dictionary
Returns void
setFlushMode
Parameters
optionalflushMode: FlushMode
Returns void
setTransactionContext
Sets the transaction context.
Parameters
ctx: any
Returns void
transactional
Runs your callback wrapped inside a database transaction.
Type parameters
- T
Parameters
cb: (em: D[typeof EntityManagerType]) => Promise<T>
options: TransactionOptions = {}
Returns Promise<T>
upsert
Creates or updates the entity, based on whether it is already present in the database. This method performs an
insert on conflict mergequery ensuring the database is in sync, returning a managed entity instance. The method accepts eitherentityNametogether with the entitydata, or just entity instance.// insert into "author" ("age", "email") values (33, 'foo@bar.com') on conflict ("email") do update set "age" = 41
const author = await em.upsert(Author, { email: 'foo@bar.com', age: 33 });The entity data needs to contain either the primary key, or any other unique property. Let's consider the following example, where
Author.emailis a unique property:// insert into "author" ("age", "email") values (33, 'foo@bar.com') on conflict ("email") do update set "age" = 41
// select "id" from "author" where "email" = 'foo@bar.com'
const author = await em.upsert(Author, { email: 'foo@bar.com', age: 33 });Depending on the driver support, this will either use a returning query, or a separate select query, to fetch the primary key if it's missing from the
data.If the entity is already present in current context, there won't be any queries - instead, the entity data will be assigned and an explicit
flushwill be required for those changes to be persisted.Type parameters
- Entity: object
Parameters
entityNameOrEntity: Entity | EntityName<Entity>
optionaldata: Entity | EntityData<Entity>
options: UpsertOptions<Entity> = {}
Returns Promise<Entity>
upsertMany
Creates or updates the entity, based on whether it is already present in the database. This method performs an
insert on conflict mergequery ensuring the database is in sync, returning a managed entity instance. The method accepts eitherentityNametogether with the entitydata, or just entity instance.// insert into "author" ("age", "email") values (33, 'foo@bar.com') on conflict ("email") do update set "age" = 41
const authors = await em.upsertMany(Author, [{ email: 'foo@bar.com', age: 33 }, ...]);The entity data needs to contain either the primary key, or any other unique property. Let's consider the following example, where
Author.emailis a unique property:// insert into "author" ("age", "email") values (33, 'foo@bar.com'), (666, 'lol@lol.lol') on conflict ("email") do update set "age" = excluded."age"
// select "id" from "author" where "email" = 'foo@bar.com'
const author = await em.upsertMany(Author, [
{ email: 'foo@bar.com', age: 33 },
{ email: 'lol@lol.lol', age: 666 },
]);Depending on the driver support, this will either use a returning query, or a separate select query, to fetch the primary key if it's missing from the
data.If the entity is already present in current context, there won't be any queries - instead, the entity data will be assigned and an explicit
flushwill be required for those changes to be persisted.Type parameters
- Entity: object
Parameters
entityNameOrEntity: EntityName<Entity> | Entity[]
optionaldata: (Entity | EntityData<Entity>)[]
options: UpsertManyOptions<Entity> = {}
Returns Promise<Entity[]>
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.
driver type