复合类型

警告

复合类型仅适用于 MongoDB。

复合类型，在 MongoDB 中称为嵌入式文档，允许你在其他记录中嵌入记录。

我们在 v3.12.0 中将复合类型设为普遍可用。它们之前在 v3.10.0 的预览中可用。

本页面解释了如何

查找使用 findFirst 和 findMany 包含复合类型的记录
创建使用 create 和 createMany 包含复合类型的新记录
更新使用 update 和 updateMany 在现有记录中更新复合类型
删除使用 delete 和 deleteMany 包含复合类型的记录

示例模式

我们将使用以下示例中的模式

schema.prisma

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "mongodb"
  url      = env("DATABASE_URL")
}

model Product {
  id     String  @id @default(auto()) @map("_id") @db.ObjectId
  name   String  @unique
  price  Float
  colors Color[]
  sizes  Size[]
  photos Photo[]
  orders Order[]
}

model Order {
  id              String   @id @default(auto()) @map("_id") @db.ObjectId
  product         Product  @relation(fields: [productId], references: [id])
  color           Color
  size            Size
  shippingAddress Address
  billingAddress  Address?
  productId       String   @db.ObjectId
}

enum Color {
  Red
  Green
  Blue
}

enum Size {
  Small
  Medium
  Large
  XLarge
}

type Photo {
  height Int    @default(200)
  width  Int    @default(100)
  url    String
}

type Address {
  street String
  city   String
  zip    String
}

在此模式中，Product 模型具有 Photo[] 复合类型，而 Order 模型具有两种复合 Address 类型。shippingAddress 是必需的，但 billingAddress 是可选的。

使用复合类型时的注意事项

目前在 Prisma 客户端中使用复合类型时存在一些限制

findUnique() 无法在复合类型上进行过滤
aggregate，groupBy()，count 不支持复合操作

复合类型上必需字段的默认值

从版本 4.0.0 开始，如果你在以下所有条件都满足的情况下对复合类型执行数据库读取，则 Prisma 客户端会将默认值插入结果中。

条件

复合类型上的字段是必需的，并且
此字段具有默认值，并且
此字段未出现在返回的文档或文档中。

注意

这与模型字段相同的行为。
在读取操作中，Prisma 客户端会将默认值插入结果中，但不会将默认值插入数据库。

在我们的示例模式中，假设你向 photo 添加了一个必需字段。此字段 bitDepth 具有一个默认值

schema.prisma

...
type Photo {
  ...
  bitDepth Int @default(8)
}

...

假设你随后运行 npx prisma db push 以更新你的数据库并使用 npx prisma generate 重新生成 Prisma 客户端。然后，你运行以下应用程序代码

console.dir(await prisma.product.findMany({}), { depth: Infinity })

bitDepth 字段没有内容，因为你只是添加了此字段，因此查询返回默认值 8。

** 较早版本 **

在版本 4.0.0 之前，Prisma ORM 会抛出以下 P2032 错误

Error converting field "bitDepth" of expected non-nullable
type "int", found incompatible value of "null".

使用 `find` 和 `findMany` 查找包含复合类型的记录

可以在 where 操作中根据复合类型过滤记录。

以下部分描述了可用于按单个类型或多个类型过滤的操作，并提供了每个操作的示例。

过滤一个复合类型

使用 is、equals、isNot 和 isSet 操作更改单个复合类型

is：通过匹配复合类型过滤结果。要求至少有一个字段存在 (例如，按送货地址上的街道名称过滤订单)
equals：通过匹配复合类型过滤结果。要求所有字段都存在。 (例如，按完整送货地址过滤订单)
isNot：通过不匹配的复合类型过滤结果
isSet ：过滤可选字段，仅包含已设置的结果（设置为值或明确设置为 null）。将此过滤器设置为 true 将排除未设置的 undefined 结果。

例如，使用 is 过滤街道名称为 '555 Candy Cane Lane' 的订单

const orders = await prisma.order.findMany({
  where: {
    shippingAddress: {
      is: {
        street: '555 Candy Cane Lane',
      },
    },
  },
})

使用 equals 过滤所有字段都与送货地址匹配的订单

const orders = await prisma.order.findMany({
  where: {
    shippingAddress: {
      equals: {
        street: '555 Candy Cane Lane',
        city: 'Wonderland',
        zip: '52337',
      },
    },
  },
})

你还可以使用此查询的简写形式，其中你省略 equals

const orders = await prisma.order.findMany({
  where: {
    shippingAddress: {
      street: '555 Candy Cane Lane',
      city: 'Wonderland',
      zip: '52337',
    },
  },
})

使用 isNot 过滤邮政编码不为 '52337' 的订单

const orders = await prisma.order.findMany({
  where: {
    shippingAddress: {
      isNot: {
        zip: '52337',
      },
    },
  },
})

