Skip to main content

QJoinQueryBuilder

@quik/database

@quik/database / QJoinQueryBuilder

Class: QJoinQueryBuilder<TModel, TResult>

Defined in: database/src/repository/QJoinQueryBuilder.ts:62

Fluent builder for queries that join across tables not necessarily declared as @Relations on the base model, and that return a result shape other than the base model — any plain @Entity()-decorated class.

Unlike QQueryBuilder, this builder does not derive joins from relation metadata or force column selection; it's a thin, typed wrapper around Knex's own join/where/select/groupBy/having, reusing QWhereBuilder for conditions. Field names should be fully qualified as table.column when the query spans more than one table; see Field for a typo-checked way to build those strings.

Obtain an instance via QRepository.joinQuery.

Example​

class ProjectTeamMemberRepository extends QRepository<ProjectTeamMember> {
  async findActiveMembership(projectId: number, userId: number, date: DateTime) {
    return this.joinQuery(ActiveMembershipRow)
      .join('ProjectTeam', 'ProjectTeam.id', 'ProjectTeamMember.projectTeamId')
      .where(QWhereBuilder.New()
        .Equal('ProjectTeam.projectId', projectId)
        .And(
          Conditions.Equal('ProjectTeamMember.userId', userId),
          Conditions.LessThanOrEqual('ProjectTeamMember.startDate', date),
          (group) => group.Or(
            Conditions.IsNull('ProjectTeamMember.endDate'),
            Conditions.GreaterThanOrEqual('ProjectTeamMember.endDate', date)
          )
        ))
      .select('ProjectTeamMember.*')
      .first();
  }
}

Extends​

  • QObject

Type Parameters​

TModel​

TModel extends QModel

The base model the query starts from.

TResult​

TResult extends QEntity

The @Entity()-decorated shape rows are mapped into.

Constructors​

Constructor​

new QJoinQueryBuilder<TModel, TResult>(queryBuilder, entity, resultEntity): QJoinQueryBuilder<TModel, TResult>

Defined in: database/src/repository/QJoinQueryBuilder.ts:70

Creates a new join query builder.

Parameters​

queryBuilder​

QueryBuilder

Knex query builder already scoped to the base model's table.

entity​

TModel

Base model instance, used to resolve unqualified field names in .where()/.having().

resultEntity​

Constructor<TResult>

Constructor for the entity rows are mapped into.

Returns​

QJoinQueryBuilder<TModel, TResult>

Overrides​

QObject.constructor

Properties​

_entity​

protected _entity: TModel

Defined in: database/src/repository/QJoinQueryBuilder.ts:78

_queryBuilder​

protected _queryBuilder: QueryBuilder

Defined in: database/src/repository/QJoinQueryBuilder.ts:77

_resultEntity​

protected _resultEntity: Constructor<TResult>

Defined in: database/src/repository/QJoinQueryBuilder.ts:79

Accessors​

logger​

Get Signature​

get protected logger(): IQLogger

Defined in: core/src/QObject.ts:15

The logger getter for the object.

Returns​

IQLogger

Inherited from​

QObject.logger

name​

Get Signature​

get name(): string

Defined in: core/src/QObject.ts:8

Returns​

string

Inherited from​

QObject.name

Methods​

applyJoin()​

protected applyJoin(kind, table, first, operatorOrSecond?, second?): this

Defined in: database/src/repository/QJoinQueryBuilder.ts:91

Applies a join of the given kind, accepting either a (first, operator?, second) condition or a Knex join callback for multi-condition ON clauses.

Parameters​

kind​

QJoinKind

Join type to apply.

table​

string

Table to join.

first​

string | JoinCallback

Left-hand column, or a join callback for a multi-condition ON clause.

operatorOrSecond?​

string

Comparison operator, or the right-hand column when omitting the operator.

second?​

string

Right-hand column of the join condition, when an operator is provided.

Returns​

this

endSpan()​

protected endSpan(span): void

Defined in: core/src/QObject.ts:35

End a span returned by startSpan.

Parameters​

