Class QueryBuilder<TData, TVirtual, TInstance, TRelations>

constructor

• new QueryBuilder<
      TData extends JsonObject = JsonObject,
      TVirtual extends JsonObject = JsonObject,
      TInstance extends
          JsonObject & ModelInstanceCore<TData, TVirtual> = ModelInstance<
          TData,
          TVirtual,
      >,
      TRelations extends string = string,
  >(
      modelClass: QueryModel<TData, TVirtual, TInstance, TRelations>,
      dal: DataAccessLayer,
  ): QueryBuilder<TData, TVirtual, TInstance, TRelations>

  Type Parameters

  • TData extends JsonObject = JsonObject
  • TVirtual extends JsonObject = JsonObject
  • TInstance extends JsonObject & ModelInstanceCore<TData, TVirtual> = ModelInstance<TData, TVirtual>
  • TRelations extends string = string

  Parameters

  • modelClass: QueryModel<TData, TVirtual, TInstance, TRelations>
  • dal: DataAccessLayer

  Returns QueryBuilder<TData, TVirtual, TInstance, TRelations>

Optional_complexJoins

_includeSensitive

_joins

Optional_joinSpecs

_limit

_offset

_orderBy

_paramIndex

_params

_select

Optional_simpleJoins

_where

dal

modelClass

tableName

_aggregateFunction

• _aggregateFunction(
      func: "AVG" | "SUM" | "MIN" | "MAX",
      field: string,
  ): Promise<number>

  Compute an aggregate for the active query.

  Parameters

  • func: "AVG" | "SUM" | "MIN" | "MAX"

    SQL aggregate function identifier (e.g., AVG).
  • field: string

    Resolved field/column name to aggregate.

  Returns Promise<number>

  Numeric aggregate result or null when no rows match.

_analyzeJoinApply

• _analyzeJoinApply(applyFn: (qb: unknown) => unknown): JoinApplyAnalysis

  Parameters

  • applyFn: (qb: unknown) => unknown

  Returns JoinApplyAnalysis

_applyJoinFieldOmissions

• _applyJoinFieldOmissions(rows: any, fields: any): any

  Parameters

  • rows: any
  • fields: any

  Returns any

_assertResolvedField

• _assertResolvedField(field: string | symbol): string | symbol

  Parameters

  • field: string | symbol

  Returns string | symbol

_assignJoinResults

• _assignJoinResults(
      mainRows: Record<string, unknown>[],
      relationName: string,
      joinInfo: RelationJoinInfo,
      groupedRows: Map<unknown, Record<string, unknown>[]>,
  ): void

  Parameters

  • mainRows: Record<string, unknown>[]
  • relationName: string
  • joinInfo: RelationJoinInfo
  • groupedRows: Map<unknown, Record<string, unknown>[]>

  Returns void

_buildAggregateQuery

• _buildAggregateQuery(
      func: string,
      column: string,
  ): { params: any[]; sql: string }

  Build an aggregate query (AVG, COUNT, etc.) for the current predicates.

  Parameters

  • func: string

    Aggregate function keyword.
  • column: string

    Fully qualified column expression.

  Returns { params: any[]; sql: string }

  SQL fragment plus bound params.

_buildComplexJoinQuery

• _buildComplexJoinQuery(
      relationName: any,
      joinInfo: any,
      sourceValues: any,
      analysis?: any,
  ): { joinSourceAlias: string; params: unknown[]; query: string }

  Parameters

  • relationName: any
  • joinInfo: any
  • sourceValues: any
  • analysis: any = null

  Returns { joinSourceAlias: string; params: unknown[]; query: string }

_buildWhereClause

• _buildWhereClause(
      __namedParameters?: { qualifyColumns?: boolean },
  ): { params: any[]; sql: string }

  Parameters

  • __namedParameters: { qualifyColumns?: boolean } = {}

  Returns { params: any[]; sql: string }

_extractJoinSourceValues

• _extractJoinSourceValues(
      mainRows: Record<string, unknown>[],
      sourceColumn: string,
  ): unknown[]

  Parameters

  • mainRows: Record<string, unknown>[]
  • sourceColumn: string

  Returns unknown[]

_getModelRegistry

• _getModelRegistry(): {
      get(
          identifier: string,
      ): ModelConstructor<JsonObject, JsonObject, ModelInstance, string> & typeof Model;
  }

  Returns {
      get(
          identifier: string,
      ): ModelConstructor<JsonObject, JsonObject, ModelInstance, string> & typeof Model;
  }

_getRowValue

• _getRowValue(row: Record<string, unknown> | ModelInstance, column: string): any

  Parameters

  • row: Record<string, unknown> | ModelInstance
  • column: string

  Returns any

_groupRelatedRows

