# RelationshipSubqueryBuilder (/docs/core/reference/api/interfaces/RelationshipSubqueryBuilder)



[@kysoql/core](/docs/core/reference/api) / RelationshipSubqueryBuilder

Type-safe builder for a Salesforce child relationship subquery.

## Type Parameters [#type-parameters]

| Type Parameter                                              | Default type          |
| ----------------------------------------------------------- | --------------------- |
| `DB`                                                        | -                     |
| `TB` *extends* keyof `DB`                                   | -                     |
| `O`                                                         | -                     |
| `Depth` *extends* `ParentToChildDepth`                      | readonly \[`unknown`] |
| `FunctionMode` *extends* `RelationshipSubqueryFunctionMode` | `"none"`              |
| `ApexMode` *extends* `boolean`                              | `false`               |

## Methods [#methods]

<a id="api-call" />

### $call() [#call]

```ts
$call<T>(func): T;
```

Passes this builder to `func` and returns the callback result.

#### Type Parameters [#type-parameters-1]

| Type Parameter |
| -------------- |
| `T`            |

#### Parameters [#parameters]

| Parameter | Type          |
| --------- | ------------- |
| `func`    | (`qb`) => `T` |

#### Returns [#returns]

`T`

***

<a id="api-asserttype" />

### $assertType() [#asserttype]

