drizzle-orm 0.29.0 → 0.29.1-47754fb

package/pg-core/query-builders/select.js

@@ -146,32 +146,115 @@ class PgSelectQueryBuilderBase extends TypedQueryBuilder {
     };
   }
   /**
-   * For each row of the table, include
-   * values from a matching row of the joined
-   * table, if there is a matching row. If not,
-   * all of the columns of the joined table
-   * will be set to null.
+   * Executes a `left join` operation by adding another table to the current query.
+   * 
+   * Calling this method associates each row of the table with the corresponding row from the joined table, if a match is found. If no matching row exists, it sets all columns of the joined table to null.
+   * 
+   * See docs: {@link https://orm.drizzle.team/docs/joins#left-join}
+   * 
+   * @param table the table to join.
+   * @param on the `on` clause.
+   * 
+   * @example
+   * 
+   * ```ts
+   * // Select all users and their pets
+   * const usersWithPets: { user: User; pets: Pet | null }[] = await db.select()
+   *   .from(users)
+   *   .leftJoin(pets, eq(users.id, pets.ownerId))
+   * 
+   * // Select userId and petId
+   * const usersIdsAndPetIds: { userId: number; petId: number | null }[] = await db.select({
+   *   userId: users.id,
+   *   petId: pets.id,
+   * })
+   *   .from(users)
+   *   .leftJoin(pets, eq(users.id, pets.ownerId))
+   * ```
    */
   leftJoin = this.createJoin("left");
   /**
-   * Includes all of the rows of the joined table.
-   * If there is no matching row in the main table,
-   * all the columns of the main table will be
-   * set to null.
+   * Executes a `right join` operation by adding another table to the current query.
+   * 
+   * Calling this method associates each row of the joined table with the corresponding row from the main table, if a match is found. If no matching row exists, it sets all columns of the main table to null.
+   * 
+   * See docs: {@link https://orm.drizzle.team/docs/joins#right-join}
+   * 
+   * @param table the table to join.
+   * @param on the `on` clause.
+   * 
+   * @example
+   * 
+   * ```ts
+   * // Select all users and their pets
+   * const usersWithPets: { user: User | null; pets: Pet }[] = await db.select()
+   *   .from(users)
+   *   .rightJoin(pets, eq(users.id, pets.ownerId))
+   * 
+   * // Select userId and petId
+   * const usersIdsAndPetIds: { userId: number | null; petId: number }[] = await db.select({
+   *   userId: users.id,
+   *   petId: pets.id,
+   * })
+   *   .from(users)
+   *   .rightJoin(pets, eq(users.id, pets.ownerId))
+   * ```
    */
   rightJoin = this.createJoin("right");
   /**
-   * This is the default type of join.
-   *
-   * For each row of the table, the joined table
-   * needs to have a matching row, or it will
-   * be excluded from results.
+   * Executes an `inner join` operation, creating a new table by combining rows from two tables that have matching values.
+   * 
+   * Calling this method retrieves rows that have corresponding entries in both joined tables. Rows without matching entries in either table are excluded, resulting in a table that includes only matching pairs.
+   * 
+   * See docs: {@link https://orm.drizzle.team/docs/joins#inner-join}
+   * 
+   * @param table the table to join.
+   * @param on the `on` clause.
+   * 
+   * @example
+   * 
+   * ```ts
+   * // Select all users and their pets
+   * const usersWithPets: { user: User; pets: Pet }[] = await db.select()
+   *   .from(users)
+   *   .innerJoin(pets, eq(users.id, pets.ownerId))
+   * 
+   * // Select userId and petId
+   * const usersIdsAndPetIds: { userId: number; petId: number }[] = await db.select({
+   *   userId: users.id,
+   *   petId: pets.id,
+   * })
+   *   .from(users)
+   *   .innerJoin(pets, eq(users.id, pets.ownerId))
+   * ```
    */
   innerJoin = this.createJoin("inner");
   /**
-   * Rows from both the main & joined are included,
-   * regardless of whether or not they have matching
-   * rows in the other table.
+   * Executes a `full join` operation by combining rows from two tables into a new table.
+   * 
+   * Calling this method retrieves all rows from both main and joined tables, merging rows with matching values and filling in `null` for non-matching columns.
+   * 
+   * See docs: {@link https://orm.drizzle.team/docs/joins#full-join}
+   * 
+   * @param table the table to join.
+   * @param on the `on` clause.
+   * 
+   * @example
+   * 
+   * ```ts
+   * // Select all users and their pets
+   * const usersWithPets: { user: User | null; pets: Pet | null }[] = await db.select()
+   *   .from(users)
+   *   .fullJoin(pets, eq(users.id, pets.ownerId))
+   * 
+   * // Select userId and petId
+   * const usersIdsAndPetIds: { userId: number | null; petId: number | null }[] = await db.select({
+   *   userId: users.id,
+   *   petId: pets.id,
+   * })
+   *   .from(users)
+   *   .fullJoin(pets, eq(users.id, pets.ownerId))
+   * ```
    */
   fullJoin = this.createJoin("full");
   createSetOperator(type, isAll) {
@@ -186,29 +269,226 @@ class PgSelectQueryBuilderBase extends TypedQueryBuilder {
       return this;
     };
   }