• _groupRelatedRows(
      rows: Record<string, unknown>[],
      joinSourceAlias?: string,
  ): Map<unknown, Record<string, unknown>[]>

  Parameters

  • rows: Record<string, unknown>[]
  • joinSourceAlias: string = '_join_source_id'

  Returns Map<unknown, Record<string, unknown>[]>

_isRevisionFilterPredicate

• _isRevisionFilterPredicate(predicate: any): boolean

  Parameters

  • predicate: any

  Returns boolean

_normalizeColumnName

• _normalizeColumnName(field: any): any

  Parameters

  • field: any

  Returns any

_qualifyColumn

• _qualifyColumn(predicate: any, context: any): any

  Parameters

  • predicate: any
  • context: any

  Returns any

_renderBasicPredicate

• _renderBasicPredicate(predicate: any, context: any): string

  Parameters

  • predicate: any
  • context: any

  Returns string

_renderPredicate

• _renderPredicate(predicate: any, context: any): any

  Parameters

  • predicate: any
  • context: any

  Returns any

_resolvePredicateColumn

• _resolvePredicateColumn(tableReference: any, column: any): any

  Parameters

  • tableReference: any
  • column: any

  Returns any

_resolveTableReference

• _resolveTableReference(tableRef: any): string

  Parameters

  • tableRef: any

  Returns string

_splitFieldReference

• _splitFieldReference(
      field: any,
  ): { column: any; table: any } | { column: string; table: string }

  Parameters

  • field: any

  Returns { column: any; table: any } | { column: string; table: string }

average

• average(field: string): Promise<number>

  Calculate the average for a column.

  Parameters

  • field: string

    Column to aggregate.

  Returns Promise<number>

  Numeric average or null when no rows satisfy the predicates.

between

• between(
      startDate: string | number | Date,
      endDate: string | number | Date,
      options?: BetweenOptions,
  ): this

  Filter by date range

  Parameters

  • startDate: string | number | Date

    Start date
  • endDate: string | number | Date

    End date
  • options: BetweenOptions = {}

    Options (leftBound, rightBound)

  Returns this

  This instance for chaining

catch

• catch<TResult = never>(
      onRejected?: (reason: unknown) => TResult | PromiseLike<TResult>,
  ): Promise<TInstance[] | TResult>

  Catch handler for Promise-like usage

  Type Parameters

  • TResult = never

  Parameters

  • OptionalonRejected: (reason: unknown) => TResult | PromiseLike<TResult>

    Error handler

  Returns Promise<TInstance[] | TResult>

  Promise resolving to query results

contains

• contains(field: string, value: unknown): this

  Filter by array contains (for PostgreSQL arrays)

  Parameters

  • field: string

    Field name
  • value: unknown

    Value to check for

  Returns this

  This instance for chaining

containsJsonb

• containsJsonb(field: string, value: JsonObject): this

  Filter by JSONB field contains

  Parameters

  • field: string

    JSONB field name
  • value: JsonObject

    Value to check for

  Returns this

  This instance for chaining

count

• count(): Promise<number>

  Execute query and return count

  Returns Promise<number>

  Result count

delete

• delete(): Promise<number>

  Delete records matching the query

  Returns Promise<number>

  Delete result

deleteById

• deleteById(id: string): Promise<number>

  Delete a record by ID

  Parameters

  • id: string

    Record ID

  Returns Promise<number>

  Delete result

filterByRevisionDateRange

• filterByRevisionDateRange(
      startDate: any,
      endDate: any,
  ): QueryBuilder<TData, TVirtual, TInstance, TRelations>

  Filter by revision date range

  Parameters

  • startDate: any

    Start date (inclusive)
  • endDate: any

    End date (inclusive)

  Returns QueryBuilder<TData, TVirtual, TInstance, TRelations>

  This instance for chaining

filterByRevisionTags

• filterByRevisionTags(
      tags: any,
  ): QueryBuilder<TData, TVirtual, TInstance, TRelations>

  Filter by revision tags

  Parameters

  • tags: any

    Tag or array of tags to filter by

  Returns QueryBuilder<TData, TVirtual, TInstance, TRelations>

  This instance for chaining

filterByRevisionUser

• filterByRevisionUser(
      userId: any,
  ): QueryBuilder<TData, TVirtual, TInstance, TRelations>

  Filter by revision user

  Parameters

  • userId: any

    User ID who created the revision

  Returns QueryBuilder<TData, TVirtual, TInstance, TRelations>

  This instance for chaining

finally

• finally(onFinally?: () => void): Promise<TInstance[]>

  Finally handler for Promise-like usage

  Parameters

  • OptionalonFinally: () => void

    Finally handler

  Returns Promise<TInstance[]>

  Promise resolving to query results

first

• first(): Promise<TInstance>

  Execute query and return first result

  Returns Promise<TInstance>

  First result or null

getAllRevisions

