Skip to content
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 45 additions & 2 deletions src/content/docs/kv/api/read-key-value-pairs.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -255,9 +255,52 @@ 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 1000 operations to external services per invocation. This applies to Workers KV, as documented in [Workers KV limits](/kv/platform/limits/).

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

### 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 the need to fetch them, so that a single cached fetch retrieves all the values even if you only need one of the values. This is useful because the cooler keys share access patterns with the hotter keys, and are therefore more likely to be present in the cache. Some approaches to accomplishing this are described below.

#### 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 alive 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 unless you are careful about how you synchronize.

- **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](#concurrent-writers) of some kind.

#### Storing in metadata and shared prefix

If you do not want to merge into a single KV entry as described above, and your associated values fit within the [metadata limit](/workers/platform/limits/#kv-limits), then you can store the values within the metadata instead of the body. If you then name the keys with a shared unique prefix, your list operation will contain the value, letting you bulk read multiple keys at once through a single, cacheable list operation.

:::note[List performance]
List operations are not "write aware". This means that while they are subject to tiering, they only stay cached for up to one minute past when it was last read, even at upper tiers.

By comparison, `get` operations are cached at the upper tiers for a service managed duration that is always longer than your cacheTtl. Additionally, the cacheTtl lets you extend the duration of a single key lookup at the data center closest to the request.
:::

Since list operations are not "write aware" as described above, they are only ever cached for 1 minute. They are still subject to [tiered caching](https://blog.cloudflare.com/faster-workers-kv-architecture#a-new-horizontally-scaled-tiered-cache) as described in our blog post, so requests within the region and globally are amortized to keep the asset closer to your request. However, you still need to be reading the value about once every 30 seconds to make sure it is always present within Cloudflare's caches.

## Other methods to access KV

Expand Down