span​

TelemetrySpan

The span to end.

Returns​

void

Inherited from​

QObject.endSpan

first()​

first(): Promise<TResult>

Defined in: database/src/repository/QJoinQueryBuilder.ts:270

Executes the query and returns the first matching row mapped to TResult, or undefined when no row matches. Terminal method — consumes the underlying query builder.

Returns​

Promise<TResult>

fullOuterJoin()​

Call Signature​

fullOuterJoin(table, callback): this

Defined in: database/src/repository/QJoinQueryBuilder.ts:174

Adds a full outer join.

Parameters​
table​

string

Table to join.

callback​

JoinCallback

Join callback for a multi-condition ON clause.

Returns​

this

Call Signature​

fullOuterJoin(table, first, second): this

Defined in: database/src/repository/QJoinQueryBuilder.ts:175

Adds a full outer join.

Parameters​
table​

string

Table to join.

first​

string

second​

string

Returns​

this

Call Signature​

fullOuterJoin(table, first, operator, second): this

Defined in: database/src/repository/QJoinQueryBuilder.ts:176

Adds a full outer join.

Parameters​
table​

string

Table to join.

first​

string

operator​

string

second​

string

Returns​

this

get()​

get(): Promise<TResult[]>

Defined in: database/src/repository/QJoinQueryBuilder.ts:282

Executes the query and returns all matching rows mapped to TResult. Terminal method — consumes the underlying query builder.

Returns​

Promise<TResult[]>

groupBy()​

groupBy(...columns): this

Defined in: database/src/repository/QJoinQueryBuilder.ts:230

Adds a GROUP BY clause.

Parameters​

columns​

...string[]

Fully-qualified table.column columns to group by.

Returns​

this

having()​

having(havingBuilder): this

Defined in: database/src/repository/QJoinQueryBuilder.ts:199

Applies a QWhereBuilder's conditions as a HAVING clause, typically used after groupBy to filter on aggregate results.

Parameters​

havingBuilder​

QWhereBuilder

Conditions to apply; use fully-qualified table.column field names.

Returns​

this

See​

QQueryBuilder.applyHaving

innerJoin()​

Call Signature​

innerJoin(table, callback): this

Defined in: database/src/repository/QJoinQueryBuilder.ts:135

Alias for join.

Parameters​
table​

string

callback​

JoinCallback

Returns​

this

Call Signature​

innerJoin(table, first, second): this

Defined in: database/src/repository/QJoinQueryBuilder.ts:136

Alias for join.

Parameters​
table​

string

first​

string

second​

string

Returns​

this

Call Signature​

innerJoin(table, first, operator, second): this

Defined in: database/src/repository/QJoinQueryBuilder.ts:137

Alias for join.

Parameters​
table​

string

first​

string

operator​

string

second​

string

Returns​

this

join()​

Call Signature​

join(table, callback): this

Defined in: database/src/repository/QJoinQueryBuilder.ts:110

Adds an inner join.

Parameters​
table​

string

Table to join.

callback​

JoinCallback

Join callback for a multi-condition ON clause.

Returns​

this

Call Signature​

join(table, first, second): this

Defined in: database/src/repository/QJoinQueryBuilder.ts:118

Adds an inner join.

Parameters​
table​

string

Table to join.

first​

string

Left-hand column of the join condition.

second​

string

Right-hand column of the join condition (implicit = operator).

Returns​

this

Call Signature​

join(table, first, operator, second): this

Defined in: database/src/repository/QJoinQueryBuilder.ts:127

Adds an inner join.

Parameters​
table​

string

Table to join.

first​

string

Left-hand column of the join condition.

operator​

string

Comparison operator.

second​

string

Right-hand column of the join condition.

Returns​

this

leftJoin()​

Call Signature​

leftJoin(table, callback): this

Defined in: database/src/repository/QJoinQueryBuilder.ts:148

Adds a left join.

Parameters​
table​

string

Table to join.

callback​

JoinCallback

Join callback for a multi-condition ON clause.

Returns​

this

