跳至主要内容

使用 Json 字段

使用 Json Prisma ORM 字段类型在底层数据库中读取、写入和执行 JSON 类型的基本过滤。在以下示例中，User 模型有一个名为 extendedPetsData 的可选 Json 字段

model User {
  id               Int     @id @default(autoincrement())
  email            String  @unique
  name             String?
  posts            Post[]
  extendedPetsData Json?
}

示例字段值

{
  "pet1": {
    "petName": "Claudine",
    "petType": "House cat"
  },
  "pet2": {
    "petName": "Sunny",
    "petType": "Gerbil"
  }
}

注意：只有当 底层数据库 具有相应的 JSON 数据类型时，Json 字段才受支持。

Json 字段支持一些额外的类型，例如 string 和 boolean。这些额外的类型存在是为了匹配 JSON.parse() 支持的类型。

export declare type JsonValue =
  | string
  | number
  | boolean
  | null
  | JsonObject
  | JsonArray

JSON 字段的用例 ​

将数据存储为 JSON 而不是将数据表示为相关模型的原因包括

  • 您需要存储没有一致结构的数据
  • 您正在从另一个系统导入数据，并且不想将该数据映射到 Prisma 模型

读取 Json 字段 ​

您可以使用 Prisma.JsonArray 和 Prisma.JsonObject 实用程序类来处理 Json 字段的内容

const { PrismaClient, Prisma } = require('@prisma/client')

const user = await prisma.user.findFirst({
  where: {
    id: 9,
  },
})

// Example extendedPetsData data:
// [{ name: 'Bob the dog' }, { name: 'Claudine the cat' }]

if (
  user?.extendedPetsData &&
  typeof user?.extendedPetsData === 'object' &&
  Array.isArray(user?.extendedPetsData)
) {
  const petsObject = user?.extendedPetsData as Prisma.JsonArray

  const firstPet = petsObject[0]
}

另请参阅：高级示例：更新嵌套 JSON 键值

写入 Json 字段 ​

以下示例将 JSON 对象写入 extendedPetsData 字段

var json = [
  { name: 'Bob the dog' },
  { name: 'Claudine the cat' },
] as Prisma.JsonArray

const createUser = await prisma.user.create({
  data: {
    email: '[email protected]',
    extendedPetsData: json,
  },
})

注意：JavaScript 对象（例如 { extendedPetsData: "none"}）会自动转换为 JSON。

另请参阅：高级示例：更新嵌套 JSON 键值

在 Json 字段上过滤（简单） ​

您可以过滤 Json 类型的行。

过滤精确字段值 ​

以下查询返回 extendedPetsData 值与 json 变量完全匹配的所有用户

var json = { [{ name: 'Bob the dog' }, { name: 'Claudine the cat' }] }

const getUsers = await prisma.user.findMany({
  where: {
    extendedPetsData: {
      equals: json,
    },
  },
})

以下查询返回 extendedPetsData 值与 json 变量完全不匹配的所有用户

var json = {
  extendedPetsData: [{ name: 'Bob the dog' }, { name: 'Claudine the cat' }],
}

const getUsers = await prisma.user.findMany({
  where: {
    extendedPetsData: {
      not: json,
    },
  },
})

在 Json 字段上过滤（高级） ​

您还可以根据 Json 字段内的数据过滤行。我们称之为高级 Json 过滤。此功能仅由 PostgreSQL 和 MySQL 支持，它们使用 不同的 path 选项语法。

警告

PostgreSQL 不支持 过滤数组内的对象键值。

信息

高级 Json 过滤的可用性取决于您的 Prisma 版本

  • v4.0.0 或更高版本：高级 Json 过滤 已普遍可用。
  • 从 v2.23.0 开始，但在 v4.0.0 之前：高级 Json 过滤是 预览功能。将 previewFeatures = ["filterJson"] 添加到您的模式中。 了解更多。
  • v2.23.0 之前：您可以 过滤精确 Json 字段值，但不能使用本节中描述的其他功能。

path 语法取决于数据库 ​

以下过滤器使用 path 选项来选择 Json 值的特定部分进行过滤。该过滤的实现因连接器而异

例如，以下是一个有效的 MySQL path 值

$petFeatures.petName

以下是一个有效的 PostgreSQL path 值

