Kysoql
ReferenceAPI referenceInterfaces

SelectQueryBuilder

Generated API reference for SelectQueryBuilder in @kysoql/core.

@kysoql/core / SelectQueryBuilder

Type-safe fluent builder for Salesforce SELECT queries.

Type Parameters

Type ParameterDefault type
DB-
TB extends keyof DB-
O-
Mode extends SelectQueryModeSelectQueryMode

Methods

$call()

$call<T>(func): T;

Passes this builder to func and returns the callback result.

Type Parameters

Type Parameter
T

Parameters

ParameterType
func(qb) => T

Returns

T

$assertType()

$assertType<T>(): O extends T ? SelectQueryBuilder<DB, TB, T, Mode> : KysoqlTypeError<"$assertType() call failed: The type passed in is not equal to the output type of the query.">;

Asserts at compile time that the current query output exactly matches T.

Type Parameters

Type Parameter
T

Returns

O extends T ? SelectQueryBuilder<DB, TB, T, Mode> : KysoqlTypeError<"$assertType() call failed: The type passed in is not equal to the output type of the query.">

$castTo()

$castTo<C>(): SelectQueryBuilder<DB, TB, C, Mode>;

Changes only the TypeScript output type; the generated SOQL is unchanged.

Type Parameters

Type Parameter
C

Returns

SelectQueryBuilder<DB, TB, C, Mode>

$narrowType()

$narrowType<T>(): SelectQueryBuilder<DB, TB, NarrowPartial<O, T>, Mode>;

Narrows selected output properties at the type level without changing SOQL.

Type Parameters

Type Parameter
T

Returns

SelectQueryBuilder<DB, TB, NarrowPartial<O, T>, Mode>

$if()

$if<O2>(condition, func): SelectQueryBuilder<DB, TB, ConditionalOutput<O, O2>, Mode>;

Conditionally applies a builder callback; when false, the runtime query is unchanged.

Type Parameters

Type Parameter
O2

Parameters

ParameterType
conditionboolean
func(qb) => SelectQueryBuilder<DB, TB, O & O2, Mode>

Returns

SelectQueryBuilder<DB, TB, ConditionalOutput<O, O2>, Mode>

clearLimit()

clearLimit(): SelectQueryBuilder<DB, TB, O, Mode>;

Returns a builder with the LIMIT clause removed.

Returns

SelectQueryBuilder<DB, TB, O, Mode>

clearOffset()

clearOffset(): SelectQueryBuilder<DB, TB, O, Mode>;

Returns a builder with the OFFSET clause removed.

Returns

SelectQueryBuilder<DB, TB, O, Mode>

clearOrderBy()

clearOrderBy(): SelectQueryBuilder<DB, TB, O, Mode>;

Returns a builder with all ORDER BY items removed.

Returns

SelectQueryBuilder<DB, TB, O, Mode>

clearSelect()

clearSelect(): SelectQueryBuilder<DB, TB, unknown, "plain">;

Returns a builder with all current selections removed.

Returns

SelectQueryBuilder<DB, TB, unknown, "plain">

clearWhere()

clearWhere(): SelectQueryBuilder<DB, TB, O, Mode>;

Returns a builder with the WHERE predicate removed.

Returns

SelectQueryBuilder<DB, TB, O, Mode>

compile()

compile(): CompiledQuery<O>;

Compiles the current operation tree into a CompiledQuery.

Returns

CompiledQuery<O>

execute()

execute(options?): Promise<readonly O[]>;

Compiles and executes the query with the configured executor.

Parameters

ParameterType
options?AbortableQueryOptions

Returns

Promise<readonly O[]>

executeTakeFirst()

executeTakeFirst(options?): Promise<O | undefined>;

Executes the query and returns the first row, or undefined when no rows match.

Parameters

ParameterType
options?AbortableQueryOptions

Returns

Promise<O | undefined>

executeTakeFirstOrThrow()

executeTakeFirstOrThrow(options?): Promise<O>;

Executes the query and returns the first row, throwing when no rows match.

