Skip to content

Commit 8735b3a

Browse files
thomasgauvinOxyjun
andauthored
[KV] update how kv works to improve comparison (#20727)
* thomasgauvin: update how kv works to improve comparison * Update src/content/docs/kv/concepts/how-kv-works.mdx Co-authored-by: Jun Lee <[email protected]> * Update src/content/docs/kv/concepts/how-kv-works.mdx * Update src/content/docs/kv/concepts/how-kv-works.mdx * thomasgauvin: nits * nits 2 * applying matt recc --------- Co-authored-by: Jun Lee <[email protected]>
1 parent c30002a commit 8735b3a

File tree

1 file changed

+20
-7
lines changed

1 file changed

+20
-7
lines changed

src/content/docs/kv/concepts/how-kv-works.mdx

Lines changed: 20 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,12 @@ sidebar:
77

88
KV is a global, low-latency, key-value data store. It stores data in a small number of centralized data centers, then caches that data in Cloudflare's data centers after access.
99

10-
KV supports exceptionally high read volumes with low latency, making it possible to build highly dynamic APIs.
11-
12-
While reads are periodically revalidated in the background, requests which are not in cache and need to hit the centralized back end can experience high latencies.
10+
KV supports exceptionally high read volumes with low latency, making it possible to build dynamic APIs that scale thanks to KV's built-in caching and global distribution.
11+
Requests which are not in cache and need to access the central stores can experience higher latencies.
1312

1413
## Write data to KV and read data from KV
1514

16-
When you write to KV, your data is written to central data stores. Your data is not sent automatically to every locations cache.
15+
When you write to KV, your data is written to central data stores. Your data is not sent automatically to every location's cache.
1716

1817
![Your data is written to central data stores when you write to KV.](~/assets/images/kv/kv-write.svg)
1918

@@ -26,7 +25,7 @@ A hot read means that the data is cached on Cloudflare's edge network using the
2625

2726
![Initial reads will miss the cache and go to the nearest central data store first.](~/assets/images/kv/kv-slow-read.svg)
2827

29-
Frequent reads from the same location return the cached value without reading from anywhere else, resulting in the fastest response times. KV operates diligently to keep the latest value in the cache by refreshing from upper tiers and the central data stores in the background.
28+
Frequent reads from the same location return the cached value without reading from anywhere else, resulting in the fastest response times. KV operates diligently to update the cached values by refreshing from upper tier caches and central data stores before cache expires in the background.
3029

3130
Refreshing from upper tiers and the central data stores in the background is done carefully so that assets that are being accessed continue to be kept served from the cache without any stalls.
3231

@@ -44,8 +43,6 @@ Changes are usually immediately visible in the Cloudflare global network locatio
4443

4544
Negative lookups indicating that the key does not exist are also cached, so the same delay exists noticing a value is created as when a value is changed.
4645

47-
KV does not perform like an in-memory datastore, such as [Redis](https://redis.io). Accessing KV values, even when locally cached, has significantly more latency than reading a value from memory within a Worker script.
48-
4946
## Consistency
5047

5148
KV achieves high performance by being eventually-consistent. At the Cloudflare global network location at which changes are made, these changes are usually immediately visible. However, this is not guaranteed and therefore it is not advised to rely on this behaviour. In other global network locations changes may take up to 60 seconds or more to be visible as their cached versions of the data time-out.
@@ -60,6 +57,22 @@ If you need stronger consistency guarantees, consider using [Durable Objects](/d
6057

6158
An approach to achieve write-after-write consistency is to send all of your writes for a given KV key through a corresponding instance of a Durable Object, and then read that value from KV in other Workers. This is useful if you need more control over writes, but are satisfied with KV's read characteristics described above.
6259

60+
## Guidance
61+
62+
Workers KV is an eventually-consistent edge key-value store. That makes it ideal for **read-heavy**, highly cacheable workloads such as:
63+
64+
- Serving static assets
65+
- Storing application configuration
66+
- Storing user preferences
67+
- Implementing allow-lists/deny-lists
68+
- Caching
69+
70+
In these scenarios, Workers are invoked in a data center closest to the user and Workers KV data will be cached in that region for subsequent requests to minimize latency.
71+
72+
If you have a **write-heavy** [Redis](https://redis.io)-type workload where you are updating the same key tens or hundreds of times per second, KV will not be an ideal fit.
73+
If you can revisit how your application writes to single key-value pairs and spread your writes across several discrete keys, Workers KV can suit your needs.
74+
Alternatively, [Durable Objects](/durable-objects/) provides a key-value API with higher writes per key rate limits.
75+
6376
## Security
6477

6578
Refer to [Data security documentation](/kv/reference/data-security/) to understand how Workers KV secures data.

0 commit comments

Comments
 (0)