# KV Store API

The KV Store API allows your Functions to interact with Azion's distributed 
key-value storage directly from the runtime. This enables low-latency data 
persistence and retrieval without external API calls.

## Initializing the KV client

You can initialize the KV client using the constructor or the `open` method:

```javascript
// Using the default namespace
const kv = new Azion.KV();

// Using a specific namespace
const kv = new Azion.KV("my-namespace");

// Using the open method (async)
const kv = await Azion.KV.open("my-namespace");
```

## Available methods

The `Azion.KV` class provides the following methods for data operations:

| Method | Description | Reference |
|--------|-------------|-----------|
| `put(key, value, options?)` | Store a key-value pair | [Write key-value pairs](/en/documentation/runtime/api-reference/kv-store/write/) |
| `get(key, type?, options?)` | Retrieve a value by key | [Read key-value pairs](/en/documentation/runtime/api-reference/kv-store/read/) |
| `getWithMetadata(key, type?, options?)` | Retrieve a value with its metadata | [Read key-value pairs](/en/documentation/runtime/api-reference/kv-store/read/) |
| `delete(key)` | Delete a key-value pair | [Delete key-value pairs](/en/documentation/runtime/api-reference/kv-store/delete/) |

## Namespace management

| Method | Description |
|--------|-------------|
| `new Azion.KV()` | Creates a KV instance using the default namespace |
| `new Azion.KV(name)` | Creates a KV instance for the specified namespace |
| `Azion.KV.open(name)` | Opens a namespace asynchronously |
| `Azion.KV.delete(name)` | Deletes a namespace |

:::note
Namespaces must be created via the [Azion API](https://api.azion.com/) or Console before they can be used in Functions. You cannot create namespaces from within Functions.
:::

## Supported value types

KV Store supports the following value types:

| Type | Description |
|------|-------------|
| `string` | Text data (UTF-8 encoded) |
| `object` | JSON-serializable objects (automatically stringified) |
| `ArrayBuffer` | Binary data |
| `ReadableStream` | Streaming data for large values |

## Limits

| Limit | Value |
|-------|-------|
| Key size | Up to 512 bytes (UTF-8) |
| Value size | Up to 25 MB per item |
| Metadata size | Up to 1024 bytes (JSON-serialized) |
| Per-key write rate | Up to 1 write per second to the same key |
| Minimum `expirationTtl` | 60 seconds |
| Minimum `cacheTtl` | 60 seconds |

## Eventual consistency

KV Store uses eventual consistency. Writes are immediately visible to other 
requests in the same global network location, but can take up to 60 seconds 
(or the value of the `cacheTtl` parameter) to be visible in other locations.

## Related documentation

- [KV Store reference](/en/documentation/products/store/kv-store/)
- [How to manage KV Store with Functions](/en/documentation/products/guides/kv-store/manage-with-functions/)