跳到正文
Drizzle

关联查询

用 defineRelations 声明 v2 关系(one/many/through),通过 db.query 的 with、columns、对象化 where 一次获取嵌套数据,并了解 v1 到 v2 的迁移要点。

真实页面往往需要嵌套数据:用户及其文章、文章及其评论。Drizzle 的关系查询(Relational Queries,RQB)让你在 schema 之外声明关系,然后用 db.query 按「对象图」形状取数。本页介绍 v2 API(drizzle-orm@rc / v1 beta),示例基于 PostgreSQL。

v2 取代了 relations()

旧版 relations(users, ({ one, many }) => ...) 属于 RQB v1,已被 defineRelations 取代;rc.5 起驱动中已移除 v1 支持。旧代码迁移见文末对照表与官方 relations-v1-v2 指南。

声明关系:defineRelations

所有表的关系集中在一处声明。假设 schema 如下:

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

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

export const posts = pgTable('posts', {
  id: integer().primaryKey(),
  content: text().notNull(),
  authorId: integer('author_id').references(() => users.id),
  createdAt: timestamp('created_at').notNull().defaultNow(),
});

export const comments = pgTable('comments', {
  id: integer().primaryKey(),
  content: text().notNull(),
  postId: integer('post_id').references(() => posts.id),
  authorId: integer('author_id').references(() => users.id),
});
import { defineRelations } from 'drizzle-orm';
import * as schema from './schema';

export const relations = defineRelations(schema, (r) => ({
  users: {
    posts: r.many.posts(), // 外键已声明,可省略 from/to 自动推断
  },
  posts: {
    author: r.one.users({
      from: r.posts.authorId,
      to: r.users.id,
    }),
    comments: r.many.comments(),
  },
  comments: {
    post: r.one.posts({ from: r.comments.postId, to: r.posts.id }),
    author: r.one.users({ from: r.comments.authorId, to: r.users.id }),
  },
}));
  • r.one.users({...}):单个对象;r.many.posts():对象数组。键名(author、posts)自定义,就是查询结果里的字段名。
  • from / to 指向列,接受单列或数组(复合外键)。
  • 回调参数 r 提供全部表与 one / many / through 的完整自动补全。

初始化时通过 relations 选项传入(不再需要 mode):

import { drizzle } from 'drizzle-orm/node-postgres';
import { relations } from './relations';

// 也可用 defineRelationsPart 拆分后合并:{ relations: { ...relations, ...part } }
const db = drizzle(process.env.DATABASE_URL, { relations });

one() 的选项

author: r.one.users({
  from: r.posts.authorId,
  to: r.users.id,
  optional: false,      // 类型上去掉 null(不创建数据库约束)
  alias: 'post_author', // 同两表间多条关系时用于消歧
  where: { verified: true }, // 预定义过滤(多态关系)
}),

many() 同样支持 alias 与 where。预定义过滤让「只取已验证作者」「只取已审核评论」成为关系本身的一部分(下两例假设存在 users.verified、posts.approved 列):

users: {
  approvedPosts: r.many.posts({ where: { approved: true } }),
},

自引用与多对多

自引用(如邀请人,schema 需有 invitedBy 列)直接指向同一张表:

users: { invitee: r.one.users({ from: r.users.invitedBy, to: r.users.id }) },

多对多用 through 穿过中间表(另假设有 groups 表与中间表 usersToGroups),查询时直接拿到目标表,无需手动映射:

users: {
  groups: r.many.groups({
    from: r.users.id.through(r.usersToGroups.userId),
    to: r.groups.id.through(r.usersToGroups.groupId),
  }),
},
groups: {
  participants: r.many.users(), // 反向可省略
},

查询:findMany 与 findFirst

const allUsers = await db.query.users.findMany();
const firstUser = await db.query.users.findFirst(); // 自动 limit 1

// with:嵌套携带关系,可无限层
const usersWithPosts = await db.query.users.findMany({
  with: {
    posts: {
      with: { comments: true },
    },
  },
});

