with() — drizzle-orm Function Reference

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

Function typescript DrizzleORM RelationalQuery calls 5

Entity Profile

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

Dependency Diagram

graph TD
  de082ae7_ed27_1ff7_a0ea_26b4841c3633["with()"]
  2d57d0b7_4a77_af8e_8027_62a4fb11f803["GelDatabase"]
  de082ae7_ed27_1ff7_a0ea_26b4841c3633 -->|defined in| 2d57d0b7_4a77_af8e_8027_62a4fb11f803
  8b6fe780_2735_4d40_58d5_5812a013740c["select()"]
  de082ae7_ed27_1ff7_a0ea_26b4841c3633 -->|calls| 8b6fe780_2735_4d40_58d5_5812a013740c
  c3eded38_37aa_4fe4_bd2c_4904f6aec4e4["selectDistinct()"]
  de082ae7_ed27_1ff7_a0ea_26b4841c3633 -->|calls| c3eded38_37aa_4fe4_bd2c_4904f6aec4e4
  629dd302_a3f5_ca4b_2314_108ea327f807["selectDistinctOn()"]
  de082ae7_ed27_1ff7_a0ea_26b4841c3633 -->|calls| 629dd302_a3f5_ca4b_2314_108ea327f807
  530dda0f_a6c2_24bc_0de1_af7772e2b801["update()"]
  de082ae7_ed27_1ff7_a0ea_26b4841c3633 -->|calls| 530dda0f_a6c2_24bc_0de1_af7772e2b801
  2dfa5289_723e_ca21_62bb_5086546fc2fc["insert()"]
  de082ae7_ed27_1ff7_a0ea_26b4841c3633 -->|calls| 2dfa5289_723e_ca21_62bb_5086546fc2fc
  style de082ae7_ed27_1ff7_a0ea_26b4841c3633 fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

drizzle-orm/src/gel-core/db.ts lines 161–378

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