Parameters

ParameterType
options?| ExecuteTakeFirstOrThrowOptions | NoResultErrorConstructor | ((node) => Error)

Returns

Promise<O>

executeAll()

executeAll(options?): Promise<readonly O[]>;

Executes with the executor's Salesforce query-all semantics.

Parameters

ParameterType
options?AbortableQueryOptions

Returns

Promise<readonly O[]>

apex()

apex(): ApexSelectQueryBuilder<DB, TB, O, Mode, "static">;

Switches to the static Apex builder for the current query.

Returns

ApexSelectQueryBuilder<DB, TB, O, Mode, "static">

dynamicApex()

dynamicApex(): ApexSelectQueryBuilder<DB, TB, O, Mode, "dynamic">;

Switches to the dynamic Apex builder for the current query.

Returns

ApexSelectQueryBuilder<DB, TB, O, Mode, "dynamic">

limit()

limit(limit): SelectQueryBuilder<DB, TB, O, Mode>;

Adds or replaces the SOQL LIMIT clause.

Parameters

ParameterType
limitnumber

Returns

SelectQueryBuilder<DB, TB, O, Mode>

offset()

offset(offset): SelectQueryBuilder<DB, TB, O, Mode>;

Adds or replaces the SOQL OFFSET clause.

Parameters

ParameterType
offsetnumber

Returns

SelectQueryBuilder<DB, TB, O, Mode>

groupBy()

Call Signature

groupBy<GE>(field): AggregateSelectQueryBuilder<DB, TB, O, GE, "ordinary", 0>;

Adds a GROUP BY expression and enters aggregate-query mode.

Type Parameters
Type Parameter
GE extends string
Parameters
ParameterType
fieldUnselectedOnly<O, GE & GroupableFieldName<DB, TB, GE>>
Returns

AggregateSelectQueryBuilder<DB, TB, O, GE, "ordinary", 0>

Call Signature

groupBy<GE>(fields): AggregateSelectQueryBuilder<DB, TB, O, GE, "ordinary", 0>;

Adds a GROUP BY expression and enters aggregate-query mode.

Type Parameters
Type Parameter
GE extends string
Parameters
ParameterType
fieldsUnselectedOnly<O, readonly GE & GroupableFieldName<DB, TB, GE>[]>
Returns

AggregateSelectQueryBuilder<DB, TB, O, GE, "ordinary", 0>

Call Signature

groupBy<Expression>(expression): AggregateSelectQueryBuilder<DB, TB, O, DateFunctionIdentityOf<Expression>, "ordinary", 0>;

Adds a GROUP BY expression and enters aggregate-query mode.

Type Parameters
Type Parameter
Expression extends DateFunctionExpression<unknown, unknown, ComparisonOperator, string>
Parameters
ParameterType
expressionUnselectedOnly<O, (eb) => Expression>
Returns

AggregateSelectQueryBuilder<DB, TB, O, DateFunctionIdentityOf<Expression>, "ordinary", 0>

forView()

forView(..._mruCheck): SelectQueryBuilder<DB, TB, O, Mode>;

Adds FOR VIEW; available only for MRU-enabled objects.

Parameters

ParameterType
..._mruCheckSalesforceObjectMruEnabled<DB[TB]> extends false ? readonly [never] : readonly []

Returns

SelectQueryBuilder<DB, TB, O, Mode>

forReference()

forReference(..._mruCheck): SelectQueryBuilder<DB, TB, O, Mode>;

Adds FOR REFERENCE; available only for MRU-enabled objects.

Parameters

ParameterType
..._mruCheckSalesforceObjectMruEnabled<DB[TB]> extends false ? readonly [never] : readonly []

Returns

SelectQueryBuilder<DB, TB, O, Mode>

updateTracking()

updateTracking(..._knowledgeArticleCheck): SelectQueryBuilder<DB, TB, O, Mode>;

Adds the KnowledgeArticle UPDATE TRACKING clause.

Parameters

ParameterType
..._knowledgeArticleCheckKnowledgeArticleUpdateCheck<TB>

