EdgeOne KV Storage is a low-latency key-value data storage service where data is persisted in a small number of central nodes and cached to edge nodes upon access. Optimized for high-read scenarios, it provides edge functions with rapid data retrieval capabilities.
Note:
KV Storage is currently open via allowlist. If you need to use it, please contact us to apply for access. How It Works
When you first write data to KV, the data is written directly to the central node and is not automatically distributed to every edge node. When a client initiates a read, EdgeOne obtains data from the nearest edge node. If the node has the corresponding data cached, it returns the data directly. If the cache misses (for example, during the first access or when the cache expires), the system retrieves the data from the central node and caches it on the current edge node. The first access will experience higher latency, but subsequent requests from the same node will hit the cache directly without needing to retrieve from the origin again.
When you modify a KV key-value pair, the edge node that initiated the write immediately clears the local cache for that Key to ensure subsequent reads on that node retrieve the latest data. Deleting a key-value pair also immediately clears the cache for the corresponding Key.
KV achieves high-performance reads through caching, thus adopting an eventual consistency model. On the node where changes are initiated, updates are typically visible immediately; on other nodes, stale cached data will be updated only after it expires. The default cache time (TTL) is 60 seconds.
Based on the above working principles, KV is suitable for high-read, low-write business scenarios that are sensitive to global access latency, such as website configuration distribution, feature flags, access control lists (ACLs), and user preference storage.
Core Concepts
|
Namespace | The basic management unit of KV Storage, used to isolate key-value data of different services. Each namespace has independent storage space. |
KV Key-Value Pair | The data storage unit within a namespace, consisting of a Key and a Value. The Key uniquely identifies a data item, while the Value represents the corresponding data. |
Service Binding | The configuration that associates a KV namespace with edge functions. Via a service binding, function code can access the corresponding KV namespace at runtime using the specified variable name. |
Variable Name | The variable name defined during service binding serves as the access identifier for function code to interact with the KV namespace. Within the same function, variable names must be unique. |
Applicable Scenarios
Scenario 1: Dynamic Configuration Distribution
Business configurations (such as canary release ratios, feature flags, and rate limiting thresholds) are written to KV storage. Edge functions read them in real-time during request processing, enabling dynamic business behavior adjustments without code deployment.
Scenario 2: User Session and State Management
Storing user session tokens or state information at the edge-side, accessible across multiple edge nodes. Suitable for scenarios such as login status verification and user preference storage.
Scene 3: Allowlist and Blocklist with Rule Management
IP address allowlists/blocklists, domain rules, and risk control features are written to KV storage. Edge functions directly access and block traffic at the entry point, reducing the load on the origin server.
Scenario 4: A/B Testing and Canary Release
Experiment group configurations (such as user bucketing rules and page version mappings) are written to KV storage. Edge functions read these configurations at the request entry point and route traffic to different versions according to the rules, enabling real-time adjustment of traffic distribution ratios without redeployment.
Scenario 5: Static Resource Version Management
Static resource version numbers or path mappings are stored in KV storage. Edge functions dynamically replace resource URLs during responses, enabling rapid rollbacks or hot updates while avoiding users loading outdated resources due to caching issues.
Scenario 6: API Rate Limiting and Frequency Control
Storing request counts and time window information for users or IPs in KV storage. Edge functions read and update the count with each request, returning a rate limiting response directly at the edge when thresholds are exceeded, thus preventing requests from bypassing to the origin server.
Scenario 7: Geographic Location-based Content Customization
Regionalized content policies (such as language versions, compliance notices, and pricing systems) are written to KV storage. Edge functions read corresponding configurations based on the request's region of origin, enabling differential content delivery by region.
Use Limits
|
Per-Site Namespace Quantity | 10 |
Per-Namespace Storage Capacity | 1 GB |
Maximum Value per Entry | 1 MB |
Maximum Key Length | 512 bytes |
Daily Read Operations per Namespace | 100,000 times/day |
Daily Write Operations per Namespace | 10,000 times/day |
Note:
1. KV namespaces between SCDN sites support cross-site referencing, but cross-type invocations between Pages sites and SCDN sites are currently not supported.
2. Each namespace has a daily limit on the number of read/write requests. Once exceeded, read/write requests for that namespace will be rejected. When read/write requests are called via the edge functions Runtime API or TencentCloud API, it will return a LimitExceeded error. The quota will be automatically reset at 00:00:00 (UTC+8) the next day.
Reference