Product Introduction
Quick Start
- Agent Development
- Importing a Git Repository
- Starting From a Template
- Direct Upload
- Start with AI
Framework Guide
- Agent
- 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
Functions
- Overview
- Edge Functions
- Cloud Functions
  - Overview
  - Node.js
  - Python
  - Go
Agents
- Overview
- Quick Start
- Conversation Storage
- Observability
- Sandbox Tool
  - Overview
  - Using the Agent Framework
  - Sandbox Atomic API
  - Network Search Tool
- Agent Authentication
Models
- Overview
- Models and Vendors
  - Overview
  - Using Vendor Keys
    - OpenAI
    - Anthropic
    - Google AI Studio
    - DeepSeek
    - MiniMax
    - Hunyuan
    - Zhipu
    - MoonShot AI
- FAQs
Storage
- Overview
- KV
- Blob
Middleware
AI-Native Development
- Skills
- MCP
Copilot
- Overview
- Quick Start
API Token
EdgeOne CLI
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
- Adding an AI Chat Assistant to a Website
- 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 Makers
- Migrating from Cloudflare Pages to EdgeOne Makers
- Migrating from Netlify to EdgeOne Makers
Troubleshooting
FAQs
Limits
Pricing
Contact Us
Release Notes

KV

Overview
EdgeOne Makers KV is a key-value persistent storage deployed across multiple edge nodes. It follows eventual consistency (with edge node caching up to 60 seconds) and is suitable for storing small-scale 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 KV usage statistics and billing within the Makers business. One Makers account corresponds to one KV account, which is created after the user activates it 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
The variable name is the runtime environment variable name defined when a project is bound to a namespace. Before using namespace data, you must first bind the namespace to a Makers project. The binding relationship between namespaces and projects is many-to-many. During binding, different runtime environment variable names are used to distinguish them.
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 Makers 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.