View a markdown version of this page

Large object module reference for distributed KV caching - Amazon ElastiCache
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

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.

Large object data type overview

The main source of documentation for large objects is the large object documentation on the valkey.io website. The valkey.io website has the following pages:

  • 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 module. The large object module adds the following commands. The BLOB.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.

Large object commands
NameDescription
BLOB.INFOReturns the length, CRC32C checksum, and storage tier of a large object.
BLOB.RDMA_GETWrites a large object into client memory regions with RDMA.
BLOB.RDMA_HELLOOpens an RDMA session between the connection and the server.
BLOB.RDMA_SETStores a large object, read from client memory regions with RDMA.
BLOB.TCP_GETReturns a large object, sent inline over the connection.
BLOB.TCP_SETStores 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 on the valkey.io website.

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 on the valkey.io website.

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 on the valkey.io website.

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 ACL categories
Large object command@read@write@fast@connection@largeobj
BLOB.TCP_GETYesNoYesNoYes
BLOB.TCP_SETNoYesYesNoYes
BLOB.RDMA_HELLONoNoYesYesYes
BLOB.RDMA_GETYesNoYesNoYes
BLOB.RDMA_SETNoYesYesNoYes
BLOB.INFOYesNoYesNoYes

To create role-based access control (RBAC) users and user groups, see Role-Based Access Control (RBAC). For example access strings, see ACL on the valkey.io website.

Module configuration

ElastiCache manages the settings of the large object module. For the parameters that you can change, see Parameters.