Caches

Kotlin |Java

interface Caches

Provides an interface to explicitly manage caches for GenerativeModel.

Summary

Public functions
`suspend CachedContext`	`create(request: CreateCachedContextRequest)` Creates a cached context that can be used in future `GenerateContentRequest`s.
`suspend Boolean`	`delete(name: String)` Deletes the cache with the given name.
`suspend CachedContext?`	`get(name: String)` Returns the `CachedContext` with the given name.
`suspend List<CachedContext>`	`list()` Queries the `CachedContext`s created by `create`.

Public functions

create

suspend fun create(request: CreateCachedContextRequest): CachedContext

Creates a cached context that can be used in future GenerateContentRequests.

This experimental method can be used to create a cached context that stores the pre-processed state of a reusable part of a prompt to improve inference performance. This is useful for scenarios where a common prefix is used across multiple generation requests, such as with few-shot examples.

The created CachedContext can be used in a GenerateContentRequest. Each cache is identified by a unique name across all GenerativeModel instances within the same app. If create is called with a CreateCachedContextRequest for an existing cache name, the old cache will be overwritten.

Caches may become invalid over time (e.g., due to model update). If an invalid cache is used, a GenAiException with ErrorCode.CACHE_PROCESSING_ERROR will be thrown, indicating that the cache should be deleted or recreated.

This is a non-blocking, cancellable coroutine. If the operation is no longer needed, cancelling the coroutine will stop the execution.

Note that cache creation requests may fail under certain conditions such as:

The prefix prompt length exceeds model limitations.
The CreateCachedContextRequest contains invalid or malformed input.
Usage quotas are exceeded or safety checks fail.

Throws
`GenAiException`	if the cache creation fails.

delete

suspend fun delete(name: String): Boolean

Deletes the cache with the given name.

This experimental method removes the cached context created by create from storage, freeing up space.

Parameters
`name: String`	the name of the cache to delete.

get

suspend fun get(name: String): CachedContext?

Returns the CachedContext with the given name.

This experimental method retrieves a CachedContext created by create, returning null if no cache with that name exists.

list

suspend fun list(): List<CachedContext>

Queries the CachedContexts created by create.

This experimental method returns a list of CachedContext objects. This method can be used to inspect and manage existing caches.

Returns
`List<CachedContext>`	a `List` of `CachedContext`s.