```ts
$assertType<T>(): O extends T ? RelationshipSubqueryBuilder<DB, TB, T, Depth, FunctionMode, ApexMode> : 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-parameters-2]

| Type Parameter |
| -------------- |
| `T`            |

#### Returns [#returns-1]

`O` *extends* `T` ? `RelationshipSubqueryBuilder`\<`DB`, `TB`, `T`, `Depth`, `FunctionMode`, `ApexMode`> : [`KysoqlTypeError`](/docs/core/reference/api/interfaces/KysoqlTypeError)\<`"$assertType() call failed: The type passed in is not equal to the output type of the query."`>

***

<a id="api-castto" />

### $castTo() [#castto]

```ts
$castTo<C>(): RelationshipSubqueryBuilder<DB, TB, C, Depth, FunctionMode, ApexMode>;
```

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

#### Type Parameters [#type-parameters-3]

| Type Parameter |
| -------------- |
| `C`            |

#### Returns [#returns-2]

`RelationshipSubqueryBuilder`\<`DB`, `TB`, `C`, `Depth`, `FunctionMode`, `ApexMode`>

***

<a id="api-narrowtype" />

### $narrowType() [#narrowtype]

```ts
$narrowType<T>(): RelationshipSubqueryBuilder<DB, TB, NarrowPartial<O, T>, Depth, FunctionMode, ApexMode>;
```

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

#### Type Parameters [#type-parameters-4]

| Type Parameter |
| -------------- |
| `T`            |

#### Returns [#returns-3]

`RelationshipSubqueryBuilder`\<`DB`, `TB`, [`NarrowPartial`](/docs/core/reference/api/type-aliases/NarrowPartial)\<`O`, `T`>, `Depth`, `FunctionMode`, `ApexMode`>

***

<a id="api-if" />

### $if() [#if]

```ts
$if<O2>(condition, func): RelationshipSubqueryBuilder<DB, TB, ConditionalOutput<O, O2>, Depth, FunctionMode, ApexMode>;
```

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

#### Type Parameters [#type-parameters-5]

| Type Parameter |
| -------------- |
| `O2`           |

#### Parameters [#parameters-1]

| Parameter   | Type                                                                                                  |
| ----------- | ----------------------------------------------------------------------------------------------------- |
| `condition` | `boolean`                                                                                             |
| `func`      | (`qb`) => `RelationshipSubqueryBuilder`\<`DB`, `TB`, `O` & `O2`, `Depth`, `FunctionMode`, `ApexMode`> |

#### Returns [#returns-4]

`RelationshipSubqueryBuilder`\<`DB`, `TB`, `ConditionalOutput`\<`O`, `O2`>, `Depth`, `FunctionMode`, `ApexMode`>

***

<a id="api-clearlimit" />

### clearLimit() [#clearlimit]

```ts
clearLimit(): RelationshipSubqueryBuilder<DB, TB, O, Depth, FunctionMode, ApexMode>;
```

Returns a builder with the `LIMIT` clause removed.

#### Returns [#returns-5]

`RelationshipSubqueryBuilder`\<`DB`, `TB`, `O`, `Depth`, `FunctionMode`, `ApexMode`>

***

<a id="api-clearorderby" />

### clearOrderBy() [#clearorderby]

```ts
clearOrderBy(): RelationshipSubqueryBuilder<DB, TB, O, Depth, FunctionMode, ApexMode>;
```

Returns a builder with all `ORDER BY` items removed.

#### Returns [#returns-6]

`RelationshipSubqueryBuilder`\<`DB`, `TB`, `O`, `Depth`, `FunctionMode`, `ApexMode`>

***

<a id="api-clearselect" />

### clearSelect() [#clearselect]

```ts
clearSelect(): RelationshipSubqueryBuilder<DB, TB, unknown, Depth, ClearedFunctionMode<FunctionMode>, ApexMode>;
```

Returns a builder with all current selections removed.

#### Returns [#returns-7]

`RelationshipSubqueryBuilder`\<`DB`, `TB`, `unknown`, `Depth`, `ClearedFunctionMode`\<`FunctionMode`>, `ApexMode`>

***

<a id="api-clearwhere" />

### clearWhere() [#clearwhere]

```ts
clearWhere(): RelationshipSubqueryBuilder<DB, TB, O, Depth, FunctionMode, ApexMode>;
```

Returns a builder with the `WHERE` predicate removed.

#### Returns [#returns-8]

`RelationshipSubqueryBuilder`\<`DB`, `TB`, `O`, `Depth`, `FunctionMode`, `ApexMode`>

***

<a id="api-limit" />

### limit() [#limit]

```ts
limit(limit): RelationshipSubqueryBuilder<DB, TB, O, Depth, FunctionMode, ApexMode>;
```

Adds or replaces the SOQL `LIMIT` clause.

#### Parameters [#parameters-2]

| Parameter | Type     |
| --------- | -------- |
| `limit`   | `number` |

#### Returns [#returns-9]

`RelationshipSubqueryBuilder`\<`DB`, `TB`, `O`, `Depth`, `FunctionMode`, `ApexMode`>

***

<a id="api-orderby" />

### orderBy() [#orderby]

#### Call Signature [#call-signature]

```ts
orderBy(
   expression,
   direction?,
   nulls?
): RelationshipSubqueryBuilder<DB, TB, O, Depth, FunctionMode, ApexMode>;
```

Adds a typed `ORDER BY` item.

##### Parameters [#parameters-3]

| Parameter    | Type                                                                         |
| ------------ | ---------------------------------------------------------------------------- |
| `expression` | [`SoqlRawBuilder`](/docs/core/reference/api/interfaces/SoqlRawBuilder)       |
| `direction?` | [`OrderByDirection`](/docs/core/reference/api/type-aliases/OrderByDirection) |
| `nulls?`     | [`OrderByNulls`](/docs/core/reference/api/type-aliases/OrderByNulls)         |

##### Returns [#returns-10]

`RelationshipSubqueryBuilder`\<`DB`, `TB`, `O`, `Depth`, `FunctionMode`, `ApexMode`>

#### Call Signature [#call-signature-1]

```ts
orderBy(
   expression,
   direction?,
   nulls?
): RelationshipSubqueryBuilder<DB, TB, O, Depth, FunctionMode, ApexMode>;
```

Adds a typed `ORDER BY` item.

##### Parameters [#parameters-4]

| Parameter    | Type                                                                         |
| ------------ | ---------------------------------------------------------------------------- |
| `expression` | `DistanceOrderByFactory`\<`DB`, `TB`>                                        |
| `direction?` | [`OrderByDirection`](/docs/core/reference/api/type-aliases/OrderByDirection) |
| `nulls?`     | [`OrderByNulls`](/docs/core/reference/api/type-aliases/OrderByNulls)         |

##### Returns [#returns-11]

`RelationshipSubqueryBuilder`\<`DB`, `TB`, `O`, `Depth`, `FunctionMode`, `ApexMode`>

#### Call Signature [#call-signature-2]

```ts
orderBy<OE>(
   field,
   direction?,
   nulls?
): RelationshipSubqueryBuilder<DB, TB, O, Depth, FunctionMode, ApexMode>;
```

Adds a typed `ORDER BY` item.

##### Type Parameters [#type-parameters-6]

| Type Parameter          |
| ----------------------- |
| `OE` *extends* `string` |

##### Parameters [#parameters-5]

| Parameter    | Type                                                                         |
| ------------ | ---------------------------------------------------------------------------- |
| `field`      | `OE` & `SortableFieldName`\<`DB`, `TB`, `OE`>                                |
| `direction?` | [`OrderByDirection`](/docs/core/reference/api/type-aliases/OrderByDirection) |
| `nulls?`     | `OrderByNullsForReference`\<`DB`, `TB`, `OE`>                                |

##### Returns [#returns-12]

`RelationshipSubqueryBuilder`\<`DB`, `TB`, `O`, `Depth`, `FunctionMode`, `ApexMode`>

***

<a id="api-where" />

### where() [#where]

#### Call Signature [#call-signature-3]

```ts
where(expression): RelationshipSubqueryBuilder<DB, TB, O, Depth, FunctionMode, ApexMode>;
```

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

##### Parameters [#parameters-6]

| Parameter    | Type                                                                   |
| ------------ | ---------------------------------------------------------------------- |
| `expression` | [`SoqlRawBuilder`](/docs/core/reference/api/interfaces/SoqlRawBuilder) |

##### Returns [#returns-13]

`RelationshipSubqueryBuilder`\<`DB`, `TB`, `O`, `Depth`, `FunctionMode`, `ApexMode`>

#### Call Signature [#call-signature-4]

```ts
where(expression): RelationshipSubqueryBuilder<DB, TB, O, Depth, FunctionMode, ApexMode>;
```

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

##### Parameters [#parameters-7]

| Parameter    | Type                                                          |
| ------------ | ------------------------------------------------------------- |
| `expression` | `RelationshipWhereExpressionFactory`\<`DB`, `TB`, `ApexMode`> |

##### Returns [#returns-14]

`RelationshipSubqueryBuilder`\<`DB`, `TB`, `O`, `Depth`, `FunctionMode`, `ApexMode`>

#### Call Signature [#call-signature-5]

```ts
where(
   lhs,
   op,
   rhs
): RelationshipSubqueryBuilder<DB, TB, O, Depth, FunctionMode, ApexMode>;
```

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

##### Parameters [#parameters-8]

| Parameter | Type                                              |
| --------- | ------------------------------------------------- |
| `lhs`     | `RelationshipApexBindLeftExpression`\<`ApexMode`> |
| `op`      | `"includes"`                                      |
| `rhs`     | readonly `string`\[]                              |

##### Returns [#returns-15]

`RelationshipSubqueryBuilder`\<`DB`, `TB`, `O`, `Depth`, `FunctionMode`, `ApexMode`>

#### Call Signature [#call-signature-6]

```ts
where<RE, OP, RHS>(
   lhs,
   op,
   rhs
): RelationshipSubqueryBuilder<DB, TB, O, Depth, FunctionMode, ApexMode>;
```

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

##### Type Parameters [#type-parameters-7]

| Type Parameter                                                                                                                                                                                                                                                                    |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RE` *extends* `string`                                                                                                                                                                                                                                                           |
| `OP` *extends* \| `"="` \| `"!="` \| [`OrderedComparisonOperator`](/docs/core/reference/api/type-aliases/OrderedComparisonOperator) \| `"in"` \| `"not in"` \| [`MultiSelectComparisonOperator`](/docs/core/reference/api/type-aliases/MultiSelectComparisonOperator) \| `"like"` |
| `RHS`                                                                                                                                                                                                                                                                             |

