with() — drizzle-orm Function Reference

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

Function typescript DrizzleORM DatabaseDrivers calls 5

Entity Profile

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

Dependency Diagram

graph TD
  9373d797_a688_263a_ed31_d047e2450a06["with()"]
  7b170b6b_8109_4580_dc12_4da0d59d8d8d["PgDatabase"]
  9373d797_a688_263a_ed31_d047e2450a06 -->|defined in| 7b170b6b_8109_4580_dc12_4da0d59d8d8d
  8995ca38_e96f_9e8c_c35e_cdf5ac90572c["select()"]
  9373d797_a688_263a_ed31_d047e2450a06 -->|calls| 8995ca38_e96f_9e8c_c35e_cdf5ac90572c
  ca0e6ee4_ee25_74d1_36f1_48337059053f["selectDistinct()"]
  9373d797_a688_263a_ed31_d047e2450a06 -->|calls| ca0e6ee4_ee25_74d1_36f1_48337059053f
  927861bc_81ae_46e9_c8b8_1f8444803d6c["selectDistinctOn()"]
  9373d797_a688_263a_ed31_d047e2450a06 -->|calls| 927861bc_81ae_46e9_c8b8_1f8444803d6c
  c31c8ee9_821b_1478_1429_c044db2ed0f2["update()"]
  9373d797_a688_263a_ed31_d047e2450a06 -->|calls| c31c8ee9_821b_1478_1429_c044db2ed0f2
  31164af1_b812_4e89_c9b6_11fac44d336d["insert()"]
  9373d797_a688_263a_ed31_d047e2450a06 -->|calls| 31164af1_b812_4e89_c9b6_11fac44d336d
  style 9373d797_a688_263a_ed31_d047e2450a06 fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

drizzle-orm/src/pg-core/db.ts lines 178–397

	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(): PgSelectBuilder<undefined>;
		function select<TSelection extends SelectedFields>(fields: TSelection): PgSelectBuilder<TSelection>;
		function select<TSelection extends SelectedFields>(fields?: TSelection): PgSelectBuilder<TSelection | undefined> {
			return new PgSelectBuilder({
				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(): PgSelectBuilder<undefined>;
		function selectDistinct<TSelection extends SelectedFields>(fields: TSelection): PgSelectBuilder<TSelection>;
		function selectDistinct<TSelection extends SelectedFields>(
			fields?: TSelection,
		): PgSelectBuilder<TSelection | undefined> {
			return new PgSelectBuilder({
				fields: fields ?? undefined,