Use key prefixes

Use prefixes when a feature owns more than one KV record. Prefixes make keys easier to list and safer to clear.

Name Keys by Owner and Purpose

Use a predictable separator:

await kv.set('users:ava:preferences', { density: 'compact' })
await kv.set('users:ava:flags', { beta: true })
await kv.set('users:ben:preferences', { density: 'comfortable' })

The key should answer:

• who owns the value
• what kind of value it is
• whether the key is stable across deploys

List a Prefix

const keys = await kv.keys('users:ava')

Example response:

{
  "keys": [
    "users:ava:flags",
    "users:ava:preferences"
  ]
}

Clear a Prefix

await kv.clear('users:ava')

This is safer than clearing the whole store when only one user, tenant, or feature namespace should be reset.

Keep Prefixes Stable

Changing prefixes is a data migration. Prefer additive changes:

const key = `users:${userId}:preferences`

Avoid keys that depend on labels users can rename:

const key = `users:${displayName}:preferences`

Related Pages

• Usage
• Write and read values
• Troubleshooting