跳到正文
Drizzle

Joins

Drizzle join 完整参考:inner/left/right/full/cross 与 lateral、多表与子查询 join、自连接别名、嵌套结果类型与关系查询的取舍。

join 用于按关联列把多张表拼进一条 SQL。Drizzle 的 join 语法在 SQL 直译与类型安全之间取平衡:结果默认按表名嵌套成对象,可空性由 join 类型自动推导。本页使用如下 schema:

import { integer, pgTable, serial, text } from 'drizzle-orm/pg-core';

export const users = pgTable('users', {
  id: serial().primaryKey(),
  name: text().notNull(),
  age: integer(),
});

export const pets = pgTable('pets', {
  id: serial().primaryKey(),
  name: text().notNull(),
  ownerId: integer('owner_id').notNull().references(() => users.id),
});

Join 类型一览

方法SQL结果中哪侧可为 null
innerJoin(t, on)INNER JOIN两侧都非空
leftJoin(t, on)LEFT JOIN右表对象整体为 ... 或 null
rightJoin(t, on)RIGHT JOIN左表对象整体为 ... 或 null
fullJoin(t, on)FULL JOIN两侧都可能为 null
crossJoin(t)CROSS JOIN无 on 条件,笛卡尔积
import { eq } from 'drizzle-orm';
import { db } from './db';
import { users, pets } from './db/schema';

const result = await db.select().from(users)
  .leftJoin(pets, eq(users.id, pets.ownerId));

// 结果类型:每行一个嵌套对象
// { users: { id: number; name: string; age: number | null };
//   pets: { id: number; name: string; ownerId: number } | null }[]

没有宠物的用户仍会出现在结果里,pets 为 null——类型系统如实反映了这一点。innerJoin 则两侧都非空;rightJoin/fullJoin 镜像处理。

多表 join

链式追加即可,on 条件可以引用前面任何一张表。下例中 usersToChatGroups 是含 userId、groupId 两列的多对多中间表:

// 多对多:用户 ↔ 中间表 ↔ 群组
await db.select()
  .from(usersToChatGroups)
  .leftJoin(users, eq(usersToChatGroups.userId, users.id))
  .leftJoin(chatGroups, eq(usersToChatGroups.groupId, chatGroups.id))
  .where(eq(chatGroups.id, 1));

部分选择:扁平与嵌套结果

不想要按表嵌套时,用 select({...}) 自定义结果形状:

const rows = await db.select({
  userId: users.id,
  petId: pets.id, // leftJoin 下自动推导为 number | null
}).from(users).leftJoin(pets, eq(users.id, pets.ownerId));
// { userId: number; petId: number | null }[]

列多时可用嵌套 select 对象:整个对象可空,而不是每个字段都可空,类型更干净:

import { sql } from 'drizzle-orm';

await db.select({
  userId: users.id,
  userName: users.name,
  pet: {
    id: pets.id,
    name: pets.name,
    upperName: sql<string>`upper(${pets.name})`,
  },
}).from(users).fullJoin(pets, eq(users.id, pets.ownerId));
// pet 整体为 { ... } | null

sql 表达式的可空性要自己标

sql 表达式列不会自动获得 null 推导。leftJoin 的右表列做表达式时,显式写 sql<string | null>,否则结果类型不准确(不写泛型则是 unknown)。

join 子查询与 LATERAL

任何 .as('别名') 的子查询都能当表 join:

import { lt } from 'drizzle-orm';

const youngPets = db.select().from(pets).where(lt(pets.id, 100)).as('young_pets');
await db.select().from(users).leftJoin(youngPets, eq(users.id, youngPets.ownerId));

PG 支持 LATERAL:子查询可以引用左侧表的列。对应 leftJoinLateral / innerJoinLateral / crossJoinLateral:

import { gte, sql } from 'drizzle-orm';

const subquery = db.select().from(pets).where(gte(users.age, 16)).as('user_pets');
await db.select().from(users).leftJoinLateral(subquery, sql`true`);
// left join lateral (select ... from "pets" where "users"."age" >= 16) "user_pets" on true

自连接与表别名

同一张表 join 自己必须起别名,alias() 从各方言的 core 包导入:

import { alias } from 'drizzle-orm/pg-core';

// users 表含 parentId 自引用列
const parent = alias(users, 'parent');
const rows = await db.select().from(users)
  .leftJoin(parent, eq(parent.id, users.parentId));
// { users: {...}; parent: {...} | null }[]

别名同样可用于 update … from(见 SQL Update)。

聚合扁平行

join 结果是“每行一条组合”的扁平数据,一对多会重复左表行。需要“一个用户带宠物数组”时自行归并:

const rows = await db.select({ user: users, pet: pets })
  .from(users).leftJoin(pets, eq(users.id, pets.ownerId));

const byUser: Record<number, { user: typeof users.$inferSelect; pets: (typeof pets.$inferSelect)[] }> = {};
for (const { user, pet } of rows) {
  byUser[user.id] ??= { user, pets: [] };
  if (pet) byUser[user.id].pets.push(pet); // leftJoin 无匹配时 pet 为 null
}

也可在 SQL 端用 json_agg/array_agg 聚合(配合 sql 模板与 groupBy),把归并交给数据库。

join 还是关系查询?

场景建议
需要过滤/排序/聚合关联表的列,精确控制一条 SQLjoin(本页)
只是“取实体及其关联”,想要嵌套 JSON 结果关系查询 RQB,免写 on 条件与归并逻辑

两者可以混用:列表页用 join 做筛选分页,详情页用 RQB 取完整关联树。