Key Value Stores

Key Value (KV) Stores provide a simple and efficient way to store and retrieve data at the edge. They can be used to store configuration data, user preferences, or any other data that needs to be quickly accessed by your edge functions.

Getting Started

To begin using KV Stores:

1. Navigate to the “Compute > K/V Stores” section in the QuantCDN dashboard
2. Click “Create New Store” to create a new KV store
3. Give your store a name and description
4. Once created, you’ll receive a unique identifier for your store

Managing Data

The QuantCDN dashboard provides a simple interface to:

• Add new key-value pairs
• Edit existing values
• View all stored data
• Search for specific keys
• Delete key-value pairs
• Clear a store, either every key or only the keys that match a prefix or an age
• Delete a store once it is empty

Using KV Stores in Edge Functions

KV Stores can be easily integrated into your edge functions using the kvStore object.

Storing Data

To store data in a KV store:

await kvStore.set(KV_STORE_ID, key, data);

Retrieving Data

To retrieve data from a KV store:

const data = await kvStore.get(KV_STORE_ID, key);

Deleting Data

To delete data from a KV store:

await kvStore.delete(KV_STORE_ID, key);

Expiring Data (TTL)

Pass ttl in seconds to kvStore.set and the key expires on its own. The range is 60 seconds to 31,536,000 seconds (one year). Use this for sessions, OAuth state, nonces, rate-limit counters and any other short-lived value, so the store does not fill with stale keys.

// Expires 10 minutes after it is written
await kvStore.set(KV_STORE_ID, `oauth_state:${state}`, { returnTo: '/' }, { ttl: 600 });

How expiry behaves:

• An expired key reads as null, even before the platform removes the row, which can take up to 48 hours.
• Writing a key again without ttl removes its expiry.
• ttl can be combined with secret: true for encrypted values.
• The API returns the expiry as expires_at, a Unix timestamp in seconds, on reads and listings.

Encrypting Data

Pass secret: true to encrypt a value at rest. Reads decrypt automatically.

await kvStore.set(KV_STORE_ID, 'api-key', apiKey, { secret: true });

JSON Data Handling

When storing JSON data in a KV store, the data is automatically encoded when stored and decoded when retrieved. This means you can directly store and retrieve JavaScript objects without manual JSON parsing.

// Storing an object
const user = { name: 'John', age: 30 };
await kvStore.set(USERS_KV_STORE, 'user123', user);

// Retrieving the object
const userData = await kvStore.get(USERS_KV_STORE, 'user123');
// userData is automatically parsed as { name: 'John', age: 30 }

Clearing and Deleting Stores

From the dashboard, Clear store deletes keys in place. You can clear every key, or only the keys that start with a prefix, or only the keys older than a chosen age. Small clears finish immediately; large ones continue in the background and the key count falls over the next few minutes. The action asks you to type the store name to confirm.

A store can only be deleted once it is empty. Deleting a store that still holds keys returns an error that tells you to clear it first. Through the API, DELETE .../kv/{store_id}?force=true deletes the store together with its data.

Example Use Cases

KV Stores can be used for various purposes, such as:

• Storing user preferences or settings
• Caching API responses
• Managing feature flags
• Storing configuration data
• Maintaining rate limiting counters
• Storing temporary session data, with a ttl so it expires