• getAllRevisions(
      documentId: any,
  ): QueryBuilder<TData, TVirtual, TInstance, TRelations>

  Get all revisions of a specific document (including old and deleted)

  Parameters

  • documentId: any

    The document ID to get revisions for

  Returns QueryBuilder<TData, TVirtual, TInstance, TRelations>

  This instance for chaining

getJoin

• getJoin(joinSpec: any): QueryBuilder<TData, TVirtual, TInstance, TRelations>

  Add JOIN clauses with support for complex joins

  Parameters

  • joinSpec: any

    Join specification

  Returns QueryBuilder<TData, TVirtual, TInstance, TRelations>

  This instance for chaining

hasFields

• hasFields(field: string, key: string): this

  Filter by field existence in JSONB

  Parameters

  • field: string

    JSONB field name
  • key: string

    Key to check for existence

  Returns this

  This instance for chaining

includeSensitive

• includeSensitive(fields: string | string[]): this

  Include sensitive fields in query results

  Parameters

  • fields: string | string[]

    Array of sensitive field names to include

  Returns this

  This instance for chaining

increment

• increment<TRow extends JsonObject = JsonObject>(
      field: string,
      amount?: number,
      options?: { returning?: string[] },
  ): Promise<IncrementResult<TRow>>

  Atomically increment a numeric column on rows matching the current predicate.

  Type Parameters

  • TRow extends JsonObject = JsonObject

  Parameters

  • field: string

    Model field (resolved to a DB column) to increment
  • amount: number = 1

    Increment step (default: 1)
  • options: { returning?: string[] } = {}

    Optional returning clause

  Returns Promise<IncrementResult<TRow>>

  Rows matched/returned plus affected row count.

limit

• limit(count: any): QueryBuilder<TData, TVirtual, TInstance, TRelations>

  Add LIMIT clause

  Parameters

  • count: any

    Limit count

  Returns QueryBuilder<TData, TVirtual, TInstance, TRelations>

  This instance for chaining

offset

• offset(count: any): QueryBuilder<TData, TVirtual, TInstance, TRelations>

  Add OFFSET clause

  Parameters

  • count: any

    Offset count

  Returns QueryBuilder<TData, TVirtual, TInstance, TRelations>

  This instance for chaining

orderBy

• orderBy(
      field: any,
      direction?: string,
  ): QueryBuilder<TData, TVirtual, TInstance, TRelations>

  Add ORDER BY clause

  Parameters

  • field: any

    Field to order by
  • direction: string = 'ASC'

    Sort direction (ASC/DESC)

  Returns QueryBuilder<TData, TVirtual, TInstance, TRelations>

  This instance for chaining

orderByRelation

• orderByRelation(
      relationName: string,
      field: string,
      direction?: string,
  ): QueryBuilder<TData, TVirtual, TInstance, TRelations>

  Parameters

  • relationName: string
  • field: string
  • direction: string = 'ASC'

  Returns QueryBuilder<TData, TVirtual, TInstance, TRelations>

run

• run(): Promise<TInstance[]>

  Execute query and return all results

  Returns Promise<TInstance[]>

  Query results

sample

• sample(count?: number): Promise<TInstance[]>

  Get a random sample of records

  Parameters

  • count: number = 1

    Number of records to sample

  Returns Promise<TInstance[]>

  Array of sampled records

then

• then<TResult1 = TInstance[], TResult2 = never>(
      onFulfilled?: (value: TInstance[]) => TResult1 | PromiseLike<TResult1>,
      onRejected?: (reason: unknown) => TResult2 | PromiseLike<TResult2>,
  ): Promise<TResult1 | TResult2>

  Allow QueryBuilder to behave like a Promise (basic thenable)

  Type Parameters

  • TResult1 = TInstance[]
  • TResult2 = never

  Parameters

  • OptionalonFulfilled: (value: TInstance[]) => TResult1 | PromiseLike<TResult1>

    Success handler
  • OptionalonRejected: (reason: unknown) => TResult2 | PromiseLike<TResult2>

    Error handler

  Returns Promise<TResult1 | TResult2>

  Promise resolving to query results

whereIn

• whereIn(field: string, values: unknown[], options?: { cast?: string }): this

  Filter by membership in a list of values using PostgreSQL ANY

  Parameters

  • field: string

    Field name
  • values: unknown[]

    Values to match
  • Optionaloptions: { cast?: string } = {}

    Additional options

    • Optionalcast?: string

      Optional cast to apply to the parameter (e.g., 'uuid[]')

  Returns this

  This instance for chaining

whereRelated

• whereRelated(
      relationName: string,
      field: string,
      operator: string,
      value: unknown,
  ): this

  Add a predicate against a column on a joined relation. This will ensure the relation is joined and apply a WHERE clause to the related table using camelCase field names.

  Parameters

  • relationName: string

    Relation key from the manifest
  • field: string

    CamelCase field on the related model
  • operator: string

    Comparison operator (defaults to '=')
  • value: unknown

    Comparison value

  Returns this