跳至主要内容

API 参考

Accelerate API 参考文档基于以下模式

model User {
  id    Int     @id @default(autoincrement())
  name  String?
  email String  @unique
}

所有示例都基于User模型。

cacheStrategy​

使用 Prisma Client 的加速扩展，您可以为模型查询使用cacheStrategy参数，并使用ttl和swr参数为加速定义缓存策略。加速扩展要求您安装 Prisma Client 版本4.10.0。

选项​

cacheStrategy参数采用具有以下键的选项

选项示例类型必需描述
swr60Int否以秒为单位的陈旧-同时-重新验证时间。
ttl60Int否以秒为单位的生存时间。
标签["user"]String[]否tag作为变量来控制应用程序中特定查询的失效。它是一个可选的字符串数组，用于使缓存失效，每个标签仅包含字母数字字符和下划线，最大长度为 64 个字符。

示例​

向查询添加缓存策略，定义 60 秒的陈旧-同时-重新验证 (SWR) 值、60 秒的生存时间 (TTL) 值以及"emails_with_alice"的缓存标签

await prisma.user.findMany({
  where: {
    email: {
      contains: "[email protected]",
    },
  },
  cacheStrategy: {
    swr: 60,
    ttl: 60,
    tags: ["emails_with_alice"],
  },
});

支持的 Prisma Client 操作​

以下是支持cacheStrategy的所有读取查询操作的列表

信息

cacheStrategy参数不支持任何写入操作，例如create()。

withAccelerateInfo​

任何支持cacheStrategy的查询都可以附加withAccelerateInfo()来包装响应数据，并包含有关加速响应的附加信息。

要检索响应的状态，请使用

const { data, info } = await prisma.user
  .count({
    cacheStrategy: { ttl: 60, swr: 600 },
    where: { myField: 'value' },
  })
  .withAccelerateInfo()

console.dir(info)
信息

请注意响应对象的info属性。这是请求信息存储的位置。

返回类型​

info对象是AccelerateInfo类型，并遵循以下接口

interface AccelerateInfo {
  cacheStatus: 'ttl' | 'swr' | 'miss' | 'none'
  lastModified: Date
  region: string
  requestId: string
  signature: string
}
属性类型描述
cacheStatus"ttl" | "swr" | "miss" | "none"响应的缓存状态。
  • ttl表示在ttl持续时间内缓存命中，并且未执行数据库查询
  • swr表示在swr持续时间内缓存命中，并且数据正在后台由加速刷新
  • miss表示ttl和swr都已过期，并且请求已执行数据库查询
  • none表示未指定缓存策略，并且请求已执行数据库查询
lastModifiedDate响应最后刷新的日期。
地区String接收请求的数据中心区域。
requestIdString请求的唯一标识符。对故障排除很有用。
签名StringPrisma 操作的唯一签名。

$accelerate.invalidate​

您可以使用$accelerate.invalidate API使缓存失效。

注意

要按需使缓存的查询结果失效，需要付费计划。每个计划对每天允许的基于缓存标签的失效次数都有特定限制，但对调用$accelerate.invalidate API 本身没有限制。有关更多详细信息，请参阅我们的定价。

示例​

要使下面的查询失效

await prisma.user.findMany({
  where: {
    email: {
      contains: "[email protected]",
    },
  },
  cacheStrategy: {
    swr: 60,
    ttl: 60,
    tags: ["emails_with_alice"],
  },
});

您需要在$accelerate.invalidate API 中提供缓存标签

try {
  await prisma.$accelerate.invalidate({
    tags: ["emails_with_alice"],
  });
} catch (e) {
  if (e instanceof Prisma.PrismaClientKnownRequestError) {
    // The .code property can be accessed in a type-safe manner
    if (e.code === "P6003") {
      console.log(
        "The cache invalidation rate limit has been reached. Please try again later."
      );
    }
  }
  throw e;
}
注意

每次调用可以使最多 5 个标签失效。

错误​

与 Prisma 加速相关的错误以P6xxx开头。

您可以在此处找到 Prisma 加速的完整错误代码参考这里。