["petFeatures", "petName"]

过滤对象属性 ​

您可以过滤 JSON 块内的特定属性。在以下示例中，extendedPetsData 的值为一维、非嵌套 JSON 对象

{
  "petName": "Claudine",
  "petType": "House cat"
}

以下查询返回 petName 值为 "Claudine" 的所有用户

const getUsers = await prisma.user.findMany({
  where: {
    extendedPetsData: {
      path: ['petName'],
      equals: 'Claudine',
    },
  },
})

以下查询返回 petType 值包含 "cat" 的所有用户

const getUsers = await prisma.user.findMany({
  where: {
    extendedPetsData: {
      path: ['petType'],
      string_contains: 'cat',
    },
  },
})

以下字符串过滤器可用

过滤嵌套对象属性 ​

您可以过滤嵌套 JSON 属性。在以下示例中，extendedPetsData 的值为具有多个嵌套级别的 JSON 对象。

{
  "pet1": {
    "petName": "Claudine",
    "petType": "House cat"
  },
  "pet2": {
    "petName": "Sunny",
    "petType": "Gerbil",
    "features": {
      "eyeColor": "Brown",
      "furColor": "White and black"
    }
  }
}

以下查询返回 "pet2" → "petName" 为 "Sunny" 的所有用户

const getUsers = await prisma.user.findMany({
  where: {
    extendedPetsData: {
      path: ['pet2', 'petName'],
      equals: 'Sunny',
    },
  },
})

以下查询返回所有满足以下条件的用户：

  • "pet2" → "petName" 为 "Sunny"
  • "pet2" → "features" → "furColor" 包含 "black"
const getUsers = await prisma.user.findMany({
  where: {
    AND: [
      {
        extendedPetsData: {
          path: ['pet2', 'petName'],
          equals: 'Sunny',
        },
      },
      {
        extendedPetsData: {
          path: ['pet2', 'features', 'furColor'],
          string_contains: 'black',
        },
      },
    ],
  },
})

过滤数组值 ​

您可以过滤标量数组（字符串、整数）中是否存在特定值。在以下示例中，extendedPetsData 的值为字符串数组

["Claudine", "Sunny"]

以下查询返回宠物名为 "Claudine" 的所有用户

const getUsers = await prisma.user.findMany({
  where: {
    extendedPetsData: {
      array_contains: ['Claudine'],
    },
  },
})
信息

注意：在 PostgreSQL 中，array_contains 的值必须是数组，而不是字符串，即使该数组仅包含单个值。

以下数组过滤器可用

过滤嵌套数组值 ​

您可以过滤标量数组（字符串、整数）中是否存在特定值。在以下示例中，extendedPetsData 的值包含嵌套的标量名称数组

{
  "cats": { "owned": ["Bob", "Sunny"], "fostering": ["Fido"] },
  "dogs": { "owned": ["Ella"], "fostering": ["Prince", "Empress"] }
}

标量值数组 ​

以下查询返回收养了名为 "Fido" 的猫的所有用户

const getUsers = await prisma.user.findMany({
  where: {
    extendedPetsData: {
      path: ['cats', 'fostering'],
      array_contains: ['Fido'],
    },
  },
})
信息

注意：在 PostgreSQL 中，array_contains 的值必须是数组，而不是字符串，即使该数组仅包含单个值。

以下查询返回收养了名为 "Fido" 和 "Bob" 的猫的所有用户

const getUsers = await prisma.user.findMany({
  where: {
    extendedPetsData: {
      path: ['cats', 'fostering'],
      array_contains: ['Fido', 'Bob'],
    },
  },
})

JSON 对象数组 ​

const json = [{ status: 'expired', insuranceID: 92 }]

