1# Cloudflare Workers KV
2 
3Globally-distributed, eventually-consistent key-value store optimized for high read volume and low latency.
4 
5## Overview
6 
7KV provides:
8- Eventual consistency (60s global propagation)
9- Read-optimized performance
10- 25 MiB value limit per key
11- Auto-replication to Cloudflare edge
12- Metadata support (1024 bytes)
13 
14**Use cases:** Config storage, user sessions, feature flags, caching, A/B testing
15 
16## When to Use KV
17 
18| Need | Recommendation |
19|------|----------------|
20| Strong consistency | → [Durable Objects](../durable-objects/) |
21| SQL queries | → [D1](../d1/) |
22| Object storage (files) | → [R2](../r2/) |
23| High read, low write volume | → KV ✅ |
24| Sub-10ms global reads | → KV ✅ |
25 
26**Quick comparison:**
27 
28| Feature | KV | D1 | Durable Objects |
29|---------|----|----|-----------------|
30| Consistency | Eventual | Strong | Strong |
31| Read latency | <10ms | ~50ms | <1ms |
32| Write limit | 1/s per key | Unlimited | Unlimited |
33| Use case | Config, cache | Relational data | Coordination |
34 
35## Quick Start
36 
37```bash
38wrangler kv namespace create MY_NAMESPACE
39# Add binding to wrangler.jsonc
40```
41 
42```typescript
43// Write
44await env.MY_KV.put("key", "value", { expirationTtl: 300 });
45 
46// Read
47const value = await env.MY_KV.get("key");
48const json = await env.MY_KV.get<Config>("config", "json");
49```
50 
51## Core Operations
52 
53| Method | Purpose | Returns |
54|--------|---------|---------|
55| `get(key, type?)` | Single read | `string \| null` |
56| `get(keys, type?)` | Bulk read (≤100) | `Map<string, T \| null>` |
57| `put(key, value, options?)` | Write | `Promise<void>` |
58| `delete(key)` | Delete | `Promise<void>` |
59| `list(options?)` | List keys | `{ keys, list_complete, cursor? }` |
60| `getWithMetadata(key)` | Get + metadata | `{ value, metadata }` |
61 
62## Consistency Model
63 
64- **Write visibility:** Immediate in same location, ≤60s globally
65- **Read path:** Eventually consistent
66- **Write rate:** 1 write/second per key (429 on exceed)
67 
68## Reading Order
69 
70| Task | Files to Read |
71|------|---------------|
72| Quick start | README → configuration.md |
73| Implement feature | README → api.md → patterns.md |
74| Debug issues | gotchas.md → api.md |
75| Batch operations | api.md (bulk section) → patterns.md |
76| Performance tuning | gotchas.md (performance) → patterns.md (caching) |
77 
78## In This Reference
79 
80- [configuration.md](./configuration.md) - wrangler.jsonc setup, namespace creation, TypeScript types
81- [api.md](./api.md) - KV methods, bulk operations, cacheTtl, content types
82- [patterns.md](./patterns.md) - Caching, sessions, rate limiting, A/B testing
83- [gotchas.md](./gotchas.md) - Eventual consistency, concurrent writes, value limits
84 
85## See Also
86 
87- [workers](../workers/) - Worker runtime for KV access
88- [d1](../d1/) - Use D1 for strong consistency needs
89- [durable-objects](../durable-objects/) - Strongly consistent alternative
90