diff --git a/src/query-builder/aggregate-function-builder.ts b/src/query-builder/aggregate-function-builder.ts index 071bf68b3..7dd1bef31 100644 --- a/src/query-builder/aggregate-function-builder.ts +++ b/src/query-builder/aggregate-function-builder.ts @@ -66,13 +66,15 @@ export class AggregateFunctionBuilder } /** - * Adds a distinct clause inside the function. + * Adds a `distinct` clause inside the function. + * + * ### Examples * * ```ts * const result = await db * .selectFrom('person') - * .select( - * eb => eb.fn.count('first_name').distinct().as('first_name_count') + * .select((eb) => + * eb.fn.count('first_name').distinct().as('first_name_count') * ) * .executeTakeFirstOrThrow() * ``` @@ -94,7 +96,48 @@ export class AggregateFunctionBuilder } /** - * // TODO: ... + * Adds a `filter` clause with a nested `where` clause after the function. + * + * Similar to {@link WhereInterface}'s `where` method. + * + * Also see {@link orFilterWhere}, {@link filterWhereExists} and {@link filterWhereRef}. + * + * ### Examples + * + * Count by gender: + * + * ```ts + * const result = await db + * .selectFrom('person') + * .select([ + * (eb) => + * eb.fn + * .count('id') + * .filterWhere('gender', '=', 'female') + * .as('female_count'), + * (eb) => + * eb.fn + * .count('id') + * .filterWhere('gender', '=', 'male') + * .as('male_count'), + * (eb) => + * eb.fn + * .count('id') + * .filterWhere('gender', '=', 'other') + * .as('other_count'), + * ]) + * .executeTakeFirstOrThrow() + * ``` + * + * The generated SQL (PostgreSQL): + * + * ```sql + * select + * count("id") filter(where "gender" = $1) as "female_count", + * count("id") filter(where "gender" = $2) as "male_count", + * count("id") filter(where "gender" = $3) as "other_count" + * from "person" + * ``` */ filterWhere>( lhs: RE, @@ -119,7 +162,44 @@ export class AggregateFunctionBuilder } /** - * TODO: ... + * Adds a `filter` clause with a nested `where exists` clause after the function. + * + * Similar to {@link WhereInterface}'s `whereExists` method. + * + * ### Examples + * + * Count pet owners versus general public: + * + * ```ts + * const result = await db + * .selectFrom('person') + * .select([ + * (eb) => + * eb.fn + * .count('person.id') + * .filterWhereExists((qb) => + * qb + * .selectFrom('pet') + * .select('pet.id') + * .whereRef('pet.owner_id', '=', 'person.id') + * ) + * .as('pet_owner_count'), + * (eb) => eb.fn.count('person.id').as('total_count'), + * ]) + * .executeTakeFirstOrThrow() + * ``` + * + * The generated SQL (PostgreSQL): + * + * ```sql + * select count("person"."id") filter(where exists ( + * select "pet"."id" + * from "pet" + * where "pet"."owner_id" = "person"."id" + * )) as "pet_ower_count", + * count("person"."id") as "total_count" + * from "person" + * ``` */ filterWhereExists( arg: ExistsExpression @@ -134,7 +214,8 @@ export class AggregateFunctionBuilder } /** - * TODO: ... + * Just like {@link filterWhereExists} but creates a `not exists` clause inside + * the `filter` clause. */ filterWhereNotExists( arg: ExistsExpression @@ -149,7 +230,37 @@ export class AggregateFunctionBuilder } /** - * TODO: ... + * Adds a `filter` clause with a nested `where` clause after the function, where + * both sides of the operator are references to columns. + * + * Similar to {@link WhereInterface}'s `whereRef` method. + * + * ### Examples + * + * Count people with same first and last names versus general public: + * + * ```ts + * const result = await db + * .selectFrom('person') + * .select([ + * (eb) => + * eb.fn + * .count('id') + * .filterWhereRef('first_name', '=', 'last_name') + * .as('repeat_name_count'), + * (eb) => eb.fn.count('id').as('total_count'), + * ]) + * .executeTakeFirstOrThrow() + * ``` + * + * The generated SQL (PostgreSQL): + * + * ```sql + * select + * count("id") filter(where "first_name" = "last_name") as "repeat_name_count", + * count("id") as "total_count" + * from "person" + * ``` */ filterWhereRef( lhs: ReferenceExpression, @@ -166,7 +277,39 @@ export class AggregateFunctionBuilder } /** - * TODO: ... + * Adds a `filter` clause with a nested `or where` clause after the function. + * Otherwise works just like {@link filterWhere}. + * + * Similar to {@link WhereInterface}'s `orWhere` method. + * + * ### Examples + * + * For some reason you're tasked with counting adults (18+) or people called + * "Bob" versus general public: + * + * ```ts + * const result = await db + * .selectFrom('person') + * .select([ + * (eb) => + * eb.fn + * .count('id') + * .filterWhere('age', '>=', '18') + * .orFilterWhere('first_name', '=', 'Bob') + * .as('adult_or_bob_count'), + * (eb) => eb.fn.count('id').as('total_count'), + * ]) + * .executeTakeFirstOrThrow() + * ``` + * + * The generated SQL (PostgreSQL): + * + * ```sql + * select + * count("id") filter(where "age" >= $1 or "first_name" = $2) as "adult_or_bob_count", + * count("id") as "total_count" + * from "person" + * ``` */ orFilterWhere>( lhs: RE, @@ -193,7 +336,10 @@ export class AggregateFunctionBuilder } /** - * TODO: ... + * Just like {@link filterWhereExists} but creates an `or exists` clause inside + * the `filter` clause. + * + * Similar to {@link WhereInterface}'s `orWhereExists` method. */ orFilterWhereExists( arg: ExistsExpression @@ -208,7 +354,10 @@ export class AggregateFunctionBuilder } /** - * TODO: ... + * Just like {@link filterWhereExists} but creates an `or not exists` clause inside + * the `filter` clause. + * + * Similar to {@link WhereInterface}'s `orWhereNotExists` method. */ orFilterWhereNotExists( arg: ExistsExpression @@ -223,7 +372,12 @@ export class AggregateFunctionBuilder } /** - * TODO: ... + * Adds an `or where` clause inside the `filter` clause. Otherwise works just + * like {@link filterWhereRef}. + * + * Also see {@link orFilterWhere} and {@link filterWhere}. + * + * Similar to {@link WhereInterface}'s `orWhereRef` method. */ orFilterWhereRef( lhs: ReferenceExpression, @@ -240,7 +394,9 @@ export class AggregateFunctionBuilder } /** - * Adds an over clause (window functions) after the function. + * Adds an `over` clause (window functions) after the function. + * + * ### Examples * * ```ts * const result = await db diff --git a/src/query-builder/where-interface.ts b/src/query-builder/where-interface.ts index d81c8b2ca..3dc58cf53 100644 --- a/src/query-builder/where-interface.ts +++ b/src/query-builder/where-interface.ts @@ -208,7 +208,7 @@ export interface WhereInterface { * * The normal `where` method treats the right hand side argument as a * value by default. `whereRef` treats it as a column reference. This method is - * expecially useful with joins and correclated subqueries. + * expecially useful with joins and correlated subqueries. * * ### Examples * @@ -411,12 +411,12 @@ export interface WhereInterface { whereNotExists(arg: ExistsExpression): WhereInterface /** - * Just like {@link whereExists} but creates a `or exists` clause. + * Just like {@link whereExists} but creates an `or exists` clause. */ orWhereExists(arg: ExistsExpression): WhereInterface /** - * Just like {@link whereExists} but creates a `or not exists` clause. + * Just like {@link whereExists} but creates an `or not exists` clause. */ orWhereNotExists(arg: ExistsExpression): WhereInterface }