KV Store

Store values addressed by a key on Azion, create namespaces through the Azion API, and read and write keys from inside a function.

Last updated

View as Markdown Agent setup

A key-value store holds each value under a name you choose, and finds it again by that name alone. There are no tables, no columns, and no query language: a read asks for one key and gets back what was last written to it. That narrow shape is what makes the lookup cheap, and it is also the trade, because nothing searches the values and nothing lists the keys for you.

KV Store runs that model on Azion’s distributed infrastructure. Keys live inside a namespace, which you create through the Azion API and address by its name. A function reads and writes those keys through Azion.KV, a global of Azion Runtime that needs no import and no credential. Use KV Store for the small values a request needs immediately: session state, feature flags, routing and redirect tables, per-user preferences, and rate-limit counters.

Quickstart KV Store guides

Keys and values

A function opens a namespace by name, then reads and writes keys on the client that open returns:

JavaScript
01export default {
02 async fetch(request, env, ctx) {
03 const kv = await Azion.KV.open('sessions');
04
05 await kv.put('user-42', 'active', { metadata: { region: 'br' } });
06
07 const value = await kv.get('user-42', 'text');
08 if (value === null) {
09 return new Response('No value for that key', { status: 404 });
10 }
11
12 return new Response(value);
13 },
14};
  • Azion.KV.open is the only way to obtain a client, and it is asynchronous. Every client names a namespace, because there is no default one.
  • put takes the key, the value, and an options object. A value is a string, an object, an ArrayBuffer, a ReadableStream, or a typed array view; metadata rides alongside it and comes back with getWithMetadata.
  • get takes the key and the type you want back: text, json, arrayBuffer, or stream. Pass an array of keys instead of one, and it returns an object keyed by name.
  • A key that was never written returns null rather than throwing. The caller checks for it; it is not an error condition.

How a key reaches a function

A namespace is created once through the API. Everything after that happens inside a request:

  1. You create the namespace through the Azion API. It is synchronous, and there is no provisioning state to wait on.
  2. A request arrives for your application, and Rules Engine evaluates the rules of the current phase.
  3. A rule whose criteria match runs its behaviors, one of which selects a function instance.
  4. Azion Runtime executes that function’s handler.
  5. Azion.KV.open resolves the namespace by name. A name no namespace on the account carries throws NotFound.
  6. The handler calls put, get, getWithMetadata, or delete, and returns its response.

Creating the namespace outside the request keeps the request path short, and it costs you the ability to provision one on demand: a function cannot create the namespace it needs, so the name has to exist before the code that opens it ships.

What KV Store covers

  • Interfaces. Two. The Azion API creates, lists, and retrieves namespaces; the Azion.KV client reads and writes keys inside a function. Azion Console has no KV Store screen, and Azion CLI and the Azion Terraform provider carry no KV Store command or resource — there is nothing to look for in any of the three.
  • Availability. KV Store is a Preview product on every service plan. It is not enabled on an account by default, and access is requested through a support ticket. To request it, refer to Technical Support.
  • Bounds. A namespace name is 3 to 63 characters of letters, numbers, the hyphen, and the underscore, and it is unique across the account. A namespace is permanent: it cannot be renamed, emptied, or deleted, so its name is worth settling before the first request. For every bound and the usage each plan includes, refer to KV Store limits.
  • Consistency. A write is visible immediately where it lands and converges elsewhere afterwards, so a read can return the value a newer write replaced. How KV Store works covers what that changes about the code you write.
  • Recommendations and failures. Best practices covers naming a namespace you cannot rename, deriving key names when nothing lists them, and reading both of the error shapes the platform returns. When a call throws, a build fails on an azion:kv import copied from older material, or a namespace the API lists is not found from a function, refer to Troubleshooting.
  • What it does not do. There is no key listing, no atomic increment, and no operation that spans more than one key as a unit. KV Store holds small values addressed by name, so unstructured files belong in Object Storage, relational records in SQL Database, and a response you want served again in Cache.

Next steps

QuickstartCreate your first namespace and read a key back from a function.How KV Store worksFollow a key from the request to the function that reads it, and what consistency changes.KV clientLook up a method, a return type, an option, or an error the client throws.NamespacesLook up a field, an operation, an envelope, or an error code on the Azion API.KV Store guidesComplete a specific task with the client, from storing a value to reading a stream.LimitsLook up a bound, what happens past it, and what each plan includes.