使用 isSet 过滤可选 billingAddress 已设置（设置为值或设置为 null）的订单

const orders = await prisma.order.findMany({
  where: {
    billingAddress: {
      isSet: true,
    },
  },
})

过滤多个复合类型

使用 equals、isEmpty、every、some 和 none 操作过滤多个复合类型

equals：检查列表的完全相等性
isEmpty：检查列表是否为空
every：列表中的每个项目都必须匹配条件
some：列表中的一个或多个项目必须匹配条件
none：列表中的任何项目都不能匹配条件
isSet ：过滤可选字段，仅包含已设置的结果（设置为值或明确设置为 null）。将此过滤器设置为 true 将排除未设置的 undefined 结果。

例如，你可以使用 equals 查找具有特定照片列表的产品（所有 url、height 和 width 字段都必须匹配）

const product = prisma.product.findMany({
  where: {
    photos: {
      equals: [
        {
          url: '1.jpg',
          height: 200,
          width: 100,
        },
        {
          url: '2.jpg',
          height: 200,
          width: 100,
        },
      ],
    },
  },
})

你还可以使用此查询的简写形式，其中你省略 equals 并仅指定你想要过滤的字段

const product = prisma.product.findMany({
  where: {
    photos: [
      {
        url: '1.jpg',
        height: 200,
        width: 100,
      },
      {
        url: '2.jpg',
        height: 200,
        width: 100,
      },
    ],
  },
})

使用 isEmpty 过滤没有照片的产品

const product = prisma.product.findMany({
  where: {
    photos: {
      isEmpty: true,
    },
  },
})

使用 some 过滤一个或多个照片的 url 为 "2.jpg" 的产品

const product = prisma.product.findFirst({
  where: {
    photos: {
      some: {
        url: '2.jpg',
      },
    },
  },
})

使用 none 过滤没有照片的 url 为 "2.jpg" 的产品

const product = prisma.product.findFirst({
  where: {
    photos: {
      none: {
        url: '2.jpg',
      },
    },
  },
})

使用 `create` 和 `createMany` 创建包含复合类型的记录

信息

当你使用具有唯一约束的复合类型创建记录时，请注意 MongoDB 不会强制执行记录内的唯一值。了解更多.

可以使用 set 操作在 create 或 createMany 方法中创建复合类型。例如，你可以在 create 中使用 set 在 Order 中创建一个 Address 复合类型

const order = await prisma.order.create({
  data: {
    // Normal relation
    product: { connect: { id: 'some-object-id' } },
    color: 'Red',
    size: 'Large',
    // Composite type
    shippingAddress: {
      set: {
        street: '1084 Candycane Lane',
        city: 'Silverlake',
        zip: '84323',
      },
    },
  },
})

你还可以使用简写形式，其中你省略 set 并仅指定你想要创建的字段

const order = await prisma.order.create({
  data: {
    // Normal relation
    product: { connect: { id: 'some-object-id' } },
    color: 'Red',
    size: 'Large',
    // Composite type
    shippingAddress: {
      street: '1084 Candycane Lane',
      city: 'Silverlake',
      zip: '84323',
    },
  },
})

对于可选类型，例如 billingAddress，你还可以将值设置为 null

const order = await prisma.order.create({
  data: {
    // Normal relation
    product: { connect: { id: 'some-object-id' } },
    color: 'Red',
    size: 'Large',
    // Composite type
    shippingAddress: {
      street: '1084 Candycane Lane',
      city: 'Silverlake',
      zip: '84323',
    },
    // Embedded optional type, set to null
    billingAddress: {
      set: null,
    },
  },
})

为了模拟 product 包含多个 photos 列表的情况，你可以一次性 set 多个复合类型

const product = await prisma.product.create({
  data: {
    name: 'Forest Runners',
    price: 59.99,
    colors: ['Red', 'Green'],
    sizes: ['Small', 'Medium', 'Large'],
    // New composite type
    photos: {
      set: [
        { height: 100, width: 200, url: '1.jpg' },
        { height: 100, width: 200, url: '2.jpg' },
      ],
    },
  },
})

你还可以使用简写形式，其中你省略 set 并仅指定你想要创建的字段

const product = await prisma.product.create({
  data: {
    name: 'Forest Runners',
    price: 59.99,
    // Scalar lists that we already support
    colors: ['Red', 'Green'],
    sizes: ['Small', 'Medium', 'Large'],
    // New composite type
    photos: [
      { height: 100, width: 200, url: '1.jpg' },
      { height: 100, width: 200, url: '2.jpg' },
    ],
  },
})

这些操作也适用于 createMany 方法。例如，你可以创建多个 product，每个 product 都包含 photos 列表