Returns

SelectQueryBuilder<DB, TB, O, Mode>

updateViewstat()

updateViewstat(..._knowledgeArticleCheck): SelectQueryBuilder<DB, TB, O, Mode>;

Adds the KnowledgeArticle UPDATE VIEWSTAT clause.

Parameters

ParameterType
..._knowledgeArticleCheckKnowledgeArticleUpdateCheck<TB>

Returns

SelectQueryBuilder<DB, TB, O, Mode>

usingScope()

usingScope(scope): SelectQueryBuilder<DB, TB, O, Mode>;

Adds a Salesforce USING SCOPE clause validated against schema metadata.

Parameters

ParameterType
scopeSalesforceObjectSupportedScope<DB[TB]>

Returns

SelectQueryBuilder<DB, TB, O, Mode>

withUserId()

withUserId(userId, ..._userProfileFeedCheck): SelectQueryBuilder<DB, TB, O, Mode>;

Adds the UserProfileFeed WITH USER_ID clause.

Parameters

ParameterType
userIdstring
..._userProfileFeedCheckUserProfileFeedWithUserIdCheck<TB>

Returns

SelectQueryBuilder<DB, TB, O, Mode>

withRecordVisibilityContext()

withRecordVisibilityContext(parameters): SelectQueryBuilder<DB, TB, O, Mode>;

Adds WITH RECORD_VISIBILITY_CONTEXT options.

Parameters

ParameterType
parametersRecordVisibilityContextOptions

Returns

SelectQueryBuilder<DB, TB, O, Mode>

setOptions()

setOptions(options): SelectQueryBuilder<DB, TB, O, Mode>;

Adds object-specific Salesforce SET OPTIONS values.

Parameters

ParameterType
optionsData360SetOptionsFor<DB[TB]>

Returns

SelectQueryBuilder<DB, TB, O, Mode>

withDataCategory()

withDataCategory<Group>(
   group,
   selector,
   categories
): SelectQueryBuilder<DB, TB, O, Mode>;

Adds a typed WITH DATA CATEGORY filter.

Type Parameters

Type Parameter
Group extends never

Parameters

ParameterType
groupGroup
selectorDataCategorySelector
categoriesDataCategoryInput<SalesforceObjectDataCategory<DB[TB], Group>>

Returns

SelectQueryBuilder<DB, TB, O, Mode>

orderBy()

Call Signature

orderBy(
   expression,
   direction?,
   nulls?
): SelectQueryBuilder<DB, TB, O, Mode>;

Adds a typed ORDER BY item.

Parameters
ParameterType
expressionSoqlRawBuilder
direction?OrderByDirection
nulls?OrderByNulls
Returns

SelectQueryBuilder<DB, TB, O, Mode>

Call Signature

orderBy(
   expression,
   direction?,
   nulls?
): SelectQueryBuilder<DB, TB, O, Mode>;

Adds a typed ORDER BY item.

Parameters
ParameterType
expressionDistanceOrderByFactory<DB, TB>
direction?OrderByDirection
nulls?OrderByNulls
Returns

SelectQueryBuilder<DB, TB, O, Mode>

Call Signature

orderBy<OE>(
   field,
   direction?,
   nulls?
): SelectQueryBuilder<DB, TB, O, Mode>;

Adds a typed ORDER BY item.

Type Parameters
Type Parameter
OE extends string
Parameters
ParameterType
fieldOE & SortableFieldName<DB, TB, OE>
direction?OrderByDirection
nulls?OrderByNullsForReference<DB, TB, OE>
Returns

SelectQueryBuilder<DB, TB, O, Mode>

where()

Call Signature

where(expression): SelectQueryBuilder<DB, TB, O, Mode>;

Adds a typed WHERE predicate and combines it with any existing predicate using AND.

Parameters
ParameterType
expressionSoqlRawBuilder
Returns

SelectQueryBuilder<DB, TB, O, Mode>

Call Signature

where(expression): SelectQueryBuilder<DB, TB, O, Mode>;