columns 做字段裁剪(在 SQL 层面生效,仍是一条语句;同时出现 true 与 false 时,false 被忽略):

await db.query.posts.findMany({
  columns: { id: true, content: true }, // 只取这两列
  with: { comments: true },
});
await db.query.posts.findMany({ columns: { content: false } }); // 排除某列
await db.query.users.findMany({ columns: {}, with: { posts: true } }); // 只要关系

where:对象化过滤

v2 的 where 是对象而非回调。列名直接给值即 eq,也可用运算符对象:

await db.query.users.findMany({ where: { id: 1 } });

await db.query.posts.findMany({
  where: { id: 1 },
  with: {
    comments: { where: { createdAt: { lt: new Date() } } },
  },
});

支持的运算符:eq ne gt gte lt lte in notIn like ilike notLike notIlike isNull isNotNull arrayOverlaps arrayContained arrayContains,以及组合子 AND: []、OR: []、NOT: {} 和原生 RAW:

await db.query.users.findMany({
  where: {
    OR: [{ id: { gt: 10 } }, { name: { like: 'John%' } }],
    NOT: { name: { isNull: true } },
  },
});

还可以按关系过滤主表:

// id > 10 且至少有一篇以 M 开头文章的用户
await db.query.users.findMany({
  where: {
    id: { gt: 10 },
    posts: { content: { like: 'M%' } },
  },
});

// 只保留至少有一篇 post 的用户
await db.query.users.findMany({
  with: { posts: true },
  where: { posts: true },
});

orderBy、limit、offset

await db.query.posts.findMany({
  orderBy: { id: 'asc' },          // 对象写法
  limit: 5,
  offset: 2,
  with: {
    comments: {
      orderBy: { id: 'desc' },
      limit: 3,
      offset: 3,                   // v2 支持嵌套 offset
    },
  },
});

// 回调写法:自定义 SQL 或运算符
await db.query.posts.findMany({
  orderBy: (t) => sql`${t.id} asc`,
  with: { comments: { orderBy: (t, { desc }) => desc(t.id) } },
});

extras:附加字段与子查询

await db.query.users.findMany({
  with: { posts: true },
  extras: {
    loweredName: (t, { sql }) => sql<string>`lower(${t.name})`,
    postsCount: (t) => db.$count(posts, eq(posts.authorId, t.id)),
  },
});

必须通过回调参数引用列

在 orderBy、where.RAW、extras 及其子查询中,引用本表列必须用回调参数(如 t.id),不能直接用导入的表对象(users.id)——嵌套与自引用查询依赖回调暴露的别名表才能生成正确 SQL。另外 extras 不支持对本表行的聚合(无 group by),计数请用 db.$count 子查询。

软关系与外键

defineRelations 是应用层抽象:不生成外键、不影响数据库 schema。外键是数据库级约束,在每次写入时校验。两者互不依赖——没有外键(甚至数据库不支持外键)也能声明关系并查询;有外键时反向 many 还能省略 from/to。需要数据完整性保障时,请在 schema 中照常使用 .references()。

v1 → v2 迁移要点

v1(drizzle-orm@0.x)v2(drizzle-orm@rc)
每表一个 relations(table, ...)集中 defineRelations(schema, (r) => ...)
fields / references 数组from / to,单值或数组
relationNamealias
只有 many 也必须补 one可单独声明 many
多对多手动穿过中间表through 直达目标表
where: (t, { eq }) => eq(...)对象化 where,可选过滤需显式处理
orderBy 数组/回调对象或回调
drizzle(url, { schema, mode })drizzle(url, { relations }),无 mode
无optional: false、预定义 where、嵌套 offset、按关系过滤

也可用 drizzle-kit pull 从现有数据库直接生成 v2 关系定义。

关系查询 vs SQL join

RQB 输出嵌套对象、自动聚合,适合页面级「对象图」取数;join 输出扁平行,适合报表、聚合与跨表复杂过滤。两者可混用:同一项目中列表页用 db.query,统计报表用 db.select + join。

延伸阅读:查询工具、Join 查询、sql`` 模板运算符、事务。