Edge Developer Platform
  • Pages
    • Product Introduction
    • Quick Start
      • Importing a Git Repository
      • Starting From a Template
      • Direct Upload
    • Framework Guide
    • Project Guide
      • Project Management
      • edgeone.json
      • Configuring Cache
      • Error Codes
    • Build Guide
    • Deployment Guide
      • Overview
      • Create Deploys
      • Manage Deploys
      • Deploy Button
      • Use Github Actions
      • Using CNB Plugin
      • Using IDE Plug-In
      • Using CodeBuddy IDE
    • Domain Management
      • Overview
      • Custom Domain Name
      • Configuring an HTTPS Certificate
      • How to Configure a DNS CNAME Record
    • Pages Functions
    • KV Storage
    • Edge AI
    • API Token
    • EdgeOne CLI
    • Pages MCP
    • 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
      • Authentication
        • Supabase Integration
        • Clerk Integration
    • Best Practices
      • Using General Large Model to Quickly Build AI Application
      • Use the Deepseek-R1 model to quickly build a conversational AI site
      • Building an Ecommerce Platform with WordPress + WooCommerce and GatsbyJS
      • 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
Docs Overview/
Edge Developer Platform/
Pages/
KV Storage/

KV Storage

Overview

EdgeOne Pages KV is a multi-edge node deployment KV persistent data storage that allows users to read and write data globally. It follows final consistency and ensures global sync access within 60s. You can combine it with the function capability in EdgeOne Pages to build APIs for storing small amounts of data, websites, and more.


Case

Counter

Based on your business needs, you can store the number of clicks for a certain button or page in EdgeOne Pages KV. When clicked, refresh the key-value record in KV so that you can perform statistics and analysis on click or access behavior.


Keystore

For sensitive information that should not be placed in a code repository, you can store it in Edgeone Pages KV and dynamically obtain it for better protection of your data.


Shopping Cart

Edgeone Pages KV retains user data across multiple Pages and terminals, helping you conveniently implement simple business requirements such as user shopping cart and user order.


Basic Concept

Account

An Edgeone Pages KV Account is the minimum unit for KV Usage Statistics and billing in Pages Business. An EdgeOne Pages account corresponds to a KV Account, created by the user after console page activation. Account storage capacity is 100MB.


Namespace

A namespace is the basic unit of data isolation in Edgeone Pages KV. Each namespace can be regarded as an independent database, and data between namespaces does not interfere with one another. An account can create 10 namespaces.


Key-Value Pair

A Key-Value pair is a structure for data storage. Each data item consists of two parts: a Key and a Value. The Key is a unique identifier for user identification, and the Value is the associated data.


Variable Name

The variable name is the runtime environment variable name defined when binding the project and namespace. Before using namespace data, you must first bind the namespace to the Edgeone Pages Project. The binding relationship between namespace and project is many-to-many. During binding, different runtime environment variable names are used to distinguish usage.


Quick Start

Initializing an Account

1. Enter Console: Switch to the "KV Storage" page.
2. Apply to Open an Account: Click the "Apply Now" button.
Note:
Note: Currently, KV storage has a limited quota. Please apply for enabling. We will process as soon as possible. Once the application is successful, it can be used.





Creating a Namespace

1. Enter Namespace List: After enabling the KV Account, click the "Create Namespace" button on the "KV Storage" page.




2. Create a namespace: Manually input the namespace name you need to create, then click the "Create" button and wait for the creation to complete.




3. Creation completed: After creation, you can view the namespace created on the namespace list page.





Add Record

1. Enter namespace details: In the namespace list, click the corresponding namespace name to enter namespace details.




2. Add Record: Click the "Create Record" button.




3. Creation completed: After creation, you can view the added records in the list.






Binding a Namespace

Binding between namespace and project can be performed in both "Project" and "KV Storage".

Bind in KV Storage
1. Enter Associated Project: In the namespace details page, click the "Bind Project" tab.




2. Bind Project: Click the "Bind Project" button.




3. Binding successful: After binding succeeds, you can view the bound project in the bind project list.




Binding in Project
1. Enter Project - KV Storage: After entering the project details, click the "KV Storage" menu.




2. Bind a namespace: Click the "Bind Namespace" button.




3. Binding successful: After binding succeeds, you can view the bound namespace in the Bind Namespace List.





Using KV

Note: The following example uses my_kv as the variable name when you bind a project to a namespace, as set in figure my_kv.

Currently provides a group of KV storage operation methods for Edgeone Pages Function. The specific methods are as follows:


put

Write KV data, where 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 create or update, with a length up to 512 B, supporting only numbers, letters, and underline.
- value: The data to write, with a data length up to 25 MB.

Return Value
Returns a Promise. You must await the Promise to verify whether the write is successful.

Usage Example
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 obtain data.
- type: used to specify the value type, defaults to text.
- text: String, converts the value into string and returns it.
- json: Object, deserializes json to object and returns it.
- arrayBuffer: ArrayBuffer, converts the binary value to ArrayBuffer and returns it.
- stream: ReadableStream, usually used for large value scenarios.

Return Value
return a Promise, await the Promise to retrieve the value. If the key does not exist or the value is empty, return null.

Usage Example
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.

Return Value
Returns a Promise. You must await the Promise to verify whether deletion is successful.

Usage Example
await my_kv.delete(key);


list

Used for traversal of ALL keys in KV.
list({prefix?: string, limit?: number, cursor?: string}): Promise<ListResult>;

Parameter
- prefix: The key used to filter the specified prefix. If default is null, return in lexicographical order.
- limit: Maximum number of returned keys for pagination. Default value is 256, maximum is 256.
- cursor: Cursor, starts traversal from the specified key for pagination. Empty by default.

Return 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. true for completed, false for not completed.
- cursor: cursor, the first key for the next page. null when list traversal is complete.
- keys: An object array describing each key.

Usage Example
// 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);


KV 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", {});
}


KV Template

Counter template: It can let users record and display the occurrence count of project business needs, and can be used for statistics such as "click" and "blog access traffic" in business scenarios.