Adds a typed WHERE predicate and combines it with any existing predicate using AND.

Parameters
ParameterType
expressionWhereExpressionFactory<DB, TB>
Returns

SelectQueryBuilder<DB, TB, O, Mode>

Call Signature

where<RE, OP, RHS>(
   lhs,
   op,
   rhs
): SelectQueryBuilder<DB, TB, O, Mode>;

Adds a typed WHERE predicate and combines it with any existing predicate using AND.

Type Parameters
Type Parameter
RE extends string
OP extends | "=" | "!=" | OrderedComparisonOperator | "in" | "not in" | MultiSelectComparisonOperator | "like"
RHS
Parameters
ParameterType
lhsRE & FilterableFieldName<DB, TB, RE>
opOP
rhsRHS
Returns

SelectQueryBuilder<DB, TB, O, Mode>

select()

Call Signature

select<RawOutput>(selection): SelectQueryBuilder<DB, TB, O & RawOutput, Mode>;

Adds one or more typed selections to the query output.

Type Parameters
Type Parameter
RawOutput
Parameters
ParameterType
selectionSoqlRawBuilder<RawOutput>
Returns

SelectQueryBuilder<DB, TB, O & RawOutput, Mode>

Call Signature

select(selection): CountQueryBuilder<DB, TB>;

Adds one or more typed selections to the query output.

Parameters
ParameterType
selectionUnselectedOnly<O, CountSelectionFactory<DB, TB>>
Returns

CountQueryBuilder<DB, TB>

Call Signature

select<FunctionSelection>(selection): SelectQueryBuilder<DB, TB, O & SelectFunctionSelection<FunctionSelection>, AfterSelectFunctionMode<Mode>>;

Adds one or more typed selections to the query output.

Type Parameters
Type Parameter
FunctionSelection extends SelectFunctionSelectionArg
Parameters
ParameterType
selectionSelectFunctionFactoryForMode<Mode, SelectFunctionSelectionFactory<DB, TB, FunctionSelection>>
Returns

SelectQueryBuilder<DB, TB, O & SelectFunctionSelection<FunctionSelection>, AfterSelectFunctionMode<Mode>>

Call Signature

select<Aggregate>(selection): AggregateSelectQueryBuilder<DB, TB, AggregateSelection<Aggregate>>;

Adds one or more typed selections to the query output.

Type Parameters
Type Parameter
Aggregate extends AggregateSelectionArg
Parameters
ParameterType
selectionUnselectedOnly<O, AggregateSelectionFactory<DB, TB, Aggregate>>
Returns

AggregateSelectQueryBuilder<DB, TB, AggregateSelection<Aggregate>>

Call Signature

select<Selections>(selections): SelectQueryBuilder<DB, TB, O & Selection<DB, TB, Selections[number]>, Mode>;

Adds one or more typed selections to the query output.

Type Parameters
Type Parameter
Selections extends readonly string[]
Parameters
ParameterType
selectionsSelections & CheckedSelectExpressionList<DB, TB, O, Selections>
Returns

SelectQueryBuilder<DB, TB, O & Selection<DB, TB, Selections[number]>, Mode>

Call Signature

select<SE>(selection): SelectQueryBuilder<DB, TB, O & Selection<DB, TB, SE>, Mode>;

Adds one or more typed selections to the query output.

Type Parameters
Type Parameter
SE extends string
Parameters
ParameterType
selectionSE & SelectExpression<DB, TB, SE> & AvailableSelectExpression<DB, TB, O, SE>
Returns

SelectQueryBuilder<DB, TB, O & Selection<DB, TB, SE>, Mode>

selectFields()

selectFields<Selector>(selector, ...check): SelectQueryBuilder<DB, TB, O & FieldsSelection<DB, TB, Selector>, Mode>;

Select a server-expanded group; unavailable on field-filtered schemas.

Type Parameters

Type Parameter
Selector extends FieldsSelector

Parameters

ParameterType
selectorSelector
...checkFieldsSelectionCheck<DB, TB, O, Selector>

Returns