##### Parameters [#parameters-9]

| Parameter | Type                                            |
| --------- | ----------------------------------------------- |
| `lhs`     | `RE` & `FilterableFieldName`\<`DB`, `TB`, `RE`> |
| `op`      | `OP`                                            |
| `rhs`     | `RHS`                                           |

##### Returns [#returns-16]

`RelationshipSubqueryBuilder`\<`DB`, `TB`, `O`, `Depth`, `FunctionMode`, `ApexMode`>

***

<a id="api-select" />

### select() [#select]

#### Call Signature [#call-signature-7]

```ts
select<RawOutput>(selection): RelationshipSubqueryBuilder<DB, TB, O & RawOutput, Depth, FunctionMode, ApexMode>;
```

Adds one or more typed selections to the query output.

##### Type Parameters [#type-parameters-8]

| Type Parameter |
| -------------- |
| `RawOutput`    |

##### Parameters [#parameters-10]

| Parameter   | Type                                                                                 |
| ----------- | ------------------------------------------------------------------------------------ |
| `selection` | [`SoqlRawBuilder`](/docs/core/reference/api/interfaces/SoqlRawBuilder)\<`RawOutput`> |

##### Returns [#returns-17]

`RelationshipSubqueryBuilder`\<`DB`, `TB`, `O` & `RawOutput`, `Depth`, `FunctionMode`, `ApexMode`>