Call Signature​

leftJoin(table, first, second): this

Defined in: database/src/repository/QJoinQueryBuilder.ts:149

Adds a left join.

Parameters​
table​

string

Table to join.

first​

string

second​

string

Returns​

this

Call Signature​

leftJoin(table, first, operator, second): this

Defined in: database/src/repository/QJoinQueryBuilder.ts:150

Adds a left join.

Parameters​
table​

string

Table to join.

first​

string

operator​

string

second​

string

Returns​

this

limit()​

limit(count): this

Defined in: database/src/repository/QJoinQueryBuilder.ts:251

Limits the number of returned rows.

Parameters​

count​

number

Maximum number of rows.

Returns​

this

offset()​

offset(count): this

Defined in: database/src/repository/QJoinQueryBuilder.ts:261

Skips a number of rows.

Parameters​

count​

number

Number of rows to skip.

Returns​

this

orderBy()​

orderBy(column, direction?): this

Defined in: database/src/repository/QJoinQueryBuilder.ts:241

Adds an ORDER BY clause.

Parameters​

column​

string

Fully-qualified table.column to sort by.

direction?​

"asc" | "desc"

Sort direction. Defaults to asc.

Returns​

this

recordSpanError()​

protected recordSpanError(span, err): void

Defined in: core/src/QObject.ts:45

Record an exception on an active span.

Parameters​

span​

TelemetrySpan

The span to record the error on.

err​

unknown

The error to record.

Returns​

void

Inherited from​

QObject.recordSpanError

rightJoin()​

Call Signature​

rightJoin(table, callback): this

Defined in: database/src/repository/QJoinQueryBuilder.ts:161

Adds a right join.

Parameters​
table​

string

Table to join.

callback​

JoinCallback

Join callback for a multi-condition ON clause.

Returns​

this

Call Signature​

rightJoin(table, first, second): this

Defined in: database/src/repository/QJoinQueryBuilder.ts:162

Adds a right join.

Parameters​
table​

string

Table to join.

first​

string

second​

string

Returns​

this

Call Signature​

rightJoin(table, first, operator, second): this

Defined in: database/src/repository/QJoinQueryBuilder.ts:163

Adds a right join.

Parameters​
table​

string

Table to join.

first​

string

operator​

string

second​

string

Returns​

this

select()​

select(...columns): this

Defined in: database/src/repository/QJoinQueryBuilder.ts:214

Selects columns. Accepts fully-qualified table.column/table.* strings, { field, as } pairs to alias a plain column onto a specific result field (useful when the SQL column name doesn't already match the result entity's field name), or a Knex.Raw expression for aggregates (e.g. this.knex.raw('COUNT(??) as ??', [...]).

{ field, as } quotes field as a single identifier — it is not safe for aggregate/function expressions such as COUNT(x); use Knex.Raw for those instead.

Parameters​

columns​

...QJoinSelectOption[]

Columns to select.

Returns​

this

setSpanAttribute()​

protected setSpanAttribute(span, key, value): void

Defined in: core/src/QObject.ts:64

Set a single attribute on an active span.

Parameters​

span​

TelemetrySpan

The span to update.

key​

string

Attribute key.

value​

string | number | boolean

Attribute value.

Returns​

void

Inherited from​

QObject.setSpanAttribute

startSpan()​

protected startSpan(spanName, options?): TelemetrySpan

Defined in: core/src/QObject.ts:26

Start a telemetry span for the given operation name. Returns undefined when no telemetry provider is active.

Parameters​

spanName​

string

Name of the span.

options?​

TelemetrySpanOptions

Optional span attributes and kind.

Returns​

TelemetrySpan

Inherited from​

QObject.startSpan

where()​

where(whereBuilder): this

Defined in: database/src/repository/QJoinQueryBuilder.ts:187

Applies a QWhereBuilder's conditions to the query.

Parameters​

whereBuilder​

QWhereBuilder

Conditions to apply; use fully-qualified table.column field names.

Returns​

this

See​

QQueryBuilder.applyWhere