QueryBuilder <Entity, RootAlias, Hint, Context, RawAliases, Fields>

SQL query builder with fluent interface.

const qb = orm.em.createQueryBuilder(Publisher);
qb.select('*')
  .where({
    name: 'test 123',
    type: PublisherType.GLOBAL,
  })
  .orderBy({
    name: QueryOrder.DESC,
    type: QueryOrder.ASC,
  })
  .limit(2, 1);

const publisher = await qb.getSingleResult();

Hierarchy

• QueryBuilder
  • SelectQueryBuilder
  • CountQueryBuilder

Implements

• Subquery

Index

Properties

• __subquery

Accessors

• alias
• helper
• mainAlias
• type

Methods

• addSelect
• andHaving
• andOrderBy
• andWhere
• applyFilters
• as
• cache
• clone
• comment
• count
• delete
• distinct
• distinctOn
• execute
• from
• getCount
• getFormattedQuery
• getLoggerContext
• getNativeQuery
• getParams
• getQuery
• getResult
• getResultAndCount
• getResultList
• getSingleResult
• groupBy
• hasFlag
• having
• hintComment
• ignore
• indexHint
• innerJoin
• innerJoinAndSelect
• innerJoinLateral
• innerJoinLateralAndSelect
• insert
• join
• joinAndSelect
• leftJoin
• leftJoinAndSelect
• leftJoinLateral
• leftJoinLateralAndSelect
• limit
• merge
• offset
• onConflict
• orderBy
• orHaving
• orWhere
• returning
• select
• setFlag
• setFlushMode
• setLockMode
• setLoggerContext
• stream
• toQuery
• toRaw
• truncate
• unsetFlag
• update
• where
• withSchema
• withSubQuery

Properties

readonly__subquery

__subquery: true

Implementation of Subquery.__subquery

Accessors

alias

• get alias(): string

• Returns string

helper

• get helper(): QueryBuilderHelper

• Returns QueryBuilderHelper

mainAlias

• get mainAlias(): Alias<Entity>

• Returns Alias<Entity>

type

• get type(): QueryType

• Returns QueryType

Methods

addSelect

• addSelect<F>(fields): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases | ExtractRawAliases<F extends readonly unknown[] ? F<F> : [F]>, Fields | ExtractRootFields<F extends readonly U[] ? U & string : F & string, RootAlias, Context>>

• Adds fields to an existing SELECT query.

  ---

  Parameters

  • fields: F

  Returns SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases | ExtractRawAliases<F extends readonly unknown[] ? F<F> : [F]>, Fields | ExtractRootFields<F extends readonly U[] ? U & string : F & string, RootAlias, Context>>

andHaving

• andHaving(cond, params): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

• Parameters

  • optionalcond: string | QBFilterQuery<Entity, RootAlias, Context, RawAliases>

  • optionalparams: any[]

  Returns SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

andOrderBy

• andOrderBy(orderBy): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>
• andOrderBy<T>(orderBy): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

• Adds additional ORDER BY clause without replacing existing order.

  ---

  Parameters

  • orderBy: ContextOrderByMap<Entity, RootAlias, Context> | ContextOrderByMap<Entity, RootAlias, Context>[]

  Returns SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

andWhere

• andWhere(cond): this
• andWhere(cond, params): this

• Adds an AND WHERE clause to the query using an object condition.

  @example

  qb.where({ status: 'active' }).andWhere({ role: 'admin' });
  qb.where({ name: 'John' }).andWhere({ 'b.title': 'test' });

  ---

  Parameters

  • cond: QBFilterQuery<Entity, RootAlias, Context, RawAliases>

  Returns this

applyFilters

• applyFilters(filterOptions): Promise<void>

• Apply filters to the QB where condition.

  ---

  Parameters

  • filterOptions: FilterOptions = {}

  Returns Promise<void>

as

• as(alias): NativeQueryBuilder
• as<T>(targetEntity, alias): NativeQueryBuilder

• Returns native query builder instance with sub-query aliased with given alias.

  ---

  Parameters

  • alias: string

  Returns NativeQueryBuilder

cache

• cache(config): this