const product = await prisma.product.createMany({
  data: [
    {
      name: 'Forest Runners',
      price: 59.99,
      colors: ['Red', 'Green'],
      sizes: ['Small', 'Medium', 'Large'],
      photos: [
        { height: 100, width: 200, url: '1.jpg' },
        { height: 100, width: 200, url: '2.jpg' },
      ],
    },
    {
      name: 'Alpine Blazers',
      price: 85.99,
      colors: ['Blue', 'Red'],
      sizes: ['Large', 'XLarge'],
      photos: [
        { height: 100, width: 200, url: '1.jpg' },
        { height: 150, width: 200, url: '4.jpg' },
        { height: 200, width: 200, url: '5.jpg' },
      ],
    },
  ],
})

在 `update` 和 `updateMany` 中更改复合类型

信息

当您更新具有唯一约束的复合类型的记录时，请注意，MongoDB 不会在记录内部强制执行唯一值。了解更多.

复合类型可以在 update 或 updateMany 方法中设置、更新或删除。以下部分描述了可用于更新单个类型或多个类型的操作，并提供每个操作的示例。

更改单个复合类型

使用 set、unset update 和 upsert 操作来更改单个复合类型

使用 set 设置复合类型，覆盖任何现有值
使用 unset 取消设置复合类型。与 set: null 不同，unset 会完全删除该字段
使用 update 更新复合类型
使用 upsert 如果存在则 update 现有复合类型，否则 set 复合类型

例如，使用 update 更新 Order 中 Address 复合类型内的必需 shippingAddress

const order = await prisma.order.update({
  where: {
    id: 'some-object-id',
  },
  data: {
    shippingAddress: {
      // Update just the zip field
      update: {
        zip: '41232',
      },
    },
  },
})

对于可选的嵌入式类型，例如 billingAddress，使用 upsert 如果不存在则创建新记录，如果存在则更新记录

const order = await prisma.order.update({
  where: {
    id: 'some-object-id',
  },
  data: {
    billingAddress: {
      // Create the address if it doesn't exist,
      // otherwise update it
      upsert: {
        set: {
          street: '1084 Candycane Lane',
          city: 'Silverlake',
          zip: '84323',
        },
        update: {
          zip: '84323',
        },
      },
    },
  },
})

您也可以使用 unset 操作删除可选的嵌入式类型。以下示例使用 unset 从 Order 中删除 billingAddress

const order = await prisma.order.update({
  where: {
    id: 'some-object-id',
  },
  data: {
    billingAddress: {
      // Unset the billing address
      // Removes "billingAddress" field from order
      unset: true,
    },
  },
})

您可以在 updateMany 中使用过滤器来更新与复合类型匹配的所有记录。以下示例使用 is 过滤器来匹配订单列表中来自送货地址的街道名称

const orders = await prisma.order.updateMany({
  where: {
    shippingAddress: {
      is: {
        street: '555 Candy Cane Lane',
      },
    },
  },
  data: {
    shippingAddress: {
      update: {
        street: '111 Candy Cane Drive',
      },
    },
  },
})

更改多个复合类型

使用 set、push、updateMany 和 deleteMany 操作来更改复合类型的列表

set：设置嵌入的复合类型列表，覆盖任何现有列表
push：将值推送到嵌入的复合类型列表的末尾
updateMany：一次更新多个复合类型
deleteMany：一次删除多个复合类型

例如，使用 push 将新照片添加到 photos 列表

const product = prisma.product.update({
  where: {
    id: '62de6d328a65d8fffdae2c18',
  },
  data: {
    photos: {
      // Push a photo to the end of the photos list
      push: [{ height: 100, width: 200, url: '1.jpg' }],
    },
  },
})

使用 updateMany 更新 url 为 1.jpg 或 2.png 的照片

const product = prisma.product.update({
  where: {
    id: '62de6d328a65d8fffdae2c18',
  },
  data: {
    photos: {
      updateMany: {
        where: {
          url: '1.jpg',
        },
        data: {
          url: '2.png',
        },
      },
    },
  },
})

以下示例使用 deleteMany 删除所有 height 为 100 的照片

const product = prisma.product.update({
  where: {
    id: '62de6d328a65d8fffdae2c18',
  },
  data: {
    photos: {
      deleteMany: {
        where: {
          height: 100,
        },
      },
    },
  },
})

使用 `upsert` 更新复合类型

信息

当您创建或更新具有唯一约束的复合类型中的值时，请注意，MongoDB 不会在记录内部强制执行唯一值。了解更多.

要创建或更新复合类型，请使用 upsert 方法。您可以使用与上面的 create 和 update 方法相同的复合操作。

例如，使用 upsert 创建新产品或将照片添加到现有产品

