How KV works

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.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.KV is a global key-value store caching data in Cloudflare data centers Data lives in centralized data centers and is cached after accessKV is a global key-value store caching data in Cloudflare data centersKV

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. Requests which are not in cache and need to access the central stores can experience higher latencies.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. Requests which are not in cache and need to access the central stores can experience higher latencies.KV supports high read volumes, but cache misses see higher latency Built-in caching and global distribution scale reads; central store access is slowerKV supports high read volumes, but cache misses see higher latencyread volumes

Write data to KV and read data from KV

Writes go to central stores; reads warm caches from regional and central tiers

When you write to KV, your data is written to central data stores. Your data is not sent automatically to every location's cache.When you write to KV, your data is written to central data stores. Your data is not sent automatically to every location's cache.Writes go only to central data stores, not to every location's cache Caches are filled later on reads rather than pushed on writeWrites go only to central data stores, not to every location's cachecentral data stores

Initial reads from a location do not have a cached value. Data must be read from the nearest regional tier, followed by a central tier, degrading finally to the central stores for a truly cold global read. While the first access is slow globally, subsequent requests are faster, especially if requests are concentrated in a single region.Data must be read from the nearest regional tier, followed by a central tier, degrading finally to the central stores for a truly cold global read. While the first access is slow globally, subsequent requests are faster, especially if requests are concentrated in a single region.Cold global reads degrade through regional and central tiers to central stores First access is slow, but later requests, especially region-local, speed upCold global reads degrade through regional and central tiers to central storescold reads

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.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.Repeat reads from one location are fastest and return cached values KV refreshes cache from upper tiers and central stores before expiry in the backgroundRepeat reads from one location are fastest and return cached valuescached values

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.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.Background cache refresh keeps serving assets without stalls Refreshing is done carefully so accessed assets stay served from cacheBackground cache refresh keeps serving assets without stallscache refresh

KV is optimized for high-read applications. It stores data centrally and uses a hybrid push/pull-based replication to store data in cache. KV is suitable for use cases where you need to write relatively infrequently, but read quickly and frequently. Infrequently read values are pulled from other data centers or the central stores, while more popular values are cached in the data centers they are requested from.KV is optimized for high-read applications. … KV is suitable for use cases where you need to write relatively infrequently, but read quickly and frequently. Infrequently read values are pulled from other data centers or the central stores, while more popular values are cached in the data centers they are requested from.KV suits write-infrequently, read-frequently workloads via hybrid push/pull caching Popular values cache locally in requesting data centers; infrequent ones are pulledKV suits write-infrequently, read-frequently workloads via hybrid push/pull cachingread-frequently

Performance

Raising cacheTtl above its 60-second default improves KV read performance

To improve KV performance, increase the cacheTtl parameter up from its default 60 seconds.To improve KV performance, increase the cacheTtl parameter up from its default 60 seconds.Increase the cacheTtl parameter above its default 60 seconds to improve performanceIncrease the cacheTtl parameter above its default 60 seconds to improve performancecacheTtl parameter

KV achieves high performance by caching which makes reads eventually-consistent with writes.KV achieves high performance by caching which makes reads eventually-consistent with writes.Caching gives KV high performance but makes reads eventually-consistent with writesCaching gives KV high performance but makes reads eventually-consistent with writesCaching

Changes are usually immediately visible in the Cloudflare global network location at which they are made. Changes may take up to 60 seconds or more to be visible in other global network locations as their cached versions of the data time out.Changes are usually immediately visible in the Cloudflare global network location at which they are made. Changes may take up to 60 seconds or more to be visible in other global network locations as their cached versions of the data time out.Changes are usually immediately visible locally, but up to 60 seconds or more elsewhere Other locations wait for their cached data to time outChanges are usually immediately visible locally, but up to 60 seconds or more elsewhereChanges

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.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.Negative lookups for nonexistent keys are also cached, delaying visibility of creationNegative lookups for nonexistent keys are also cached, delaying visibility of creationNegative lookups

Consistency

KV is eventually-consistent; changes may take 60 seconds or more elsewhere

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.KV achieves high performance by being eventually-consistent. … 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.Changes are usually but not guaranteed immediately visible locally; don't rely on it Elsewhere, cache time-outs make changes take up to 60 seconds or moreChanges are usually but not guaranteed immediately visible locally; don't rely on iteventually-consistent

Visibility of changes takes longer in locations which have recently read a previous version of a given key (including reads that indicated the key did not exist, which are also cached locally).Visibility of changes takes longer in locations which have recently read a previous version of a given key (including reads that indicated the key did not exist, which are also cached locally).Locations that recently read a previous version see changes later Locally cached reads, including negative ones, delay new dataLocations that recently read a previous version see changes laterprevious version

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.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.Route all writes for a key through a Durable Object for write-after-write consistency Then read the value from KV in other Workers; useful when KV read traits sufficeRoute all writes for a key through a Durable Object for write-after-write consistencyDurable Object

Guidance

KV suits read-heavy, cacheable workloads, not write-heavy per-key updates

Workers KV is an eventually-consistent edge key-value store. That makes it ideal for read-heavy, highly cacheable workloads such as:Workers KV is an eventually-consistent edge key-value store. That makes it ideal for read-heavy, highly cacheable workloads such as:Workers KV is an eventually-consistent edge store ideal for read-heavy, cacheable workloadsWorkers KV is an eventually-consistent edge store ideal for read-heavy, cacheable workloadsWorkers KV

• Serving static assets
• Storing application configuration
• Storing user preferences
• Implementing allow-lists/deny-lists
• Caching

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.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.Workers run nearest the user and KV data caches there to minimize latencyWorkers run nearest the user and KV data caches there to minimize latencylatency

If you have a write-heavy Redis-type workload where you are updating the same key tens or hundreds of times per second, KV will not be an ideal fit. 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. Alternatively, Durable Objects provides a key-value API with higher writes per key rate limits.If you have a write-heavy Redis-type workload where you are updating the same key tens or hundreds of times per second, KV will not be an ideal fit. 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. Alternatively, Durable Objects provides a key-value API with higher writes per key rate limits.KV fits poorly with write-heavy same-key updates; spread writes or use Durable Objects Splitting writes across discrete keys can make KV suitable; Durable Objects offer higher write limitsKV fits poorly with write-heavy same-key updates; spread writes or use Durable Objectswrite-heavy

Security

Workers KV data security is detailed in the data security documentation

Refer to Data security documentation to understand how Workers KV secures data.Refer to Data security documentation to understand how Workers KV secures data.Workers KV data security is covered in the data security documentationWorkers KV data security is covered in the data security documentationdata security