Low-Level KV Storage

<Note> KV is deprecated. It is a low-level escape hatch kept for backward compatibility. For new actors, prefer [in-memory state](/docs/actors/state) for small serializable values or [SQLite](/docs/actors/sqlite) for larger or queryable data. </Note>

Every Rivet Actor includes a lightweight key-value store on c.kv. It is useful for dynamic keys, blobs, or data that does not fit well in structured state.

If your data has a known schema, prefer state. KV is best for flexible or user-defined keys.

Basic Usage

Keys and values default to text, so you can use strings without extra options.

<CodeSnippet file="examples/docs/actors-kv/basic-usage.ts" />

Value Types

You can store binary values by passing Uint8Array or ArrayBuffer. Use type on both reads and writes to get the right value type: binary for Uint8Array and arrayBuffer for ArrayBuffer.

<CodeSnippet file="examples/docs/actors-kv/value-types.ts" />

TypeScript returns a concrete type based on the option you pass in:

<CodeSnippet file="examples/docs/actors-kv/typed-returns.ts" />

Key Types

Keys accept either string or Uint8Array. String keys are encoded as UTF-8 by default.

When listing by prefix, you can control how keys are decoded with keyType. Returned keys have the prefix removed.

<CodeSnippet file="examples/docs/actors-kv/key-types.ts" />

If you use binary keys, set keyType: "binary" so the returned keys stay as Uint8Array.

Range Operations

Use listRange(start, end) to read an arbitrary half-open range [start, end). Use deleteRange(start, end) to clear that same range efficiently.

<CodeSnippet file="examples/docs/actors-kv/range-operations.ts" />

Batch Operations

KV supports batch operations for efficiency. batchPut and batchGet work on raw Uint8Array keys and values, so encode strings before passing them in.

<CodeSnippet file="examples/docs/actors-kv/batch-operations.ts" />

API Reference

• ActorContext - c.kv is available on the context