• Parameters

  • config: number | boolean | [string, number] = true

  Returns this

clone

• clone(reset, preserve): QueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

• Parameters

  • optionalreset: boolean | string[]

  • optionalpreserve: string[]

  Returns QueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

comment

• comment(comment): this

• Prepend comment to the sql query using the syntax /* ... *‍/. Some characters are forbidden such as /*, *‍/ and ?.

  ---

  Parameters

  • comment: undefined | string | string[]

  Returns this

count

• count<F>(field, distinct): CountQueryBuilder<Entity>

• Creates a COUNT query to count matching rows.

  @example

  const count = await em.createQueryBuilder(User)
    .count()
    .where({ isActive: true })
    .execute('get');

  ---

  Parameters

  • optionalfield: F | F[]

  • distinct: boolean = false

  Returns CountQueryBuilder<Entity>

delete

• delete(cond): DeleteQueryBuilder<Entity, RootAlias, Context>

• Creates a DELETE query. Use where() to specify which rows to delete.

  @example

  await em.createQueryBuilder(User)
    .delete()
    .where({ id: 1 })
    .execute();
  
  // Or pass the condition directly
  await em.createQueryBuilder(User)
    .delete({ isActive: false })
    .execute();

  ---

  Parameters

  • optionalcond: QBFilterQuery<Entity, RootAlias, Context, RawAliases>

  Returns DeleteQueryBuilder<Entity, RootAlias, Context>

distinct

• distinct(): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

• Returns SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

distinctOn

• distinctOn<F>(fields): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>
• distinctOn<F>(fields): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

• postgres only

  ---

  Parameters

  • fields: F

  Returns SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

execute

• execute<U>(method, options): Promise<U>

• Executes this QB and returns the raw results, mapped to the property names (unless disabled via last parameter). Use method to specify what kind of result you want to get (array/single/meta).

  ---

  Parameters

  • optionalmethod: get | all | run

  • optionaloptions: boolean | ExecuteOptions

  Returns Promise<U>

from

• from<Entity>(target, aliasName): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>
• from<Entity>(target): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

• Specifies FROM which entity's table select/update/delete will be executed, removing all previously set FROM-s. Allows setting a main string alias of the selection data.

  ---

  Parameters

  • target: QueryBuilder<Entity, never, never, never, never, *>

  • optionalaliasName: string

  Returns SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

getCount

• getCount<F>(field, distinct): Promise<number>

• Executes count query (without offset and limit), returning total count of results

  ---

  Parameters

  • optionalfield: F | F[]

  • optionaldistinct: boolean

  Returns Promise<number>

getFormattedQuery

• getFormattedQuery(): string

• Returns raw interpolated query string with all the parameters inlined.

  ---

  Returns string

getLoggerContext

• getLoggerContext<T>(): T

• Gets logger context for this query builder.

  ---

  Returns T

getNativeQuery

• getNativeQuery(processVirtualEntity): NativeQueryBuilder

• Parameters

  • processVirtualEntity: boolean = true

  Returns NativeQueryBuilder

getParams

• getParams(): readonly unknown[]

• Returns the list of all parameters for this query.

  ---

  Returns readonly unknown[]

getQuery

• getQuery(): string

• Returns the query with parameters as wildcards.

  ---

  Returns string

getResult

• getResult(): Promise<Loaded<Entity, Hint, Fields>[]>

• Alias for qb.getResultList()

  ---

  Returns Promise<Loaded<Entity, Hint, Fields>[]>

getResultAndCount

• getResultAndCount(): Promise<[Loaded<Entity, Hint, Fields>[], number]>

• Executes the query, returning both array of results and total count query (without offset and limit).

  ---

  Returns Promise<[Loaded<Entity, Hint, Fields>[], number]>

getResultList

• getResultList(limit): Promise<Loaded<Entity, Hint, Fields>[]>

• Executes the query, returning array of results mapped to entity instances.

  ---

  Parameters

  • optionallimit: number

  Returns Promise<Loaded<Entity, Hint, Fields>[]>

getSingleResult

• getSingleResult(): Promise<null | Loaded<Entity, Hint, Fields>>

• Executes the query, returning the first result or null

  ---

  Returns Promise<null | Loaded<Entity, Hint, Fields>>

groupBy

• groupBy<F>(fields): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>
• groupBy<F>(fields): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>
• groupBy<P>(fields): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

• Adds a GROUP BY clause to the query.

  @example

  qb.select([raw('count(*) as count'), 'status'])
    .groupBy('status');

  ---

  Parameters

  • fields: F

  Returns SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

hasFlag

• hasFlag(flag): boolean

• Parameters

  • flag: QueryFlag

  Returns boolean

having

• having(cond, params, operator): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

• Adds a HAVING clause to the query, typically used with GROUP BY.

  @example

  qb.select([raw('count(*) as count'), 'status'])
    .groupBy('status')
    .having({ count: { $gt: 5 } });

  ---

  Parameters

  • cond: string | QBFilterQuery<Entity, RootAlias, Context, RawAliases> = {}

  • optionalparams: any[]

  • optionaloperator: $and | $or

  Returns SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

hintComment

• hintComment(comment): this

• Add hints to the query using comment-like syntax /*+ ... *‍/. MySQL and Oracle use this syntax for optimizer hints. Also various DB proxies and routers use this syntax to pass hints to alter their behavior. In other dialects the hints are ignored as simple comments.

  ---

  Parameters

  • comment: undefined | string | string[]

  Returns this

ignore

• ignore(): this

• Returns this

indexHint

• indexHint(sql): this

• Adds index hint to the FROM clause.

  ---

  Parameters

  • sql: undefined | string

  Returns this

innerJoin

• innerJoin<Field, Alias>(field, alias, cond, schema): SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, Field, Alias, false>, RawAliases, *>
• innerJoin<Alias>(field, alias, cond, schema): SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, string, Alias, false>, RawAliases, *>

• Adds an INNER JOIN clause to the query for an entity relation.

  ---

  Parameters

  • field: Field

  • alias: Alias

  • optionalcond: JoinCondition<ExpandProperty<GetType<Entity, Context, Field>[GetPropName<Field> & keyof GetType<Entity, Context, Field>]>, Alias>

  • optionalschema: string

  Returns SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, Field, Alias, false>, RawAliases, *>

innerJoinAndSelect

• innerJoinAndSelect<Field, Alias, JoinFields>(field, alias, cond, fields, schema): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>, RawAliases, ModifyFields<Fields, RootAlias, Context, Field, Alias, JoinFields>>

• Parameters

  • field: Field | [Field, RawQueryFragment<string> | QueryBuilder<any, never, never, never, never, *>]

  • alias: Alias

  • cond: JoinCondition<ExpandProperty<GetType<Entity, Context, Field>[GetPropName<Field> & keyof GetType<Entity, Context, Field>]>, Alias> = ...

  • optionalfields: JoinFields

  • optionalschema: string

  Returns SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>, RawAliases, ModifyFields<Fields, RootAlias, Context, Field, Alias, JoinFields>>

innerJoinLateral

• innerJoinLateral<Alias>(field, alias, cond, schema): SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, string, Alias, false>, RawAliases, *>

• Parameters

  • field: RawQueryFragment<string> | QueryBuilder<any, never, never, never, never, *>

  • alias: Alias

  • cond: RawJoinCondition = {}

  • optionalschema: string

  Returns SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, string, Alias, false>, RawAliases, *>

innerJoinLateralAndSelect

• innerJoinLateralAndSelect<Field, Alias, JoinFields>(field, alias, cond, fields, schema): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>, RawAliases, ModifyFields<Fields, RootAlias, Context, Field, Alias, JoinFields>>

• Parameters

  • field: [Field, RawQueryFragment<string> | QueryBuilder<any, never, never, never, never, *>]

  • alias: Alias

  • cond: JoinCondition<ExpandProperty<GetType<Entity, Context, Field>[GetPropName<Field> & keyof GetType<Entity, Context, Field>]>, Alias> = ...

  • optionalfields: JoinFields

  • optionalschema: string

  Returns SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>, RawAliases, ModifyFields<Fields, RootAlias, Context, Field, Alias, JoinFields>>

insert

• insert(data): InsertQueryBuilder<Entity, RootAlias, Context>

• Creates an INSERT query with the given data.

  @example

  await em.createQueryBuilder(User)
    .insert({ name: 'John', email: 'john@example.com' })
    .execute();
  
  // Bulk insert
  await em.createQueryBuilder(User)
    .insert([{ name: 'John' }, { name: 'Jane' }])
    .execute();

  ---

  Parameters

  • data: RequiredEntityData<Entity> | RequiredEntityData<Entity>[]

  Returns InsertQueryBuilder<Entity, RootAlias, Context>

join

• join<Field, Alias>(field, alias, cond, type, path, schema): SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, Field, Alias, false>, RawAliases, *>
• join<Alias>(field, alias, cond, type, path, schema): SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, string, Alias, false>, RawAliases, *>

• Adds a JOIN clause to the query for an entity relation.

  @example

  const qb = em.createQueryBuilder(Book, 'b');
  qb.select('*')
    .join('b.author', 'a')
    .where({ 'a.name': 'John' });

  ---

  Parameters

  • field: Field

  • alias: Alias

  • optionalcond: JoinCondition<ExpandProperty<GetType<Entity, Context, Field>[GetPropName<Field> & keyof GetType<Entity, Context, Field>]>, Alias>

  • optionaltype: JoinType

  • optionalpath: string

  • optionalschema: string

  Returns SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, Field, Alias, false>, RawAliases, *>

joinAndSelect

• joinAndSelect<Field, Alias, JoinFields>(field, alias, cond, type, path, fields, schema): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>, RawAliases, ModifyFields<Fields, RootAlias, Context, Field, Alias, JoinFields>>

• Adds a JOIN clause and automatically selects the joined entity's fields. This is useful for eager loading related entities.

  @example

  const qb = em.createQueryBuilder(Book, 'b');
  qb.select('*')
    .joinAndSelect('b.author', 'a')
    .where({ 'a.name': 'John' });

  ---

  Parameters

  • field: Field | [Field, RawQueryFragment<string> | QueryBuilder<any, never, never, never, never, *>]

  • alias: Alias

  • cond: JoinCondition<ExpandProperty<GetType<Entity, Context, Field>[GetPropName<Field> & keyof GetType<Entity, Context, Field>]>, Alias> = ...

  • type: JoinType = JoinType.innerJoin

  • optionalpath: string

  • optionalfields: JoinFields

  • optionalschema: string

  Returns SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>, RawAliases, ModifyFields<Fields, RootAlias, Context, Field, Alias, JoinFields>>

leftJoin

• leftJoin<Field, Alias>(field, alias, cond, schema): SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, Field, Alias, false>, RawAliases, *>
• leftJoin<Alias>(field, alias, cond, schema): SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, string, Alias, false>, RawAliases, *>

• Adds a LEFT JOIN clause to the query for an entity relation.

  ---

  Parameters

  • field: Field

  • alias: Alias

  • optionalcond: JoinCondition<ExpandProperty<GetType<Entity, Context, Field>[GetPropName<Field> & keyof GetType<Entity, Context, Field>]>, Alias>

  • optionalschema: string

  Returns SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, Field, Alias, false>, RawAliases, *>

leftJoinAndSelect

• leftJoinAndSelect<Field, Alias, JoinFields>(field, alias, cond, fields, schema): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>, RawAliases, ModifyFields<Fields, RootAlias, Context, Field, Alias, JoinFields>>

• Parameters

  • field: Field | [Field, RawQueryFragment<string> | QueryBuilder<any, never, never, never, never, *>]

  • alias: Alias

  • cond: JoinCondition<ExpandProperty<GetType<Entity, Context, Field>[GetPropName<Field> & keyof GetType<Entity, Context, Field>]>, Alias> = ...

  • optionalfields: JoinFields

  • optionalschema: string

  Returns SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>, RawAliases, ModifyFields<Fields, RootAlias, Context, Field, Alias, JoinFields>>

leftJoinLateral

• leftJoinLateral<Alias>(field, alias, cond, schema): SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, string, Alias, false>, RawAliases, *>

• Parameters

  • field: RawQueryFragment<string> | QueryBuilder<any, never, never, never, never, *>

  • alias: Alias

  • cond: RawJoinCondition = {}

  • optionalschema: string

  Returns SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, string, Alias, false>, RawAliases, *>

leftJoinLateralAndSelect

• leftJoinLateralAndSelect<Field, Alias, JoinFields>(field, alias, cond, fields, schema): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>, RawAliases, ModifyFields<Fields, RootAlias, Context, Field, Alias, JoinFields>>

• Parameters

  • field: [Field, RawQueryFragment<string> | QueryBuilder<any, never, never, never, never, *>]

  • alias: Alias

  • cond: JoinCondition<ExpandProperty<GetType<Entity, Context, Field>[GetPropName<Field> & keyof GetType<Entity, Context, Field>]>, Alias> = ...

  • optionalfields: JoinFields

  • optionalschema: string

  Returns SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>, RawAliases, ModifyFields<Fields, RootAlias, Context, Field, Alias, JoinFields>>

limit

• limit(limit, offset): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

• Sets a LIMIT clause to restrict the number of results.

  @example

  qb.select('*').limit(10);        // First 10 results
  qb.select('*').limit(10, 20);    // 10 results starting from offset 20

  ---

  Parameters

  • optionallimit: number

  • offset: number = 0

  Returns SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

merge

• merge<P>(data): this
• merge<F>(data): this

• Parameters

  • data: readonly NestedAutoPath<Entity, RootAlias, Context, P>[]

  Returns this

offset

• offset(offset): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

• Sets an OFFSET clause to skip a number of results.

  @example

  qb.select('*').limit(10).offset(20);  // Results 21-30

  ---

  Parameters

  • optionaloffset: number

  Returns SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

onConflict

• onConflict<F>(fields): InsertQueryBuilder<Entity, RootAlias, Context>

• Parameters

  • fields: RawQueryFragment<string> | F | F[] = ...

  Returns InsertQueryBuilder<Entity, RootAlias, Context>

orderBy

• orderBy(orderBy): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>
• orderBy<T>(orderBy): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

• Adds an ORDER BY clause to the query, replacing any existing order.

  @example

  qb.orderBy({ name: 'asc', createdAt: 'desc' });
  qb.orderBy([{ name: 'asc' }, { createdAt: 'desc' }]);
  qb.orderBy({ profile: { bio: 'asc' } }); // nested via object
  qb.orderBy({ 'profile.bio': 'asc' }); // nested via dot notation

  ---

  Parameters

  • orderBy: ContextOrderByMap<Entity, RootAlias, Context> | ContextOrderByMap<Entity, RootAlias, Context>[]

  Returns SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

orHaving

• orHaving(cond, params): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

• Parameters

  • optionalcond: string | QBFilterQuery<Entity, RootAlias, Context, RawAliases>

  • optionalparams: any[]

  Returns SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>

orWhere

• orWhere(cond): this
• orWhere(cond, params): this

• Adds an OR WHERE clause to the query using an object condition.

  @example

  qb.where({ status: 'active' }).orWhere({ role: 'admin' });
  qb.where({ name: 'John' }).orWhere({ name: 'Jane' });

  ---

  Parameters

  • cond: QBFilterQuery<Entity, RootAlias, Context, RawAliases>

  Returns this

returning

• returning<F>(fields): this

• Parameters

  • optionalfields: F | F[]

  Returns this

select

• select<F>(fields, distinct): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases | ExtractRawAliases<F>, ExtractRootFields<F[number] & string, RootAlias, Context>>
• select<P>(fields, distinct): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, ExtractRootFields<P, RootAlias, Context>>
• select<P>(fields, distinct): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, ExtractRootFields<P, RootAlias, Context>>
• select<F>(fields, distinct): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases | ExtractRawAliasFromField<F>, ExtractRootFields<F & string, RootAlias, Context>>

• Creates a SELECT query, specifying the fields to retrieve.

  @example

  // Select specific fields
  const qb = em.createQueryBuilder(User, 'u');
  qb.select(['u.id', 'u.name', 'u.email']);
  
  // Select with raw expressions
  qb.select([raw('count(*) as total')]);
  
  // Select with distinct
  qb.select('*', true);

  ---

  Parameters

  • fields: F

  • optionaldistinct: boolean

  Returns SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases | ExtractRawAliases<F>, ExtractRootFields<F[number] & string, RootAlias, Context>>

setFlag

• setFlag(flag): this

• Parameters

  • flag: QueryFlag

  Returns this

setFlushMode

• setFlushMode(flushMode): this

• Parameters

  • optionalflushMode: FlushMode

  Returns this

setLockMode

• setLockMode(mode, tables): this

• Parameters

  • optionalmode: LockMode

  • optionaltables: string[]

  Returns this

setLoggerContext

• setLoggerContext(context): void

• Sets logger context for this query builder.

  ---

  Parameters

  • context: LoggingOptions & Dictionary

  Returns void

stream

• stream(options): AsyncIterableIterator<Loaded<Entity, Hint, Fields>, any, any>

• Executes the query and returns an async iterable (async generator) that yields results one by one. By default, the results are merged and mapped to entity instances, without adding them to the identity map. You can disable merging and mapping by passing the options { mergeResults: false, mapResults: false }. This is useful for processing large datasets without loading everything into memory at once.

  const qb = em.createQueryBuilder(Book, 'b');
  qb.select('*').where({ title: '1984' }).leftJoinAndSelect('b.author', 'a');
  
  for await (const book of qb.stream()) {
    // book is an instance of Book entity
    console.log(book.title, book.author.name);
  }

  ---

  Parameters

  • optionaloptions: QBStreamOptions

  Returns AsyncIterableIterator<Loaded<Entity, Hint, Fields>, any, any>

toQuery

• toQuery(): { params: readonly unknown[]; sql: string }

• Returns { params: readonly unknown[]; sql: string }

  • params: readonly unknown[]

  • sql: string

toRaw

• toRaw(): RawQueryFragment<string>

• Returns raw fragment representation of this QueryBuilder.

  ---

  Returns RawQueryFragment<string>

truncate

• truncate(): TruncateQueryBuilder<Entity>

• Creates a TRUNCATE query to remove all rows from the table.

  ---

  Returns TruncateQueryBuilder<Entity>

unsetFlag

• unsetFlag(flag): this

• Parameters

  • flag: QueryFlag

  Returns this

update

• update(data): UpdateQueryBuilder<Entity, RootAlias, Context>

• Creates an UPDATE query with the given data. Use where() to specify which rows to update.

  @example

  await em.createQueryBuilder(User)
    .update({ name: 'John Doe' })
    .where({ id: 1 })
    .execute();

  ---

  Parameters

  • data: EntityData<Entity>

  Returns UpdateQueryBuilder<Entity, RootAlias, Context>

where

• where(cond, operator): this
• where(cond, params, operator): this

• Adds a WHERE clause to the query using an object condition.

  Supports filtering by:

  • Direct entity properties: { name: 'John' }
  • Nested relations/embedded: { author: { name: 'John' } }
  • Aliased properties after joins: { 'a.name': 'John' } or { 'b.title': 'test' }
  • Filter operators: { age: { $gte: 18 } }
  • Logical operators: { $or: [{ name: 'John' }, { name: 'Jane' }] }

  @example

  // Filter by entity properties
  qb.where({ name: 'John', age: { $gte: 18 } });
  
  // Filter by nested relation
  qb.where({ author: { name: 'John' } });
  
  // Filter by aliased properties after join
  qb.leftJoin('a.books', 'b').where({ 'b.title': 'test' });
  
  // Combine with logical operators
  qb.where({ $or: [{ status: 'active' }, { role: 'admin' }] });

  ---

  Parameters

  • cond: QBFilterQuery<Entity, RootAlias, Context, RawAliases>

  • optionaloperator: $and | $or

  Returns this

withSchema

• withSchema(schema): this

• Parameters

  • optionalschema: string

  Returns this

withSubQuery

• withSubQuery(subQuery, alias): this

• Parameters

  • subQuery: RawQueryFragment<string> | NativeQueryBuilder

  • alias: string

  Returns this