API Reference

The Accelerate API reference documentation is based on the following schema:

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

All example are based on the User model.

cacheStrategy

With the Accelerate extension for Prisma Client, you can use the cacheStrategy parameter for model queries and use the ttl and swr parameters to define a cache strategy for Accelerate. The Accelerate extension requires that you install Prisma Client version 4.10.0.

Options

The cacheStrategy parameter takes an option with the following keys:

Option	Example	Type	Required	Description
swr	60	Int	No	The stale-while-revalidate time in seconds.
ttl	60	Int	No	The time-to-live time in seconds.
tags	["user"]	String[]	No	The tag serves as a variable to control the invalidation of specific queries within your application. It is an optional array of strings to invalidate the cache, with each tag containing only alphanumeric characters and underscores, and a maximum length of 64 characters.

Examples

Add a caching strategy to the query, defining a 60-second stale-while-revalidate (SWR) value, a 60-second time-to-live (TTL) value, and a cache tag of "emails_with_alice":

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

Supported Prisma Client operations

The following is a list of all read query operations that support cacheStrategy:

• findUnique()
• findUniqueOrThrow()
• findFirst()
• findFirstOrThrow()
• findMany()
• count()
• aggregate()
• groupBy()

info

The cacheStrategy parameter is not supported on any write operations, such as create().

withAccelerateInfo

Any query that supports the cacheStrategy can append withAccelerateInfo() to wrap the response data and include additional information about the Accelerate response.

To retrieve the status of the response, use:

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

console.dir(info)

info

Notice the info property of the response object. This is where the request information is stored.

Return type

The info object is of type AccelerateInfo and follows the interface below:

interface AccelerateInfo {
  cacheStatus: 'ttl' | 'swr' | 'miss' | 'none'
  lastModified: Date
  region: string
  requestId: string
  signature: string
}

Property	Type	Description
cacheStatus	"ttl" | "swr" | "miss" | "none"	The cache status of the response. ttl indicates a cache hit within the ttl duration and no database query was executed swr indicates a cache hit within the swr duration and the data is being refreshed by Accelerate in the background miss indicates that both ttl and swr have expired and the database query was executed by the request none indicates that no cache strategy was specified and the database query was executed by the request
lastModified	Date	The date the response was last refreshed.
region	String	The data center region that received the request.
requestId	String	Unique identifier of the request. Useful for troubleshooting.
signature	String	The unique signature of the Prisma operation.

$accelerate.invalidate

You can invalidate the cache using the $accelerate.invalidate API.

note

To invalidate cached query results on-demand, a paid plan is required. Each plan has specific limits on the number of cache tag-based invalidations allowed per day, though there are no limits on calling the $accelerate.invalidate API itself. See our pricing for more details.

Example

To invalidate the query below:

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

You need to provide the cache tag in the $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;
}

note

You can invalidate up to 5 tags per call.

Errors

Prisma Accelerate-related errors start with P6xxx.

You can find the full error code reference for Prisma Accelerate here.