+  /**
+   * Adds `union` set operator to the query.
+   * 
+   * Calling this method will combine the result sets of the `select` statements and remove any duplicate rows that appear across them.
+   * 
+   * See docs: {@link https://orm.drizzle.team/docs/set-operations#union}
+   * 
+   * @example
+   * 
+   * ```ts
+   * // Select all unique names from customers and users tables
+   * await db.select({ name: users.name })
+   *   .from(users)
+   *   .union(
+   *     db.select({ name: customers.name }).from(customers)
+   *   );
+   * // or
+   * import { union } from 'drizzle-orm/pg-core'
+   * 
+   * await union(
+   *   db.select({ name: users.name }).from(users), 
+   *   db.select({ name: customers.name }).from(customers)
+   * );
+   * ```
+   */
   union = this.createSetOperator("union", false);
+  /**
+   * Adds `union all` set operator to the query.
+   * 
+   * Calling this method will combine the result-set of the `select` statements and keep all duplicate rows that appear across them.
+   * 
+   * See docs: {@link https://orm.drizzle.team/docs/set-operations#union-all}
+   * 
+   * @example
+   * 
+   * ```ts
+   * // Select all transaction ids from both online and in-store sales
+   * await db.select({ transaction: onlineSales.transactionId })
+   *   .from(onlineSales)
+   *   .unionAll(
+   *     db.select({ transaction: inStoreSales.transactionId }).from(inStoreSales)
+   *   );
+   * // or
+   * import { unionAll } from 'drizzle-orm/pg-core'
+   * 
+   * await unionAll(
+   *   db.select({ transaction: onlineSales.transactionId }).from(onlineSales),
+   *   db.select({ transaction: inStoreSales.transactionId }).from(inStoreSales)
+   * );
+   * ```
+   */
   unionAll = this.createSetOperator("union", true);
+  /**
+   * Adds `intersect` set operator to the query.
+   * 
+   * Calling this method will retain only the rows that are present in both result sets and eliminate duplicates.
+   * 
+   * See docs: {@link https://orm.drizzle.team/docs/set-operations#intersect}
+   * 
+   * @example
+   * 
+   * ```ts
+   * // Select course names that are offered in both departments A and B
+   * await db.select({ courseName: depA.courseName })
+   *   .from(depA)
+   *   .intersect(
+   *     db.select({ courseName: depB.courseName }).from(depB)
+   *   );
+   * // or
+   * import { intersect } from 'drizzle-orm/pg-core'
+   * 
+   * await intersect(
+   *   db.select({ courseName: depA.courseName }).from(depA),
+   *   db.select({ courseName: depB.courseName }).from(depB)
+   * );
+   * ```
+   */
   intersect = this.createSetOperator("intersect", false);
