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 deployed 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 the function capability in EdgeOne Pages to build APIs or websites that require storing small amounts of data.


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 info 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 like user shopping carts and user orders.


Basic Concept

Account

The 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 after user activation on the console page. Account storage capacity: 100MB.


Namespace

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


Key-Value Pair

A Key-Value pair is a structure for storing data, where 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 linked to the Key.


Variable Name

The 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 the Edgeone Pages Project. The binding relationship between namespaces and projects is many-to-many, and different runtime environment variable names are used to distinguish them during binding.


Quick Start

Initializing Account

1. Enter Console: Switch to the "KV Storage" page.
2. 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, 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.





Adding a 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

Namespace and project binding 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 succeeded: After successful binding, you can view the bound project in the bind project list.




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




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




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





Using KV

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

Currently provides a group of KV storage operation methods for Edgeone Pages function usage. Follow these steps:


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 create or update, length less than or equal to 512 B, only support numbers, letters and underline.
- value: The data to write, data length up 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: Used to specify the value type to return, default is text.
- text: String, converts the value into string and returns it.
- json: Object, deserializes the json into an object and returns it.
- arrayBuffer: ArrayBuffer, converts the binary value to ArrayBuffer and returns it.
- stream: ReadableStream, usually used for large value scenarios.

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: Used for filtering keys with a specified prefix. When empty by default, returns in lexicographical order.
- limit: Maximum number of returned keys for pagination. Default value is 256, maximum is 256.
- cursor: Cursor for traversal starting from a specified key, used for pagination. 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, true for completed, false for incomplete.
- cursor: Cursor for the first key of the next page, 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);


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 lets users record and display the occurrence count of project business needs, and can be used to track "clicks", "blog access traffic" and other business scenarios.