关系查询
Prisma Client 的一个关键特性是能够查询两个或多个模型之间的关系。关系查询包括:
Prisma Client 还提供用于遍历关系的流畅 API。
嵌套读取
嵌套读取允许你从数据库中的多个表读取相关数据,例如用户及其帖子。你可以:
关系加载策略(预览)
从版本 5.8.0 开始,你可以通过 PostgreSQL 数据库的 relationLoadStrategy
选项,在每个查询级别决定 Prisma Client 如何执行关系查询(即应该应用哪种加载策略)。
从版本 5.10.0 开始,此功能也适用于 MySQL。
由于 relationLoadStrategy
选项目前处于预览阶段,你需要在 Prisma schema 文件中通过 relationJoins
预览功能标志启用它
generator client {
provider = "prisma-client-js"
previewFeatures = ["relationJoins"]
}
添加此标志后,你需要再次运行 prisma generate
以重新生成 Prisma Client。relationJoins
功能目前在 PostgreSQL、CockroachDB 和 MySQL 上可用。
Prisma Client 支持两种关系加载策略
join
(默认):使用数据库级别的LATERAL JOIN
(PostgreSQL) 或相关子查询 (MySQL),并通过一次数据库查询获取所有数据。query
:向数据库发送多个查询(每个表一个),并在应用程序级别进行连接。
这两个选项之间的另一个重要区别是 join
策略在数据库级别使用 JSON 聚合。这意味着它在数据库中就已经创建了 Prisma Client 返回的 JSON 结构,从而节省了应用程序级别的计算资源。
示例
你可以在任何支持 include
或 select
的查询的顶层使用 relationLoadStrategy
选项。
以下是使用 include
的示例
const users = await prisma.user.findMany({
relationLoadStrategy: 'join', // or 'query'
include: {
posts: true,
},
})
以下是另一个使用 select
的示例
const users = await prisma.user.findMany({
relationLoadStrategy: 'join', // or 'query'
select: {
posts: true,
},
})
何时使用哪种加载策略?
- 在大多数情况下,
join
策略(默认)会更有效。在 PostgreSQL 上,它结合使用LATERAL JOINs
和 JSON 聚合来减少结果集中的冗余,并将查询结果转换为预期 JSON 结构的工作委托给数据库服务器。在 MySQL 上,它使用相关子查询通过单个查询获取结果。 - 在某些边缘情况下,根据数据集和查询的特性,
query
可能会表现更好。我们建议你分析数据库查询以识别这些情况。 - 如果你想节省数据库服务器上的资源,并在应用程序服务器中进行大量的数据合并和转换工作(这可能更容易扩展),请使用
query
。
包含关系
以下示例返回单个用户及其帖子
const user = await prisma.user.findFirst({
include: {
posts: true,
},
})
包含特定关系的所有字段
以下示例返回帖子及其作者
const post = await prisma.post.findFirst({
include: {
author: true,
},
})
包含深度嵌套的关系
你可以嵌套 include
选项以包含关系的关系。以下示例返回用户的帖子以及每个帖子的类别
const user = await prisma.user.findFirst({
include: {
posts: {
include: {
categories: true,
},
},
},
})
选择包含关系的特定字段
你可以使用嵌套的 select
来选择要返回的关系字段子集。例如,以下查询返回用户的 name
和每个相关帖子的 title
const user = await prisma.user.findFirst({
select: {
name: true,
posts: {
select: {
title: true,
},
},
},
})
你也可以在 include
中嵌套 select
- 以下示例返回所有 User
字段和每个帖子的 title
字段
const user = await prisma.user.findFirst({
include: {
posts: {
select: {
title: true,
},
},
},
})
请注意,你不能在同一级别使用 select
和 include
。这意味着如果你选择 include
用户的帖子并 select
每个帖子的标题,你不能只 select
用户的 email
// The following query returns an exception
const user = await prisma.user.findFirst({
select: { // This won't work!
email: true
}
include: { // This won't work!
posts: {
select: {
title: true
}
}
},
})
相反,请使用嵌套的 select
选项
const user = await prisma.user.findFirst({
select: {
// This will work!
email: true,
posts: {
select: {
title: true,
},
},
},
})
关系计数
在 3.0.1 及更高版本中,你可以include
或 select
关系计数以及字段——例如,用户的帖子计数。
const relationCount = await prisma.user.findMany({
include: {
_count: {
select: { posts: true },
},
},
})
过滤关系列表
当你使用 select
或 include
返回相关数据的子集时,你可以在 select
或 include
内部过滤和排序关系列表。
例如,以下查询返回与用户关联的未发布帖子标题列表
const result = await prisma.user.findFirst({
select: {
posts: {
where: {
published: false,
},
orderBy: {
title: 'asc',
},
select: {
title: true,
},
},
},
})
你也可以使用 include
编写相同的查询,如下所示
const result = await prisma.user.findFirst({
include: {
posts: {
where: {
published: false,
},
orderBy: {
title: 'asc',
},
},
},
})
嵌套写入
嵌套写入允许你通过单次事务将关系数据写入数据库。
嵌套写入
- 为在单个 Prisma Client 查询中跨多个表创建、更新或删除数据提供事务保证。如果查询的任何部分失败(例如,创建用户成功但创建帖子失败),Prisma Client 会回滚所有更改。
- 支持数据模型支持的任何嵌套级别。
- 在使用模型的创建或更新查询时,适用于关系字段。以下部分显示了每个查询可用的嵌套写入选项。
创建相关记录
你可以同时创建一条记录和一条或多条相关记录。以下查询创建一条 User
记录和两条相关的 Post
记录
const result = await prisma.user.create({
data: {
email: 'elsa@prisma.io',
name: 'Elsa Prisma',
posts: {
create: [
{ title: 'How to make an omelette' },
{ title: 'How to eat an omelette' },
],
},
},
include: {
posts: true, // Include all posts in the returned object
},
})
创建单个记录和多个相关记录
有两种方法可以创建或更新单个记录和多个相关记录——例如,一个用户拥有多个帖子
- 使用嵌套的
create
查询 - 使用嵌套的
createMany
查询
在大多数情况下,嵌套的 create
更受欢迎,除非需要skipDuplicates
查询选项。这是一个描述两种选项之间差异的快速表格
功能 | create | createMany | 备注 |
---|---|---|---|
支持嵌套额外关系 | ✔ | ✘ * | 例如,你可以在一个查询中创建用户、多个帖子和每个帖子的多个评论。 * 你可以在一对一关系中手动设置外键——例如: { authorId: 9} |
支持一对多关系 | ✔ | ✔ | 例如,你可以创建一个用户和多个帖子(一个用户有多个帖子) |
支持多对多关系 | ✔ | ✘ | 例如,你可以创建一个帖子和多个类别(一个帖子可以有多个类别,一个类别可以有多个帖子) |
支持跳过重复记录 | ✘ | ✔ | 使用 skipDuplicates 查询选项。 |
使用嵌套的 create
以下查询使用嵌套的 create
来创建
- 一个用户
- 两个帖子
- 一个帖子类别
该示例还使用嵌套的 include
将所有帖子和帖子类别包含在返回的数据中。
const result = await prisma.user.create({
data: {
email: 'yvette@prisma.io',
name: 'Yvette',
posts: {
create: [
{
title: 'How to make an omelette',
categories: {
create: {
name: 'Easy cooking',
},
},
},
{ title: 'How to eat an omelette' },
],
},
},
include: {
// Include posts
posts: {
include: {
categories: true, // Include post categories
},
},
},
})
以下是嵌套创建操作如何一次写入数据库中多个表的视觉表示
使用嵌套的 createMany
以下查询使用嵌套的 createMany
来创建
- 一个用户
- 两个帖子
该示例还使用嵌套的 include
将所有帖子包含在返回的数据中。
const result = await prisma.user.create({
data: {
email: 'saanvi@prisma.io',
posts: {
createMany: {
data: [{ title: 'My first post' }, { title: 'My second post' }],
},
},
},
include: {
posts: true,
},
})
请注意,无法在突出显示的查询中嵌套额外的 create
或 createMany
,这意味着你无法同时创建用户、帖子和帖子类别。
作为变通方法,你可以先发送一个查询来创建将要连接的记录,然后创建实际记录。例如
const categories = await prisma.category.createManyAndReturn({
data: [
{ name: 'Fun', },
{ name: 'Technology', },
{ name: 'Sports', }
],
select: {
id: true
}
});
const posts = await prisma.post.createManyAndReturn({
data: [{
title: "Funniest moments in 2024",
categoryId: categories.filter(category => category.name === 'Fun')!.id
}, {
title: "Linux or macOS — what's better?",
categoryId: categories.filter(category => category.name === 'Technology')!.id
},
{
title: "Who will win the next soccer championship?",
categoryId: categories.filter(category => category.name === 'Sports')!.id
}]
});
如果你想在单个数据库查询中创建所有记录,请考虑使用$transaction
或类型安全的原始 SQL。
创建多个记录和多个相关记录
你无法在 createMany()
或 createManyAndReturn()
查询中访问关系,这意味着你无法在单个嵌套写入中创建多个用户和多个帖子。以下情况不可能发生
const createMany = await prisma.user.createMany({
data: [
{
name: 'Yewande',
email: 'yewande@prisma.io',
posts: {
// Not possible to create posts!
},
},
{
name: 'Noor',
email: 'noor@prisma.io',
posts: {
// Not possible to create posts!
},
},
],
})
连接多条记录
以下查询创建一个新的 User
记录(create
),并将该记录(connect
)连接到三个现有帖子
const result = await prisma.user.create({
data: {
email: 'vlad@prisma.io',
posts: {
connect: [{ id: 8 }, { id: 9 }, { id: 10 }],
},
},
include: {
posts: true, // Include all posts in the returned object
},
})
注意:如果任何帖子记录无法找到,Prisma Client 将抛出异常:
connect: [{ id: 8 }, { id: 9 }, { id: 10 }]
连接单个记录
你可以将现有记录连接
到新用户或现有用户。以下查询将现有帖子(id: 11
)连接到现有用户(id: 9
)
const result = await prisma.user.update({
where: {
id: 9,
},
data: {
posts: {
connect: {
id: 11,
},
},
},
include: {
posts: true,
},
})
连接或创建记录
如果相关记录可能存在也可能不存在,请使用 connectOrCreate
连接相关记录
- 连接电子邮件地址为
viola@prisma.io
的User
或 - 如果用户不存在,则创建新的电子邮件地址为
viola@prisma.io
的User
const result = await prisma.post.create({
data: {
title: 'How to make croissants',
author: {
connectOrCreate: {
where: {
email: 'viola@prisma.io',
},
create: {
email: 'viola@prisma.io',
name: 'Viola',
},
},
},
},
include: {
author: true,
},
})
断开相关记录
要从记录列表中 断开连接
一条(例如,一篇特定的博客文章),请提供要断开连接的记录的 ID 或唯一标识符
const result = await prisma.user.update({
where: {
id: 16,
},
data: {
posts: {
disconnect: [{ id: 12 }, { id: 19 }],
},
},
include: {
posts: true,
},
})
要 断开连接
一条记录(例如,帖子的作者),请使用 disconnect: true
const result = await prisma.post.update({
where: {
id: 23,
},
data: {
author: {
disconnect: true,
},
},
include: {
author: true,
},
})
断开所有相关记录
要 断开
一对多关系中所有相关记录(一个用户有多个帖子),请将关系 设置
为空列表,如下所示
const result = await prisma.user.update({
where: {
id: 16,
},
data: {
posts: {
set: [],
},
},
include: {
posts: true,
},
})
删除所有相关记录
删除所有相关的 Post
记录
const result = await prisma.user.update({
where: {
id: 11,
},
data: {
posts: {
deleteMany: {},
},
},
include: {
posts: true,
},
})
删除特定的相关记录
通过删除所有未发布的帖子来更新用户
const result = await prisma.user.update({
where: {
id: 11,
},
data: {
posts: {
deleteMany: {
published: false,
},
},
},
include: {
posts: true,
},
})
通过删除特定帖子来更新用户
const result = await prisma.user.update({
where: {
id: 6,
},
data: {
posts: {
deleteMany: [{ id: 7 }],
},
},
include: {
posts: true,
},
})
更新所有相关记录(或过滤)
你可以使用嵌套的 updateMany
来更新特定用户的所有相关记录。以下查询将特定用户的所有帖子设置为未发布状态
const result = await prisma.user.update({
where: {
id: 6,
},
data: {
posts: {
updateMany: {
where: {
published: true,
},
data: {
published: false,
},
},
},
},
include: {
posts: true,
},
})
更新特定相关记录
const result = await prisma.user.update({
where: {
id: 6,
},
data: {
posts: {
update: {
where: {
id: 9,
},
data: {
title: 'My updated title',
},
},
},
},
include: {
posts: true,
},
})
更新或创建相关记录
以下查询使用嵌套的 upsert
来更新 "bob@prisma.io"
(如果该用户存在),或者如果用户不存在则创建该用户
const result = await prisma.post.update({
where: {
id: 6,
},
data: {
author: {
upsert: {
create: {
email: 'bob@prisma.io',
name: 'Bob the New User',
},
update: {
email: 'bob@prisma.io',
name: 'Bob the existing user',
},
},
},
},
include: {
author: true,
},
})
向现有记录添加新的相关记录
你可以在 update
中嵌套 create
或 createMany
以向现有记录添加新的相关记录。以下查询向 id
为 9 的用户添加两个帖子
const result = await prisma.user.update({
where: {
id: 9,
},
data: {
posts: {
createMany: {
data: [{ title: 'My first post' }, { title: 'My second post' }],
},
},
},
include: {
posts: true,
},
})
关系过滤器
过滤“-多对多”关系
Prisma Client 提供 some
、every
和 none
选项,用于根据关系“多对多”侧相关记录的属性过滤记录。例如,根据用户帖子的属性过滤用户。
例如
要求 | 要使用的查询选项 |
---|---|
"我想要一个具有至少一个未发布 Post 记录的 User 列表" | some 帖子未发布 |
"我想要一个没有未发布 Post 记录的 User 列表" | none 帖子未发布 |
"我想要一个只有未发布 Post 记录的 User 列表" | every 帖子都未发布 |
例如,以下查询返回符合以下条件的 User
:
- 没有浏览量超过 100 的帖子
- 所有帖子点赞数少于或等于 50
const users = await prisma.user.findMany({
where: {
posts: {
none: {
views: {
gt: 100,
},
},
every: {
likes: {
lte: 50,
},
},
},
},
include: {
posts: true,
},
})
过滤“-一对一”关系
Prisma Client 提供 is
和 isNot
选项,用于根据关系“-一对一”侧相关记录的属性过滤记录。例如,根据帖子作者的属性过滤帖子。
例如,以下查询返回符合以下条件的 Post
记录
- 作者姓名不是 Bob
- 作者年龄大于 40 岁
const users = await prisma.post.findMany({
where: {
author: {
isNot: {
name: 'Bob',
},
is: {
age: {
gt: 40,
},
},
},
},
include: {
author: true,
},
})
过滤不存在的“-多对多”记录
例如,以下查询使用 none
返回所有没有帖子的用户
const usersWithZeroPosts = await prisma.user.findMany({
where: {
posts: {
none: {},
},
},
include: {
posts: true,
},
})
过滤不存在的“-一对一”关系
以下查询返回所有没有作者关系的帖子
const postsWithNoAuthor = await prisma.post.findMany({
where: {
author: null, // or author: { }
},
include: {
author: true,
},
})
过滤是否存在相关记录
以下查询返回所有至少有一个帖子的用户
const usersWithSomePosts = await prisma.user.findMany({
where: {
posts: {
some: {},
},
},
include: {
posts: true,
},
})
流畅 API
流畅 API 允许你通过函数调用流畅地遍历模型的关系。请注意,最后一个函数调用决定了整个查询的返回类型(下面的代码片段中添加了相应的类型注释以使其明确)。
此查询返回特定 User
的所有 Post
记录
const postsByUser: Post[] = await prisma.user
.findUnique({ where: { email: 'alice@prisma.io' } })
.posts()
这等同于以下 findMany
查询
const postsByUser = await prisma.post.findMany({
where: {
author: {
email: 'alice@prisma.io',
},
},
})
这些查询的主要区别在于,流畅 API 调用被翻译成两个独立的数据库查询,而另一个只生成一个查询(参见此 GitHub issue)
注意:你可以利用
.findUnique({ where: { email: 'alice@prisma.io' } }).posts()
查询由 Prisma Client 中的 Prisma dataloader 自动批处理的事实,以避免 GraphQL 解析器中的 n+1 问题。
此请求返回特定帖子的所有类别
const categoriesOfPost: Category[] = await prisma.post
.findUnique({ where: { id: 1 } })
.categories()
请注意,你可以随意串联任意数量的查询。在此示例中,串联从 Profile
开始,通过 User
到 Post
const posts: Post[] = await prisma.profile
.findUnique({ where: { id: 1 } })
.user()
.posts()
链式调用的唯一要求是前一个函数调用必须只返回一个单个对象(例如,由 findUnique
查询或“一对一关系”如 profile.user()
返回)。
以下查询是不可能的,因为 findMany
不返回单个对象,而是返回一个列表
// This query is illegal
const posts = await prisma.user.findMany().posts()