Skip to content
HotKVDocs

Ask the HotKV docs

Answers come only from these docs and can be wrong; check the linked pages before you rely on them.

PCACHE.STATS

Last updated 
PCACHE.STATS namespace
Group
Prompt cache
Complexity
O(1)
Arity
2 (exactly, counting the command name)
Flags
read-only, fast
Keys
first 1, last 1, step 1
HotKV Cloud
Performance and Scale
On-Premise
requires the prompt-cache license feature

The prompt cache is an exact-match cache for LLM prompt and response pairs, organised in named namespaces. PCACHE.STATS reports counters for one namespace. For a namespace that does not exist, every counter is zero.

Return value

Section titled “Return value”

The reply is a flat array of alternating field names and values in both RESP2 and RESP3 (it is not sent as a RESP3 map). The fields, in order:

Field Type Meaning
entries Integer Entries currently stored.
hits Integer Lookups that found a live entry.
misses Integer Lookups that found nothing or an expired entry.
evictions Integer Entries removed to make room or because they expired.
memory_bytes Integer Approximate memory used by the entries.
hit_rate Bulk string hits / (hits + misses), or 0.
p50_ns, p95_ns, p99_ns Integer Lookup latency percentiles in nanoseconds.
cost_saved_usd Bulk string hits multiplied by the namespace’s COST_PER_HIT.
usage_saved_requests Integer Hits on entries that carried usage options.
usage_saved_input_tokens Integer Input tokens those hits did not have to spend.
usage_saved_output_tokens Integer Output tokens those hits did not have to spend.
usage_saved_cache_read_tokens Integer Provider cache-read tokens saved.
usage_saved_cache_write_tokens Integer Provider cache-write tokens saved (5-minute and 1-hour combined).
usage_saved_cost_usd Bulk string Cost saved in US dollars with six decimals, for priced models only.

The usage_saved_* fields only grow for entries stored with the usage options of PCACHE.SET.

Errors:

  • ERR wrong number of arguments for 'pcache.stats' command if the argument count is wrong.
  • NOLICENSE prompt-cache requires a HotKV license. Contact sales@hotkv.com if your license does not include the prompt-cache feature.

Examples

Section titled “Examples”
127.0.0.1:6379> PCACHE.CREATE llm_prompts COST_PER_HIT 0.012
OK
127.0.0.1:6379> PCACHE.SET llm_prompts "Translate: Hello" "Bonjour" MODEL gpt-4o INPUT 20 OUTPUT 3
OK
127.0.0.1:6379> PCACHE.GET llm_prompts "Translate: Hello"
"Bonjour"
127.0.0.1:6379> PCACHE.STATS llm_prompts
 1) "entries"
 2) (integer) 1
 3) "hits"
 4) (integer) 1
 5) "misses"
 6) (integer) 0
 7) "evictions"
 8) (integer) 0
 9) "memory_bytes"
10) (integer) 87
11) "hit_rate"
12) "1"
13) "p50_ns"
14) (integer) 2000
15) "p95_ns"
16) (integer) 2000
17) "p99_ns"
18) (integer) 2000
19) "cost_saved_usd"
20) "0.012"
21) "usage_saved_requests"
22) (integer) 1
23) "usage_saved_input_tokens"
24) (integer) 20
25) "usage_saved_output_tokens"
26) (integer) 3
27) "usage_saved_cache_read_tokens"
28) (integer) 0
29) "usage_saved_cache_write_tokens"
30) (integer) 0
31) "usage_saved_cost_usd"
32) "0.000080"

The latency and memory figures depend on your server and data.

Compatibility

Section titled “Compatibility”

HotKV-only command. Redis and Valkey have no equivalent.

See also

Section titled “See also”

PCACHE.CREATE, PCACHE.SET, PCACHE.GET, PCACHE.GETEX, PCACHE.DEL, PCACHE.FLUSH, PCACHE.DROP, PCACHE.LIST, PCACHE.CONFIG, LLMSTATS.PRICE, AI features guide