+  /**
+   * Adds `intersect all` set operator to the query.
+   * 
+   * Calling this method will retain only the rows that are present in both result sets including all duplicates.
+   * 
+   * See docs: {@link https://orm.drizzle.team/docs/set-operations#intersect-all}
+   * 
+   * @example
+   * 
+   * ```ts
+   * // Select all products and quantities that are ordered by both regular and VIP customers
+   * await db.select({ 
+   *   productId: regularCustomerOrders.productId, 
+   *   quantityOrdered: regularCustomerOrders.quantityOrdered
+   * })
+   * .from(regularCustomerOrders)
+   * .intersectAll(
+   *   db.select({ 
+   *     productId: vipCustomerOrders.productId, 
+   *     quantityOrdered: vipCustomerOrders.quantityOrdered 
+   *   })
+   *   .from(vipCustomerOrders)
+   * );
+   * // or
+   * import { intersectAll } from 'drizzle-orm/pg-core'
+   * 
+   * await intersectAll(
+   *   db.select({
+   *     productId: regularCustomerOrders.productId,
+   *     quantityOrdered: regularCustomerOrders.quantityOrdered
+   *   })
+   *   .from(regularCustomerOrders),
+   *   db.select({
+   *     productId: vipCustomerOrders.productId,
+   *     quantityOrdered: vipCustomerOrders.quantityOrdered
+   *   })
+   *   .from(vipCustomerOrders)
+   * );
+   * ```
+   */
   intersectAll = this.createSetOperator("intersect", true);
+  /**
+   * Adds `except` set operator to the query.
+   * 
+   * Calling this method will retrieve all unique rows from the left query, except for the rows that are present in the result set of the right query.
+   * 
+   * See docs: {@link https://orm.drizzle.team/docs/set-operations#except}
+   * 
+   * @example
+   * 
+   * ```ts
+   * // Select all courses offered in department A but not in department B
+   * await db.select({ courseName: depA.courseName })
+   *   .from(depA)
+   *   .except(
+   *     db.select({ courseName: depB.courseName }).from(depB)
+   *   );
+   * // or
+   * import { except } from 'drizzle-orm/pg-core'
+   * 
+   * await except(
+   *   db.select({ courseName: depA.courseName }).from(depA),
+   *   db.select({ courseName: depB.courseName }).from(depB)
+   * );
+   * ```
+   */
   except = this.createSetOperator("except", false);
+  /**
+   * Adds `except all` set operator to the query.
+   * 
+   * Calling this method will retrieve all rows from the left query, except for the rows that are present in the result set of the right query.
+   * 
+   * See docs: {@link https://orm.drizzle.team/docs/set-operations#except-all}
+   * 
+   * @example
+   * 
+   * ```ts
+   * // Select all products that are ordered by regular customers but not by VIP customers
+   * await db.select({
+   *   productId: regularCustomerOrders.productId,
+   *   quantityOrdered: regularCustomerOrders.quantityOrdered,
+   * })
+   * .from(regularCustomerOrders)
+   * .exceptAll(
+   *   db.select({
+   *     productId: vipCustomerOrders.productId,
+   *     quantityOrdered: vipCustomerOrders.quantityOrdered,
+   *   })
+   *   .from(vipCustomerOrders)
+   * );
+   * // or
+   * import { exceptAll } from 'drizzle-orm/pg-core'
+   * 
+   * await exceptAll(
+   *   db.select({
+   *     productId: regularCustomerOrders.productId,
+   *     quantityOrdered: regularCustomerOrders.quantityOrdered
+   *   })
+   *   .from(regularCustomerOrders),
+   *   db.select({
+   *     productId: vipCustomerOrders.productId,
+   *     quantityOrdered: vipCustomerOrders.quantityOrdered
+   *   })
+   *   .from(vipCustomerOrders)
+   * );
+   * ```
+   */
   exceptAll = this.createSetOperator("except", true);
   /** @internal */
   addSetOperators(setOperators) {
     this.config.setOperators.push(...setOperators);
     return this;
   }
