Product Introduction
Quick Start
- Importing a Git Repository
- Starting From a Template
- Direct Upload
- Start with AI
Framework Guide
- Frontends
  - Vite
  - React
  - Vue
  - Hugo
  - Other Frameworks
- Backends
- Full-stack
  - Next.js
  - Nuxt
  - Astro
  - React Router
  - SvelteKit
  - TanStack Start
  - Vike
- Custom 404 Page
Project Guide
- Project Management
- edgeone.json
- Configuring Cache
- Building Output Configuration
- Error Codes
Build Guide
Deployment Guide
- Overview
- Create Deploys
- Manage Deploys
- Deploy Button
- Using Github Actions
- Using Gitlab CI/CD
- Using CNB Plugin
- Using IDE PlugIn
- Using CodeBuddy IDE
Domain Management
- Overview
- Custom Domain
- HTTPS Configuration
  - Overview
  - Apply for Free Certificate
  - Using Managed SSL Certificate
- Configure DNS CNAME Record
Observability
- Overview
- Metric Analysis
- Log Analysis
Pages Functions
- Overview
- Edge Functions
- Cloud Functions
  - Overview
  - Node.js
  - Python
  - Go
Middleware
Storage
- Overview
- KV
- Blob
Edge AI
API Token
EdgeOne CLI
Copilot
- Overview
- Quick Start
Pages MCP
Pages Skills
Message Notification
Integration Guide
- AI
  - Dialogue Large Models Integration
  - Large Models for Images Integration
- Database
  - Supabase Integration
  - Pages KV Integration
- Ecommerce
  - Shopify Integration
  - WooCommerce Integration
- Payment
  - Stripe Integration
  - Integrating Paddle
- CMS
  - WordPress Integration
  - Contentful Integration
  - Sanity Integration
  - Payload Integration
- Authentication
  - Supabase Integration
  - Clerk Integration
Best Practices
- AI Dialogue Deployment: Deploy Project with One Sentence Using Skill
- Using General Large Model to Quickly Build AI Application
- Use the DeepSeek model to quickly build a conversational AI site
- Building an Ecommerce Platform with Shopify
- Building a SaaS Site Using Supabase and Stripe
- Building a Company Brand Site Quickly
- How to Quickly Build a Blog Site
Migration Guides
- Migrating from Vercel to EdgeOne Pages
- Migrating from Cloudflare Pages to EdgeOne Pages
- Migrating from Netlify to EdgeOne Pages
Troubleshooting
FAQs
Contact Us
Release Notes

KV

