Docs / Developers / Storage & I/O / Key-value store
BuildSDK 0.10.1

Key-value store

These docs are public. To publish a plugin you need a YourBot account: sign in to open the Dev Portal.

Per-server JSON store. Keys are namespaced to your plugin and the active server — you cannot read another plugin's keys, and your keys for server A are isolated from server B. Capability: storage:kv.

Get / set / delete

ctx.kv.set("welcome_channel", "1234567890")
ctx.kv.set("session", {"user": "alice"}, ttl_seconds=3600)
val = ctx.kv.get("welcome_channel")
ctx.kv.delete("session")
exists = ctx.kv.exists("welcome_channel")

Counters

ctx.kv.increment("messages_today")            # +1
ctx.kv.increment("xp:user:42", amount=10)
ctx.kv.increment("stats", path="voice.hours") # dot-path into a JSON value
ctx.kv.decrement("lives_remaining")

increment(key, amount=1, *, path="") is atomic in a single round-trip — use it instead of get + modify + set. path is keyword-only and targets a nested field inside a JSON object value (decrement takes no path).

Bulk & listing

keys   = ctx.kv.list(prefix="user:", limit=100)          # [key, key, ...]
values = ctx.kv.list_values(prefix="user:", limit=100)   # {key: value}
batch  = ctx.kv.get_many(["a", "b", "c"])                # {key: value}, max 50
ctx.kv.set_many({"a": 1, "b": 2})                        # max 25 pairs
total  = ctx.kv.count(prefix="xp:")

list() returns key names only. When you need the stored values too, use list_values() — it avoids the N+1 of list + get.

Quotas. 50,000 keys per (server, plugin) plus a global cap of 500,000 keys per plugin across all servers, 64 KB max value, 512-byte key names. Exceeding a key-count quota raises KvQuotaError; an oversize key or value fails with a plain error. list() returns at most 1000 keys and list_values() at most 100 entries per call, so paginate with prefix ranges on big keyspaces.

Was this page helpful?
YourBot docs Reference tables are generated from the code that is running. Ask in Discord