Cache
Elasticsearch implementation of cache capability.
This module provides an Elasticsearch implementation of the CacheCapability protocol for storing and retrieving cached data.
References
NONE
ElasticsearchCacheCapability(index_name, client, em_invoker=None, query_field='text', vector_query_field='vector', retrieval_strategy=None, distance_strategy=None)
Elasticsearch implementation of CacheCapability protocol.
This class provides cache storage and retrieval operations using Elasticsearch with support for exact, fuzzy, and semantic matching.
Attributes:
| Name | Type | Description |
|---|---|---|
index_name |
str
|
The name of the Elasticsearch index. |
vector_store |
AsyncElasticsearchStore
|
The underlying Elasticsearch vector store. |
Initialize the Elasticsearch cache capability.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
index_name |
str
|
The name of the Elasticsearch index. |
required |
client |
AsyncElasticsearch
|
The Elasticsearch client. |
required |
em_invoker |
BaseEMInvoker | None
|
The embedding model to perform vectorization. Defaults to None, in which case semantic matching is not available. |
None
|
query_field |
str
|
The field name for text queries. Defaults to "text". |
'text'
|
vector_query_field |
str
|
The field name for vector queries. Defaults to "vector". |
'vector'
|
retrieval_strategy |
Any | None
|
The retrieval strategy for retrieval. Defaults to None, in which case DenseVectorStrategy() is used. |
None
|
distance_strategy |
str | None
|
The distance strategy for retrieval. Defaults to None. |
None
|
create(key, value, metadata=None)
async
Insert a value into cache with optional metadata.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key |
str
|
Cache key. |
required |
value |
Any
|
Value to cache. |
required |
metadata |
dict[str, Any] | None
|
Optional metadata for advanced matching. Defaults to None. |
None
|
delete(key, filters=None)
async
Delete entries by exact key match with optional filters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key |
str | list[str]
|
Single key or list of keys to delete. |
required |
filters |
QueryFilter | None
|
Query filters to apply. Defaults to None. |
None
|
delete_expired(now=None)
async
Delete expired entries.
This method deletes all entries whose expiration time is earlier than the current time.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
now |
datetime | None
|
Reference timestamp for expiration checks. Defaults to current UTC time. |
None
|
delete_lfu(num_entries)
async
Delete least frequently used entries safely (LFU eviction).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
num_entries |
int
|
Number of entries to delete. |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If num_entries <= 0. |
delete_lru(num_entries)
async
Delete least recently used entries safely (LRU eviction).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
num_entries |
int
|
Number of entries to delete. |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If num_entries <= 0. |
retrieve_exact(key, filters=None)
async
Retrieve exact key match from cache.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key |
str
|
Cache key to retrieve. |
required |
filters |
QueryFilter | None
|
Query filters to apply. Defaults to None. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
Any |
Any | None
|
Cached value if found, None otherwise. |
retrieve_fuzzy(key, max_distance=2, filters=None)
async
Find fuzzy matches for key within distance threshold.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key |
str
|
Base key for fuzzy matching. |
required |
max_distance |
int
|
Maximum edit distance for matches. Defaults to 2. |
2
|
filters |
QueryFilter | None
|
Query filters to apply. Defaults to None. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
Any |
Any | None
|
Best matching value or None. |
retrieve_semantic(key, min_similarity=0.8, filters=None)
async
Find semantically similar matches using embeddings.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key |
str
|
Base key for semantic matching. |
required |
min_similarity |
float
|
Minimum similarity threshold (0.0-1.0). Defaults to 0.8. |
0.8
|
filters |
QueryFilter | None
|
Query filters to apply. Defaults to None. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
Any |
Any | None
|
Best matching value or None. |
update(key, value, metadata=None, filters=None)
async
Update an entry in the cache using Elasticsearch update_by_query.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key |
str
|
Cache key to update. |
required |
value |
Any
|
Value to update. |
required |
metadata |
dict[str, Any] | None
|
New metadata values to set. Defaults to None. |
None
|
filters |
QueryFilter | None
|
Query filters to apply. Defaults to None. |
None
|