# API KV Store

A API KV Store permite que suas Functions interajam com o armazenamento 
chave-valor distribuído da Azion diretamente do runtime. Isso possibilita 
persistência e recuperação de dados com baixa latência sem chamadas de API externas.

## Inicializando o cliente KV

Você pode inicializar o cliente KV usando o construtor ou o método `open`:

```javascript
// Usando o namespace padrão
const kv = new Azion.KV();

// Usando um namespace específico
const kv = new Azion.KV("meu-namespace");

// Usando o método open (assíncrono)
const kv = await Azion.KV.open("meu-namespace");
```

## Métodos disponíveis

A classe `Azion.KV` fornece os seguintes métodos para operações de dados:

| Método | Descrição | Referência |
|--------|-----------|------------|
| `put(key, value, options?)` | Armazena um par chave-valor | [Escrever pares chave-valor](/pt-br/documentacao/runtime/api-reference/kv-store/write/) |
| `get(key, type?, options?)` | Recupera um valor pela chave | [Ler pares chave-valor](/pt-br/documentacao/runtime/api-reference/kv-store/read/) |
| `getWithMetadata(key, type?, options?)` | Recupera um valor com seus metadados | [Ler pares chave-valor](/pt-br/documentacao/runtime/api-reference/kv-store/read/) |
| `delete(key)` | Exclui um par chave-valor | [Excluir pares chave-valor](/pt-br/documentacao/runtime/api-reference/kv-store/delete/) |

## Gerenciamento de namespaces

| Método | Descrição |
|--------|-----------|
| `new Azion.KV()` | Cria uma instância KV usando o namespace padrão |
| `new Azion.KV(name)` | Cria uma instância KV para o namespace especificado |
| `Azion.KV.open(name)` | Abre um namespace de forma assíncrona |
| `Azion.KV.delete(name)` | Exclui um namespace |

:::note
Namespaces devem ser criados via [API da Azion](https://api.azion.com/) ou Console antes de poderem ser usados em Functions. Você não pode criar namespaces de dentro de Functions.
:::

## Tipos de valores suportados

O KV Store suporta os seguintes tipos de valores:

| Tipo | Descrição |
|------|-----------|
| `string` | Dados de texto (codificados em UTF-8) |
| `object` | Objetos serializáveis em JSON (automaticamente convertidos para string) |
| `ArrayBuffer` | Dados binários |
| `ReadableStream` | Dados em streaming para valores grandes |

## Limites

| Limite | Valor |
|--------|-------|
| Tamanho da chave | Até 512 bytes (UTF-8) |
| Tamanho do valor | Até 25 MB por item |
| Tamanho dos metadados | Até 1024 bytes (JSON-serializado) |
| Taxa de gravação por chave | Até 1 gravação por segundo para a mesma chave |
| Mínimo `expirationTtl` | 60 segundos |
| Mínimo `cacheTtl` | 60 segundos |

## Consistência eventual

O KV Store usa consistência eventual. Gravações são imediatamente visíveis para 
outras requisições na mesma localização da rede global, mas podem levar até 60 
segundos (ou o valor do parâmetro `cacheTtl`) para serem visíveis em outras 
localizações.

## Documentação relacionada

- [Referência do KV Store](/pt-br/documentacao/produtos/store/kv-store/)
- [Como gerenciar KV Store com Functions](/pt-br/documentacao/produtos/guias/kv-store/gerenciar-com-funcoes/)