#### Call Signature [#call-signature-8]

```ts
select<Selections>(selections): RelationshipSubqueryBuilder<DB, TB, O & Selection<DB, TB, Selections[number]>, Depth, FunctionMode, ApexMode>;
```

Adds one or more typed selections to the query output.

##### Type Parameters [#type-parameters-9]

| Type Parameter                              |
| ------------------------------------------- |
| `Selections` *extends* readonly `string`\[] |

##### Parameters [#parameters-11]

| Parameter    | Type                                                                         |
| ------------ | ---------------------------------------------------------------------------- |
| `selections` | `Selections` & `CheckedSelectExpressionList`\<`DB`, `TB`, `O`, `Selections`> |

##### Returns [#returns-18]

`RelationshipSubqueryBuilder`\<`DB`, `TB`, `O` & `Selection`\<`DB`, `TB`, `Selections`\[`number`]>, `Depth`, `FunctionMode`, `ApexMode`>

#### Call Signature [#call-signature-9]

```ts
select<FunctionSelection>(selection): RelationshipSubqueryBuilder<DB, TB, O & SelectFunctionSelection<FunctionSelection>, Depth, "present", ApexMode>;
```

Adds one or more typed selections to the query output.

##### Type Parameters [#type-parameters-10]

| Type Parameter                                             |
| ---------------------------------------------------------- |
| `FunctionSelection` *extends* `SelectFunctionSelectionArg` |

##### Parameters [#parameters-12]

| Parameter   | Type                                                                    |
| ----------- | ----------------------------------------------------------------------- |
| `selection` | `SelectFunctionForMode`\<`FunctionMode`, (`eb`) => `FunctionSelection`> |

##### Returns [#returns-19]

`RelationshipSubqueryBuilder`\<`DB`, `TB`, `O` & `SelectFunctionSelection`\<`FunctionSelection`>, `Depth`, `"present"`, `ApexMode`>

#### Call Signature [#call-signature-10]

```ts
select<SE>(selection): RelationshipSubqueryBuilder<DB, TB, O & Selection<DB, TB, SE>, Depth, FunctionMode, ApexMode>;
```

Adds one or more typed selections to the query output.

##### Type Parameters [#type-parameters-11]

| Type Parameter          |
| ----------------------- |
| `SE` *extends* `string` |

##### Parameters [#parameters-13]

| Parameter   | Type                                                                                               |
| ----------- | -------------------------------------------------------------------------------------------------- |
| `selection` | `SE` & `SelectExpression`\<`DB`, `TB`, `SE`> & `AvailableSelectExpression`\<`DB`, `TB`, `O`, `SE`> |

