with() — drizzle-orm Function Reference

Architecture documentation for the with() function in db.ts from the drizzle-orm codebase.

Function typescript DrizzleORM SQLDialects calls 3

Entity Profile

DrizzleORM→ SQLDialects→ with() — drizzle-orm Function Reference

Dependency Diagram

graph TD
  511441a5_4f3e_873f_b0b5_120a4a7fe793["with()"]
  10fbad18_129f_69a2_7ce3_79ea63dcf5d7["MySqlDatabase"]
  511441a5_4f3e_873f_b0b5_120a4a7fe793 -->|defined in| 10fbad18_129f_69a2_7ce3_79ea63dcf5d7
  d9537013_dc8d_a9d5_6b54_e1724abbdd2f["select()"]
  511441a5_4f3e_873f_b0b5_120a4a7fe793 -->|calls| d9537013_dc8d_a9d5_6b54_e1724abbdd2f
  1a12f96f_7b6a_911e_9e6f_4669ecb64b4f["selectDistinct()"]
  511441a5_4f3e_873f_b0b5_120a4a7fe793 -->|calls| 1a12f96f_7b6a_911e_9e6f_4669ecb64b4f
  7d0caa08_9013_3d08_d559_97226a65da99["update()"]
  511441a5_4f3e_873f_b0b5_120a4a7fe793 -->|calls| 7d0caa08_9013_3d08_d559_97226a65da99
  style 511441a5_4f3e_873f_b0b5_120a4a7fe793 fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

drizzle-orm/src/mysql-core/db.ts lines 177–322

	with(...queries: WithSubquery[]) {
		const self = this;

		/**
		 * Creates a select query.
		 *
		 * Calling this method with no arguments will select all columns from the table. Pass a selection object to specify the columns you want to select.
		 *
		 * Use `.from()` method to specify which table to select from.
		 *
		 * See docs: {@link https://orm.drizzle.team/docs/select}
		 *
		 * @param fields The selection object.
		 *
		 * @example
		 *
		 * ```ts
		 * // Select all columns and all rows from the 'cars' table
		 * const allCars: Car[] = await db.select().from(cars);
		 *
		 * // Select specific columns and all rows from the 'cars' table
		 * const carsIdsAndBrands: { id: number; brand: string }[] = await db.select({
		 *   id: cars.id,
		 *   brand: cars.brand
		 * })
		 *   .from(cars);
		 * ```
		 *
		 * Like in SQL, you can use arbitrary expressions as selection fields, not just table columns:
		 *
		 * ```ts
		 * // Select specific columns along with expression and all rows from the 'cars' table
		 * const carsIdsAndLowerNames: { id: number; lowerBrand: string }[] = await db.select({
		 *   id: cars.id,
		 *   lowerBrand: sql<string>`lower(${cars.brand})`,
		 * })
		 *   .from(cars);
		 * ```
		 */
		function select(): MySqlSelectBuilder<undefined, TPreparedQueryHKT>;
		function select<TSelection extends SelectedFields>(
			fields: TSelection,
		): MySqlSelectBuilder<TSelection, TPreparedQueryHKT>;
		function select(fields?: SelectedFields): MySqlSelectBuilder<SelectedFields | undefined, TPreparedQueryHKT> {
			return new MySqlSelectBuilder({
				fields: fields ?? undefined,
				session: self.session,
				dialect: self.dialect,
				withList: queries,
			});
		}

		/**
		 * Adds `distinct` expression to the select query.
		 *
		 * Calling this method will return only unique values. When multiple columns are selected, it returns rows with unique combinations of values in these columns.
		 *
		 * Use `.from()` method to specify which table to select from.
		 *
		 * See docs: {@link https://orm.drizzle.team/docs/select#distinct}
		 *
		 * @param fields The selection object.
		 *
		 * @example
		 * ```ts
		 * // Select all unique rows from the 'cars' table
		 * await db.selectDistinct()
		 *   .from(cars)
		 *   .orderBy(cars.id, cars.brand, cars.color);
		 *
		 * // Select all unique brands from the 'cars' table
		 * await db.selectDistinct({ brand: cars.brand })
		 *   .from(cars)
		 *   .orderBy(cars.brand);
		 * ```
		 */
		function selectDistinct(): MySqlSelectBuilder<undefined, TPreparedQueryHKT>;
		function selectDistinct<TSelection extends SelectedFields>(
			fields: TSelection,
		): MySqlSelectBuilder<TSelection, TPreparedQueryHKT>;
		function selectDistinct(