# KV Store 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](/en/documentation/platform/kv-store/quickstart/) [KV Store guides](/en/documentation/platform/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 export default { async fetch(request, env, ctx) { const kv = await Azion.KV.open('sessions'); await kv.put('user-42', 'active', { metadata: { region: 'br' } }); const value = await kv.get('user-42', 'text'); if (value === null) { return new Response('No value for that key', { status: 404 }); } return new Response(value); }, }; ``` - `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: ```mermaid flowchart TD API["Azion API: POST /v4/workspace/kv/namespaces"] --> NS["A namespace, addressed by its name"] Request["A request for your application"] --> Rule["A Rules Engine rule whose criteria match"] Rule --> Instance["The function instance the rule names"] Instance --> Runtime["Azion Runtime executes the handler"] Runtime --> Open["Azion.KV.open resolves the namespace by name"] NS --> Open Open --> Ops["put, get, getWithMetadata, delete"] Ops --> Response["The handler returns a response"] ``` 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](/en/documentation/platform/kv-store/namespaces/) creates, lists, and retrieves namespaces; the [`Azion.KV` client](/en/documentation/devtools/runtime/api-reference/kv-store/) 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](/en/documentation/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](/en/documentation/platform/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](/en/documentation/platform/kv-store/how-it-works/) covers what that changes about the code you write. - **Recommendations and failures.** [Best practices](/en/documentation/platform/kv-store/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](/en/documentation/platform/kv-store/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](/en/documentation/platform/object-storage/), relational records in [SQL Database](/en/documentation/platform/sql-database/), and a response you want served again in [Cache](/en/documentation/platform/applications/#cache). --- ## Next steps - [Quickstart](/en/documentation/platform/kv-store/quickstart.md): Create your first namespace and read a key back from a function. - [How KV Store works](/en/documentation/platform/kv-store/how-it-works.md): Follow a key from the request to the function that reads it, and what consistency changes. - [KV client](/en/documentation/devtools/runtime/api-reference/kv-store.md): Look up a method, a return type, an option, or an error the client throws. - [Namespaces](/en/documentation/platform/kv-store/namespaces.md): Look up a field, an operation, an envelope, or an error code on the Azion API. - [KV Store guides](/en/documentation/platform/kv-store/guides.md): Complete a specific task with the client, from storing a value to reading a stream. - [Limits](/en/documentation/platform/kv-store/limits.md): Look up a bound, what happens past it, and what each plan includes.