##### Returns [#returns-20]

`RelationshipSubqueryBuilder`\<`DB`, `TB`, `O` & `Selection`\<`DB`, `TB`, `SE`>, `Depth`, `FunctionMode`, `ApexMode`>

***

<a id="api-selectfields" />

### selectFields() [#selectfields]

```ts
selectFields<Selector>(selector, ...check): RelationshipSubqueryBuilder<DB, TB, O & FieldsSelection<DB, TB, Selector>, Depth, FunctionMode, ApexMode>;
```

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

#### Type Parameters [#type-parameters-12]

| Type Parameter                                                                                |
| --------------------------------------------------------------------------------------------- |
| `Selector` *extends* [`FieldsSelector`](/docs/core/reference/api/type-aliases/FieldsSelector) |

#### Parameters [#parameters-14]

| Parameter  | Type                                                 |
| ---------- | ---------------------------------------------------- |
| `selector` | `Selector`                                           |
| ...`check` | `FieldsSelectionCheck`\<`DB`, `TB`, `O`, `Selector`> |

#### Returns [#returns-21]

`RelationshipSubqueryBuilder`\<`DB`, `TB`, `O` & `FieldsSelection`\<`DB`, `TB`, `Selector`>, `Depth`, `FunctionMode`, `ApexMode`>

***

<a id="api-selectsubquery" />

### selectSubquery() [#selectsubquery]

```ts
selectSubquery<Relationship, SubqueryOutput, SubqueryFunctionMode>(relationship, callback): RelationshipSubqueryBuilder<DB, TB, O & { readonly [Key in string]: SalesforceQueryResult<Simplify<SubqueryOutput>> }, Depth, MergeFunctionMode<FunctionMode, SubqueryFunctionMode>, ApexMode>;
```

Adds a typed child-relationship subquery selection.

#### Type Parameters [#type-parameters-13]

| Type Parameter                                                      |
| ------------------------------------------------------------------- |
| `Relationship` *extends* `string`                                   |
| `SubqueryOutput`                                                    |
| `SubqueryFunctionMode` *extends* `RelationshipSubqueryFunctionMode` |

#### Parameters [#parameters-15]

| Parameter      | Type                                                                                                                                                                                                                                      |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `relationship` | `Relationship` & `SelectableChildRelationship`\<`DB`, `TB`, `Relationship`, `Depth`>                                                                                                                                                      |
| `callback`     | (`query`) => `RelationshipSubqueryBuilder`\<`DB`, `ChildObjectName`\<`DB`, `TB`, `Extract`\<`Relationship`, `ChildRelationshipName`\<`DB`, `TB`>>>, `SubqueryOutput`, readonly \[`Depth`, `unknown`], `SubqueryFunctionMode`, `ApexMode`> |

#### Returns [#returns-22]

`RelationshipSubqueryBuilder`\<`DB`, `TB`, `O` & `{ readonly [Key in string]: SalesforceQueryResult<Simplify<SubqueryOutput>> }`, `Depth`, `MergeFunctionMode`\<`FunctionMode`, `SubqueryFunctionMode`>, `ApexMode`>

***

<a id="api-tooperationnode" />

### toOperationNode() [#tooperationnode]

```ts
toOperationNode(): RelationshipSubqueryNode;
```

Returns the immutable operation node represented by this builder.

#### Returns [#returns-23]

[`RelationshipSubqueryNode`](/docs/core/reference/api/type-aliases/RelationshipSubqueryNode)

## Properties [#properties]

| Property                              | Modifier   | Type                                                                                                                                                            | Description                                                             |
| ------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| <a id="api-property-pilot" /> `pilot` | `readonly` | [`RelationshipSubqueryPilotModule`](/docs/core/reference/api/interfaces/RelationshipSubqueryPilotModule)\<`DB`, `TB`, `O`, `Depth`, `FunctionMode`, `ApexMode`> | Explicitly opt into Salesforce pilot-only relationship-subquery syntax. |