-  /**
-   * Specify a condition to narrow the result set. Multiple
-   * conditions can be combined with the `and` and `or`
-   * functions.
-   *
-   * ## Examples
-   *
+  /** 
+   * Adds a `where` clause to the query.
+   * 
+   * Calling this method will select only those rows that fulfill a specified condition.
+   * 
+   * See docs: {@link https://orm.drizzle.team/docs/select#filtering}
+   * 
+   * @param where the `where` clause.
+   * 
+   * @example
+   * You can use conditional operators and `sql function` to filter the rows to be selected.
+   * 
    * ```ts
-   * // Find cars made in the year 2000
-   * db.select().from(cars).where(eq(cars.year, 2000));
+   * // Select all cars with green color
+   * await db.select().from(cars).where(eq(cars.color, 'green'));
+   * // or
+   * await db.select().from(cars).where(sql`${cars.color} = 'green'`)
    * ```
-   */
+   * 
+   * You can logically combine conditional operators with `and()` and `or()` operators:
+   * 
+   * ```ts
+   * // Select all BMW cars with a green color
+   * await db.select().from(cars).where(and(eq(cars.color, 'green'), eq(cars.brand, 'BMW')));
+   * 
+   * // Select all cars with the green or blue color
+   * await db.select().from(cars).where(or(eq(cars.color, 'green'), eq(cars.color, 'blue')));
+   * ```
+  */
   where(where) {
     if (typeof where === "function") {
       where = where(
@@ -222,11 +502,26 @@ class PgSelectQueryBuilderBase extends TypedQueryBuilder {
     return this;
   }
   /**
-   * Sets the HAVING clause of this query, which often
-   * used with GROUP BY and filters rows after they've been
-   * grouped together and combined.
-   *
-   * {@link https://www.postgresql.org/docs/current/sql-select.html#SQL-HAVING | Postgres having clause documentation}
+   * Adds a `having` clause to the query.
+   * 
+   * Calling this method will select only those rows that fulfill a specified condition. It is typically used with aggregate functions to filter the aggregated data based on a specified condition.
+   * 
+   * See docs: {@link https://orm.drizzle.team/docs/select#aggregations}
+   * 
+   * @param having the `having` clause.
+   * 
+   * @example
+   * 
+   * ```ts
+   * // Select all brands with more than one car
+   * await db.select({
+   * 	brand: cars.brand,
+   * 	count: sql<number>`cast(count(${cars.id}) as int)`,
+   * })
+   *   .from(cars)
+   *   .groupBy(cars.brand)
+   *   .having(({ count }) => gt(count, 1));
+   * ```
    */
   having(having) {
     if (typeof having === "function") {
@@ -279,17 +574,20 @@ class PgSelectQueryBuilderBase extends TypedQueryBuilder {
     return this;
   }
   /**
-   * Set the maximum number of rows that will be
-   * returned by this query.
+   * Adds a `limit` clause to the query.
+   * 
+   * Calling this method will set the maximum number of rows that will be returned by this query.
    *
-   * ## Examples
+   * See docs: {@link https://orm.drizzle.team/docs/select#limit--offset}
+   * 
+   * @param limit the `limit` clause.
+   * 
+   * @example
    *
    * ```ts
    * // Get the first 10 people from this query.
-   * db.select().from(people).limit(10);
+   * await db.select().from(people).limit(10);
    * ```
-   *
-   * {@link https://www.postgresql.org/docs/current/sql-select.html#SQL-LIMIT | Postgres LIMIT documentation}
    */
   limit(limit) {
     if (this.config.setOperators.length > 0) {
@@ -300,14 +598,19 @@ class PgSelectQueryBuilderBase extends TypedQueryBuilder {
     return this;
   }
   /**
-   * Skip a number of rows when returning results
-   * from this query.
-   *
-   * ## Examples
+   * Adds an `offset` clause to the query.
+   * 
+   * Calling this method will skip a number of rows when returning results from this query.
+   * 
+   * See docs: {@link https://orm.drizzle.team/docs/select#limit--offset}
+   * 
+   * @param offset the `offset` clause.
+   * 
+   * @example
    *
    * ```ts
    * // Get the 10th-20th people from this query.
-   * db.select().from(people).offset(10).limit(10);
+   * await db.select().from(people).offset(10).limit(10);
    * ```
    */
   offset(offset) {
@@ -319,11 +622,14 @@ class PgSelectQueryBuilderBase extends TypedQueryBuilder {
     return this;
   }
   /**
-   * The FOR clause specifies a lock strength for this query
-   * that controls how strictly it acquires exclusive access to
-   * the rows being queried.
-   *
-   * {@link https://www.postgresql.org/docs/current/sql-select.html#SQL-FOR-UPDATE-SHARE | PostgreSQL locking clause documentation}
+   * Adds a `for` clause to the query.
+   * 
+   * Calling this method will specify a lock strength for this query that controls how strictly it acquires exclusive access to the rows being queried.
+   * 
+   * See docs: {@link https://www.postgresql.org/docs/current/sql-select.html#SQL-FOR-UPDATE-SHARE}
+   * 
+   * @param strength the lock strength.
+   * @param config the lock configuration.
    */
   for(strength, config = {}) {
     this.config.lockingClause = { strength, config };