Caches

Kotlin | Java

public interface Caches

Provides an interface to explicitly manage caches for GenerativeModel .

Summary

Public methods
`abstract @ NonNull CachedContext`	`create (@ NonNull CreateCachedContextRequest request)` Creates a cached context that can be used in future `GenerateContentRequest` s.
`abstract boolean`	`delete (@ NonNull String name)` Deletes the cache with the given name.
`abstract CachedContext`	`get (@ NonNull String name)` Returns the `CachedContext` with the given name.
`abstract @ NonNull List <@ NonNull CachedContext >`	`list ()` Queries the `CachedContext` s created by `create` .

Public methods

create

abstract @ NonNull 
 CachedContext 
 create 
(@ NonNull 
 CreateCachedContextRequest 
 request)

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

abstract boolean  delete 
(@ NonNull 
 String 
 name)

Deletes the cache with the given name.

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

Parameters
`@ NonNull String name`	the name of the cache to delete.

get

abstract  CachedContext 
 get 
(@ NonNull 
 String 
 name)

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

abstract @ NonNull 
 List 
<@ NonNull 
 CachedContext 
>  list 
()

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
`@ NonNull List <@ NonNull CachedContext >`	a `List` of `CachedContext` s.