# Ler pares chave-valor

Para obter o valor de uma chave específica, chame o método `get()` na sua 
instância KV:

```javascript
// Ler chave individual
const value = await kv.get(key);

// Ler múltiplas chaves
const values = await kv.get(keys);
```

O método `get()` retorna uma promise que você pode usar `await` para obter o valor.

Se você solicitar uma única chave como string, receberá uma única resposta na 
promise. Se a chave não for encontrada, a promise resolverá com o valor literal 
`null`.

Você também pode solicitar um array de chaves. O valor de retorno será um 
objeto com pares chave-valor, onde chaves não encontradas têm valores `null`.

```javascript
async function handleRequest(request) {
  const kv = new Azion.KV();

  try {
    // Ler chave única, retorna valor ou null
    const value = await kv.get("primeira-chave", "text");

    // Ler múltiplas chaves, retorna objeto com valores
    const values = await kv.get(["primeira-chave", "segunda-chave"], "text");

    // Ler chave única com metadados
    const valueWithMetadata = await kv.getWithMetadata("primeira-chave", "text");

    // Ler múltiplas chaves com metadados
    const valuesWithMetadata = await kv.getWithMetadata(["primeira-chave", "segunda-chave"], "text");

    return new Response(JSON.stringify({
      value: value,
      values: values,
      valueWithMetadata: valueWithMetadata,
      valuesWithMetadata: valuesWithMetadata
    }), {
      headers: { "Content-Type": "application/json" }
    });
  } catch (e) {
    return new Response(e.message, { status: 500 });
  }
}

addEventListener("fetch", (event) => {
  event.respondWith(handleRequest(event.request));
});
```

:::note
Os métodos `get()` e `getWithMetadata()` podem retornar valores desatualizados. 
Se uma chave foi lida recentemente em uma determinada localização, gravações ou 
atualizações na chave feitas em outras localizações podem levar até 60 segundos 
(ou a duração do `cacheTtl`) para serem exibidas.
:::

---

## Referência

Os seguintes métodos são fornecidos para ler do KV Store:

