diff --git a/src/content/docs/kv/api/read-key-value-pairs.mdx b/src/content/docs/kv/api/read-key-value-pairs.mdx index 2d6ae78ee627942..d2feb112498f0ea 100644 --- a/src/content/docs/kv/api/read-key-value-pairs.mdx +++ b/src/content/docs/kv/api/read-key-value-pairs.mdx @@ -255,9 +255,41 @@ The effective `cacheTtl` of an already cached item can be reduced by getting it ### Requesting more keys per Worker invocation with bulk requests -Workers are limited to 1000 operations to external services per invocation. This applies to Workers KV, as documented in [Workers KV limits](/kv/platform/limits/). +Workers are limited to 1,000 operations to external services per invocation. This applies to Workers KV, as documented in [Workers KV limits](/kv/platform/limits/). + +To read more than 1,000 keys per operation, you can use the bulk read operations to read multiple keys in a single operation. These count as a single operation against the 1,000 operation limit. + +### Reducing cardinality by coalescing keys + +If you have a set of related key-value pairs that have a mixed usage pattern (some hot keys and some cold keys), consider coalescing them. By coalescing cold keys with hot keys, cold keys will be cached alongside hot keys which can provide faster reads than if they were uncached as individual keys. + +#### Merging into a "super" KV entry + +One coalescing technique is to make all the keys and values part of a super key-value object. An example is shown below. + +``` +key1: value1 +key2: value2 +key3: value3 +``` + +becomes + +``` +coalesced: { + key1: value1, + key2: value2, + key3: value3, +} +``` + +By coalescing the values, the cold keys benefit from being kept warm in the cache because of access patterns of the warmer keys. + +This works best if you are not expecting the need to update the values independently of each other, which can pose race conditions. + +- **Advantage**: Infrequently accessed keys are kept in the cache. +- **Disadvantage**: Size of the resultant value can push your worker out of its memory limits. Safely updating the value requires a [locking mechanism](/kv/api/write-key-value-pairs/#concurrent-writes-to-the-same-key) of some kind. -To read more than 1000 keys per operation, you can use the bulk read operations to read multiple keys in a single operation. These count as a single operation against the 1000 operation limit. ## Other methods to access KV