SelectQueryBuilder<DB, TB, O & FieldsSelection<DB, TB, Selector>, Mode>

selectTypeOf()

selectTypeOf<Reference, Builder>(
   reference,
   callback,
   ..._modeCheck
): SelectQueryBuilder<DB, TB, O & TypeOfSelection<DB, TB, Reference, TypeOfValue<PolymorphicRelationshipTargets<DB, TB, Reference>, Builder>>, AfterTypeOfMode<Mode>>;

Adds a typed TYPEOF selection for a polymorphic relationship.

Type Parameters

Type Parameter
Reference extends string
Builder extends CompletedTypeOfBuilder

Parameters

ParameterType
referenceReference & PolymorphicRelationshipReference<DB, TB, Reference> & AvailableTypeOfReference<O, Reference>
callback(typeOf) => Builder
..._modeCheckTypeOfModeCheck<Mode>

Returns

SelectQueryBuilder<DB, TB, O & TypeOfSelection<DB, TB, Reference, TypeOfValue<PolymorphicRelationshipTargets<DB, TB, Reference>, Builder>>, AfterTypeOfMode<Mode>>

selectSubquery()

selectSubquery<Relationship, SubqueryOutput, SubqueryFunctionMode>(relationship, callback): SelectQueryBuilder<DB, TB, O & { readonly [Key in string]: SalesforceQueryResult<Simplify<SubqueryOutput>> }, AfterSubqueryMode<Mode, SubqueryFunctionMode>>;

Adds a typed child-relationship subquery selection.

Type Parameters

Type Parameter
Relationship extends string
SubqueryOutput
SubqueryFunctionMode extends "none" | "present" | "forbidden"

Parameters

ParameterType
relationshipRelationship & ChildRelationshipReference<DB, TB, Relationship>
callback(query) => RelationshipSubqueryBuilder<DB, ChildObjectName<DB, TB, Extract<Relationship, ChildRelationshipName<DB, TB>>>, SubqueryOutput, readonly [unknown], SubqueryFunctionMode>

Returns

SelectQueryBuilder<DB, TB, O & { readonly [Key in string]: SalesforceQueryResult<Simplify<SubqueryOutput>> }, AfterSubqueryMode<Mode, SubqueryFunctionMode>>

toOperationNode()

toOperationNode(): SelectQueryNode;

Returns the immutable operation node represented by this builder.

Returns

SelectQueryNode

SelectionNode

Generated API reference for SelectionNode in @kysoql/core.

SelectQueryBuilderProps

Generated API reference for SelectQueryBuilderProps in @kysoql/core.

On this page

Type ParametersMethods$call()Type ParametersParametersReturns$assertType()Type ParametersReturns$castTo()Type ParametersReturns$narrowType()Type ParametersReturns$if()Type ParametersParametersReturnsclearLimit()ReturnsclearOffset()ReturnsclearOrderBy()ReturnsclearSelect()ReturnsclearWhere()Returnscompile()Returnsexecute()ParametersReturnsexecuteTakeFirst()ParametersReturnsexecuteTakeFirstOrThrow()ParametersReturnsexecuteAll()ParametersReturnsapex()ReturnsdynamicApex()Returnslimit()ParametersReturnsoffset()ParametersReturnsgroupBy()Call SignatureCall SignatureCall SignatureforView()ParametersReturnsforReference()ParametersReturnsupdateTracking()ParametersReturnsupdateViewstat()ParametersReturnsusingScope()ParametersReturnswithUserId()ParametersReturnswithRecordVisibilityContext()ParametersReturnssetOptions()ParametersReturnswithDataCategory()Type ParametersParametersReturnsorderBy()Call SignatureCall SignatureCall Signaturewhere()Call SignatureCall SignatureCall Signatureselect()Call SignatureCall SignatureCall SignatureCall SignatureCall SignatureCall SignatureselectFields()Type ParametersParametersReturnsselectTypeOf()Type ParametersParametersReturnsselectSubquery()Type ParametersParametersReturnstoOperationNode()Returns