关系查询

Prisma 客户端的一项关键功能是能够查询两个或多个模型之间的关系。关系查询包括

嵌套读取（有时称为急切加载），通过 select 和 include
嵌套写入，具有事务保证
筛选相关记录

Prisma 客户端还具有用于遍历关系的流畅 API。

嵌套读取

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

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

关系加载策略 (预览)

从版本5.8.0 开始，您可以决定如何在查询级别让 Prisma 客户端执行关系查询（即应用什么加载策略），方法是使用 PostgreSQL 数据库的 relationLoadStrategy 选项。

从版本5.10.0 开始，此功能也适用于 MySQL。

由于 relationLoadStrategy 选项目前处于预览阶段，您需要通过 Prisma 架构文件中的 relationJoins 预览功能标志启用它

schema.prisma

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["relationJoins"]
}

添加此标志后，您需要再次运行 prisma generate 以重新生成 Prisma 客户端。此功能目前在 PostgreSQL、CockroachDB 和 MySQL 上可用。

Prisma 客户端支持两种关系加载策略

join（默认）：使用数据库级别的 LATERAL JOIN（PostgreSQL）或相关子查询（MySQL）并通过对数据库的单个查询获取所有数据。
query：向数据库发送多个查询（每个表一个），并在应用程序级别进行连接。

这两个选项之间另一个重要的区别是 join 策略在数据库级别使用 JSON 聚合。这意味着它在数据库中创建了 Prisma 客户端返回的 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 选项以包含关系的关系。以下示例返回用户的帖子以及每个帖子的类别

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。这意味着，如果您选择包含用户的帖子并选择每个帖子的标题，则不能仅选择用户的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 及更高版本中，您可以包含或选择关系的计数以及字段 - 例如，用户的帖子计数。

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 客户端查询中跨多个表创建、更新或删除数据提供事务保证。如果查询的任何部分失败（例如，创建用户成功，但创建帖子失败），Prisma 客户端将回滚所有更改。
支持数据模型支持的任何嵌套级别。
在使用模型的创建或更新查询时，可用于关系字段。以下部分显示了每个查询可用的嵌套写入选项。

您可以同时创建记录和一个或多个相关记录。以下查询创建 User 记录和两个相关的 Post 记录

