Edge Developer Platform
  • Pages
    • Product Introduction
    • Quick Start
    • Framework Guide
    • Project Guide
      • Project Management
      • edgeone.json
      • Error Codes
    • Build Guide
    • Deployment Guide
    • Domain Management
    • Pages Functions
    • KV Storage
    • EdgeOne CLI
    • FAQs
    • Contact Us
    • Release Notes
    • Migration Guides
      • Migrating from Vercel to EdgeOne Pages
      • Migrating from Cloudflare Pages to EdgeOne Pages
      • Migrating from Netlify to EdgeOne Pages
Docs Overview/
Edge Developer Platform/
Pages/
KV Storage/

KV Storage

Overview

EdgeOne Pages KV is a multi-edge node deployment KV persistent data storage, allowing users to read and write data globally. It follows final consistency and ensures global synchronous access within 60 seconds. You can combine the function capability in EdgeOne Pages to build APIs, websites, etc. that need to store small data.


Case

Counter

You can store the number of clicks on a button or page into EdgeOne Pages KV based on business needs. Update the key-value record in KV when clicked to facilitate statistics and analysis of clicks or access behavior.


Key Vault

For some sensitive information that is inconvenient to place in the Code Repository, you can store it in Edgeone Pages KV and dynamically acquire it to better protect your data.


Shopping Cart

Edgeone Pages KV can retain User Data across multiple pages and multiple terminals, which helps you easily implement simple business needs such as User Shopping Cart and User Orders.


Basic Concepts

Account

Edgeone Pages KV account is the smallest unit for KV Usage Statistics and billing period in the Pages service. One EdgeOne Pages account corresponds to one KV account, created by the user after the Console Page Activation. Account Storage Capacity is 100MB.


Namespace

The Namespace (namespace) is the basic unit of Data Isolation in Edgeone Pages KV. Each namespace can be seen as an independent database. Data Non-interference exists between different namespaces. An account can create 10 namespaces.


Key-Value Pair

A Key-Value Pair is a structure of User Coarse Data, where each data item consists of two parts: Key and Value. The Key is a unique identifier, User Identification Value, and the Value is the data associated with the Key.


Variable Name

Variable name is the Runtime Environment Variable Name defined when binding the project with the namespace. Before using namespace data, the namespace must be bound to the Edgeone Pages project. The Binding Relationship between namespace and project is Many-to-Many, and different Runtime Environment Variable Names are used to distinguish them during binding.


Quick Start

Initialize Account

1. Enter Console: Switch to the "KV Storage" page.
2. Apply for account activation: Click the "Apply Now" button.
Note:
Currently, there are limited spots available for KV storage. Please apply for activation, and we will process it as soon as possible. Once the application is successful, you can use it.





Creating Namespace

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




2. Create Namespace: Enter the desired namespace name and click the "Create" button, then wait for completion.




3. Creation Complete: After completion, you can view the created namespace in 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 Complete: After completion, you can view the added record in the record list.






Bind Namespace

Binding between namespaces and projects can be done in both "Project" and "Key-Value 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 successfully, you can view the bound project in the bound project list.




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




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




3. Binding Successful: After binding successfully, you can view the bound namespace in the bound namespace list.





Use KV

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

Currently, a set of KV storage operation methods are provided for Edgeone Pages functions. The specific methods are as follows:


put

Write KV data, 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>;

Parameters
- Key: The key to be created or updated, with a length less than or equal to 512 B.
- Value: The data to be written, with a length less than or equal to 25 MB.

Return Value
Return a Promise, you need to await the Promise to verify if the write was successful.

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


get

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

Parameters
- Key: The key to retrieve the data.
- Type: Specifies the type of the returned value, default is text.
- Text: String, returns the value as a string.
- json:Object, the user deserializes the JSON into an object and returns it.
- arrayBuffer:ArrayBuffer, the user converts the binary value to an ArrayBuffer and returns it.
- stream:ReadableStream, usually used in scenarios where the value is large.

Return Value
Returns a Promise, you need to await the Promise to get the value. If the key does not exist or the value is empty, null is returned.

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 the KV store.
delete(key: string): Promise<void>;

Parameters
- Key: The key of the key-value pair to be deleted.

Return Value
Return a Promise, you need to await the Promise to verify if the deletion was successful.

Usage Example
await my_kv.delete(key);


list

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

Parameters
- Prefix: Used to filter keys with the specified prefix. When empty, returns in lexicographical order.
- Limit: The maximum number of keys to return, used for pagination. The default value is 256, with an upper limit of 256.
- cursor: Cursor, starts traversal from the specified key, used for pagination. Default is empty.

Return Value
Returns a Promise, you need to await the Promise to get the ListResult:

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

class ListKey {
    key: String;
}

- complete: Indicates whether the list operation is complete; true for complete, false for incomplete.
- cursor: Cursor, the first key of the next page. When the list traversal is complete, it is null.
- keys: Array of objects describing each key.

Usage Example
// Get partial 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 }) {
    // Get the namespace key named 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 number of occurrences of project business needs, which can be used for statistics in business scenarios such as "click count," "blog visits," etc.