- [get()](#método-get)
- [getWithMetadata()](#método-getwithmetadata)

### Método `get()`

Use o método `get()` para obter um único valor, ou múltiplos valores se forem 
fornecidas múltiplas chaves.

#### Solicitar uma única chave

Para obter o valor de uma única chave, chame o método `get()` na sua instância KV:

```javascript
await kv.get(key, type?, options?);
```

##### Parâmetros

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `key` | `string` | A chave do par KV. |
| `type` | `"text"` \| `"json"` \| `"arrayBuffer"` \| `"stream"` | Opcional. O tipo do valor a ser retornado. `text` é o padrão. |
| `options` | `{ cacheTtl?: number }` | Opcional. Objeto contendo a propriedade `cacheTtl`. |

##### Opções

| Opção | Tipo | Descrição |
|-------|------|-----------|
| `cacheTtl` | `number` | Tempo em segundos para armazenar o resultado em cache localmente. O valor mínimo é 60. |

##### Resposta

| Resposta | Tipo | Descrição |
|----------|------|-----------|
| `response` | `Promise<string \| object \| ArrayBuffer \| ReadableStream \| null>` | O valor para o par KV solicitado, ou `null` se não encontrado. |

O tipo de resposta depende do parâmetro `type`:

| Tipo | Retorna |
|------|---------|
| `"text"` | Uma `string` (padrão) |
| `"json"` | Um objeto decodificado de uma string JSON |
| `"arrayBuffer"` | Uma instância de `ArrayBuffer` |
| `"stream"` | Um `ReadableStream` |

#### Solicitar múltiplas chaves

Para obter os valores de múltiplas chaves, chame o método `get()` com um array:

```javascript
await kv.get(keys, type?);
```

##### Parâmetros

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `keys` | `string[]` | As chaves dos pares KV. |
| `type` | `"text"` \| `"json"` | Opcional. O tipo do valor a ser retornado. `text` é o padrão. |

##### Resposta

| Resposta | Tipo | Descrição |
|----------|------|-----------|
| `response` | `Promise<object>` | Um objeto com pares chave-valor. Chaves não encontradas têm valores `null`. |

---

### Método `getWithMetadata()`

Use o método `getWithMetadata()` para obter um único valor junto com seus 
metadados, ou múltiplos valores com seus metadados.

#### Solicitar uma única chave com metadados

Para obter o valor de uma chave junto com seus metadados:

```javascript
await kv.getWithMetadata(key, type?, options?);
```

Metadados são um valor serializável que você anexa a cada entrada KV ao usar `put()`.

##### Parâmetros

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `key` | `string` | A chave do par KV. |
| `type` | `"text"` \| `"json"` \| `"arrayBuffer"` \| `"stream"` | Opcional. O tipo do valor a ser retornado. `text` é o padrão. |
| `options` | `{ cacheTtl?: number }` | Opcional. Objeto contendo a propriedade `cacheTtl`. |

##### Resposta

| Resposta | Tipo | Descrição |
|----------|------|-----------|
| `response` | `Promise<{ value: string \| object \| ArrayBuffer \| ReadableStream \| null, metadata: object \| null }>` | Um objeto contendo o valor e os metadados. |

Se não houver metadados associados ao par chave-valor solicitado, `null` será 
retornado para metadata.

#### Solicitar múltiplas chaves com metadados

Para obter os valores de múltiplas chaves junto com seus metadados:

```javascript
await kv.getWithMetadata(keys, type?);
```

##### Parâmetros

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `keys` | `string[]` | As chaves dos pares KV. |
| `type` | `"text"` \| `"json"` | Opcional. O tipo do valor a ser retornado. `text` é o padrão. |

##### Resposta

| Resposta | Tipo | Descrição |
|----------|------|-----------|
| `response` | `Promise<object>` | Um objeto com chaves mapeadas para objetos `{ value, metadata }`. |

---

## Orientações

### Parâmetro type

Para valores simples, use o tipo padrão `text` que fornece seu valor como uma 
`string`. Por conveniência, um tipo `json` também é especificado que converterá 
um valor JSON em um objeto antes de retorná-lo. Para valores grandes, use 
`stream` para solicitar um `ReadableStream`. Para valores binários, use 
`arrayBuffer` para solicitar um `ArrayBuffer`.

Para valores grandes, a escolha do `type` pode ter um efeito notável na latência 
e uso de CPU. Para referência, o `type` pode ser ordenado do mais rápido ao mais 
lento como `stream`, `arrayBuffer`, `text` e `json`.

```javascript
async function handleRequest(request) {
  const kv = new Azion.KV();

  // Obter como texto (padrão)
  const textValue = await kv.get("minha-chave", "text");

  // Obter como JSON (automaticamente parseado)
  const jsonValue = await kv.get("minha-chave", "json");
  console.log(jsonValue.someProperty);

  // Obter como ArrayBuffer
  const bufferValue = await kv.get("minha-chave", "arrayBuffer");
  const decoder = new TextDecoder("utf-8");
  const decodedString = decoder.decode(bufferValue);

  // Obter como ReadableStream
  const streamValue = await kv.get("minha-chave", "stream");

  return new Response(textValue);
}

addEventListener("fetch", (event) => {
  event.respondWith(handleRequest(event.request));
});
```

### Parâmetro cacheTtl

`cacheTtl` é um parâmetro que define o tempo em segundos que um resultado KV 
é armazenado em cache na localização da rede global onde é acessado.

Definir o tempo em segundos é útil para reduzir a latência de leitura fria em 
chaves que são lidas com pouca frequência. `cacheTtl` é útil se seus dados são 
escritos uma vez ou raramente.

:::note[Leituras quentes e frias]
Uma leitura quente significa que os dados estão em cache localmente. Uma 
leitura fria significa que os dados não estão em cache, então devem ser 
buscados dos armazenamentos centrais. Tanto pares chave-valor existentes 
quanto pares chave-valor inexistentes (lookups negativos) são armazenados 
em cache.
:::

`cacheTtl` não é recomendado se seus dados são atualizados frequentemente e 
você precisa ver as atualizações logo após serem escritas, porque gravações 
de outras localizações da rede global não serão visíveis até que o valor em 
cache expire.

O valor mínimo para `cacheTtl` é 60 segundos.

```javascript
// Armazenar o resultado em cache por 5 minutos
const value = await kv.get("chave-config", "json", { cacheTtl: 300 });
```

### Tratando chaves inexistentes

Quando uma chave não existe, `get()` retorna `null`:

```javascript
async function handleRequest(request) {
  const kv = new Azion.KV();

  const value = await kv.get("chave-inexistente", "text");

  if (value === null) {
    return new Response("Chave não encontrada", { status: 404 });
  }

  return new Response(value);
}

addEventListener("fetch", (event) => {
  event.respondWith(handleRequest(event.request));
});
```

### Lendo streams

Para valores grandes armazenados como streams, processe os dados incrementalmente:

```javascript
async function handleRequest(request) {
  const kv = new Azion.KV();

  const stream = await kv.get("arquivo-grande", "stream");

  if (stream instanceof ReadableStream) {
    const decoder = new TextDecoder();
    let text = "";

    for await (const chunk of stream) {
      text += decoder.decode(chunk, { stream: true });
    }
    text += decoder.decode();

    console.log(`Recuperados ${text.length} caracteres`);
  }

  // Ou retorne o stream diretamente na resposta
  return new Response(stream);
}

addEventListener("fetch", (event) => {
  event.respondWith(handleRequest(event.request));
});
```

### Trabalhando com metadados

Recupere tanto o valor quanto os metadados em uma única chamada:

```javascript
async function handleRequest(request) {
  const kv = new Azion.KV();

  const result = await kv.getWithMetadata("perfil-usuario", "json");

  console.log("Valor:", result.value);
  console.log("Metadados:", result.metadata);

  if (result.metadata && result.metadata.version) {
    console.log("Versão:", result.metadata.version);
  }

  return new Response(JSON.stringify(result), {
    headers: { "Content-Type": "application/json" }
  });
}

addEventListener("fetch", (event) => {
  event.respondWith(handleRequest(event.request));
});
```

---

## Relacionados

- [Escrever pares chave-valor](/pt-br/documentacao/runtime/api-reference/kv-store/write/)
- [Excluir pares chave-valor](/pt-br/documentacao/runtime/api-reference/kv-store/delete/)
- [Visão geral da API KV Store](/pt-br/documentacao/runtime/api-reference/kv-store/)