关系查询
Prisma Client 的一个关键特性是能够查询两个或多个模型之间的关系。关系查询包括
Prisma Client 还具有用于遍历关系的流畅 API。
嵌套读取
嵌套读取允许你从数据库中的多个表读取相关数据 - 例如用户以及该用户的帖子。你可以
关系加载策略(预览版)
自 5.8.0 版本以来,你可以决定在每个查询级别如何希望 Prisma Client 执行关系查询(即应应用什么加载策略),通过 PostgreSQL 数据库的 relationLoadStrategy
选项。
自 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 结构,从而节省了应用程序级别的计算资源。
注意:一旦
relationLoadStrategy
从预览版移至正式发布版,join
将普遍成为所有关系查询的默认设置。
示例
你可以在任何支持 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 JOIN
和 JSON 聚合的组合来减少结果集中的冗余,并将查询结果转换为数据库服务器上预期的 JSON 结构的工作委托给数据库服务器。在 MySQL 上,它使用相关子查询通过单个查询获取结果。 - 在某些极端情况下,根据数据集和查询的特性,
query
可能会更高效。我们建议你分析你的数据库查询以识别这些情况。 - 如果你想节省数据库服务器上的资源,并在应用程序服务器中进行合并和转换数据的繁重工作,而应用程序服务器可能更容易扩展,请使用
query
。
包含关系
以下示例返回单个用户以及该用户的帖子
const user = await prisma.user.findFirst({
include: {
posts: true,
},
})
包含特定关系的所有字段
以下示例返回帖子及其作者
const post = await prisma.post.findFirst({
include: {
author: true,
},
})
包含深度嵌套的关系
你可以嵌套 include
选项以包含关系的 relation。以下示例返回用户的帖子以及每个帖子的类别
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,
},
},
},
})
你还可以将 select
嵌套在 include
内部 - 以下示例返回所有 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 会回滚所有更改。
- 支持数据模型支持的任何级别的嵌套。
- 当使用模型的 create 或 update 查询时,可用于关系字段。以下部分显示了每个查询可用的嵌套写入选项。
创建相关记录
你可以同时创建一个记录和一个或多个相关记录。以下查询创建一个 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
},
},
},
})
这是一个可视化表示,说明嵌套的 create 操作如何一次写入数据库中的多个表
使用嵌套的 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[0].id
}, {
title: "Linux or macOS — what's better?",
categoryId: categories[1].id
},
{
title: "Who will win the next soccer championship?",
categoryId: categories[2].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!
},
},
],
})
连接多个记录
以下查询创建 (create
) 一个新的 User
记录,并将该记录 (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 }]
连接单个记录
你可以 connect
一个现有记录到一个新的或现有用户。以下查询将现有帖子 (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,
},
})
断开相关记录
要从记录列表中 disconnect
一个记录(例如,特定的博客文章),请提供要断开连接的记录的 ID 或唯一标识符
const result = await prisma.user.update({
where: {
id: 16,
},
data: {
posts: {
disconnect: [{ id: 12 }, { id: 19 }],
},
},
include: {
posts: true,
},
})
要 disconnect
一个记录(例如,帖子的作者),请使用 disconnect: true
const result = await prisma.post.update({
where: {
id: 23,
},
data: {
author: {
disconnect: true,
},
},
include: {
author: true,
},
})
断开所有相关记录
要 disconnect
一对多关系中的所有相关记录(一个用户有很多帖子),请将关系 set
为空列表,如下所示
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
选项,用于按关系“一对多”侧的相关记录的属性过滤记录。例如,根据用户的帖子属性过滤用户。
例如
要求 | 要使用的查询选项 |
---|---|
“我想要一个 User 列表,其中每个 User 都有至少一个未发布的 Post 记录” | some 帖子未发布 |
“我想要一个 User 列表,其中每个 User 都没有未发布的 Post 记录” | none 帖子未发布 |
“我想要一个 User 列表,其中每个 User 都只有未发布的 Post 记录” | 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()