const result = await prisma.user.create({
  data: {
    email: '[email protected]',
    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 查询

在大多数情况下，除非需要skipDuplicates 查询选项，否则嵌套的 create 将是更好的选择。以下是一个快速表格，描述了这两个选项之间的区别

功能	`create`	`createMany`	注释
支持嵌套其他关系	✔	✘ *	例如，您可以在一个查询中创建一个用户、多个帖子以及每个帖子的多个评论。 * 你可以在一对一关系中手动设置外键 - 例如：`{ authorId: 9}`
支持 1-n 关系	✔	✔	例如，您可以创建一个用户和多个帖子（一个用户有多个帖子）
支持 m-n 关系	✔	✘	例如，您可以创建一个帖子和多个类别（一个帖子可以有多个类别，一个类别可以有多个帖子）
支持跳过重复记录	✘	✔	使用 `skipDuplicates` 查询选项。

使用嵌套 `create`

以下查询使用嵌套的 create 来创建

一个用户
两个帖子
一个帖子类别

此示例还使用嵌套的 include 将所有帖子和帖子类别包含在返回的数据中。

const result = await prisma.user.create({
  data: {
    email: '[email protected]',
    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: '[email protected]',
    posts: {
      createMany: {
        data: [{ title: 'My first post' }, { title: 'My second post' }],
      },
    },
  },
  include: {
    posts: true,
  },
})

显示查询结果

警告

注意：在突出显示的查询中，无法嵌套额外的 create 或 createMany，这意味着您不能同时创建用户、帖子和帖子类别。

您无法在 createMany() 或 createManyAndReturn() 查询中访问关系，这意味着您不能在单个嵌套写入中创建多个用户和多个帖子。以下操作不可行

const createMany = await prisma.user.createMany({
  data: [
    {
      name: 'Yewande',
      email: '[email protected]',
      posts: {
        // Not possible to create posts!
      },
    },
    {
      name: 'Noor',
      email: '[email protected]',
      posts: {
        // Not possible to create posts!
      },
    },
  ],
})

连接多个记录

以下查询创建 (create ) 一个新的 User 记录，并将该记录 (connect ) 连接到三个现有的帖子

const result = await prisma.user.create({
  data: {
    email: '[email protected]',
    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 连接相关记录

使用电子邮件地址 [email protected] 连接 User或
如果用户不存在，则使用电子邮件地址 [email protected] 创建一个新的 User

const result = await prisma.post.create({
  data: {
    title: 'How to make croissants',
    author: {
      connectOrCreate: {
        where: {
          email: '[email protected]',
        },
        create: {
          email: '[email protected]',
          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 一对多关系中所有相关记录（一个用户有多个帖子），请将关系设置为如所示的空列表

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 更新 "[email protected]"（如果该用户存在），或创建该用户（如果该用户不存在）

const result = await prisma.post.update({
  where: {
    id: 6,
  },
  data: {
    author: {
      upsert: {
        create: {
          email: '[email protected]',
          name: 'Bob the New User',
        },
        update: {
          email: '[email protected]',
          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,
  },
})

关系筛选器

筛选“-to-many”关系

Prisma Client 提供了 some、every 和 none 选项，根据关系“-to-many”一侧相关记录的属性筛选记录。例如，根据用户的帖子的属性筛选用户。

例如

要求	要使用的查询选项
"我想要一个包含至少一个未发布 `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,
  },
})

筛选“-to-one”关系

Prisma Client 提供了 is 和 isNot 选项，根据关系“-to-one”一侧相关记录的属性筛选记录。例如，根据帖子的作者的属性筛选帖子。

例如，以下查询返回满足以下条件的 Post 记录

作者姓名不是 Bob
作者年龄超过 40 岁

const users = await prisma.post.findMany({
  where: {
    author: {
      isNot: {
        name: 'Bob',
      },
      is: {
        age: {
          gt: 40,
        },
      },
    },
  },
  include: {
    author: true,
  },
})

筛选“-to-many”记录的缺失

例如，以下查询使用 none 返回所有没有帖子的用户

const usersWithZeroPosts = await prisma.user.findMany({
  where: {
    posts: {
      none: {},
    },
  },
  include: {
    posts: true,
  },
})

筛选“-to-one”关系的缺失

以下查询返回所有没有作者关系的帖子

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: '[email protected]' } })
  .posts()

这等效于以下 findMany 查询

const postsByUser = await prisma.post.findMany({
  where: {
    author: {
      email: '[email protected]',
    },
  },
})

这两个查询的主要区别在于，流畅 API 调用被翻译成两个独立的数据库查询，而另一个查询只生成一个查询（请参阅此 GitHub 问题）。

注意：您可以利用 .findUnique({ where: { email: '[email protected]' } }).posts() 查询通过 Prisma Client 中的 Prisma 数据加载器自动批处理，从而避免 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()

嵌套读取​

关系加载策略 (预览)​

示例​

何时使用哪种加载策略？​

包含关系​

包含特定关系的所有字段​

包含深度嵌套的关系​

选择包含关系的特定字段​

关系计数​

筛选关系列表​

嵌套写入​

创建相关记录​

创建单个记录和多个相关记录​

使用嵌套 create​

使用嵌套 createMany​

创建多个记录和多个相关记录​

连接多个记录​

连接单个记录​

连接或创建记录​

断开相关记录​

断开所有相关记录​

删除所有相关记录​

删除特定的相关记录​

更新所有相关记录（或筛选）​

更新特定相关记录​

更新或创建相关记录​

向现有记录添加新的相关记录​

关系筛选器​

筛选“-to-many”关系​

筛选“-to-one”关系​

筛选“-to-many”记录的缺失​

筛选“-to-one”关系的缺失​

筛选相关记录的存在​

流畅 API​

嵌套读取

关系加载策略 (预览)

示例

何时使用哪种加载策略？

包含关系

包含特定关系的所有字段

包含深度嵌套的关系

选择包含关系的特定字段

关系计数

筛选关系列表

嵌套写入

创建相关记录

创建单个记录和多个相关记录

使用嵌套 `create`

使用嵌套 `createMany`

创建多个记录和多个相关记录

连接多个记录

连接单个记录

连接或创建记录

断开相关记录

断开所有相关记录

删除所有相关记录

删除特定的相关记录

更新所有相关记录（或筛选）

更新特定相关记录

更新或创建相关记录

向现有记录添加新的相关记录

关系筛选器

筛选“-to-many”关系

筛选“-to-one”关系

筛选“-to-many”记录的缺失

筛选“-to-one”关系的缺失

筛选相关记录的存在

流畅 API