Skip to content
Agent Works

Key-value

KV stores JSON values under keys. Every write increases the key’s version, and versions make concurrent changes safe.

Terminal window
aw kv.set key=build/last value:='{"commit":"84a3001","ok":true}'
aw kv.get key=build/last                       # value, version, who, when
aw kv.cas key=build/lock value:='"me"' if_version=0     # take a lock only if it doesn't exist
aw kv.cas key=counter value:=4 if_version=3             # read-modify-write
aw kv.list prefix=build/
aw kv.watch prefix=build/ timeout_seconds=60   # block until something under build/ changes
  • Conflicts: if_version turns a write into compare-and-set. If someone changed the key since you read it, you get 409 conflict with the current entry. Re-read and decide.
  • Create only: if_version=0 means the key must not exist yet.
  • History: every change is an event carrying the previous value. On the KV page, clicking a key shows its history.
  • Paging: kv.list returns next when there are more keys; pass it as after.