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
      • Error Codes
    • Build Guide
    • Deployment Guide
      • Overview
      • Create Deploys
      • Manage Deploys
      • Deploy Button
    • Domain Management
      • Overview
      • Custom Domain Name
      • Configuring an HTTPS Certificate
      • How to Configure a DNS CNAME Record
    • Pages Functions
    • KV Storage
    • Edge AI
    • EdgeOne CLI
    • Pages MCP
    • Best Practices
      • 1-Minute Quick Deployment + Free Beta Test in Progress | Your Exclusive DeepSeek, Handled by EdgeOne!
      • Deploy WordPress Gatsby To EdgeOne Pages
      • Build an Ecommerce Platform Using WordPress + GatsbyJS
      • Combining Sanity to Deploy a Portfolio Template
    • Migration Guides
      • Migrating from Vercel to EdgeOne Pages
      • Migrating from Cloudflare Pages to EdgeOne Pages
      • Migrating from Netlify to EdgeOne Pages
    • FAQs
    • Contact Us
    • Release Notes
Unlock 1 Year of EdgeOne + 1TB CDN: Join Our Developer Journey
Get Started Now !
Docs Overview/
Edge Developer Platform/
Pages/
KV Storage/

KV Storage

Overview

EdgeOne Pages KV is a KV persistent data storage deployed in multi-edge nodes, allowing users to globally read and write data. It follows final consistency and ensures global synchronization access within 60 seconds. You can combine the function capability in EdgeOne Pages to build APIs, websites, etc. that require storing small amounts of data.


Case

Counter

Based on your business needs, you can store the number of clicks of a certain button or page in EdgeOne Pages KV. Update the key-value record in KV when clicking, so that you can conduct statistics and analysis on click or access behavior.


Keystore

For some sensitive information that is inconvenient to place in a code repository, you can store it in Edgeone Pages KV and dynamically obtain it to better protect your data.


Shopping Cart

Edgeone Pages KV can retain user data across multiple pages and multiple terminals, and can help you conveniently implement simple business requirements such as user shopping carts and user orders.


Basic Concept

Account

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


Namespace

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


Key-Value Pair

A Key-Value pair is a structure for users to store data, where each data item consists of two parts: a Key and a Value. The Key is a unique identifier that identifies the user Value, and the Value is the data associated with the Key.


Variable Name

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


Quick Start

Initializing Account

1. Enter Console: Switch to the "KV Storage" page.
2. Apply for Account Activation: Click the "Apply Now" button.
Note:
The current quota for KV storage is limited. Please apply for enabling it. We will process your application as soon as possible. It can be used once the application is successful.





Creating Namespace

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




2. Create Namespace: Input the namespace name to be created, 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 the namespace details.




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




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






Bind Namespace

Namespace binding between projects can be done in "Projects" 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, the bound projects can be viewed in the bind project list.




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




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




3. Binding succeeded: After successful binding, the bound namespace can be viewed in the Bind Namespace List.





Use KV

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

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


put

Write KV data, users create a new key-value pair or update 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, with a length of up to 512 B.
- value: The data to be written, with a data length of up to 25 MB.

Return Value
Return a Promise. You need to await this Promise to verify whether the writing is successful.

Usage Example
await my_kv.put(key, value);


get

Read the data in KV according to a specific key, and return the data of the specified type.
get(key:string, object?:{type:string}): Promise<value:string|object|ArrayBuffer|ReadableStream>

Parameter
- key: Specify the key for retrieving data.
- type: Used to specify the return value type. The default is text.
- text: String, return the value in the form of string.
- json: Object, the user deserializes json into an object form for return.
- arrayBuffer: ArrayBuffer, the user converts the binary value to an ArrayBuffer and returns it.
- stream: ReadableStream, usually used for scenarios where the value is large.

Return Value
Return a Promise. It is required to await this 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 that needs to be deleted.

Return Value
Return a Promise. You need to await this Promise to verify whether deletion is successful.

Usage Example
await my_kv.delete(key);


list

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

Parameter
-prefix: Used to filter keys with a specified prefix. When it is empty by default, return them in lexicographical order.
- limit: Maximum number of returned keys, for pagination. Default value is 256, maximum is 256.
- cursor: Cursor, start traversal from the specified key, for pagination. Empty by default.

Return Value
Return a Promise. It is required to await this Promise to retrieve the ListResult.

class ListResult {
    complete: Boolean;
    cursor: String;
    keys: Array<ListKey>;
}

class ListKey {
    key: String;
}

- complete: Indicates whether the list operation is completed. true means completed, false means incomplete.
- cursor: Cursor, the first key of the next page, null when list traversal is completed.
- keys: An object array describing each key.

Usage Example
// Get some data through list
let result = await kv.list({ "prefix": "a", "limit": 10, "cursor": "abc" });

// Traverse all data through 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 }) {
    // Retrieve the namespace key with the 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: Allows users to record and display the occurrence count of project business needs. Can be used for statistics of business scenarios such as "clicks" and "blog access traffic".