Overview
EdgeOne Pages KV is a key-value persistent storage deployed across multiple edge nodes. It follows eventual consistency (edge node caches last up to 60 seconds), making it suitable for storing small data such as configurations, counters, and sessions.
Note:
The free edition package provides 1GB account storage capacity.
Currently, it is only supported for use within Edge Functions.
How It Works
KV adopts an centralized storage + edge caching architecture and follows eventual consistency: Write operations are concurrently persisted to both the nearest edge node and the central storage. For read operations, the system first accesses the local cache of the nearest edge node. If the cache misses or has expired (with a maximum validity of 60 seconds), the data is fetched from the central storage and the cache is refreshed.
Operation
Behavior
Write
Writes to the current nearest edge node and the central storage in parallel. After the write is completed, the same node can immediately read the latest value.
Read
Prioritizes hitting the cache of the nearest edge node (with millisecond-level response). When a cache miss or expiration occurs, pulls the latest value from the central storage and refreshes the cache.
Update / Delete
The current node takes effect immediately. The old cache at other edge nodes expires naturally within a maximum of 60 seconds, after which the latest value can be read.
Note:
A write operation only updates the cache of the node that initiated the request. Other nodes may still read stale values for up to 60 seconds. If your business requires immediate global consistency, use the strong consistency mode of Blob storage.
Use Cases
Counter
You can store the click counts of a specific button or page to KV based on your business needs. Update the key-value records in KV upon each click to facilitate the statistics and analysis of click or visit behaviors.
Keystore
For sensitive information that is not suitable for storage in a code repository, you can store it in KV and dynamically obtain it to better protect your data.
Shopping Cart
KV can retain user data across multiple pages and terminals, helping you conveniently implement simple business requirements such as user shopping carts and user orders.
Basic Concept
Account
A KV account is the smallest unit for measuring and billing KV usage within the Pages service. One Pages account corresponds to one KV account, which is created by the user after activation on the console page. The account storage capacity is 1GB.
Namespace
A namespace (namespace) is the fundamental unit for data isolation in KV. Each namespace can be regarded as an independent database, and data between different namespaces does not interfere with each other. An account can create up to 10 namespaces.
Key-Value Pair
A key-value pair is a structure for storing user data, where each data item consists of two parts: a key and a value. The key is a unique identifier for referencing the value, and the value is the data associated with the key.
Variable Name
A variable name is the runtime environment variable name defined when binding a project to a namespace. Before using namespace data, you must first bind the namespace to a Pages project. The binding relationship between namespaces and projects is many-to-many. During binding, different runtime environment variable names are used to distinguish their usage.
Quick Start
Initializing Account
1. Go to the console: Switch to the "Storage - KV" page.
2. Open an Account: Click Apply Now.
﻿
﻿
﻿
Creating a Namespace
1. Go to the namespace list: After enabling the KV Account, on the "KV Storage" page, click Create Namespace.
﻿
﻿
﻿
2. Create a namespace: Enter the name for the namespace you want to create, click Create, and wait for the creation to complete.
﻿
﻿
﻿
3. Creation completed: After creation, you can view the namespace created on the namespace list page.
﻿
﻿
﻿
Adding a Record
1. Enter namespace details: In the namespace list, click the corresponding namespace name to enter namespace details.
﻿
﻿
﻿
2. Add a record: Click Create Record.
﻿
﻿
﻿
3. Creation completed: After creation, you can view the added records in the list.
﻿
﻿
﻿
Binding a Namespace
Namespace and project binding can be performed in both "Project" and "KV Storage".
Binding in KV Storage
1. Go to Associated Project: On the namespace details page, click the Bind Project tab.
﻿
﻿
﻿
2. Bind Project: Click Bind Project.
﻿
﻿
﻿
3. Binding succeeded: After successful binding, you can view the bound project in the bind project list.
﻿
﻿
﻿
Binding in the Project
1. Go to Project - KV Storage: After entering the project details, click the KV Storage menu.
2. Bind a namespace: Click Bind Namespace.
﻿
﻿
﻿
3. Binding succeeded: After binding succeeds, you can view the bound namespace in the Bind Namespace List.
﻿
﻿
﻿
API
Note: In the following example, my_kv is the variable name when you bind project to namespace.
A set of KV storage operation methods is currently provided for use by Pages Functions. The specific methods are as follows:
put
Write KV data, the user creates a new key-value pair or updates the value of an existing key-value pair.
put(key: string,value: string | ArrayBuffer | ArrayBufferView | ReadableStream): Promise<void>;
Parameter
key: The key to be created or updated. Its length must be less than or equal to 512 B, and it can only contain numbers, letters, and underscores.
value: The data to be written. Its length must be less than or equal to 25 MB.
Returned Value
Returns a Promise, which must be awaited to verify whether the write is successful.
Use Case
await my_kv.put(key, value);
get
Read data from KV with a specific key and specify the type of returned data.
get(key:string, object?:{type:string}): Promise<value:string|object|ArrayBuffer|ReadableStream>
Parameter
key: Specifies the key to retrieve data.
type: Specifies the type of the returned value. The default is text.
text: String. Converts the value into a string and returns it.
json: Object. Deserializes the json into an object and returns it.
arrayBuffer: ArrayBuffer. Converts the binary value into an ArrayBuffer and returns it.
stream: ReadableStream. It is typically used for scenarios where the value is large.
Returned Value
Returns a Promise, await the Promise to retrieve the value. If the key does not exist or the value is empty, return null.
Use Case
let value = await my_kv.get(key);
let value = await my_kv.get(key, "json");
let value = await my_kv.get(key, {type: "json"});
delete
Delete the specified key from KV.
delete(key: string): Promise<void>;
Parameter
key: The key of the key-value pair to be deleted.
Returned Value
Returns a Promise, which must be awaited to verify whether deletion is successful.
Use Case
await my_kv.delete(key);
list
Used to traverse ALL keys in KV.
list({prefix?: string, limit?: number, cursor?: string}): Promise<ListResult>;
Parameter
prefix: Filters keys with a specified prefix. When left empty by default, returns results sorted in lexicographical order.
limit: The maximum number of keys to return, used for pagination. The default value is 256, and the maximum is 256.
cursor: A cursor for pagination that starts traversal from a specified key. It is empty by default.
Returned Value
return a Promise, await the Promise to retrieve ListResult:
class ListResult {
    complete: Boolean;
    cursor: String;
    keys: Array<ListKey>;
}
﻿
class ListKey {
    key: String;
}
complete: Indicates whether the list operation is completed, with true for completed and false for incomplete.
cursor: A cursor that points to the first key of the next page and becomes null when the list traversal is complete.
keys: An object array describing each key.
Use Case
// Retrieve partial data via list
let result = await kv.list({ "prefix": "a", "limit": 10, "cursor": "abc" });
﻿
// Traverse all data via list
let result;
let cursor;
do {
    result = await kv.list(options);
    cursor = result.cursor;
} while (result && !result.complete);
Example
export async function onRequest({ request, params, env }) {
    // get the namespace key with variable name my_kv
    let count = await my_kv.get("count");
    count = Number(count) + 1;
    
    // rewrite the visitCount key-value
    await my_kv.put("count", String(count));
﻿
    return new Response("ok", {});
}
Example Template
Use KV to Record Page Visits:
Preview URL: https://functions-kv.edgeone.app
Source Code URL: https://github.com/TencentEdgeOne/pages-templates/tree/main/examples/functions-kv

Operation	Behavior
Write	Writes to the current nearest edge node and the central storage in parallel. After the write is completed, the same node can immediately read the latest value.
Read	Prioritizes hitting the cache of the nearest edge node (with millisecond-level response). When a cache miss or expiration occurs, pulls the latest value from the central storage and refreshes the cache.
Update / Delete	The current node takes effect immediately. The old cache at other edge nodes expires naturally within a maximum of 60 seconds, after which the latest value can be read.