const checkJson = await prisma.user.findMany({
  where: {
    extendedPetsData: {
      path: ['insurances'],
      array_contains: json,
    },
  },
})

  • 如果您使用的是 PostgreSQL，则必须传入一个对象数组进行匹配，即使该数组只包含一个对象

    [{ status: 'expired', insuranceID: 92 }]
    // PostgreSQL

    如果您使用的是 MySQL，则必须传入一个对象进行匹配

    { status: 'expired', insuranceID: 92 }
    // MySQL

  • 如果您的过滤器数组包含多个对象，PostgreSQL 仅当所有对象都存在时才会返回结果 - 而不是至少存在一个对象。

  • 您必须将 array_contains 设置为 JSON 对象，而不是字符串。如果您使用字符串，Prisma Client 会转义引号，查询将不会返回结果。例如

    array_contains: '[{"status": "expired", "insuranceID": 92}]'

    发送到数据库

    [{\"status\": \"expired\", \"insuranceID\": 92}]

通过索引定位数组元素 ​

您可以过滤特定位置的元素的值。

{ "owned": ["Bob", "Sunny"], "fostering": ["Fido"] }
const getUsers = await prisma.user.findMany({
  where: {
    comments: {
      path: ['owned', '1'],
      string_contains: 'Bob',
    },
  },
})

过滤数组内的对象键值 ​

根据您的提供商，您可以过滤数组内的对象键值。

警告

在数组中根据对象键值进行过滤 **仅** 受 MySQL 数据库连接器 支持。但是，您仍然可以 根据整个 JSON 对象的存在进行过滤。

在以下示例中，extendedPetsData 的值是一个包含对象的数组，其中包含一个嵌套的 insurances 数组，该数组包含两个对象。

[
  {
    "petName": "Claudine",
    "petType": "House cat",
    "insurances": [
      { "insuranceID": 92, "status": "expired" },
      { "insuranceID": 12, "status": "active" }
    ]
  },
  {
    "petName": "Sunny",
    "petType": "Gerbil"
  },
  {
    "petName": "Gerald",
    "petType": "Corn snake"
  },
  {
    "petName": "Nanna",
    "petType": "Moose"
  }
]

以下查询返回所有至少有一只宠物是驼鹿的用户。

const getUsers = await prisma.user.findMany({
  where: {
    extendedPetsData: {
      path: '$[*].petType',
      array_contains: 'Moose',
    },
  },
})
  • $[*] 是宠物对象的根数组
  • petType 与任何宠物对象中的 petType 键匹配

以下查询返回所有至少有一只宠物保险已过期的用户。

const getUsers = await prisma.user.findMany({
  where: {
    extendedPetsData: {
      path: '$[*].insurances[*].status',
      array_contains: 'expired',
    },
  },
})
  • $[*] 是宠物对象的根数组
  • insurances[*] 与任何宠物对象中的任何 insurances 数组匹配
  • status 与任何保险对象中的任何 status 键匹配

高级示例：更新嵌套的 JSON 键值​

以下示例假定 extendedPetsData 的值为以下示例的变体

{
  "petName": "Claudine",
  "petType": "House cat",
  "insurances": [
    { "insuranceID": 92, "status": "expired" },
    { "insuranceID": 12, "status": "active" }
  ]
}

以下示例

  1. 获取所有用户
  2. 将每个保险对象的 "status" 更改为 "expired"
  3. 获取所有 ID 为 92 且保险已过期的用户
const userQueries: string | any[] = []

getUsers.forEach((user) => {
  if (
    user.extendedPetsData &&
    typeof user.extendedPetsData === 'object' &&
    !Array.isArray(user.extendedPetsData)
  ) {
    const petsObject = user.extendedPetsData as Prisma.JsonObject

    const i = petsObject['insurances']

    if (i && typeof i === 'object' && Array.isArray(i)) {
      const insurancesArray = i as Prisma.JsonArray

      insurancesArray.forEach((i) => {
        if (i && typeof i === 'object' && !Array.isArray(i)) {
          const insuranceObject = i as Prisma.JsonObject

          insuranceObject['status'] = 'expired'
        }
      })

      const whereClause = Prisma.validator<Prisma.UserWhereInput>()({
        id: user.id,
      })

      const dataClause = Prisma.validator<Prisma.UserUpdateInput>()({
        extendedPetsData: petsObject,
      })

      userQueries.push(
        prisma.user.update({
          where: whereClause,
          data: dataClause,
        })
      )
    }
  }
})

if (userQueries.length > 0) {
  console.log(userQueries.length + ' queries to run!')
  await prisma.$transaction(userQueries)
}

const json = [{ status: 'expired', insuranceID: 92 }]

const checkJson = await prisma.user.findMany({
  where: {
    extendedPetsData: {
      path: ['insurances'],
      array_contains: json,
    },
  },
})

console.log(checkJson.length)

使用 null 值​

SQL 数据库中 JSON 字段可能存在两种类型的 null 值。

  • 数据库 NULL：数据库中的值为 NULL。
  • JSON null：数据库中的值包含一个值为 null 的 JSON 值。

为了区分这些可能性，我们引入了三个您可以使用的 *null 枚举*

  • JsonNull：表示 JSON 中的 null 值。
  • DbNull：表示数据库中的 NULL 值。
  • AnyNull：表示 null JSON 值和 NULL 数据库值。（仅在过滤时）
信息

从 v4.0.0 开始，JsonNull、DbNull 和 AnyNull 是对象。在 v4.0.0 之前，它们是字符串。

信息
  • 在使用任何 *null 枚举* 进行过滤时，您不能使用简写并省略 equals 运算符。
  • 这些 *null 枚举* 不适用于 MongoDB，因为在 MongoDB 中，JSON null 和数据库 NULL 之间的区别不存在。
  • 这些 *null 枚举* 不适用于所有数据库中的 array_contains 运算符，因为 JSON 数组中只能包含 JSON null。由于 JSON 数组中不能包含数据库 NULL，因此 { array_contains: null } 不含糊。

例如

model Log {
  id   Int  @id
  meta Json
}

以下是如何使用 AnyNull 的示例

import { Prisma } from '@prisma/client'

prisma.log.findMany({
  where: {
    data: {
      meta: {
        equals: Prisma.AnyNull,
      },
    },
  },
})

插入 null 值​

这也适用于 create、update 和 upsert。要将 null 值插入 Json 字段，您需要编写

import { Prisma } from '@prisma/client'

prisma.log.create({
  data: {
    meta: Prisma.JsonNull,
  },
})

要将数据库 NULL 插入 Json 字段，您需要编写

import { Prisma } from '@prisma/client'

prisma.log.create({
  data: {
    meta: Prisma.DbNull,
  },
})

根据 null 值进行过滤​

要根据 JsonNull 或 DbNull 进行过滤，您需要编写

import { Prisma } from '@prisma/client'

prisma.log.findMany({
  where: {
    meta: {
      equals: Prisma.AnyNull,
    },
  },
})
信息

这些 *null 枚举* 不适用于 MongoDB，因为 MongoDB 不区分 JSON null 和数据库 NULL。它们也不适用于所有数据库中的 array_contains 运算符，因为 JSON 数组中只能包含 JSON null。由于 JSON 数组中不能包含数据库 NULL，因此 { array_contains: null } 不含糊。

类型化 Json​

默认情况下，Json 字段在 Prisma 模型中没有类型。要在这些字段内部实现强类型，您需要使用像 prisma-json-types-generator 这样的外部包来实现这一点。

使用 prisma-json-types-generator​

首先，安装并配置 prisma-json-types-generator 根据该包的说明进行操作。

然后，假设您有一个像下面这样的模型

model Log {
  id   Int  @id
  meta Json
}

您可以使用 抽象语法树注释 更新它并对其进行类型化。

schema.prisma
model Log {
  id Int @id

  /// [LogMetaType]
  meta Json
}

然后，确保您在包含在 tsconfig.json 中的类型声明文件中定义了上述类型。

types.ts
declare global {
  namespace PrismaJson {
    type LogMetaType = { timestamp: number; host: string }
  }
}

现在，在使用 Log.meta 时，它将被强类型化！

Json 常见问题解答​

您可以选择要返回的 JSON 键/值的子集吗？​

不能 - 现在还不能 选择要返回的 JSON 元素。Prisma Client 返回整个 JSON 对象。

您可以根据特定键的存在进行过滤吗？​

不能 - 现在还不能根据特定键的存在进行过滤。

是否支持不区分大小写的过滤？​

不能 - 不区分大小写的过滤 现在还不可用。

如何为 JSON 字段设置默认值？​

当您要为 Json 类型设置 @default 值时，您需要将它用双引号括起来放在 @default 属性中（并可能使用反斜杠转义任何 "内部" 双引号），例如

model User {
  id    Int  @id @default(autoincrement())
  json1 Json @default("[]")
  json2 Json @default("{ \"hello\": \"world\" }")
}