跳到主要内容

关系查询

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

Prisma Client 还提供用于遍历关系的流畅 API

嵌套读取

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

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

关系加载策略(预览)

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

从版本 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 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,
},
},
},
})
显示查询结果

请注意,你不能同一级别使用 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 会回滚所有更改。
  • 支持数据模型支持的任何嵌套级别。
  • 在使用模型的创建或更新查询时,适用于关系字段。以下部分显示了每个查询可用的嵌套写入选项。

你可以同时创建一条记录和一条或多条相关记录。以下查询创建一条 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
},
},
},
})
显示查询结果

以下是嵌套创建操作如何一次写入数据库中多个表的视觉表示

使用嵌套的 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.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.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,
},
})
显示查询结果

要从记录列表中 断开连接 一条(例如,一篇特定的博客文章),请提供要断开连接的记录的 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 中嵌套 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 选项,用于根据关系“多对多”侧相关记录的属性过滤记录。例如,根据用户帖子的属性过滤用户。

例如

要求要使用的查询选项
"我想要一个具有至少一个未发布 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 提供 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()
© . All rights reserved.