跳到主要内容

关系查询

Prisma Client 的一个关键特性是能够查询两个或多个模型之间的关系。关系查询包括

Prisma Client 还具有用于遍历关系的流畅 API

嵌套读取

嵌套读取允许你从数据库中的多个表读取相关数据 - 例如用户以及该用户的帖子。你可以

  • 使用 include 在查询响应中包含相关记录,例如用户的帖子或个人资料。
  • 使用嵌套的 select 从相关记录中包含特定字段。你还可以将 select 嵌套在 include 内部。

关系加载策略(预览版)

5.8.0 版本以来,你可以决定在每个查询级别如何希望 Prisma Client 执行关系查询(即应应用什么加载策略),通过 PostgreSQL 数据库的 relationLoadStrategy 选项。

5.10.0 版本以来,此功能也适用于 MySQL。

由于 relationLoadStrategy 选项目前处于预览版,你需要通过 Prisma schema 文件中的 relationJoins 预览功能标志来启用它

schema.prisma
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 将普遍成为所有关系查询的默认设置。

示例

你可以在任何支持 includeselect 的查询的顶层使用 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,
},
},
},
})
显示查询结果

请注意,你不能同一级别上使用 selectinclude。这意味着,如果你选择 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
}
}
},
})
显示CLI结果

相反,请使用嵌套的 select 选项

const user = await prisma.user.findFirst({
select: {
// This will work!
email: true,
posts: {
select: {
title: true,
},
},
},
})

关系计数

3.0.1 及更高版本中,你可以 includeselect 关系的计数 以及字段 - 例如,用户的帖子计数。

const relationCount = await prisma.user.findMany({
include: {
_count: {
select: { posts: true },
},
},
})
显示查询结果

过滤关系列表

当你使用 selectinclude 返回相关数据的子集时,你可以在 selectinclude 内部过滤和排序关系列表

例如,以下查询返回与用户关联的未发布帖子的标题列表

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 将是首选,除非需要 skipDuplicates 查询选项。这是一个快速表格,描述了这两个选项之间的区别

功能createcreateMany注释
支持嵌套其他关系✘ *例如,你可以在一个查询中创建一个用户、多个帖子以及每个帖子的多个评论。
* 你可以在一对一关系中手动设置外键 - 例如:{ 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,
},
})
显示查询结果

请注意,不可能在突出显示的查询内部嵌套额外的 createcreateMany,这意味着你不能同时创建一个用户、帖子和帖子类别。

作为一种解决方法,你可以发送一个查询来首先创建将被连接的记录,然后创建实际的记录。例如

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.ioUser
  • 如果用户尚不存在,则创建一个新的电子邮件地址为 viola@prisma.ioUser
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 内部嵌套 createcreateMany,以向现有记录添加新的相关记录。以下查询向 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 提供了 someeverynone 选项,用于按关系“一对多”侧的相关记录的属性过滤记录。例如,根据用户的帖子属性过滤用户。

例如

要求要使用的查询选项
“我想要一个 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 提供了 isisNot 选项,用于按关系“一对一”侧的相关记录的属性过滤记录。例如,根据帖子的作者属性过滤帖子。

例如,以下查询返回符合以下条件的 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 开始,经过 UserPost

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()