const product = await prisma.product.upsert({
  where: {
    name: 'Forest Runners',
  },
  create: {
    name: 'Forest Runners',
    price: 59.99,
    colors: ['Red', 'Green'],
    sizes: ['Small', 'Medium', 'Large'],
    photos: [
      { height: 100, width: 200, url: '1.jpg' },
      { height: 100, width: 200, url: '2.jpg' },
    ],
  },
  update: {
    photos: {
      push: { height: 300, width: 400, url: '3.jpg' },
    },
  },
})

使用 `delete` 和 `deleteMany` 删除包含复合类型的记录

要删除嵌入复合类型的记录，请使用 delete 或 deleteMany 方法。这也会删除嵌入的复合类型。

例如，使用 deleteMany 删除所有 size 为 "Small" 的产品。这也会删除任何嵌入的 photos。

const deleteProduct = await prisma.product.deleteMany({
  where: {
    sizes: {
      equals: 'Small',
    },
  },
})

您也可以使用过滤器来删除与复合类型匹配的记录。以下示例使用 some 过滤器来删除包含特定照片的产品

const product = await prisma.product.deleteMany({
  where: {
    photos: {
      some: {
        url: '2.jpg',
      },
    },
  },
})

排序复合类型

您可以使用 orderBy 操作以升序或降序排列结果。

例如，以下命令查找所有订单，并按送货地址中的城市名称升序排列

const orders = await prisma.order.findMany({
  orderBy: {
    shippingAddress: {
      city: 'asc',
    },
  },
})

复合类型唯一字段中的重复值

在对具有唯一约束的复合类型的记录执行以下任何操作时，请小心。在这种情况下，MongoDB 不会在记录内部强制执行唯一值。

当您创建记录时
当您向记录添加数据时
当您更新记录中的数据时

如果您的模式具有带有 @@unique 约束的复合类型，则 MongoDB 会阻止您在包含此复合类型的两个或多个记录中存储受约束值的相同值。但是，MongoDB 不会阻止您在单个记录中存储相同字段值的多个副本。

请注意，您可以使用 Prisma ORM 关系来解决此问题.

例如，在以下模式中，MailBox 具有一个复合类型 addresses，该类型对 email 字段具有 @@unique 约束。

type Address {
  email String
}

model MailBox {
  name      String
  addresses Address[]

  @@unique([addresses.email])
}

以下代码创建一个记录，其中 address 中有两个相同的值。MongoDB 在这种情况下不会抛出错误，并且它在 addresses 中两次存储 [email protected]。

await prisma.MailBox.createMany({
  data: [
    {
      name: 'Alice',
      addresses: {
        set: [
          {
            address: '[email protected]', // Not unique
          },
          {
            address: '[email protected]', // Not unique
          },
        ],
      },
    },
  ],
})

注意：如果您尝试在两个单独的记录中存储相同的值，MongoDB 会抛出错误。在上面的示例中，如果您尝试为用户 Alice 和用户 Bob 存储电子邮件地址 [email protected]，MongoDB 不会存储数据并会抛出错误。

使用 Prisma ORM 关系在记录中强制执行唯一值

在上面的示例中，MongoDB 并未对嵌套的地址名称强制执行唯一约束。但是，您可以以不同的方式对数据进行建模以在记录中强制执行唯一值。为此，请使用 Prisma ORM 关系将复合类型转换为集合。为此集合设置关系，并在要设置为唯一的字段上放置唯一约束。

在以下示例中，MongoDB 在记录中强制执行唯一值。Mailbox 和 Address 模型之间存在关系。此外，Address 模型中的 name 字段具有唯一约束。

model Address {
  id        String   @id @default(auto()) @map("_id") @db.ObjectId
  name      String
  mailbox   Mailbox? @relation(fields: [mailboxId], references: [id])
  mailboxId String?  @db.ObjectId

  @@unique([name])
}

model Mailbox {
  id        String    @id @default(auto()) @map("_id") @db.ObjectId
  name      String
  addresses Address[] @relation
}

await prisma.MailBox.create({
  data: {
    name: 'Alice',
    addresses: {
      create: [
        { name: '[email protected]' }, // Not unique
        { name: '[email protected]' }, // Not unique
      ],
    },
  },
})

如果您运行上面的代码，MongoDB 将强制执行唯一约束。它不允许您的应用程序添加两个名称为 [email protected] 的地址。

示例模式​

使用复合类型时的注意事项​

复合类型上必需字段的默认值​

使用 find 和 findMany 查找包含复合类型的记录​

过滤一个复合类型​

过滤多个复合类型​

使用 create 和 createMany 创建包含复合类型的记录​

在 update 和 updateMany 中更改复合类型​

更改单个复合类型​

更改多个复合类型​

使用 upsert 更新复合类型​

使用 delete 和 deleteMany 删除包含复合类型的记录​

排序复合类型​

复合类型唯一字段中的重复值​

使用 Prisma ORM 关系在记录中强制执行唯一值​