Valkey Large Object - Overview · Valkey

Valkey Large Object - Overview

Description

Note: valkey-large-object is at version 0.x. Commands, arguments, replies, and configuration can change before version 1.0.

The valkey-large-object module (BSD-3-Clause) adds a data type and commands to store large binary values in Valkey. Typical values are blocks of a machine learning KV cache, tensors, embeddings, and other blobs that are megabytes or larger in size. The module keeps objects in DRAM, or in a tiered layout where NVMe holds each object and DRAM is a read cache. Clients can transfer values over the normal Valkey connection (TCP), or over RDMA with libfabric. With RDMA, the server writes object bytes directly into client memory and reads them directly from client memory, for example with an Elastic Fabric Adapter (EFA) (see Providers).

The module registers with the name largeobj. Its value type is largeob-k.

Key concepts

Operating modes

The largeobj.operating-mode configuration selects one of two modes when the module loads.

Segments and maximum object size

The module allocates memory in fixed-size segments (largeobj.segment-size, from 1MB to 1GB). In Dram mode, an object must fit in a single segment. Thus an object of largeobj.max-object-size bytes, plus a small overhead for each chunk, must fit in one segment, and the largest object in Dram mode is less than 1GB. The module also divides objects into chunks (largeobj.chunk-size) for streaming I/O. Each chunk adds a small allocation overhead in the segment. Each pool has at most 16384 segments, so the DRAM pool does not grow past 16384 x largeobj.segment-size (1TB with 64MB segments), also when maxmemory is larger.

The default largeobj.max-object-size is 512MB. The smallest object is 1 byte. See Cross-configuration rules for the rules that relate these values.

Transports

If the fabric does not start, the module still loads, and only the TCP commands are available. See Valkey Large Object - RDMA Transfers for the full RDMA model.

CRC32C checksum

The server calculates a CRC32C (Castagnoli) checksum of each object when it stores the object. BLOB.INFO and BLOB.RDMA_GET return this value. On BLOB.RDMA_SET, a client can send its own CRC32C value. The server then rejects the write if the checksum of the transferred bytes is different.

Supported commands

See the complete list of large object commands.

Core commands also operate on large object keys. DEL, UNLINK, overwrite, expiry, and eviction free the object storage in the background. See Core commands on large object keys. MEMORY USAGE counts the payload only when the payload is in DRAM.

When notify-keyspace-events includes module key type events (d), the module sends largeobj.create when a write creates a key and largeobj.update when a write replaces a value.

Limitations

The current version has these limitations:

Persistence behavior

These operations work while large object keys exist, but they do not keep the object data:

The server log shows a warning, for example largeobj: persistence is not supported: blobs are saved to RDB/DUMP without their data, the first time that each case occurs.

Replication

The module does not replicate large objects:

Cluster mode

The module loads on each node of a cluster. Each command uses a single key (or no key for BLOB.RDMA_HELLO), so cluster clients can route commands by slot.

Core commands on large object keys

These results are the same in Dram and Tiered mode.

Command Result
COPY Works. The copy has its own data.
RENAME, RENAMENX Work.
MOVE, SWAPDB Work.
EXPIRE, PEXPIRE, TTL, PERSIST Work.
TYPE Returns largeob-k.
OBJECT ENCODING Returns raw.
DUMP Returns a value without the object data.
RESTORE Fails with ERR Bad data format.
DEL, UNLINK Work. The module frees the storage in the background.
FLUSHALL, FLUSHALL ASYNC Work.

Topics