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 GenerateContentRequest s.

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 CachedContext s 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.