Large object module reference for distributed KV caching
A large object is a binary value that a node keeps in dynamic random-access memory (DRAM) and on local Non-Volatile Memory Express (NVMe) storage. Distributed key-value (KV) caching stores KV cache blocks as large objects when LMCache uses the rdma or blob-tcp transport. For the size limits, see Size limits.
This page describes the large object data type, its commands, and the limits of the module. For the cluster requirements and setup, see Distributed KV caching.
Topics
Large object data type overview
The main source of documentation for large objects is the large object documentation
Large object overview
on the valkey.io website: key concepts, transports, supported commands, and limitations such as cluster mode, replication, and core commands on large object keys Getting started
on the valkey.io website: first commands, and errors at load time and run time Configuration
on the valkey.io website: module configs, memory and eviction, ACLs, security, what to watch, and INFO fields RDMA
on the valkey.io website: the session model, memory region triples, CRC behavior, and RDMA errors Use cases
on the valkey.io website: large language model (LLM) inference KV caches, model artifacts, and examples over TCP and RDMA
Large object commands overview
Distributed KV caching with ElastiCache uses the Valkey large object moduleBLOB.TCP_* commands send data inline over the Transport Layer Security (TLS) connection. The BLOB.RDMA_* commands move data with remote direct memory access (RDMA) over Elastic Fabric Adapter (EFA). Each command name links to its page on the valkey.io website.
| Name | Description |
|---|---|
| BLOB.INFO | Returns the length, CRC32C checksum, and storage tier of a large object. |
| BLOB.RDMA_GET | Writes a large object into client memory regions with RDMA. |
| BLOB.RDMA_HELLO | Opens an RDMA session between the connection and the server. |
| BLOB.RDMA_SET | Stores a large object, read from client memory regions with RDMA. |
| BLOB.TCP_GET | Returns a large object, sent inline over the connection. |
| BLOB.TCP_SET | Stores a large object, sent inline over the connection. |
For the full syntax, replies, and errors of each command, see the command page on the valkey.io website, or the large object command list
Transactions and scripts
BLOB.TCP_SET, BLOB.TCP_GET, BLOB.RDMA_SET, and BLOB.RDMA_GET can't run inside a MULTI/EXEC block, a Lua script, or a function. For more information, see Core commands on large object keys
Core commands on large object keys
DUMP returns a value without the object data, and RESTORE of that value fails with ERR Bad data format, so MIGRATE fails on large object keys. For information about how DEL, EXPIRE, COPY, RENAME, TYPE, and other core commands behave, see Core commands on large object keys
Large object ACLs
Similar to the existing per-data-type access control list (ACL) categories, such as @string and @hash, the @largeobj category makes it easier to manage access to large object commands and data. No other Valkey or Redis OSS commands are in the @largeobj category.
The large object commands are also in four existing ACL categories: @read, @write, @fast, and @connection. The following table shows the categories of each large object command.
| Large object command | @read | @write | @fast | @connection | @largeobj |
|---|---|---|---|---|---|
BLOB.TCP_GET | Yes | No | Yes | No | Yes |
BLOB.TCP_SET | No | Yes | Yes | No | Yes |
BLOB.RDMA_HELLO | No | No | Yes | Yes | Yes |
BLOB.RDMA_GET | Yes | No | Yes | No | Yes |
BLOB.RDMA_SET | No | Yes | Yes | No | Yes |
BLOB.INFO | Yes | No | Yes | No | Yes |
To create role-based access control (RBAC) users and user groups, see Role-Based Access Control (RBAC). For example access strings, see ACL
Module configuration
ElastiCache manages the settings of the large object module. For the parameters that you can change, see Parameters.